-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathjournalscript.1
180 lines (180 loc) · 4.97 KB
/
journalscript.1
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
176
177
178
179
180
.\" Automatically generated by Pandoc 3.0.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "journalscript" "1" "FEBRUARY 2023" "" "Journalscript Manual"
.hy
.SH NAME
.PP
journalscript - an interactive command line journaling tool.
.SH SYNOPSIS
.PP
journalscript
.PP
journalscript \f[V]COMMAND [ARG...]\f[R]
.PP
journalscript \f[V][--help|-v|--verions]\f[R]
.SH DESCRIPTION
.PP
Journalscript is an interactive journaling tool for the command line.
.PP
It allows users to manage multiple journals, and it organizes them in
directories.
Each directory corresponds to a journal.
Journal entries are stored in journal directories, and each entry is
name as the current date (i.e.\ \f[V]2023-02-14.txt\f[R]).
.PP
Journalscript is highly configurable.
However it requires no configuration upfront; its default behavior is
sufficient and functional.
.SH OPTIONS
.TP
\f[V]-v\f[R], \f[V]--version\f[R]\[rs]
Prints version information and quits.
.TP
\f[V]--help\f[R]\[rs]
Prints usage statement and quits.
.SH COMMANDS
.SS write [journal]
.PP
Writes a new entry to the journal.
If no journal is provided, it writes to the default journal.
Journals are stored as directories and each journal entry is a file in
the journal directory.
Each journal entry corresponds to a day, and their name is formated:
YYYY-mm-dd.
.PP
The command creates new files if they don\[cq]t exists, and it copies a
template into them if template is configured.
Then it launches the configured editor to open the new journal entry (or
an existing one).
Once the user closes the editor, journalscript invokes a backup hook if
any exists.
.SS configure [show|init]
.PP
Assists with the configuration of journalscript.
When configure is invoked with no arguments it defaults to show.
.PP
\f[B]show\f[R]
.PD 0
.P
.PD
.PP
Displays the configuration parameters (also referred as environment
variables) along with its assigned values, and quits.
.PP
\f[B]init\f[R]
.PD 0
.P
.PD
.PP
Launches an interactive wizard that helps the user setting up a
journalscript configuration.
.SH RETURN VALUE
.PP
Returns 1 in case of error.
Otherwise returns 0.
.SH ENVIRONMENT
.TP
JOURNALSCRIPT_FILE_TYPE\[rs]
Sets the file name extension.
Defaults \f[V]txt\f[R]
.TP
JOURNALSCRIPT_EDITOR\[rs]
Sets the editor journalscript uses to open files.
.TP
JOURNALSCRIPT_JOURNAL_DIR\[rs]
The directory where journals will be located.
.TP
JOURNALSCRIPT_TEMPLATE_DIR\[rs]
The directory where journalscript sources templates.
.TP
JOURNALSCRIPT_DEFAULT_JOURNAL\[rs]
When journalscript wire is invoked without arguments, it writes to the
default journal.
Its default value is \f[V]life\f[R]
.SH FILES
.SS Configuration
.PP
Journalscript behavior is customizable with via environment variables
(see ENVIRONMENT).
Additionally, journalscript supports loading variables from a file named
\f[V]journalscript.env\f[R].
So user can either modify the environment or write a
\f[V]journalscript.env\f[R] in order to customize journalscript.
Journalscript looks for \f[V]journalscript.env\f[R] in two locations:
first in \f[V]\[ti]/.config/journalscript/\f[R], then in
\f[V]\[ti]/.journalscript/\f[R], and it only loads variables declared in
the file that are not in the environment.
That is, variables in the environment are not overridden.
.PP
Note: journalscript is not limited to loading journalscript-specific
variables declared in file; any variable in journalscript.env will be
declared.
This makes journalscript.env a suitable place to declare additional
variables used by hooks.
.SS Hooks
.PP
Hooks are bash scripts that Journalscript runs in order to sync and
backup journal entries, and they allow users to customize these two
actions.
There are two types of hooks: sync and backup.
.PP
Sync hook scripts, as the name suggests, synchronizes journal entries
with an externally backedup version of the journal.
It is invoked before editing a journal.
.PP
Backup hook scripts are routines to back up journal entries.
A backup hook is runs after an open hook and once the user closes the
editor.
The default behavior is to do nothing.
.PP
Hooks directory structure
.IP
.nf
\f[C]
<config root>/hooks/
|----- sync.d/ # stores editor specific hooks
|----- sync # default sync hook
|----- backup.d/ # stores backup tool specific hooks
|----- backup # default backup hook
\f[R]
.fi
.PP
Journalscript runs only 1 sync hook, and it searches for it in these
locations in order:
.PD 0
.P
.PD
.IP "1." 3
A hook specified by JOURNALSCRIPT_SYNC_BACKUP env var.
.PD 0
.P
.PD
.IP "2." 3
The default hook \f[V]<configuration/dir>/hooks/backup\f[R]
.PP
Journalscript runs only 1 backup hook, and it searches for it in these
locations in order:
.PD 0
.P
.PD
.IP "1." 3
A hook specified by JOURNALSCRIPT_SYNC_BACKUP env var.
.PD 0
.P
.PD
.IP "2." 3
The default hook \f[V]<configuration/dir>/hooks/backup\f[R]