From a2d6cae82590246e7f77b9bb94d91ee658de5cc5 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Fri, 14 Jun 2019 10:58:43 +0300 Subject: Add: sketch for a jt fable --- jt.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 jt.md (limited to 'jt.md') diff --git a/jt.md b/jt.md new file mode 100644 index 0000000..085c5b5 --- /dev/null +++ b/jt.md @@ -0,0 +1,158 @@ +--- +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 +``` -- cgit v1.2.1