~sjm/can-docs

e61e63ddf79f089f41228bde89ff61443417722c — Sam Marshall 2 years ago 12f9c5b
update backlinks
M docs/20200508183245.md => docs/20200508183245.md +2 -2
@@ 5,8 5,8 @@ can should process notes in the [writing folder](./writing-folder.md) as markdow
## Backlinks
* [can should allow for multiple formats of notes](./20200508183355.md)
	* [can's default note file will be markdown](./20200508183245.md), but can should provide the ability for multiple supported formats.
* [can-md](./can-md.md)
	* The `can-md` command should take a string of markdown through standard input and will output can's [internal ast](./internal-ast.md) format for the provided markdown. [The default note format will be markdown](./20200508183245.md). 
* [can-status](./can-status.md)
	* The `can-status` command should report when markdown files in the [writing folder](./writing-folder.md) are new to the notebook and can be added. [The default note file will be markdown](./20200508183245.md), but [can should allow for multiple formats of notes](./20200508183355.md)
* [can-md](./can-md.md)
	* The `can-md` command should take a string of markdown through standard input and will output can's [internal ast](./internal-ast.md) format for the provided markdown. [The default note format will be markdown](./20200508183245.md). 


M docs/20200513141518.md => docs/20200513141518.md +7 -0
@@ 31,3 31,10 @@ But now $B$'s content has changed, and $\text{addr}B$ is `#2`. This leads to us 
The best technical solution I could think of to this is the aformentioned 'meta-note'. Cycles like $A$ and $B$ would be put into the same structure $Z$ in a canonical order, and they could refer to the other using this order. They then share an address $\text{addr}(A \land B)$ with the canonical order appended, `#0/0` for $A$ and `#0/1` for $B$. The problem with this solution is that the cycle could easily be much bigger than two notes, encompassing much of a notebook. `A -> B -> C -> D -> A` is possible, and this shared metanote could easily slowly consume an entire notebook over time if left unchecked. 

I'm not saying this solution will never be used, but for now I don't think it's a good solution even though it works. I'd rather leave the cycle in place for the human author to unwind and allow notes to be stored with an address per note.

## Backlinks
* [Notebook](./notebook.md)
	* [It isn't possible to build cycles in your notes](./20200513141518.md) for now. That means that you can't have a note `A` linking to a note `B`, which links back to note `A`. Or even `A -> B -> C -> A`. This is to avoid issues with storing notes, and you should be warned if you try to add notes which form a cycle to your notebook. If you find that this happens, try making another note with the content that your cycling notes can refer to. Instead of
* [can-add](./can-add.md)
	* [It isn't possible to include cycles in `can` notes](./20200513141518.md), so `can-add` should print a warning and exit if a cycle exists in the notes.


M docs/can-add.md => docs/can-add.md +13 -0
@@ 11,3 11,16 @@ Internal links should be translated into addresses before being placed into the 
To achieve this, `can-add` will have to build a graph of notes existing in the writing folder. Starting with any leaf-node, `can-add` will write the contents of the file to its address and add the name of the file as metadata. It will remove the leaf-node from it's internal graph and do the same for another leaf-node, until no notes remain.

If `can-add` would add a note with the same name as another note already in the notebook, it should be added as normal. The metadata of the old note should be updated to remove this name and references to the old note should be updated with a reference to the new note. This process will bloom out to all transitive dependencies. It's possible that a separate command will be built to handle each step of these updates. `can-add` should add this information to a log, to allow the process to be viewed or reversed later.

## Backlinks
* [It isn't possible to build cycles in your notes](./20200513141518.md)
	* It isn't possible to use `can` to build your notes to link into a cycle in any way. The [`can status`](./can-status.md) command should warn you if your working notes form a cycle, and [`can add`](./can-add.md) will refuse to add notes which form a cycle.
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |
| [can-address](./can-address.md) | find the address of a particular AST                                             |


M docs/can-address.md => docs/can-address.md +1 -0
@@ 9,6 9,7 @@ The `can-address` command will take a string of can's [internal AST](./internal-
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |

M docs/can-ast-at.md => docs/can-ast-at.md +1 -0
@@ 6,6 6,7 @@ The `can-ast-at` command should accept a note address through stdin. It should p
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |

M docs/can-md.md => docs/can-md.md +1 -0
@@ 6,6 6,7 @@ The `can-md` command should take a string of markdown through standard input and
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |

M docs/can-new.md => docs/can-new.md +1 -0
@@ 6,6 6,7 @@ The `can-new` command should create a new [writing folder](./writing-folder.md) 
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |

M docs/can-status.md => docs/can-status.md +3 -0
@@ 11,9 11,12 @@ The `can-status` command should report when markdown files in the [writing folde
A heading of "new notes" will be displayed, under which each new note will have a line with the title of the note when it is added - the file name.

## Backlinks
* [It isn't possible to build cycles in your notes](./20200513141518.md)
	* It isn't possible to use `can` to build your notes to link into a cycle in any way. The [`can status`](./can-status.md) command should warn you if your working notes form a cycle, and [`can add`](./can-add.md) will refuse to add notes which form a cycle.
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |

M docs/locality.md => docs/locality.md +5 -0
@@ 3,3 3,8 @@
`can` is entirely local. Your notes are stored on your machine, wherever you've set up your [writing folder](./writing-folder.md). You can use tools like `git` to sync your files across machines (which should work really well), but `can` core tools should never access your network. It is possible that some tools will be built to aid syncing / working in a distributed manner - but those will be explicit and entirely opt-in if and when they exist at all.

[On top of this, `can` stores its notebooks in a plaintext format](./plain-text.md) so you can always get your notes back.

## Backlinks
* [can : core concepts](./core-concepts.md)
	* [locality](./locality.md)


M docs/notebook.md => docs/notebook.md +5 -2
@@ 32,11 32,16 @@ Notes aren't stored by name in the notebook, but by address. Each address contai
## Backlinks
* [Writing Folder](./writing-folder.md)
	* In can, your 'writing folder' is the directory on your computer which contains your current working documents and your [notebook](./notebook.md).
* [can-add](./can-add.md)
	* The `can-add` command is used to add notes into the [notebook](./notebook.md) from the [writing folder](./writing-folder.md).
* [can-status](./can-status.md)
	* The `can-status` command should report different aspects of the current status of the [notebook](./notebook.md) and writing folder.
* [Internal abstract syntax tree](./internal-ast.md)
	* can [notebooks](./notebook.md) will store notes as a json representation of a normalised [abstract syntax tree](https://notes.sjm.codes/abstract-syntax-tree/).
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |


@@ 45,6 50,4 @@ Notes aren't stored by name in the notebook, but by address. Each address contai
	* [the notebook](./notebook.md)
* [can-new](./can-new.md)
	* The `can-new` command should create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) in the directory they are called in. The writing folder should be named `writing-folder` and should contain an empty `.notebook` directory.
* [can-status](./can-status.md)
	* The `can-status` command should report different aspects of the current status of the [notebook](./notebook.md) and writing folder.


M docs/plain-text.md => docs/plain-text.md +7 -0
@@ 1,3 1,10 @@
# Plain text

`can` stores notes in plain text (using `remark`/`mdast`'s abstract syntax trees), so it shouldn't be too difficult to find or build tools to get your notes back even if you uninstall `can` at any point and don't want to reinstall it just for exporting your notes.

## Backlinks
* [can : core concepts](./core-concepts.md)
	* [plain text](./plain-text.md)
* [Locality](./locality.md)
	* [On top of this, `can` stores its notebooks in a plaintext format](./plain-text.md) so you can always get your notes back.


M docs/writing-folder.md => docs/writing-folder.md +7 -2
@@ 13,17 13,22 @@ You can add your whole writing folder to `git` for version control - the importa
	* In can, your notebook is the collection of all your notes. Using can, you can search and shuffle through these notes and pull them into your [writing folder](./writing-folder.md) for working with.
* [The default note file will be markdown](./20200508183245.md)
	* can should process notes in the [writing folder](./writing-folder.md) as markdown by default. [Can should allow for multiple formats of notes](./20200508183355.md) in the future.
* [can-add](./can-add.md)
	* The `can-add` command is used to add notes into the [notebook](./notebook.md) from the [writing folder](./writing-folder.md).
* [can-status](./can-status.md)
	* The `can-status` command should report when markdown files in the [writing folder](./writing-folder.md) are new to the notebook and can be added. [The default note file will be markdown](./20200508183245.md), but [can should allow for multiple formats of notes](./20200508183355.md)
* [can commands](./can-commands.md)
	* | command                         | description                                                                      |
| [can-status](./can-status.md)   | report the current state of the writing folder                                   |
| [can-add](./can-add.md)         | add notes from the writing folder into the notebook                              |
| [can-new](./can-new.md)         | create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) |
| [can-ast-at](./can-ast-at.md)   | given an address, find the AST of a note                                         |
| [can-md](./can-md.md)           | convert from markdown to can's internal AST format                               |
| [can-address](./can-address.md) | find the address of a particular AST                                             |
* [can : core concepts](./core-concepts.md)
	* [the writing folder](./writing-folder.md)
* [Locality](./locality.md)
	* `can` is entirely local. Your notes are stored on your machine, wherever you've set up your [writing folder](./writing-folder.md). You can use tools like `git` to sync your files across machines (which should work really well), but `can` core tools should never access your network. It is possible that some tools will be built to aid syncing / working in a distributed manner - but those will be explicit and entirely opt-in if and when they exist at all.
* [can-new](./can-new.md)
	* The `can-new` command should create a new [writing folder](./writing-folder.md) and [notebook](./notebook.md) in the directory they are called in. The writing folder should be named `writing-folder` and should contain an empty `.notebook` directory.
* [can-status](./can-status.md)
	* The `can-status` command should report when markdown files in the [writing folder](./writing-folder.md) are new to the notebook and can be added. [The default note file will be markdown](./20200508183245.md), but [can should allow for multiple formats of notes](./20200508183355.md)