~sjm/can-docs

dce90afbd2b85050d208552c863f4dc4182302ed — Sam Marshall 2 years ago e61e63d
update docs with can-note-graph
M docs/can-add.md => docs/can-add.md +8 -7
@@ 16,11 16,12 @@ If `can-add` would add a note with the same name as another note already in the 
* [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                                             |
	* | 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


M docs/can-address.md => docs/can-address.md +8 -7
@@ 7,11 7,12 @@ The `can-address` command will take a string of can's [internal AST](./internal-

## Backlinks
* [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                                             |
	* | 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


M docs/can-ast-at.md => docs/can-ast-at.md +8 -7
@@ 4,11 4,12 @@ The `can-ast-at` command should accept a note address through stdin. It should p

## Backlinks
* [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                                             |
	* | 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


M docs/can-commands.md => docs/can-commands.md +9 -8
@@ 6,14 6,15 @@ This is beneficial for multiple reasons. Development on commands can stay focuse

The commands shown here are all commands, including internal commands. Those closer to the top are more likely to be used by the end-user.

| 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                                             |
| 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |

## Backlinks
* [can](./index.md)

M docs/can-md.md => docs/can-md.md +8 -7
@@ 4,11 4,12 @@ The `can-md` command should take a string of markdown through standard input and

## Backlinks
* [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                                             |
	* | 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


M docs/can-new.md => docs/can-new.md +8 -7
@@ 4,11 4,12 @@ The `can-new` command should create a new [writing folder](./writing-folder.md) 

## Backlinks
* [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                                             |
	* | 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


A docs/can-note-graph.md => docs/can-note-graph.md +45 -0
@@ 0,0 1,45 @@
# can-note-graph

`can-note-graph` constructs a list of addressed notes with metadata and [AST](./internal-ast.md) fully prepared for storage. The AST should have any internal links pointing at an address rather than a filename.

It takes no input. When it runs, it should produce output of the following shape using any notes it finds with valid extensions (see [config: extensions](./config-extensions.md)).

```typescript
[
    {
        file: string,
        metadata: {
            name: string,
        },
        ast: unist.Node,
        address: string,
    },
    ...
]
```
The name of the note is derived from the file name. Effectively, the notes produced by `can-note-graph` should be ready for storage

### Error Codes

`can-note-graph` will exit with an error-code if it runs into any problems

| code | meaning                                                 |
|------|---------------------------------------------------------|
| 1    | unknown error                                           |
| 2    | not run in a directory with a [notebook](./notebook.md) |
| 3    | notes form a cycle                                      |
| 4    | internal links point to a file which doesn't exist yet  |

Error code `4` may only be used for referencing notes which don't exist at all in the future. `can-note-graph` may start to check inside the notebook for a note with a name. For now, pull all notes you're linking to into the [writing folder](./writing-folder.md) before running `can-note-graph`

## Backlinks
* [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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


M docs/can-status.md => docs/can-status.md +8 -7
@@ 14,11 14,12 @@ A heading of "new notes" will be displayed, under which each new note will have 
* [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                                             |
	* | 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 containing a notebook           |
| [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-note-graph](./can-note-graph.md) | construct a list of addressed notes from the writing folder |


A docs/config-extensions.md => docs/config-extensions.md +8 -0
@@ 0,0 1,8 @@
# config: extensions

The only valid extension for a note file is currently `.md`. This may change to allow configuration. `can` doesn't yet have the concept of configuration, but it should develop over time.

## Backlinks
* [can-note-graph](./can-note-graph.md)
	* It takes no input. When it runs, it should produce output of the following shape using any notes it finds with valid extensions (see [config: extensions](./config-extensions.md)).


A docs/inbox.md => docs/inbox.md +4 -0
@@ 0,0 1,4 @@
# Inbox

Ideas, snippets and things I don't know where to put yet


M docs/internal-ast.md => docs/internal-ast.md +2 -0
@@ 9,4 9,6 @@ can [notebooks](./notebook.md) will store notes as a json representation of a no
	* The `can-ast-at` command should accept a note address through stdin. It should pipe the [internal AST](./internal-ast.md) for that address into stdout. If no note is found at that address, the process should exit with a code of `2`.
* [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-note-graph](./can-note-graph.md)
	* `can-note-graph` constructs a list of addressed notes with metadata and [AST](./internal-ast.md) fully prepared for storage. The AST should have any internal links pointing at an address rather than a filename.


M docs/notebook.md => docs/notebook.md +6 -8
@@ 38,16 38,14 @@ Notes aren't stored by name in the notebook, but by address. Each address contai
	* 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                               |
| [can-address](./can-address.md) | find the address of a particular AST                                             |
* [can : core concepts](./core-concepts.md)
	* [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-note-graph](./can-note-graph.md)
	* | code | meaning                                                 |
| 1    | unknown error                                           |
| 2    | not run in a directory with a [notebook](./notebook.md) |
| 3    | notes form a cycle                                      |
| 4    | internal links point to a file which doesn't exist yet  |


M docs/writing-folder.md => docs/writing-folder.md +2 -8
@@ 17,18 17,12 @@ You can add your whole writing folder to `git` for version control - the importa
	* 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-note-graph](./can-note-graph.md)
	* Error code `4` may only be used for referencing notes which don't exist at all in the future. `can-note-graph` may start to check inside the notebook for a note with a name. For now, pull all notes you're linking to into the [writing folder](./writing-folder.md) before running `can-note-graph`