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
|
# Introduction
The **jt** software (short for "journalling tool") is a helper for
maintaining a journal or personal knowledge base. It has been written
for the personal use of its authors, but might be useful for others.
The guiding principle for jt is that having longevity for one's data
and complete control over it are crucial. Because of these, the
approach taken by jt is to build a static web site from source files
stored in a version control system. The files will be edited with a
text editor chosen by the journal writer, rather than via a custom
web, desktop, or mobile application. The built journal is then served
with some suitable web server.
The role of jt is to make it easier to create new journal entries (new
Markdown files), and to make all the common tasks of maintaining a
knowledge base have minimal friction.
## Example
The following example creates a new journal, which will be the default
journal for the user, and a new journal entry. The entry is a draft
until it's finished.
~~~sh
$ jt init ~/Journal default "My private journal"
$ jt new --tag meta --tag journalling "My first journal entry"
... # text editor is opened so the new entry can be written
$ jt finish
~~~
# Acceptance criteria and their verification
This chapter defines detailed acceptance criteria and how they're
verified using *scenarios* for the [Subplot][] tool.
[Subplot]: https://subplot.liw.fi/
## Create a new local journal repository
`jt` works on a local repository, and it can be created an initialised
using the tool.
~~~scenario
when I invoke jt init jrnl default "My test journal"
then command is successful
and directory jrnl exists
when I invoke jt is-journal jrnl
then command is successful
when I invoke jt is-journal bogus
then command fails
~~~
## Create a new draft, edit it, then publish it
Verify that we can create a new draft entry for the journal.
~~~scenario
when I invoke jt init jrnl default "My test journal"
then command is successful
and there are no drafts in jrnl
and there are no journal entries in jrnl
when I invoke jt new "Abracadabra" --editor=none --dirname=jrnl
then command is successful
and there is one draft in jrnl
and draft 0 in jrnl contains "Abracadabra"
given an executable script append.sh
when I invoke jt edit --editor=./append.sh --dirname=jrnl
then command is successful
and draft 0 in jrnl contains "Open sesame!"
when I invoke jt finish --dirname=jrnl
then command is successful
and there is one journal entry in jrnl, at FILE
and file <FILE> contains "Abracadabra"
and file <FILE> contains "Open sesame!"
and there are no drafts in jrnl
~~~
~~~{#append.sh .file .numberLines}
#!/bin/sh
set -eux
echo "Open sesame!" >> "$1"
~~~
---
title: "jt—a journalling tool"
author:
- Lars Wirzenius
- Daniel Silverstone
bindings:
- subplot/jt.yaml
- subplot/runcmd.yaml
functions:
- subplot/jt.py
- subplot/runcmd.py
...
|
