jt.md


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

# 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 and 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
then there is one draft in jrnl
and draft 0 in jrnl contains "Abracadabra"

when I edit draft 0 in jrnl to also contain "Behold!"
and I invoke jt finish --dirname=jrnl
then command is successful
then there is one journal entry in jrnl, at FILE
and file <FILE> contains "Abracadabra"
and file <FILE> contains "Behold!"
and there are no drafts in jrnl
~~~


---
title: "jt&mdash;a journalling tool"
author:
- Lars Wirzenius
- Daniel Silverstone
bindings:
- subplot/jt.yaml
- subplot/runcmd.yaml
functions:
- subplot/jt.py
- subplot/runcmd.py
...