summaryrefslogtreecommitdiff
path: root/jt.md
blob: 085c5b57b38103a97e990eb597c2c6606011d77b (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
---
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
```