Author: Kevin Schoon [kevinschoon@gmail.com]
Hash: 7a86468363baf46b25a263eb70dad7f85e7781e4
Timestamp: Tue, 02 Feb 2021 16:11:51 +0000 (3 years ago)

+313 -233 +/-15 browse
clean up docs
1diff --git a/.gitignore b/.gitignore
2index 7bcace9..a7d7ca9 100644
3--- a/.gitignore
4+++ b/.gitignore
5 @@ -1,2 +1,4 @@
6 .merlin
7 _build/
8+ doc/*
9+ !doc/*.scd
10 diff --git a/Makefile b/Makefile
11new file mode 100644
12index 0000000..ca5cfbe
13--- /dev/null
14+++ b/Makefile
15 @@ -0,0 +1,46 @@
16+ .PHONY: clean clean-docs docs
17+
18+ default:
19+ true
20+
21+ clean: clean-docs
22+
23+ clean-docs:
24+ find doc -type f -not -name '*.scd' -delete
25+
26+ docs: \
27+ doc/note.1 \
28+ doc/note.5 \
29+ doc/note-cat.1 \
30+ doc/note-config.1 \
31+ doc/note-create.1 \
32+ doc/note-edit.1 \
33+ doc/note-ls.1 \
34+ doc/note-sync.1
35+
36+ doc/note.1: doc/note.1.scd
37+ scdoc < $< > $@
38+
39+ doc/note.5: doc/note.5.scd
40+ scdoc < $< > $@
41+
42+ doc/note-cat.1: doc/note-cat.1.scd
43+ scdoc < $< > $@
44+
45+ doc/note-config.1: doc/note-config.1.scd
46+ scdoc < $< > $@
47+
48+ doc/note-create.1: doc/note-create.1.scd
49+ scdoc < $< > $@
50+
51+ doc/note-delete.1: doc/note-delete.1.scd
52+ scdoc < $< > $@
53+
54+ doc/note-edit.1: doc/note-edit.1.scd
55+ scdoc < $< > $@
56+
57+ doc/note-ls.1: doc/note-ls.1.scd
58+ scdoc < $< > $@
59+
60+ doc/note-sync.1: doc/note-sync.1.scd
61+ scdoc < $< > $@
62 diff --git a/doc/note-cat.1.scd b/doc/note-cat.1.scd
63new file mode 100644
64index 0000000..7c16ed2
65--- /dev/null
66+++ b/doc/note-cat.1.scd
67 @@ -0,0 +1,38 @@
68+ note-cat(1)
69+
70+ # NAME
71+
72+ note-cat - write notes to stdout
73+
74+ # SYNOPSIS
75+
76+ note cat [options] [FILTER ...]
77+
78+ # DESCRIPTION
79+
80+ Write one or more notes to stdout. By default the cat command will write every
81+ note to stdout as plain text however the encoding can be adjusted to yaml or
82+ json for consumption by other tools.
83+
84+ # OPTIONS
85+
86+ *positional arguments*
87+
88+ *FILTER*
89+ tag or text based search terms
90+
91+ *optional arguments*
92+
93+ *-encoding*
94+ specify the output encoding
95+
96+ *-fulltext*
97+ perform full text search instead of key comparision
98+
99+ # EXAMPLES
100+ ```
101+ # print the parsed content of the fuubar note
102+ note cat fuubar
103+ # write all commands as a json list
104+ note cat -encoding json
105+ ```
106 diff --git a/doc/note-config.1.scd b/doc/note-config.1.scd
107new file mode 100644
108index 0000000..69d1198
109--- /dev/null
110+++ b/doc/note-config.1.scd
111 @@ -0,0 +1,34 @@
112+ note-config(1)
113+
114+ # NAME
115+
116+ note-config - configuration management
117+
118+ # SYNOPSIS
119+
120+ note config [get | set | show]
121+
122+ # DESCRIPTION
123+
124+ Modify the note configuration file
125+
126+ # OPTIONS
127+
128+ *positional arguments*
129+
130+ *get*
131+ get a certain configuration value
132+
133+ *set*
134+ set a certain configuration value
135+
136+ *show*
137+ show all of the configuration with defaults
138+
139+
140+ # EXAMPLES
141+
142+ ```
143+ # show the configured state directory
144+ note config get state_dir
145+ ```
146 diff --git a/doc/note-create.1.scd b/doc/note-create.1.scd
147new file mode 100644
148index 0000000..41482db
149--- /dev/null
150+++ b/doc/note-create.1.scd
151 @@ -0,0 +1,42 @@
152+ note-create(1)
153+
154+ # NAME
155+
156+ note-create - Create a New Note
157+
158+ # SYNOPSIS
159+
160+ note create [options] TITLE [TAG ...]
161+
162+ # DESCRIPTION
163+
164+ Create a new note and save it to disk in your configured state_dir. The
165+ on_modification callback will be invoked if the file is committed to disk.
166+
167+ # OPTIONS
168+
169+ *positional arguments*
170+
171+ *TITLE*
172+ name of the new note
173+ *TAG*
174+ string based tags
175+
176+ *optional arguments*
177+
178+ *-stdin*
179+ read content from stdin and copy it into the note body
180+
181+ # EXAMPLES
182+ ```
183+ # create a new note with the given title and tags
184+ note create "Remember The Milk" groceries fuu bar
185+ # create a note by reading from stdin
186+ note create -stdin <<EOF
187+ # My Important Note
188+
189+ Hello World!
190+ EOF
191+ # the title will be inferred from the heading
192+ note ls "My Important Note"
193+ ```
194 diff --git a/doc/note-delete.1.scd b/doc/note-delete.1.scd
195new file mode 100644
196index 0000000..d526886
197--- /dev/null
198+++ b/doc/note-delete.1.scd
199 @@ -0,0 +1,31 @@
200+ note-delete(1)
201+
202+ # NAME
203+
204+ note-delete - delete one or more notes
205+
206+ # SYNOPSIS
207+
208+ note delete [options] [FILTER ...]
209+
210+ # DESCRIPTION
211+
212+ Delete one or more notes that match the filter criteria.
213+
214+ # OPTIONS
215+
216+ *positional arguments*
217+
218+ *FILTER*
219+ tag or text based search terms
220+
221+ *optional arguments*
222+
223+ *-fulltext*
224+ perform full text search instead of key comparision
225+
226+ # EXAMPLES
227+ ```
228+ # delete a note called fuubar
229+ note delete fuubar
230+ ```
231 diff --git a/doc/note-edit.1.scd b/doc/note-edit.1.scd
232new file mode 100644
233index 0000000..f86b349
234--- /dev/null
235+++ b/doc/note-edit.1.scd
236 @@ -0,0 +1,31 @@
237+ note-edit(1)
238+
239+ # NAME
240+
241+ note-edit - open a note in your text editor
242+
243+ # SYNOPSIS
244+
245+ note edit [options] [FILTER ...]
246+
247+ # DESCRIPTION
248+
249+ Select a note that matches the filter criteria and open it in your text editor.
250+
251+ # OPTIONS
252+
253+ *positional arguments*
254+
255+ *FILTER*
256+ tag or text based search terms
257+
258+ *optional arguments*
259+
260+ *-fulltext*
261+ perform full text search instead of key comparision
262+
263+ # EXAMPLES
264+ ```
265+ # edit a note called fuubar
266+ note edit fuubar
267+ ```
268 diff --git a/doc/note-ls.1.scd b/doc/note-ls.1.scd
269new file mode 100644
270index 0000000..208bea1
271--- /dev/null
272+++ b/doc/note-ls.1.scd
273 @@ -0,0 +1,38 @@
274+ note-ls(1)
275+
276+ # NAME
277+
278+ note-ls - list notes
279+
280+ # SYNOPSIS
281+
282+ note ls [options] [FILTER ...]
283+
284+ # DESCRIPTION
285+
286+ List one or more notes that match the filter criteria, if no filter criteria
287+ is provided then all notes will be listed.
288+
289+ # OPTIONS
290+
291+ *positional arguments*
292+
293+ *FILTER*
294+ tag or text based search terms
295+
296+ *optional arguments*
297+
298+ *-columns*
299+ columns to show in the note list
300+
301+ *-fulltext*
302+ perform full text search instead of key comparision
303+
304+ *-style*
305+ list style [fixed | wide | simple]
306+
307+ # EXAMPLES
308+ ```
309+ # list notes
310+ note ls
311+ ```
312 diff --git a/doc/note-sync.1.scd b/doc/note-sync.1.scd
313new file mode 100644
314index 0000000..19859b8
315--- /dev/null
316+++ b/doc/note-sync.1.scd
317 @@ -0,0 +1,26 @@
318+ note-sync(1)
319+
320+ # NAME
321+
322+ note-sync - sync notes to a remote server
323+
324+ # SYNOPSIS
325+
326+ note sync [options]
327+
328+ # DESCRIPTION
329+
330+ Synchronize notes to a remote server. This command requires that the on_sync
331+ config option to be set.
332+
333+ # OPTIONS
334+
335+ *positional arguments*
336+
337+ *optional arguments*
338+
339+ # EXAMPLES
340+ ```
341+ # synchronize notes1
342+ note sync
343+ ```
344 diff --git a/doc/note.1 b/doc/note.1
345deleted file mode 100644
346index ed2edce..0000000
347--- a/doc/note.1
348+++ /dev/null
349 @@ -1,73 +0,0 @@
350- .\" Generated by scdoc 1.11.0
351- .\" Complete documentation for this program is not available as a GNU info page
352- .ie \n(.g .ds Aq \(aq
353- .el .ds Aq '
354- .nh
355- .ad l
356- .\" Begin generated content:
357- .TH "note" "1" "2020-09-17"
358- .P
359- .SH NAME
360- .P
361- note - a simple note taking command line interface
362- .P
363- .SH SYNOPSIS
364- .P
365- \fBnote\fR COMMAND [OPTIONS.\&.\&.\&]
366- .P
367- .SH DESCRIPTION
368- .P
369- \fBnote\fR is a command line interface for recording notes in the markdown format.\& It can be
370- configured to automatically commit modifications to a git repository and even synchronize
371- changes to a remote host.\&
372- .P
373- .SH SUBCOMMANDS
374- .P
375- .SS cat
376- .P
377- output one or more notes to stdout
378- .P
379- .SS config
380- .P
381- display the configuration
382- .P
383- .SS create
384- .P
385- create a new note
386- .P
387- .SS delete
388- .P
389- delete an existing note
390- .P
391- .SS edit
392- .P
393- edit an existing note
394- .P
395- .SS ls
396- .P
397- list notes in the database
398- .P
399- .SH EXAMPLES
400- .P
401- .SS Create a new Note reading from stdin and save it to the state_dir
402- .nf
403- .RS 4
404-
405- note create -stdin "Hello World" <<EOF
406-
407- # An Important New Note 🐪
408-
409- ```json
410- [1,2,3]
411- ```
412- EOF
413- .fi
414- .RE
415- .P
416- .SH SEE ALSO
417- .P
418- \fBnote\fR(5)
419- .P
420- .SH AUTHORS
421- .P
422- Written by Kevin Schoon <kevinschoon@pm.\&me>.\& Source code available at https://github.\&com/kevinschoon/note
423 diff --git a/doc/note.1.scd b/doc/note.1.scd
424index a635392..5fc98f3 100644
425--- a/doc/note.1.scd
426+++ b/doc/note.1.scd
427 @@ -2,7 +2,7 @@ note(1)
428
429 # NAME
430
431- note - a simple note taking command line interface
432+ *Note* is a simple CLI based note taking application
433
434 # SYNOPSIS
435
436 @@ -10,35 +10,15 @@ note - a simple note taking command line interface
437
438 # DESCRIPTION
439
440- *note* is a command line interface for recording notes in the markdown format. It can be
441- configured to automatically commit modifications to a git repository and even synchronize
442- changes to a remote host.
443+ *note* is a command line interface for recording notes in the markdown format.
444+ It maintains a directory of plain text files with a preamble of structured
445+ data for indexing, reference, and additional functionality.
446
447- # SUBCOMMANDS
448+ # SYNCHRONIZING
449
450- ## cat
451-
452- output one or more notes to stdout
453-
454- ## config
455-
456- display the configuration
457-
458- ## create
459-
460- create a new note
461-
462- ## delete
463-
464- delete an existing note
465-
466- ## edit
467-
468- edit an existing note
469-
470- ## ls
471-
472- list notes in the database
473+ Synchronization can be accomplished by writing shell scripts that are invoked
474+ by the *note* program. Note is shipped with some example scripts that you can
475+ find with your package manager.
476
477 # EXAMPLES
478
479 @@ -55,10 +35,14 @@ note create -stdin "Hello World" <<EOF
480 EOF
481 ```
482
483+ note cat "Hello World" | jq '.data[0] | add'
484+ 14
485+
486 # SEE ALSO
487
488 *note*(5)
489
490 # AUTHORS
491
492- Written by Kevin Schoon <kevinschoon@pm.me>. Source code available at https://github.com/kevinschoon/note
493+ Written by Kevin Schoon <kevinschoon@pm.me>.
494+ Source code available at https://github.com/kevinschoon/note
495 diff --git a/doc/note.5 b/doc/note.5
496deleted file mode 100644
497index 01dad4a..0000000
498--- a/doc/note.5
499+++ /dev/null
500 @@ -1,80 +0,0 @@
501- .\" Generated by scdoc 1.11.0
502- .\" Complete documentation for this program is not available as a GNU info page
503- .ie \n(.g .ds Aq \(aq
504- .el .ds Aq '
505- .nh
506- .ad l
507- .\" Begin generated content:
508- .TH "note" "5" "2020-09-17"
509- .P
510- .SH NAME
511- .P
512- note - configuration file and format
513- .P
514- .SS The Anatomy of a Note
515- 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 `---`.\&
516- .P
517- .nf
518- .RS 4
519- ---
520- title: This is a Note
521- tags: [ocaml, programming]
522- ---
523-
524- # Hello World!
525-
526- Today will be a nice day\&.
527- .fi
528- .RE
529- .P
530- .SS The State Directory
531- .P
532- Each note is stored as a flat file inside the `state_dir` with a slug that corresponds to the
533- date (YYYYMMDD) on which it was created.\& If multiple notes are created on one day, an index will
534- be appended to the file.\&
535- .P
536- .nf
537- .RS 4
538- $ tree ~/\&.local/share/note/
539- /home/kevin/\&.local/share/note/
540- ├── note-20200818-1\&.md
541- ├── note-20200819-1\&.md
542- ├── note-20200819-2\&.md
543- └── note-20200819-3\&.md
544- .fi
545- .RE
546- .P
547- .SS Configuration
548- .P
549- 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:
550- .P
551- .nf
552- .RS 4
553- state_dir: /home/kevin/\&.local/share/note
554- lock_file: /home/kevin/\&.local/share/note\&.lock
555- editor: nvim
556- on_modification: note_commit\&.sh
557- .fi
558- .RE
559- .P
560- .SS Persisting Notes with Git
561- .P
562- 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:
563- .P
564- .nf
565- .RS 4
566- #!/bin/bash
567- # This is an example script that can be used in conjunction with the
568- # on_modification config option to commit every note change to a git
569- # repository\&. You'll need to place it somewhere on your $PATH\&. This
570- # script assumes that your state_dir is also a git repository\&.
571- set -e
572-
573- STATE_DIR="$(note config -get state_dir)"
574-
575- pushd "$STATE_DIR"
576- git add --all
577- git commit -m 'automated commit'
578- popd
579- .fi
580- .RE
581 diff --git a/doc/note.5.scd b/doc/note.5.scd
582index 14b2243..7bef94f 100644
583--- a/doc/note.5.scd
584+++ b/doc/note.5.scd
585 @@ -10,6 +10,7 @@ A note is a simple markdown document that contains zero or more instances of str
586 ```
587 ---
588 title: This is a Note
589+ description: ""
590 tags: [ocaml, programming]
591 ---
592
593 diff --git a/lib/cmd.ml b/lib/cmd.ml
594index 8d4c083..f92e065 100644
595--- a/lib/cmd.ml
596+++ b/lib/cmd.ml
597 @@ -36,19 +36,12 @@ let key_arg =
598
599 let cat_note =
600 let open Command.Let_syntax in
601- Command.basic ~summary:"write a note to stdout"
602+ Command.basic ~summary:"write notes to stdout"
603 ~readme:(fun () ->
604 {|
605- Write one or more notes to stdout. By default the cat command will write every note
606- to stdout as plain text however the encoding can be adjusted to `yaml` or `json`
607- for consumption by other tools.
608-
609- Examples:
610-
611- # print the parsed content of the fuubar note
612- note cat fuubar
613- # write all commands as a json list
614- note cat -encoding json
615+ Write one or more notes to stdout. By default the cat command will write every
616+ note to stdout as plain text however the encoding can be adjusted to yaml or
617+ json for consumption by other tools.
618 |})
619 [%map_open
620 let filter_args = anon (sequence ("filter" %: filter_arg))
621 @@ -99,21 +92,8 @@ let create_note =
622 Command.basic ~summary:"create a new note"
623 ~readme:(fun () ->
624 {|
625- Create a new note and save it to disk in your configured `state_dir`.
626- The `on_modification` call back will be invoked if the file is committed to disk.
627-
628- Examples:
629-
630- # create a new note with the given title and tags
631- note create "Remember The Milk" groceries fuu bar
632- # create a note by reading from stdin
633- note create -stdin <<EOF
634- # My Important Note
635-
636- Hello World!
637- EOF
638- # the title will be inferred from the heading
639- note ls "My Important Note"
640+ Create a new note and save it to disk in your configured state_dir. The
641+ on_modification callback will be invoked if the file is committed to disk.
642 |})
643 [%map_open
644 let open_stdin =
645 @@ -145,12 +125,7 @@ let delete_note =
646 Command.basic ~summary:"delete an existing note"
647 ~readme:(fun () ->
648 {|
649- Delete the first note that matches the filter criteria. The `on_modification` call back will be invoked if the note is deleted.
650-
651- Examples
652-
653- # delete the note called fuubar
654- note delete fuubar
655+ Delete the first note that matches the filter criteria.
656 |})
657 [%map_open
658 let filter_args = anon (sequence ("filter" %: filter_arg))
659 @@ -176,13 +151,8 @@ let edit_note =
660 let open Command.Let_syntax in
661 Command.basic ~summary:"edit an existing note"
662 ~readme:(fun () ->
663- {|
664- 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.
665-
666- Examples
667-
668- # edit the fuubar note
669- note edit fuubar
670+ {|
671+ Select a note that matches the filter criteria and open it in your text editor.
672 |})
673 [%map_open
674 let filter_args = anon (sequence ("filter" %: filter_arg))
675 @@ -209,13 +179,8 @@ let list_notes =
676 Command.basic ~summary:"list existing notes"
677 ~readme:(fun () ->
678 {|
679- List notes that match the filter criteria, if no filter criteria is given all notes will be listed
680-
681- Examples
682-
683- # list all notes
684- note ls
685- ```
686+ List one or more notes that match the filter criteria, if no filter criteria
687+ is provided then all notes will be listed.
688 |})
689 [%map_open
690 let filter_args = anon (sequence ("filter" %: filter_arg))
691 diff --git a/scripts/generate_man_page.sh b/scripts/generate_man_page.sh
692deleted file mode 100755
693index 1152438..0000000
694--- a/scripts/generate_man_page.sh
695+++ /dev/null
696 @@ -1,5 +0,0 @@
697- #!/bin/bash
698- set -e
699-
700- scdoc < doc/note.1.scd > doc/note.1
701- scdoc < doc/note.5.scd > doc/note.5