--- title: "Journal Tool (jt) acceptance tests" author: Lars Wirzenius ... Introduction ============================================================================= [ikiwiki]: http://ikiwiki.info/ [markdown]: https://en.wikipedia.org/wiki/Markdown [git]: https://en.wikipedia.org/wiki/Git Journal Tool (jt) is a Unix command line tool for maintaining my personal journal. The journal is rendered into a (private) website using [ikiwiki][], and jt creates files and puts them into version control (git). All jt does is manipulate some files in a git repository. All the insteresting parts of building a useful journal, or personal knowledge base, comes from the user entering information and using ikiwiki constructs to make it accessible. The main constructs I use are blogging, tagging, and categories. The journal is structured as a private blog, where jt allows the user to create new entries as "notes". The notes are collected by ikiwiki into a timeline. Each entry can be assigned arbitrary tags, and ikiwiki constructs a list of entries with each tag. I can also create topic pages for specific categories, e.g., for projects, and again ikiwiki will construct a list of entries in each category. The journal is manipulated as a "source tree", consisting of files in the [markdown][] format. The files are stored in a [git][] repository, for version control, and for sharing between computers. How the source tree is laid out mostly don't matter for jt, except for the following details: * a directory for drafts of new entries ("drafts") * a directory for finished journal entries ("notes") The names of both directories can be configured for jt; the default names are as above. If the directories don't exist, jt will create them as needed. When a new journal is started, the git repository needs to exist, and the user needs to add any category pages, and other structures to it, but jt will help with creating new journal entries and topics. Basic operation ============================================================================= Make the first journal entry ----------------------------------------------------------------------------- We start a new journal and create the first journal entry. The content of the entry don't matter, only that the draft file is created. ```fable given an empty journal when I run jt new "random title" then there is 1 draft and draft 0 has title "random title" and there are no journal entries ``` We have a draft, and at this point we spend some time writing the entry, using the editor that jt starts. When we're done, we tell jt that we're finished with the entry. Note that jt can't rely on the editor exiting to know this, because the editor might be something like emacsclient, which exits at once (after telling a background emacs to open the file), but also because we might decide to back out of writing the journal entry in the first place. ```fable when I run jt finish then there are no drafts and there is 1 journal entry ``` Edit two drafts ----------------------------------------------------------------------------- We can have multiple drafts happening. The jt tool will need to be told which draft to operate on. ```fable given an empty journal when I run jt new "first entry" and I run jt new "second entry" then there are 2 drafts and draft 0 has title "first entry" and draft 1 has title "second entry" when I run jt finish then it fails ``` Drafts can be finished in any order. ```fable when I run jt finish 0 then there is 1 draft and there is 1 journal entry when I run jt finish then there are no drafts and there are 2 journal entries ``` Remove draft ----------------------------------------------------------------------------- We can decide not to finish a draft and remove it instead. Removal always requires specifying the draft. ```fable given an empty journal when I run jt new "random title" then there is 1 draft when I run jt remove then it fails when I run jt remove 0 then there are no drafts ``` Attach a file to a draft ----------------------------------------------------------------------------- It's possible to attach files to drafts, for example images. The attachments will be published with the entry. ```fable given an empty journal and a file pretty.jpg when I run jt new "title" and I run jt attach 0 pretty.jpg then there is 1 draft, with attachment pretty.jpg when I run jt finish then there are no drafts and there is 1 journal entry, with attachment pretty.jpg ``` Create a topic ----------------------------------------------------------------------------- JT can create topic pages as well and mark new entries as belonging to a topic. The topic pages tell ikiwiki collect all entries belonging to the topic. ```fable given an empty journal when I run jt new-topic topics/cats "Kittens" then there there is 1 topic, topics/cats, titled "Kittens" when I run jt new --topic topics/cats "New kitten" and I run jt finish then there is 1 journal entry, belonging to topics/cats ```