Author: Kevin Schoon [kevinschoon@gmail.com]
Hash: 41863133f1678a95e06bd4d49ed82ed2e0eec32c
Timestamp: Thu, 17 Sep 2020 18:58:41 +0000 (4 years ago)

+253 -293 +/-8 browse
switch man page generator to scdoc
1diff --git a/README.md b/README.md
2index e38cc8f..b9c99b7 100644
3--- a/README.md
4+++ b/README.md
5 @@ -17,7 +17,6 @@ tags: [ocaml, programming]
6 Today will be a nice day.
7 ```
8
9-
10 ## Configuration
11
12 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](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). You can view the resolved configuration by running `note config`:
13 @@ -110,83 +109,3 @@ popd
14 ## Web UI
15
16 Notes are stored in a format that is compatible with the static website generator [Hugo](https://gohugo.io/content-management/front-matter/) and thus you can point your `state_dir` to a Hugo content directory and get a web based interface for all of your notes.
17-
18- ## Subcommands
19-
20- ### Cat
21-
22- Write one or more notes to stdout. By default the cat command will write every note to stdout as plain text however the encoding can be adjusted to `yaml` or `json` for consumption by other tools.
23-
24- #### Examples
25-
26- ```bash
27- # print the parsed content of the fuubar note
28- note cat fuubar
29- # write all commands as a json list
30- note cat -encoding json
31- ```
32-
33- ### Config
34-
35- Display the current configuration as inferred by Note. It is also possible to extract specific values by specifying a key value.
36-
37- #### Examples
38-
39- ```bash
40- # display the current configuration
41- note config
42- # extract a specific value from the configuration
43- note config -get state_dir
44- ```
45-
46- ### Create
47-
48- Create a new note and save it to disk in your configured `state_dir`. The `on_modification` call back will be invoked if the file is committed to disk.
49-
50- #### Examples
51-
52- ```bash
53- # create a new note with the given title and tags
54- note create "Remember The Milk" groceries fuu bar
55- # create a note by reading from stdin
56- note create -stdin <<EOF
57- # My Important Note
58-
59- Hello World!
60- EOF
61- # the title will be inferred from the heading
62- note ls "My Important Note"
63- ```
64-
65- ### Delete
66-
67- Delete the first note that matches the filter criteria. The `on_modification` call back will be invoked if the note is deleted.
68-
69- #### Examples
70-
71- ```bash
72- # delete the note called fuubar
73-
74- note delete fuubar
75- ```
76-
77- ### Edit
78-
79- Select a note that matches the filter criteria and open it in your `$EDITOR`. The `on_modification` call back will be invoked if the edited file differs from the original.
80-
81- #### Examples
82-
83- ```bash
84- # edit the fuubar note
85- note edit fuubar
86- ```
87-
88- ### List
89- List notes that match the filter criteria, if no filter criteria is given all notes will be listed
90-
91- #### Examples
92-
93- ```bash
94- # list all notes
95- note ls
96- ```
97 diff --git a/bin/dune b/bin/dune
98index cb16adc..6feb0e1 100644
99--- a/bin/dune
100+++ b/bin/dune
101 @@ -7,7 +7,7 @@
102
103 (install
104 (section man)
105- (files ../doc/note.7))
106+ (files ../doc/note.1))
107 (install
108 (section share)
109 (files ../completion/note))
110 diff --git a/doc/note.1 b/doc/note.1
111new file mode 100644
112index 0000000..ed2edce
113--- /dev/null
114+++ b/doc/note.1
115 @@ -0,0 +1,73 @@
116+ .\" Generated by scdoc 1.11.0
117+ .\" Complete documentation for this program is not available as a GNU info page
118+ .ie \n(.g .ds Aq \(aq
119+ .el .ds Aq '
120+ .nh
121+ .ad l
122+ .\" Begin generated content:
123+ .TH "note" "1" "2020-09-17"
124+ .P
125+ .SH NAME
126+ .P
127+ note - a simple note taking command line interface
128+ .P
129+ .SH SYNOPSIS
130+ .P
131+ \fBnote\fR COMMAND [OPTIONS.\&.\&.\&]
132+ .P
133+ .SH DESCRIPTION
134+ .P
135+ \fBnote\fR is a command line interface for recording notes in the markdown format.\& It can be
136+ configured to automatically commit modifications to a git repository and even synchronize
137+ changes to a remote host.\&
138+ .P
139+ .SH SUBCOMMANDS
140+ .P
141+ .SS cat
142+ .P
143+ output one or more notes to stdout
144+ .P
145+ .SS config
146+ .P
147+ display the configuration
148+ .P
149+ .SS create
150+ .P
151+ create a new note
152+ .P
153+ .SS delete
154+ .P
155+ delete an existing note
156+ .P
157+ .SS edit
158+ .P
159+ edit an existing note
160+ .P
161+ .SS ls
162+ .P
163+ list notes in the database
164+ .P
165+ .SH EXAMPLES
166+ .P
167+ .SS Create a new Note reading from stdin and save it to the state_dir
168+ .nf
169+ .RS 4
170+
171+ note create -stdin "Hello World" <<EOF
172+
173+ # An Important New Note 🐪
174+
175+ ```json
176+ [1,2,3]
177+ ```
178+ EOF
179+ .fi
180+ .RE
181+ .P
182+ .SH SEE ALSO
183+ .P
184+ \fBnote\fR(5)
185+ .P
186+ .SH AUTHORS
187+ .P
188+ Written by Kevin Schoon <kevinschoon@pm.\&me>.\& Source code available at https://github.\&com/kevinschoon/note
189 diff --git a/doc/note.1.scd b/doc/note.1.scd
190new file mode 100644
191index 0000000..a635392
192--- /dev/null
193+++ b/doc/note.1.scd
194 @@ -0,0 +1,64 @@
195+ note(1)
196+
197+ # NAME
198+
199+ note - a simple note taking command line interface
200+
201+ # SYNOPSIS
202+
203+ *note* COMMAND [OPTIONS...]
204+
205+ # DESCRIPTION
206+
207+ *note* is a command line interface for recording notes in the markdown format. It can be
208+ configured to automatically commit modifications to a git repository and even synchronize
209+ changes to a remote host.
210+
211+ # SUBCOMMANDS
212+
213+ ## cat
214+
215+ output one or more notes to stdout
216+
217+ ## config
218+
219+ display the configuration
220+
221+ ## create
222+
223+ create a new note
224+
225+ ## delete
226+
227+ delete an existing note
228+
229+ ## edit
230+
231+ edit an existing note
232+
233+ ## ls
234+
235+ list notes in the database
236+
237+ # EXAMPLES
238+
239+ ## Create a new Note reading from stdin and save it to the state_dir
240+ ```
241+
242+ note create -stdin "Hello World" <<EOF
243+
244+ # An Important New Note 🐪
245+
246+ \```json
247+ [1,2,3]
248+ \```
249+ EOF
250+ ```
251+
252+ # SEE ALSO
253+
254+ *note*(5)
255+
256+ # AUTHORS
257+
258+ Written by Kevin Schoon <kevinschoon@pm.me>. Source code available at https://github.com/kevinschoon/note
259 diff --git a/doc/note.5 b/doc/note.5
260new file mode 100644
261index 0000000..5430ed6
262--- /dev/null
263+++ b/doc/note.5
264 @@ -0,0 +1,63 @@
265+ .\" Generated by scdoc 1.11.0
266+ .\" Complete documentation for this program is not available as a GNU info page
267+ .ie \n(.g .ds Aq \(aq
268+ .el .ds Aq '
269+ .nh
270+ .ad l
271+ .\" Begin generated content:
272+ .TH "note" "5" "2020-09-17"
273+ .P
274+ .SH NAME
275+ .P
276+ note - configuration file and format
277+ .P
278+ .SS The Anatomy of a Note
279+ 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 `---`.\&
280+ .P
281+ .nf
282+ .RS 4
283+ ---
284+ title: This is a Note
285+ tags: [ocaml, programming]
286+ ---
287+
288+ # Hello World!
289+
290+ Today will be a nice day\&.
291+ .fi
292+ .RE
293+ .P
294+ .SS Configuration
295+ .P
296+ The behavior of \fBnote\fR can be configured with yaml file stored in \fB~/.\&config/note/config.\&yaml\fR 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 \fBnote config\fR:
297+ .P
298+ .nf
299+ .RS 4
300+ state_dir: /home/kevin/\&.local/share/note
301+ lock_file: /home/kevin/\&.local/share/note\&.lock
302+ editor: nvim
303+ on_modification: note_commit\&.sh
304+ .fi
305+ .RE
306+ .P
307+ .SS Persisting Notes with Git
308+ .P
309+ 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:
310+ .P
311+ .nf
312+ .RS 4
313+ #!/bin/bash
314+ # This is an example script that can be used in conjunction with the
315+ # on_modification config option to commit every note change to a git
316+ # repository\&. You'll need to place it somewhere on your $PATH\&. This
317+ # script assumes that your state_dir is also a git repository\&.
318+ set -e
319+
320+ STATE_DIR="$(note config -get state_dir)"
321+
322+ pushd "$STATE_DIR"
323+ git add --all
324+ git commit -m 'automated commit'
325+ popd
326+ .fi
327+ .RE
328 diff --git a/doc/note.5.scd b/doc/note.5.scd
329new file mode 100644
330index 0000000..a1dbdd3
331--- /dev/null
332+++ b/doc/note.5.scd
333 @@ -0,0 +1,50 @@
334+ note(5)
335+
336+ # NAME
337+
338+ note - configuration file and format
339+
340+ ## The Anatomy of a Note
341+ 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 `---`.
342+
343+ ```
344+ ---
345+ title: This is a Note
346+ tags: [ocaml, programming]
347+ ---
348+
349+ # Hello World!
350+
351+ Today will be a nice day.
352+ ```
353+
354+ ## Configuration
355+
356+ 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*:
357+
358+ ```
359+ state_dir: /home/kevin/.local/share/note
360+ lock_file: /home/kevin/.local/share/note.lock
361+ editor: nvim
362+ on_modification: note_commit.sh
363+ ```
364+
365+ ## Persisting Notes with Git
366+
367+ 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:
368+
369+ ```
370+ #!/bin/bash
371+ # This is an example script that can be used in conjunction with the
372+ # on_modification config option to commit every note change to a git
373+ # repository. You'll need to place it somewhere on your $PATH. This
374+ # script assumes that your state_dir is also a git repository.
375+ set -e
376+
377+ STATE_DIR="$(note config -get state_dir)"
378+
379+ pushd "$STATE_DIR"
380+ git add --all
381+ git commit -m 'automated commit'
382+ popd
383+ ```
384 diff --git a/doc/note.7 b/doc/note.7
385deleted file mode 100644
386index 093b7ae..0000000
387--- a/doc/note.7
388+++ /dev/null
389 @@ -1,203 +0,0 @@
390- .TH "Note" 7 2020-09-09
391- .SH Note 🐪
392- .LP
393- \f[CR]Note\f[R] is a simple CLI based note taking application.
394- .SS The Anatomy of a Note
395- .LP
396- 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 \f[CR]front-matter\f[R] at the head of each file, which is YAML or JSON enclosed by a pair of \f[CR]---\f[R].
397- .sp 1
398- .nf
399- .ft CR
400- ---
401- title: This is a Note
402- tags: [ocaml, programming]
403- ---
404-
405- # Hello World!
406-
407- Today will be a nice day.
408- .ft
409- .fi
410- .SS Configuration
411- .LP
412- The behavior of \f[CR]note\f[R] can be configured with yaml file stored in \f[CR]\(ti/.config/note/config.yaml\f[R] and configure itself per the XDG Base Directory
413- \f[I]specification\f[R].
414- You can view the resolved configuration by running \f[CR]note config\f[R]:
415- .sp 1
416- .nf
417- .ft CR
418- state_dir: /home/kevin/.local/share/note
419- lock_file: /home/kevin/.local/share/note.lock
420- editor: nvim
421- on_modification: note_commit.sh
422- .ft
423- .fi
424- .SS Structured Data
425- .LP
426- Notes that contain code blocks with structured data as well as front-matter are automatically parsed and exposed via the command API.
427- .SS Example
428- .sp 1
429- .nf
430- .ft CR
431- note create -stdin <<EOF
432-
433- # Musical Styles
434-
435- \(ga\(ga\(gayaml
436- - style: Bomba
437- influenced:
438- - style: Plena
439- - style: Reggaetón
440- influenced:
441- - style: Latin Trap
442- - style: Bachatón
443- \(ga\(ga\(ga
444- EOF
445-
446- # Now let's inspect the code block with jq
447- note cat -encoding json "Musical Styles" | jq .data[0]
448- [
449- {
450- "style": "Bomba",
451- "influenced": [
452- {
453- "style": "Plena"
454- },
455- {
456- "style": "Reggaetón",
457- "influenced": [
458- {
459- "style": "Latin Trap"
460- },
461- {
462- "style": "Bachatón"
463- }
464- ]
465- }
466- ]
467- }
468- ]
469- .ft
470- .fi
471- .SS The State Directory
472- .LP
473- Each note is stored as a flat file inside the \f[CR]state_dir\f[R] with a slug that corresponds to the
474- date (YYYYMMDD) on which it was created. If multiple notes are created on one day, an index will
475- be appended to the file.
476- .sp 1
477- .nf
478- .ft CR
479- $ tree \(ti/.local/share/note/
480- /home/kevin/.local/share/note/
481- ├── note-20200818-1.md
482- ├── note-20200819-1.md
483- ├── note-20200819-2.md
484- └── note-20200819-3.md
485- .ft
486- .fi
487- .SS Persisting Notes with Git
488- .LP
489- If the \f[CR]on_modification\f[R] 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:
490- .sp 1
491- .nf
492- .ft CR
493- #!/bin/bash
494- # This is an example script that can be used in conjunction with the
495- # on_modification config option to commit every note change to a git
496- # repository. You'll need to place it somewhere on your $PATH. This
497- # script assumes that your state_dir is also a git repository.
498- set -e
499-
500- STATE_DIR="$(note config -get state_dir)"
501-
502- pushd "$STATE_DIR"
503- git add --all
504- git commit -m 'automated commit'
505- popd
506- .ft
507- .fi
508- .SS Web UI
509- .LP
510- Notes are stored in a format that is compatible with the static website generator
511- \f[I]Hugo\f[R]
512- and thus you can point your \f[CR]state_dir\f[R] to a Hugo content directory and get a web based interface for all of your notes.
513- .SS Subcommands
514- .SS Cat
515- .LP
516- Write one or more notes to stdout. By default the cat command will write every note to stdout as plain text however the encoding can be adjusted to \f[CR]yaml\f[R] or \f[CR]json\f[R] for consumption by other tools.
517- .SS Examples
518- .sp 1
519- .nf
520- .ft CR
521- # print the parsed content of the fuubar note
522- note cat fuubar
523- # write all commands as a json list
524- note cat -encoding json
525- .ft
526- .fi
527- .SS Config
528- .LP
529- Display the current configuration as inferred by Note. It is also possible to extract specific values by specifying a key value.
530- .SS Examples
531- .sp 1
532- .nf
533- .ft CR
534- # display the current configuration
535- note config
536- # extract a specific value from the configuration
537- note config -get state_dir
538- .ft
539- .fi
540- .SS Create
541- .LP
542- Create a new note and save it to disk in your configured \f[CR]state_dir\f[R]. The \f[CR]on_modification\f[R] call back will be invoked if the file is committed to disk.
543- .SS Examples
544- .sp 1
545- .nf
546- .ft CR
547- # create a new note with the given title and tags
548- note create "Remember The Milk" groceries fuu bar
549- # create a note by reading from stdin
550- note create -stdin <<EOF
551- # My Important Note
552-
553- Hello World!
554- EOF
555- # the title will be inferred from the heading
556- note ls "My Important Note"
557- .ft
558- .fi
559- .SS Delete
560- .LP
561- Delete the first note that matches the filter criteria. The \f[CR]on_modification\f[R] call back will be invoked if the note is deleted.
562- .SS Examples
563- .sp 1
564- .nf
565- .ft CR
566- # delete the note called fuubar
567-
568- note delete fuubar
569- .ft
570- .fi
571- .SS Edit
572- .LP
573- Select a note that matches the filter criteria and open it in your \f[CR]$EDITOR\f[R]. The \f[CR]on_modification\f[R] call back will be invoked if the edited file differs from the original.
574- .SS Examples
575- .sp 1
576- .nf
577- .ft CR
578- # edit the fuubar note
579- note edit fuubar
580- .ft
581- .fi
582- .SS List
583- .LP
584- List notes that match the filter criteria, if no filter criteria is given all notes will be listed
585- .SS Examples
586- .sp 1
587- .nf
588- .ft CR
589- # list all notes
590- note ls
591- .ft
592- .fi
593 diff --git a/scripts/generate_man_page.sh b/scripts/generate_man_page.sh
594index 9d9ce4a..1152438 100755
595--- a/scripts/generate_man_page.sh
596+++ b/scripts/generate_man_page.sh
597 @@ -1,11 +1,5 @@
598 #!/bin/bash
599 set -e
600
601- TEMP_FILE="$(mktemp)"
602-
603- echo "title:Note" >> "$TEMP_FILE"
604- echo "date:$(date +%Y-%m-%d)" >> "$TEMP_FILE"
605- echo >> "$TEMP_FILE"
606- cat README.md >> "$TEMP_FILE"
607-
608- lowdown -sTman "$TEMP_FILE"
609+ scdoc < doc/note.1.scd > doc/note.1
610+ scdoc < doc/note.5.scd > doc/note.5