From 8fa52e443773e386bfd2e2f78a561c07ed94772c Mon Sep 17 00:00:00 2001 From: Marc Coquand Date: Thu, 16 May 2024 10:30:03 -0500 Subject: Update docs --- README.org | 81 +++++++++------------------------------------------- bin/main.ml | 84 +++++++++++++++++++++++++++++++++++++++++++++++++----- lib/help_screen.ml | 2 +- 3 files changed, 92 insertions(+), 75 deletions(-) diff --git a/README.org b/README.org index 2822000..1c7e045 100644 --- a/README.org +++ b/README.org @@ -1,50 +1,31 @@ * Stitch - Note Composer -Stitch is a minimal grep-based CLI tool for composing notes. It is -built around the idea of writing notes separately and then using tags -to compose these notes together. +Stitch is a minimal grep-based CLI tool for composing and viewing notes and +TODO notes. It is built around the idea of writing notes separately and +then using tags to compose these notes together. Stitch does not have any opinion about which file format you use for file capturing, use org, markdown, whatever you want. You can also customize the grep command to speed up performance. -Stitch tries to have few dependencies, and stick only to coreutils by -default - -Stitch limits itself only to note composing. For capturing notes, you -will have to set up your own system. - -** AIMS +** FEATURES - Single binary -- Minimal +- Minimal & fast +- UNIXy - Work with any file format ** CREDIT -Stitch is based and largely a stripped down copy of the note composing -system of Howm for Emacs. - -** INSTALLATION - -Chmod +x the binary and put in PATH. +Stitch is based on the note composing system Howm for Emacs. -Set the environment variables: +** USAGE -STICH_DIRECTORY -STICH_GREP_CMD (default "grep") -STITCH_HEADLINE_PATTERN_REGEXP (default "^\\* ") -STITCH_HEADLINE_PATTERN (default "* ") -STITCH_TAG_PATTERN (default ":[a-z-]+:", matches :a-tag:) -STITCH_TODO (default "* TODO") -STITCH_TODO_REGEXP (default "^\\* TODO") -STITCH_DONE (default "* DONE") -STITCH_DONE_REGEXP (default "^\\* DONE") +Run ~stitch --help~ or ~man stitch~ for explanation and how to get started -** SPEED UP +** INSTALLATION -Stitch uses grep by default. As your notes grow, this will -become rather slow. To speed it up, you can replace it grep with ugrep. +Chmod +x the binary and put in PATH. ** DEVELOPMENT @@ -57,33 +38,9 @@ And to run: dune exec -- stitch +To generate man pages, run -** RECIPES - -- Building a journaling system -You can build a basic capture command using $EDITOR and date command: - -#+begin_src sh -export STITCH_DIRECTORY=/home/me/notes -function capture { - JRNL="$STITCH_DIRECTORY/$(date +'%y-%m-%d.%H:%M.%S').org" - echo '* :journal:' >> $JRNL - $EDITOR "$JRNL" +1:3 -} - -function todo { - JRNL="$STITCH_DIRECTORY/$(date +'%y-%m-%d.%H:%M.%S').org" - echo '* TODO ' >> $JRNL - kak "$JRNL" +1:8 -e "execute-keys i" -} - -alias jrnl='stitch -t :journal:' -#+end_src - -and then you can find your journal entries, automatically sorted by -creation date with stitch and the journal tag: - -alias jrnl="stitch -t journal" +dune exec -- stitch --help=groff * KNOWN ISSUES @@ -94,16 +51,6 @@ alias jrnl="stitch -t journal" One solution is to force one uniform file name that we can regexp (and also tweak). I am not sure yet what's best. - - * Author -Marc Coquand, 2024 - -* LICENSE - -BSD-3-Clause - - - - +Marc Coquand (https://mccd.space) diff --git a/bin/main.ml b/bin/main.ml index cda58ca..1708f13 100644 --- a/bin/main.ml +++ b/bin/main.ml @@ -8,7 +8,7 @@ let tag_arg = let headlines_t = Term.(const Stitch.start $ tag_arg $ const ()) let envs = - let docs = "ENVIRONMENT VARIABLES" in + let docs = Cmdliner.Manpage.s_environment in [ Cmd.Env.info ~docs ~doc: @@ -29,7 +29,7 @@ let envs = ~docs ~doc: "Pattern to use by grep to fetch headlines. Needs to be double escaped for \ - OCaml. (Default \"^\\* \")" + OCaml. (Default \"^\\\\* \")" "STITCH_HEADLINE_PATTERN_REGEXP" ; Cmd.Env.info ~docs @@ -43,7 +43,7 @@ let envs = ~docs ~doc: "Regexp used by grep to find TODO items. Needs to be double escaped for OCaml. \ - (Default \"^\\* TODO\")" + (Default \"^\\\\* TODO\")" "STITCH_TODO_REGEXP" ; Cmd.Env.info ~docs @@ -53,15 +53,85 @@ let envs = ~docs ~doc: "Regexp used by grep to find DONE items. Needs to be double escaped for OCaml. \ - (Default \"^\\* DONE\")" + (Default \"^\\\\* DONE\")" "STITCH_DONE_REGEXP" ] let headlines_cmd = - let doc = "Show titles in a condensed list" in - let man = [ `S Manpage.s_bugs; `P "Email bug reports to marc@mccd.space" ] in - let info = Cmd.info ~envs "headlines" ~version:"0.1" ~doc ~man in + let doc = "write notes seperately and compose" in + let author = [ `S Manpage.s_authors; `P "Marc Coquand (mccd.space)" ] in + let bugs = [ `S Manpage.s_bugs; `P "Email bug reports to marc@mccd.space" ] in + let description = + [ `S Manpage.s_description + ; `P + "Stitch is a minimal note and todo composing tool inspired by Howm for Emacs. It \ + works with any CLI editor and file format." + ; `P + "Stitch comes preconfigured to handle an org-esque file format, but can be \ + reconfigured to handle any file format you want (SEE ENVIRONMENT). " + ; `P + "To set up, you will need to set STITCH_DIRECTORY (SEE ENVIRONMENT) at minimum. \ + Stitch does not come with any built-in note-capturing tool, but you can easily \ + set one up on your own (SEE EXAMPLES)." + ; `P + "When you enter the program for the first time, press '?' to see the list of \ + keybindings." + ] + in + let example_set_up_basic = + [ `S Manpage.s_examples + ; `P "To get started, start by setting up a note directory in your shell profile" + ; `Pre "export STITCH_DIRECTORY=/home/bob/notes" + ; `P + "Stitch does not specify anything on how to capture your notes, but you can add \ + the following in your profile to have a basic note capture command" + ; `Pre + "function capture {\n\ + \ NEW_NOTE=\"\\$STITCH_DIRECTORY/\\$(date +'%y-%m-%d.%H:%M.%S').org\"\n\ + \ echo '* ' >> \\$NEW_NOTE \n\ + \ \\$EDITOR \"\\$NEW_NOTE\" +1:3 \"\n\ + }\n" + ; `P + "With that, you can begin to capture your notes and they will be displayed in \ + reverse chronological order in stitch. You can add tags, for example :journal: \ + and :work:." + ; `P + "Once added, you can start viewing your notes in Stitch. So if you added a few \ + journal notes, you can view them with" + ; `Pre "stitch -t :journal:" + ; `P + "If you press s, you will see toggle to see all notes stitched together. You can \ + see all commands with '?'" + ; `P "You can also launch stitch without arguments to see all." + ; `P + "To set up TODO capturing, you can add a command to your shell profile to \ + capture TODO items" + ; `Pre + "function todo {\n\ + \ NEW_NOTE=\"\\$STITCH_DIRECTORY/\\$(date +'%y-%m-%d.%H:%M.%S').org\"\n\ + \ echo '* TODO ' >> \\$NEW_NOTE \n\ + \ \\$EDITOR \"\\$NEW_NOTE\" +1 \n\ + }" + ; `P + "After that, you can capture a few TODO items, and you will be able to view them \ + if you press 2. You can see done items if you press 3. Press '?' to see how to \ + toggle the todo items." + ] + in + let credit = + [ `S "CREDIT" + ; `P "Stitch was inspired by the note-taking tool Howm for EMacs by HIRAOKA Kazuyuki." + ] + in + let info = + Cmd.info + ~envs + "stitch" + ~version:"0.1 ALPHA" + ~doc + ~man:(List.concat [ bugs; author; description; example_set_up_basic; credit ]) + in Cmd.v info headlines_t diff --git a/lib/help_screen.ml b/lib/help_screen.ml index 637b65a..4dc527e 100644 --- a/lib/help_screen.ml +++ b/lib/help_screen.ml @@ -29,7 +29,7 @@ let general_help_menu = ; "Note View", "1" ; "Todo View", "2" ; "Done View", "3" - ; "Edit File", "Enter, e" + ; "Edit File in $EDITOR", "Enter, e" ] -- cgit v1.2.3