summaryrefslogtreecommitdiff
path: root/jt.md
blob: 69dc534a0100b08c7373fd68923b15fc6eff7ac1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
---
title: "Journal Tool (jt) acceptance tests"
author: Lars Wirzenius
documentclass: report
abstract: |
  jt is a tool for managing my personal journal and knowlege base. It
  creates and mannipulates files in a git repository. The journal is
  rendered to a website using ikiwiki. This document is the automated
  acceptance test suite for jt.
...

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][]. All jt does is create and 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.

This document forms the automated acceptance test suite for jt.

The journal is structured as a private blog, where jt allows the user
to create new entries. The entries are collected by ikiwiki into a
timeline. Each entry can be assigned arbitrary tags, and ikiwiki
constructs a list of entries with each tag. JT 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 doesn't matter for
jt, except the following subdirectories in the journal must exist:

* a directory for drafts of new entries ("drafts")
* a directory for finished journal entries ("blog")

The names of both directories can be configured for jt. If the
directories don't exist, jt will create them as needed. Further, jt
will put finished entries into a date-based hierarchy. The minimal
tree for jt would look look something like below.

```
path/to/journal/
    .git/
    drafts/
    blog/
        2019/
            06/
                15/
                    my_first_journal_entry.mdwn
```

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 try to 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 try to 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
```