Commit
+69 -27 +/-1 browse
| 1 | diff --git a/doc/note.5.scd b/doc/note.5.scd |
| 2 | index 7bef94f..073c409 100644 |
| 3 | --- a/doc/note.5.scd |
| 4 | +++ b/doc/note.5.scd |
| 5 | @@ -2,10 +2,13 @@ note(5) |
| 6 | |
| 7 | # NAME |
| 8 | |
| 9 | - note - configuration file and format |
| 10 | + note - design and configuration |
| 11 | |
| 12 | - ## The Anatomy of a Note |
| 13 | - A note is a simple markdown document that contains zero or more instances of structured data encoded as YAML or JSON. Notes can optionally contain `front-matter` at the head of each file, which is YAML or JSON enclosed by a pair of `---`. |
| 14 | + # The Anatomy of a Note |
| 15 | + A note is a simple markdown document that contains zero or more instances of |
| 16 | + structured data encoded as YAML or JSON. Notes can optionally contain |
| 17 | + *front-matter* at the head of each file, which is YAML or JSON enclosed by a |
| 18 | + pair of "*---*". |
| 19 | |
| 20 | ``` |
| 21 | --- |
| 22 | @@ -17,13 +20,14 @@ tags: [ocaml, programming] |
| 23 | # Hello World! |
| 24 | |
| 25 | Today will be a nice day. |
| 26 | + |
| 27 | ``` |
| 28 | |
| 29 | - ## The State Directory |
| 30 | + # The State Directory |
| 31 | |
| 32 | - Each note is stored as a flat file inside the `state_dir` with a slug that corresponds to the |
| 33 | - date (YYYYMMDD) on which it was created. If multiple notes are created on one day, an index will |
| 34 | - be appended to the file. |
| 35 | + Each note is stored as a flat file inside the *state_dir* with a slug that |
| 36 | + corresponds to the date (YYYYMMDD) on which it was created. If multiple notes |
| 37 | + are created on one day, an index will be appended to the file. |
| 38 | |
| 39 | ``` |
| 40 | $ tree ~/.local/share/note/ |
| 41 | @@ -34,33 +38,71 @@ $ tree ~/.local/share/note/ |
| 42 | └── note-20200819-3.md |
| 43 | ``` |
| 44 | |
| 45 | - ## Configuration |
| 46 | + # Configuration |
| 47 | + |
| 48 | + The behavior of *note* can be modified with yaml file stored in the XDG Base |
| 49 | + Directory, e.g. *~/.config/note/config.yaml*. The configuration can be modified |
| 50 | + with the *note config* subcommand. |
| 51 | + |
| 52 | + ## Options |
| 53 | + |
| 54 | + *state_dir* directory to save notes in |
| 55 | + |
| 56 | + *lock_file* lockfile to aquire for io operations |
| 57 | + |
| 58 | + *editor* your text editor |
| 59 | + |
| 60 | + *on_modification* hook to run when a note is modified |
| 61 | + |
| 62 | + *on_sync* hook to run when *note sync* is called |
| 63 | + |
| 64 | + *list_style* style to output the list of notes with |
| 65 | |
| 66 | - The behavior of *note* can be configured with yaml file stored in *~/.config/note/config.yaml* and configure itself per the XDG Base Directory specification, see https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html. You can view the resolved configuration by running *note config*: |
| 67 | + *encoding* encoding for note output |
| 68 | + |
| 69 | + *column_list* columns to include in note output |
| 70 | + |
| 71 | + *styles* map to styles to apply to tags |
| 72 | + |
| 73 | + ## Example |
| 74 | |
| 75 | ``` |
| 76 | - state_dir: /home/kevin/.local/share/note |
| 77 | lock_file: /home/kevin/.local/share/note.lock |
| 78 | editor: nvim |
| 79 | - on_modification: note_commit.sh |
| 80 | + on_modification: note-on-modification |
| 81 | + on_sync: note-on-sync |
| 82 | + list_style: fixed |
| 83 | + encoding: raw |
| 84 | + column_list: |
| 85 | + - title |
| 86 | + - description |
| 87 | + - tags |
| 88 | + - words |
| 89 | + styles: |
| 90 | + - pattern: linux |
| 91 | + style: |
| 92 | + - Foreground White |
| 93 | + - Background Red |
| 94 | + - pattern: ocaml |
| 95 | + style: |
| 96 | + - Foreground White |
| 97 | + - Background Green |
| 98 | + - Underlined |
| 99 | + |
| 100 | ``` |
| 101 | |
| 102 | + # Git Storage and Synchronization |
| 103 | + |
| 104 | ## Persisting Notes with Git |
| 105 | |
| 106 | - If the `on_modification` configuration option is set it will be called each time a note is modified. This feature can be used to automatically commit your notes to a git repository with a script such as below: |
| 107 | + If the *on_modification* configuration option is set it will be called each |
| 108 | + time a note is modified. This feature can be used to automatically commit your |
| 109 | + notes to a git repository. An example script is included with this package and |
| 110 | + should be available on your path as *note-on-modification*. |
| 111 | + |
| 112 | + ## Synchronization with Git |
| 113 | + |
| 114 | + The *on_sync* configuration option can be used to synchronize and resolve |
| 115 | + conflicts with git backed storage. An example script is included with this |
| 116 | + package and should be available on your path as *note-on-sync*. |
| 117 | |
| 118 | - ``` |
| 119 | - #!/bin/bash |
| 120 | - # This is an example script that can be used in conjunction with the |
| 121 | - # on_modification config option to commit every note change to a git |
| 122 | - # repository. You'll need to place it somewhere on your $PATH. This |
| 123 | - # script assumes that your state_dir is also a git repository. |
| 124 | - set -e |
| 125 | - |
| 126 | - STATE_DIR="$(note config -get state_dir)" |
| 127 | - |
| 128 | - pushd "$STATE_DIR" |
| 129 | - git add --all |
| 130 | - git commit -m 'automated commit' |
| 131 | - popd |
| 132 | - ``` |