aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAkshay <[email protected]>2021-01-26 15:29:03 +0000
committerAkshay <[email protected]>2021-01-26 15:29:03 +0000
commit2cb819bdcbb98a64ef7cbededc0de8168312c7ea (patch)
treebd3129a43403eeaa70d42e21f9344e0aa63bbad8
parentf4de2e0219ef2ce96cd30c02eee18eedd22b556a (diff)
parent0dcb7a8c81cbc75eb86f76211d44b79145cd1bd1 (diff)
Merge branch 'doc/man-pages' into master
-rw-r--r--dijo.1479
1 files changed, 479 insertions, 0 deletions
diff --git a/dijo.1 b/dijo.1
new file mode 100644
index 0000000..7664416
--- /dev/null
+++ b/dijo.1
@@ -0,0 +1,479 @@
1.TH DIJO 1 "January 26, 2021" dijo-0.2.3
2
3.SH NAME
4dijo \- digital journal
5
6.SH SYNOPSIS
7.B dijo
8[\fBFLAGS\fR]
9[\fBOPTIONS\fR]
10
11.SH DESCRIPTION
12.B dijo
13is scriptable, curses-based and modal, much like \fIvim\fR, digital habit tracker
14
15.SH FLAGS
16.TP
17.BR \-h ", " \-\-help
18Prints help information
19.TP
20.BR \-l ", " \-\-list
21List dijo habits
22.TP
23.BR \-V ", " \-\-version
24Prints version information
25
26.SH OPTIONS
27.TP
28.BR \-c ", " \-\-command " " \fIcommand
29Run a dijo command
30
31.SH FEATURES
32.TP
33\(bu \fBvim like motions\fR
34Navigate with \fBhjkl\fR!
35.TP
36\(bu \fBdijo is modal\fR
37Different modes to view different stats!
38.TP
39\(bu \fBvim like command mode\fR
40Add with \fB:add\fR, delete with \fB:delete\fR and above all, quit with \fB:q!\fR.
41.TP
42\(bu \fBFully scriptable\fR
43You can configure it to track your \fIgit\fR commits!
44
45.SH GETTING STARTED
46.PP
47On running \fBdijo\fR at the command line, you are presented with a blank screen. This is the \fBDAY\fR mode, analogous to the \fBNORMAL\fR mode in Vim. In this mode, you may view stats for every day of the current month.
48.PP
49To start tracking habits, enter the command mode with \fB:.\fR Use the add command to add a habit to begin tracking.
50.TP
51Say, I would like to track the number of French lessons I took on Duolingo, and I aim to do 5 lessons each day:
52.nf
53\fB
54:add french 5
55 | |
56 `-----|----- habit name
57 `---- goal (optional)
58\fR
59.fi
60.TP
61Go ahead and add a couple more habits the same way:
62.nf
63\fB
64:add lifting 1 <-- a yes/no kind of habit (represented by a dot grid)
65:add water <-- no goal provided
66\fR
67.fi
68.PP
69To track your progress for the day:
70.IP
71\(bu focus the habit you want to track, (the focused habit is highlighted in bright white).
72.IP
73\(bu Hit \fBEnter\fR on the keyboard to increase the value, or \fBBackspace\fR to reduce it.
74.IP
75\(bu Once you reach your daily goal, the day is marked in green and the habit name is struck through with a line.
76.PP
77Check your weekly progress for a given habit by pressing \fBv\fR on the keyboard, this is \fBWEEK\fR mode, and press \fB<ESC>\fR to go back to \fBDAY\fR mode. \fB<Shift-v>\fR is a shortcut to display weekly progress for every habit. The current mode is indicated on the status line.
78.PP
79Review your progress for previous months by pressing \fB[\fR on the keyboard, sift through months with \fB[\fR and \fB]\fR.
80
81.SH CUSTOMIZATION
82.PP
83\fBdijo (>= v0.2.3)\fR, can be configured via a configuration file. After its first run, \fBdijo\fR creates a configuration file. \fBdijo\fR must be restarted for changes in the configuration file to take effect.
84.PP
85This file is saved in different directories based on your operating system:
86
87.nf
88.IP
89\(bu GNU/Linux: \fB$XDG_CONFIG_HOME/dijo/config.toml\fR
90.IP
91\(bu MacOS: \fB$HOME/Library/Application Support/rs.nerdypepper.dijo/config.toml\fR
92.IP
93\(bu Win10: \fB{FOLDERID_RoamingAppData}\[rs]nerdypepper\[rs]dijo\[rs]config\[rs]config.toml\fR
94.fi
95
96.PP
97The default config file (created on first run) looks something like this, \fBconfig.toml\fR:
98.IP
99.nf
100\fB
101[look]
102true_chr = \[dq]\[pc]\[dq]
103false_chr = \[dq]\[pc]\[dq]
104future_chr = \[dq]\[pc]\[dq]
105
106[colors]
107reached = \[dq]cyan\[dq]
108todo = \[dq]magenta\[dq]
109inactive = \[dq]light black\[dq]
110\fR
111.fi
112
113.SS Look
114.PP
115Variables in this section define the characters \fBdijo\fR uses in \fBDAY\fR mode to represent days of the month. Every value in this section must span exactly 1 character in length.
116
117.IP
118\(bu \fBtrue_chr\fR: The character to use in a Bit habit when the goal is \fBreached\fR
119.IP
120\(bu \fBfalse_chr\fR: The character to use in a Bit habit when the goal is \fBnot reached\fR
121.IP
122\(bu \fBfuture_chr\fR: The character to use in a Bit habit when the day is \fBuntracked\fR.
123
124.SS Colors
125.PP
126Variables in this section define the colors \fBdijo\fR uses in all modes:
127
128.IP
129\(bu \fBreached\fR: The color to use when the goal is \fBreached\fR for the day. This is also the color used in \fBWEEK\fR mode to fill the progress bar.
130.IP
131\(bu \fBtodo\fR: The color to use when the goal is \fByet to be reached\fR.
132.IP
133\(bu \fBinactive\fR: The color to use for \fBunfocused habits and untracked days\fR.
134
135.PP
136The values in this section are strings, and may be populated by one of the following:
137.IP
138.nf
139\fB
140 black light black
141 red light red
142 green light green
143 yellow light yellow
144 blue light blue
145 magenta light magenta
146 cyan light cyan
147 white light white
148
149 default -- uses your terminal\[aq]s background color
150 #123456 -- any color in hex (supported only on true color terminals)
151\fR
152.fi
153
154.PP
155\fBNote\fR: These values have to be quoted (ex.: \fBreached = \[dq]black\[dq]\fR)
156
157.SH AUTO HABITS
158.PP
159\fBdijo\fR supports auto-trackable habits, that is, habits that can be updated via scripts. Add an auto-habit to, say, track your git commits:
160.IP
161.nf
162\fB
163:add-auto commits 5
164\fR
165.fi
166.PP
167You can control \fBdijo\fR externally by calling it with the
168\fB-c\fR flag:
169.IP
170.nf
171\fB
172dijo -c \[dq]track-up commits\[dq] # a +1 on today\[aq]s count
173dijo -c \[dq]track-down commits\[dq] # a -1 on today\[aq]s count
174\fR
175.fi
176.PP
177Firstly, point \fBgit\fR to your hooks directory
178(\fB\[ti]/.hooks\fR in this case):
179.IP
180.nf
181\fB
182# contents of \[ti]/.gitconfig
183
184[core]
185hooksPath = \[dq]/home/\fIusername\fB/.hooks\[dq]
186\fR
187.fi
188.PP
189Create a file called \fBpost-commit\fR in the \fB\[ti]/.hooks\fR directory, with the following contents (you should run \fBmkdir \[ti]/.hooks\fR if it doesn\[cq]t exist):
190.IP
191.nf
192\fB
193#! /usr/bin/env bash
194
195dijo -c \[dq]track-up commits\[dq]
196\fR
197.fi
198.IP
199.nf
200\fB
201# make the post-commit script an executable
202
203chmod +x \[ti]/.hooks/post-commit
204\fR
205.fi
206.PP
207Voil\[`a]! Every time you make a commit, \fBdijo\fR will automatically track it under the \fBcommits\fR habit.
208
209.SH MODES
210.PP
211Any habit in the interactive program can exist in one of two modes:
212.IP
213\(bu \fBDAY\fR: the default mode
214.IP
215\(bu \fBWEEK\fR: can be toggled on an off with \fBv\fR
216.SS \fBDAY\fR mode
217
218.PP
219\fBDAY\fR mode is the default mode for every habit. It shows you every day of the current month. In this mode, counting-type habits display their counts for each day of the month. Bit-type habits (yes/no) display their bits in the form of a \fB\[pc]\fR (U+00B7 Middle Dot). Days whose goals have been reached are displayed in cyan and those that haven\[cq]t been reached are displayed in magenta. Days that haven\[cq]t been tracked are displayed in \[lq]light black\[rq].
220
221.SS \fBWEEK\fR mode
222.PP
223\fBWEEK\fR mode can be triggered for a single habit via \fBv\fR,
224and for every habit via \fBV\fR. \fBWEEK\fR mode will show you a summary of your progress for every week of the month. The current week\[cq]s percentage is indicated in white, other weeks are colored in \[lq]light black\[rq]. The progress for a given week is calculated as follows:
225.IP "1." 3
226if the goal is reached for a day of the week, the day contributes
227exactly 14.28% (100/7) towards that week\[cq]s progress.
228.IP "2." 3
229if the goal is not reached for a day of the week, the day contributes
230\fBprogress / goal * 100\fR towards that week\[cq]s progress.
231.PP
232That means, to achieve a 100% for a week, you have to reach your goal
233\fIevery single day of the week\fR.
234
235.SS The Command mode
236.PP
237The command mode is different from the other modes in that it is a \[lq]control\[rq] mode rather than an \[lq]observe\[rq] mode. One can enter the command mode by hitting \fB:\fR on the keyboard. You will notice a \fB:\fR pop up at the bottom of the screen. You may now begin typing a command, once you are done, press \fBEnter\fR on the keyboard to execute it.
238.PP
239The command mode may also be accessed without running the program interactively, by starting \fBdijo\fR with the \fB-c\fR flag and passing a string to it as a command:
240.IP
241.nf
242\fB
243$ dijo -c \[dq]track-up commits\[dq]
244\fR
245.fi
246.PP
247You can hit \fBTab\fR on the keyboard inside Command mode to
248trigger completions. For example:
249.IP
250.nf
251\fB
252:d<Tab>
253# completes to
254:delete
255
256:delete fr<Tab>
257# completes to
258:delete french
259\fR
260.fi
261
262.SH COMMANDS
263.SS Keybinds
264.PP
265These are key binds you can use at \fBDAY\fR or \fBWEEK\fR modes. Some of them are dependent on the currently focused habit and some are global. Those that are dependent on the currently focused habit are marked with
266a \fB[f]\fR.
267.IP \(bu 2
268Motions:
269.RS 2
270.nf
271.IP \(bu 2
272\fBh\fR - move one cell to the left (aliases: \fB<Tab>\fR, \fB<Arrow-Left>\fR)
273.IP \(bu 2
274\fBj\fR - move one cell down (aliases: \fB<Arrow-Down>\fR)
275.IP \(bu 2
276\fBk\fR - move one cell up (alases: \fB<Arrow-Up>\fR)
277.IP \(bu 2
278\fBl\fR - move one cell to the right (aliases: \fB<Shift-Tab>\fR,
279\fB<Arrow-Right>\fR)
280.fi
281.RE
282.IP \(bu 2
283Editing
284.RS 2
285.nf
286.IP \(bu 2
287\fB<Enter>\fR - increment the currently focused habit (aliases: \fBn\fR) \fB[f]\fR
288.IP \(bu 2
289\fB<Backspace>\fR - decrement the currently focused habit (aliases: \fBp\fR) \fB[f]\fR
290.fi
291.RE
292.IP \(bu 2
293Modes
294.RS 2
295.IP \(bu 2
296\fBv\fR - enter \fBWEEK\fR mode for currently focused habit
297\fB[f]\fR
298.IP \(bu 2
299\fBV\fR - enter \fBWEEK\fR mode for all habits
300.IP \(bu 2
301\fB<Esc>\fR - return to \fBDAY\fR mode
302.RE
303.IP \(bu 2
304Time Travel
305.RS 2
306.IP \(bu 2
307\fB[\fR - shift view port back by one month
308.IP \(bu 2
309\fB]\fR - shift view port forward by one month
310.IP \(bu 2
311\fB}\fR - return to present
312.RE
313.IP \(bu 2
314Control
315.RS 2
316.IP \(bu 2
317\fB<Ctrl-c>\fR - quit without saving (subject to change)
318.RE
319.SS Commandline
320.PP
321Enter the command mode with \fB:\fR. Type out a command and press \fB<Enter>\fR on the keyboard to execute it. Most commands have `aliases', or short forms. Command mode supports auto-complete also.
322.IP \(bu 2
323Help: show command syntax
324.RS 2
325.IP \(bu 2
326Inputs: optional command or alias
327.IP \(bu 2
328Usage: \fBhelp [command]\fR
329.IP \(bu 2
330Example: \fB:help aa\fR
331.IP \(bu 2
332Aliases: \fBh\fR
333.RE
334.IP \(bu 2
335Add: add a habit
336.RS 2
337.IP \(bu 2
338Inputs: name of habit, optional daily goal
339.IP \(bu 2
340Usage: \fBadd <habit-name> [goal]\fR
341.IP \(bu 2
342Example: \fB:add french 5\fR
343.IP \(bu 2
344Aliases: \fBa\fR
345.RE
346.IP \(bu 2
347Add Auto: add an auto-trackable habit
348.RS 2
349.IP \(bu 2
350Inputs: name of habit, optional daily goal
351.IP \(bu 2
352Usage: \fBadd-auto <habit-name> [goal]\fR
353.IP \(bu 2
354Example: \fB:add-auto commits 5\fR
355.IP \(bu 2
356Aliases: \fBaa\fR
357.RE
358.IP \(bu 2
359Delete: delete a habit
360.RS 2
361.IP \(bu 2
362Inputs: name of habit to delete
363.IP \(bu 2
364Usage: \fBdelete <habit-name>\fR
365.IP \(bu 2
366Example: \fB:delete water\fR
367.IP \(bu 2
368Aliases: \fBd\fR
369.RE
370.IP \(bu 2
371Month motions: stats from the past
372.RS 2
373.IP \(bu 2
374Inputs: None
375.IP \(bu 2
376Usage: \fBmonth-prev\fR, \fBmonth-next\fR
377.IP \(bu 2
378Example: \fB:month-prev\fR
379.IP \(bu 2
380Aliases: \fBmprev\fR, \fBmnext\fR
381.RE
382.IP \(bu 2
383Tracking: For use only with \fBdijo --command\fR, works only on
384auto-habits
385.RS 2
386.IP \(bu 2
387Inputs: name of habit to track up/down
388.IP \(bu 2
389Usage: \fBtrack-up <habit-name>\fR,
390\fBtrack-down <habit-name>\fR
391.IP \(bu 2
392Example: \fB:track-up commits\fR
393.IP \(bu 2
394Aliases: \fBtup\fR, \fBtdown\fR
395.RE
396.IP \(bu 2
397Write: write progress to disk
398.RS 2
399.IP \(bu 2
400Inputs: None
401.IP \(bu 2
402Usage: \fBwrite\fR
403.IP \(bu 2
404Example: \fB:write\fR
405.IP \(bu 2
406Aliases: \fBw\fR
407.RE
408.IP \(bu 2
409Quit: save and quit
410.RS 2
411.IP \(bu 2
412Inputs: None
413.IP \(bu 2
414Usage: \fBquit\fR
415.IP \(bu 2
416Example: \fB:quit\fR
417.IP \(bu 2
418Aliases: \fBq\fR
419.RE
420
421.SH INTERNALS
422.PP
423This document delves into the internals of \fBdijo\fR.
424.SS Files
425.PP
426After its first run, \fBdijo\fR creates three files on your file system, one to record habit data, \fBhabit_record.json\fR, one to record auto-habit data, \fBhabit_record[auto].json\fR, and one to store the default configuration in, \fBconfig.toml\fR. Data is saved in a human-readable format: JSON (a lot of work went into this). The config file is stored in TOML.
427
428.SS Data files:
429.PP
430Making changes to these files while \fBdijo\fR is running, is not recommended (\fBdijo\fR will overwrite your changes on save).
431.nf
432.IP \(bu 2
433GNU/Linux: \fB$XDG_DATA_HOME/dijo/*.json\fR
434.IP \(bu 2
435MacOS: \fB$HOME/Library/Application Support/rs.nerdypepper.dijo/*.json\fR
436.IP \(bu 2
437Win10: \fB{FOLDERID_RoamingAppData}\[rs]nerdypepper\[rs]dijo\[rs]data\[rs]*.json\fR
438.fi
439
440.SS Config files:
441.PP
442You can read more about configuring \fBdijo\fR at the Customization page.
443.nf
444.IP \(bu 2
445GNU/Linux: \fB$XDG_CONFIG_HOME/dijo/config.toml\fR
446.IP \(bu 2
447MacOS: \fB$HOME/Library/Application Support/rs.nerdypepper.dijo/config.toml\fR
448.IP \(bu 2
449Win10: \fB{FOLDERID_RoamingAppData}\[rs]nerdypepper\[rs]dijo\[rs]config\[rs]config.toml\fR
450.fi
451.PP
452\fBdijo\fR will not run on your computer if it can\[cq]t find your home directory.
453
454.SS Data format
455.PP
456The general structure of a habit is as follows:
457.IP
458.nf
459\fB
460type :: String,
461name :: String,
462goal :: HabitType,
463auto :: bool,
464stats :: Map<Date, HabitType>
465\fR
466.fi
467.PP
468\fBHabitType\fR is the type of data to be tracked and it is a \fBbool\fR for bit-type habits and a \fBu32\fR for counting habits.
469
470.SS File watchers
471.PP
472\fBdijo\fR sets up a file watcher (in the interactive mode), and watches \fBhabit_record[auto].json\fR for changes. When changes are made to this file via \fBdijo -c\fR or equivalent, the interactive mode receives an update. However, the change is not reflected immediately because of \fBdijo\fR\[cq]s event based redrawing. You may force a redraw, and thereby update auto habits by pressing any button on the keyboard.
473
474.SH AUTHOR
475Akshay <[email protected]>
476
477.SH SEE ALSO
478.PP
479\fIvi\fR(1), \fIvim\fR(1), \fInvim\fR(1), \fIjq\fR(1), \fIgit\fR(1)