Add: sketch for a jt fable

2 files changed, 159 insertions, 0 deletions

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
+```
diff --git a/jt.yaml b/jt.yaml
new file mode 100644
index 0000000..fe51488
--- /dev/null
+++ b/jt.yaml
@@ -0,0 +1 @@
+[]