commit 167acfeab06b5a223522b1634c1ac352b397ac07
parent c23defd18433100c984c58d2b335d0ae77c003f4
Author: Andreas Gruhler <agruhl@gmx.ch>
Date: Sat, 8 Jan 2022 21:00:10 +0100
feat(man): use scdoc
Diffstat:
| M | docs/TESTING.md | | | 33 | ++++++++++++++++++++++++--------- |
| M | man1/diary.1 | | | 675 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------ |
| M | man1/diary.1.html | | | 599 | ++++++++++++++++++++++++++++++++++++++++--------------------------------------- |
| A | man1/diary.1.scd | | | 299 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | man1/style.css | | | 47 | +++++++++++++++++++++++++++++++++++++++++++++++ |
5 files changed, 1139 insertions(+), 514 deletions(-)
diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -46,24 +46,39 @@ diary 2>/dev/null
## Render Documentation / Man Page
-### Plain Text
+### Generate Runoff
+Install [scdoc](https://git.sr.ht/~sircmpwn/scdoc).
+
+Generate the "runoff" text with `scdoc` from the Markdown like `.scd` file:
+```bash
+scdoc < diary.1.scd > diary.1
+```
+
+### View Manpage in Terminal
Generate plain text from "runoff" text:
```bash
-tbl man1/diary.1 | nroff -man | less
+tbl diary.1 | nroff -man | less
```
-### `mandoc` HTML (preferred)
-Install [`mandoc`](https://en.wikipedia.org/wiki/Mandoc):
+### `mandoc` HTML (Preferred)
+Install [`mandoc`](https://en.wikipedia.org/wiki/Mandoc) >= [1.14.6 (helps to format paragraphs with CSS)](https://mandoc.bsd.lv/NEWS):
```bash
-sudo apt-get install mandoc
+curl -sO https://mandoc.bsd.lv/snapshots/mandoc-1.14.6.tar.gz
+tar -xf mandoc-1.14.6.tar.gz
+cd mandoc-1.14.6
+./configure
+make
```
-Generate HTML file:
+Generate HTML page from runoff:
```bash
-mandoc -Thtml -O style=https://soju.im/doc/man-style.css man1/diary.1 > man1/diary.1.html
+../../mandoc-1.14.6/mandoc -Thtml -O style=style.css diary.1 > diary.1.html
```
-### `groff` HTML
+### `groff` HTML (Alternative)
+
+Limitation: `groff` produces unstyled output (no CSS).
+
Install [`groff`](https://www.gnu.org/software/groff):
```bash
sudo apt-get install groff
@@ -71,5 +86,5 @@ sudo apt-get install groff
Generate HTML file (`-t` for `tbl`):
```bash
-groff -t -mandoc -Thtml man1/diary.1 > man1/diary.1.html
+groff -t -mandoc -Thtml diary.1 > diary.1.html
```
diff --git a/man1/diary.1 b/man1/diary.1
@@ -1,150 +1,308 @@
-.TH DIARY 1
+.\" Generated by scdoc 1.10.1
+.\" Complete documentation for this program is not available as a GNU info page
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.nh
+.ad l
+.\" Begin generated content:
+.TH "DIARY" "1" "2022-01-08"
+.P
.SH NAME
-diary \- Text-based journaling program
-
+.P
+diary - text-based journaling program
+.P
.SH SYNOPSIS
-.B diary
-[\fIOPTION\fR]... [\fIDIRECTORY\fR]...
-.br
-
+.P
+\fBdiary\fR [OPTION]... [DIARY_DIR]...
+.P
.SH DESCRIPTION
-.B diary
-is a text-based program for managing journal entries.
-
+Open the \fBdiary\fR journal for entries stored in DIARY_DIR.
+.P
+DIARY_DIR is required, if not set as environment variable or defined in the
+configuration file.
+.P
.SH OPTIONS
-.TP
-\fB\-v\fR, \fB\-\-version\fR
+.P
+\fB-v, --version\fR
+.P
+.RS 4
Print diary version
-.TP
-\fB\-h\fR, \fB\-\-help\fR
+.P
+.RE
+\fB-h, --help\fR
+.P
+.RS 4
Show diary help text
-.TP
-\fB\-d\fR, \fB\-\-dir\fR=\fI\,DIARY_DIR\/\fR
-Diary storage directory DIARY_DIR
-.TP
-\fB\-e\fR, \fB\-\-editor\fR=\fI\,EDITOR\/\fR
-EDITOR is the text editor used for opening the journal files.
-.TP
-\fB\-f\fR, \fB\-\-fmt\fR=\fI\,FMT\/\fR
-FMT is a custom date and file format. Change with care, because the diary
-reads and writes to files with file name FMT. The new FMT is only
-applied to newly saved entries. Existing entries with the old FMT are not
-automatically migrated to the new FMT and do not show up with a new FMT
-specifier. Consequently, a change in FMT shows an empty diary at first.
-Rename all files in the DIARY_DIR to migrate to a new FMT.
-.TP
-\fB\-F\fR, \fB\-\-fmt-cmd\fR=\fI\,FMT_CMD\/\fR
+.P
+.RE
+\fB-d, --dir\fR=DIARY_DIR
+.P
+.RS 4
+Directory with the journal text files
+.P
+.RE
+\fB-e, --editor\fR=EDITOR
+.P
+.RS 4
+Text editor used for opening the journal files
+.P
+.RE
+\fB-f, --fmt\fR=FMT
+.P
+.RS 4
+FMT is a custom date and file format. Change with care, because the
+diary reads and writes to files with file name FMT. The new FMT is only
+applied to newly saved entries. Existing entries with the old FMT are
+not automatically migrated to the new FMT and do not show up with a new
+FMT specifier. Consequently, a change in FMT shows an empty diary at
+first. Rename all files in the \fBDIARY_DIR\fR to migrate to a new FMT.
+.P
+.RE
+\fB-F, --fmt-cmd\fR=FMT_CMD
+.P
+.RS 4
Journal entries are formatted with this command. If not set (default),
the characters are printed to the preview screen character by character
-(without word wrap). For example, to enable word wrap after 75 characters,
-use "fmt -s" as FMT_CMD. To format markdown, use "mdcat -c" or similar,
-see \fBCustom Formatting\fR.
-.TP
-\fB\-p\fR, \fB\-\-no-pty\fR
-No pseudo terminal (pty) for entry preview. Only effective in combination
-with \fB--fmt-cmd\fR. If set, the output of \fB--fmt-cmd\fR is displayed
+(without word wrap). For example, to enable word wrap after 75
+characters, use "fmt -s" as FMT_CMD. To format markdown, use "mdcat -c"
+or similar, see \fBCUSTOM FORMATTING\fR.
+.P
+.RE
+\fB-p, --no-pty\fR
+.P
+.RS 4
+No pseudo terminal (pty) for entry preview. Only effective in
+combination with \fB--fmt-cmd\fR. If set, the output of \fB--fmt-cmd\fR is displayed
with Ncurses. If not set (default), the result of \fB--fmt-cmd\fR (journal
-entry preview) is printed on a pseudo-terminal (pty) and not processed with
-Ncurses. The pty supports the ANSI escape sequences (e.g. colors, font types,
-etc.) of the native terminal.
-.TP
-\fB\-m\fR, \fB\-\-no-mouse\fR
-Disable mouse, don't listen for mouse events. Mouse events are enabled by default.
-Without \fB--no-mouse\fR flag (default), native text selection and right-click
-in the preview window requires holding down the \fBSHIFT key\fR, see \fBMOUSE EVENTS\fR.
-.TP
-\fB\-r\fR, \fB\-\-range\fR=\fI\,RANGE\/\fR
-RANGE is the number of years to show before/after todays date. Defaults to 1 year.
-.TP
-\fB\-f\fR, \fB\-\-weekday\fR=\fI\,DAY\/\fR
-First day of the week. DAY is an integer in range (0..6), interpreted as 0 or 7 = Sun,
-1 = Mon, ..., 6 = Sat. If glibc is installed, the first day of the week is derived
-from the current locale setting (\'$LANG\', see man locale). Without glibc, the
-first weekday defaults to 1 (Monday), unless specified otherwise with this option.
-
+entry preview) is printed on a pseudo-terminal (pty) and not processed
+with Ncurses. The pty supports the ANSI escape sequences (e.g. colors,
+font types, etc.) of the native terminal.
+.P
+.RE
+\fB-m, --no-mouse\fR
+.P
+.RS 4
+Disable mouse, don't listen for mouse events. Mouse events are enabled
+by default. Without \fB--no-mouse\fR flag (default), native text selection and
+right-click in the preview window requires holding down the SHIFT key,
+see \fBMOUSE EVENTS\fR.
+.P
+.RE
+\fB-r, --range\fR=RANGE
+.P
+.RS 4
+The number of years to show before/after today. Defaults to 1 year.
+.P
+.RE
+\fB-f, --weekday\fR=DAY
+.P
+.RS 4
+First day of the week. DAY is an integer in range (0..6), interpreted as
+0 or 7 = Sun, 1 = Mon, ..., 6 = Sat. If glibc is installed, the first
+day of the week is derived from the current locale setting ($LANG, see
+man locale). Without glibc, the first weekday defaults to 1 (Monday),
+unless specified otherwise with this option.
+.P
+.RE
.SH NAVIGATION
+.P
Navigation is done using the following vim-inspired keyboard shortcuts:
-
+.P
.TS
-tab(|);
-l l.
-Key(s) | Action
-====== | ======
-e, Enter | edit current entry
-d, x | delete current entry
-s | sync current entry with CalDAV server (ALPHA)
-S | sync all entries with CalDAV server (ALPHA)
-i | import entries from .ics file (ALPHA)
-E | export entries to .ics file (ALPHA)
-
-t | jump to today
-f | jump to or find specific day
-
-j, down | go forward by 1 week
-k, up | go backward by 1 week
-h, left | go left by 1 day
-l, right | go right by 1 day
-J | go forward by 1 month
-K | go backward by 1 month
-
-N | go to the previous journal entry
-n | go to the next journal entry
-g | go to start of journal
-G | go to end of journal
-
-q | quit the program
+allbox;l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx
+l lx.
+T{
+\fBKey(s)\fR
+T} T{
+Action
+T}
+T{
+\fBe, Enter\fR
+T} T{
+edit current entry
+T}
+T{
+\fBd, x\fR
+T} T{
+delete current entry
+T}
+T{
+\fBt\fR
+T} T{
+jump to today
+T}
+T{
+\fBf\fR
+T} T{
+jump to or find specific day
+T}
+T{
+\fBj, down\fR
+T} T{
+go forward by 1 week
+T}
+T{
+\fBk, up\fR
+T} T{
+go backward by 1 week
+T}
+T{
+\fBh, left\fR
+T} T{
+go left by 1 day
+T}
+T{
+\fBl, right\fR
+T} T{
+go right by 1 day
+T}
+T{
+\fBJ\fR
+T} T{
+go forward by 1 month
+T}
+T{
+\fBK\fR
+T} T{
+go backward by 1 month
+T}
+T{
+\fBN\fR
+T} T{
+go to the previous journal entry
+T}
+T{
+\fBn\fR
+T} T{
+go to the next journal entry
+T}
+T{
+\fBg\fR
+T} T{
+go to start of journal
+T}
+T{
+\fBG\fR
+T} T{
+go to end of journal
+T}
+T{
+\fBq\fR
+T} T{
+quit the program
+T}
.TE
-
+.sp 1
+.P
+Alpha features:
+.P
+.TS
+allbox;l lx
+l lx
+l lx
+l lx.
+T{
+\fBKey(s)\fR
+T} T{
+Action
+T}
+T{
+\fBs, S\fR
+T} T{
+sync selected/all with CalDAV server
+T}
+T{
+\fBi\fR
+T} T{
+import entries from .ics file
+T}
+T{
+\fBe\fR
+T} T{
+export entries to .ics file
+T}
+.TE
+.sp 1
+.P
.SH ENVIRONMENT
-
-.IP DIARY_DIR
-If this variable is set to a directory that can be opened,
-.B diary
-will use it to store diary files. Diary files are simple text files named
-after their date, formatted according to FMT (see \'-f\'/\'--fmt\' options and
-\'fmt\' config key). The format defaults to "%Y-%m-%d", which is "YYYY-MM-DD"
-(see man strftime). All other files different from FMT are ignored.
-
-.IP EDITOR
-The program used to edit journal entries.
-
-.IP LANG
-The default locale used to display the first day of the week.
-
+.P
+\fBDIARY_DIR\fR
+.RS 4
+If this variable is set to a directory that can be opened, diary will
+use it to store diary files. Diary files are simple text files named
+after their date, formatted according to \fBFMT\fR (see \fB--fmt\fR option). The
+format defaults to "%Y-%m-%d", which is "YYYY-MM-DD" (see man strftime).
+All other files different from FMT are ignored.
+.P
+.RE
+\fBEDITOR\fR
+.RS 4
+The program used to edit journal entries inside \fBDIARY_DIR\fR.
+.P
+.RE
+\fBLANG\fR
+.RS 4
+The default locale used to display the first day of the week, see
+\fB--weekday\fR option.
+.P
+.P
+.P
+.RE
.SH ARGUMENTS
-
-If the argument \fIDIRECTORY\fR is given, diary files are read from and
-stored to that directory, ignoring the DIARY_DIR environment variable,
-any \'-d\'/\'--dir\' options or the \'dir\' value set in the config file.
-
+.P
+If the argument \fBDIARY_DIR\fR is given, diary files are read from and stored to
+that directory, ignoring the $DIARY_DIR environment variable, any \fB--dir\fR option
+or the \fBdir\fR value set in the \fBCONFIGURATION FILE\fR.
+.P
.SH FILES
-.TP
-.I ${PREFIX:-/usr/local/bin}/diary
+.P
+${PREFIX:-/usr/local/bin}/\fBdiary\fR
+.RS 4
The diary binary
-.TP
-.I ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg
-An optional diary configuration file
-
+.P
+.RE
+${XDG_CONFIG_HOME:-~/.config}/diary/\fBdiary.cfg\fR
+.RS 4
+An optional diary \fBCONFIGURATION FILE\fR
+.P
+.RE
.SH CONFIGURATION FILE
-The diary.cfg configuration file can optionally be used to persist diary
-configuration. Use the \'#\' or \';\' characters to comment lines.
-
-Create default config location:
-
+.P
+The \fBdiary.cfg\fR configuration file can optionally be used to persist diary
+configuration. Use the "#" or ";" characters to comment lines.
+.P
+Create default configuration location:
+.P
.nf
- mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary
+.RS 4
+mkdir -p ${XDG_CONFIG_HOME:-~/\&.config}/diary
.fi
-
-Install an example config file with defaults:
-
-.in 0
+.RE
+.P
+Install an example configuration file with defaults:
+.P
.nf
-tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
+.RS 4
+tee ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg <<EOF
# Path that holds the journal text files
#dir = ~/diary
# Number of years to show before/after todays date
range = 1
-# 0 = Sunday, 1 = Monday, ..., 6 = Saturday
+# 0 = Sunday, 1 = Monday, \&.\&.\&., 6 = Saturday
weekday = 1
# Date and file format, change with care
fmt = %Y-%m-%d
@@ -162,99 +320,205 @@ editor =
#google_clientid =
#google_secretid =
# Google OAuth2 tokenfile
-#google_tokenfile = ~/.diary-token
+#google_tokenfile = ~/\&.diary-token
EOF
.fi
-
-.SH Custom Formatting
-
-The preview of the journal entries can be processed with a custom \fB--fmt-cmd\fR,
-\fB-F\fR or \fBfmt_cmd\fR in the configuration file.
-
-The result of this formatting command is printed to a pseudo-terminal (pty) by default
-(behavior can be changed with the \fB--no-pty\fR flag).
-
-The output processed on the pty (not with Ncurses, without \fB--no-pty\fR flag) includes
-all ANSI escape characters supported by the terminal (colors, font types, etc.).
-
-Thus, formatters like \fBfmt\fR or any "cat like program" such as mdcat to process Markdown
-can be plugged in for \fB--fmt-cmd\fR.
-
+.RE
+.P
+.SH CUSTOM FORMATTING
+.P
+The preview of the journal entries can be processed with a custom \fB--fmt-cmd\fR.
+The result of this formatting command is printed to a pseudo-terminal (pty) by
+default. This behavior can be changed with the \fB--no-pty\fR flag. The output
+processed on the pty (without Ncurses) includes all ANSI escape characters
+supported by the terminal (colors, font types, etc.). Thus, formatters like
+"fmt", or any "cat like program" ("mdcat" to process Markdown) can be plugged in
+for \fB--fmt-cmd\fR.
+.P
.SH MOUSE EVENTS
-Mouse events are listened for by default (no_mouse=false). This behavior can
-be disabled with the \fB--no-mouse\fR flag or in the configuration file (no_mouse=true).
-
-With no_mouse=false (default), use the \fBSHIFT key\fR for native text selection
-and right-click in the preview window.
-
+.P
+Mouse events are listened for by default (\fBno_mouse\fR=false configuration). This
+behavior can be disabled with the \fB--no-mouse\fR flag or in the configuration file
+(\fBno_mouse\fR=true). With \fBno_mouse\fR=false (default), use the SHIFT key for native
+text selection and right-click in the preview window.
+.P
.SH PRECEDENCE RULES
-
-The default variables, for instance, for the configuration variables \'editor\',
-\'dir\' and \'weekday\', are populated with values in the following order:
-
-.TP
-1.
-No default for \'DIARY_DIR\'. Defaults for \'range\', \'weekday\', \'fmt\' and \'editor\'
-are provided in \'diary.h\'. If \'EDITOR\' is unset and no editor is provided in the
-config file or via the \'-e\' option, the
-.B
-diary
-works read-only. Journal files cannot be opened. If \'DIARY_DIR\' is not provided, the
-.B
-diary
-won't open.
-.TP
-2.
-.B
-Config file
-(empty default for \'editor\', no default for \'dir\')
-.TP
-3.
-.B
-Environment
-variables \'$DIARY_DIR\', \'$EDITOR\' and \'$LANG\' for locale (\'weekday\')
-.TP
-4.
-.B
-Option
-arguments, see section
-.B
-OPTIONS
-.TP
-5.
-First non-option argument \fIDIRECTORY\fR is interpreted as \'DIARY_DIR\'
-
+.P
+The default variables, for instance, for the configuration variables "editor",
+"dir" and "weekday", are populated with values in the following order:
+.P
+.TS
+allbox;l lx
+l lx
+l lx
+l lx
+l lx
+l lx.
+T{
+\fBPriority\fR
+T} T{
+\fBDescription\fR
+T}
+T{
+1
+T} T{
+No default for \fBDIARY_DIR\fR. Defaults for "range", "weekday", "fmt" and "editor" are provided in "diary.h". If \fBEDITOR\fR is unset and no editor is provided in the configuration file or \fB--editor\fR option, the diary works read-only. Journal files cannot be opened. If \fBDIARY_DIR\fR is not provided, the diary won't open.
+T}
+T{
+2
+T} T{
+\fBCONFIGURATION FILE\fR (empty default for "editor", no default for "dir")
+T}
+T{
+3
+T} T{
+Environment variables $DIARY_DIR, $EDITOR and $LANG for locale ("weekday")
+T}
+T{
+4
+T} T{
+Option arguments, see section \fBOPTIONS\fR
+T}
+T{
+5
+T} T{
+First non-option argument is interpreted as \fBDIARY_DIR\fR
+T}
+.TE
+.sp 1
.SH PRECEDENCE EXAMPLE: LOCALE AND FIRST DAY OF WEEK
-
-If glibc is installed, the first weekday defaults to the locale defined in the current shell
-environment ($LANG, see man locale), unless specified otherwise via the \'--weekday\'/\'-w\'.
-
+.P
+If glibc is installed, the first weekday defaults to the locale defined in the
+current shell environment ($LANG, see man locale), unless specified otherwise
+with the \fB--weekday\fR option.
+.P
+Start with weekday=3(Wed), overrule any other configuration value:
.nf
-# start with weekday=3(Wed), overrule any other configuration value
+.RS 4
diary -w3
-
-# start with glibc derived weekday=1, regardless of \'weekday\' in config file
+.fi
+.RE
+.P
+Start with glibc derived weekday=1, regardless of weekday in config file:
+.nf
+.RS 4
LANG=de_CH diary
-
-# if glibc is installed, start with glibc derived base date (weekday=0)
+.fi
+.RE
+.P
+If glibc is installed, start with glibc derived base date (weekday=0):
+.nf
+.RS 4
LANG= diary
-
-# disable environment variable, default to value from config file
+.fi
+.RE
+.P
+Disable environment variable, default to value from config file:
+.nf
+.RS 4
unset LANG
-
-# start with \'weekday\' default from config file, if available
+.fi
+.RE
+.P
+Start with weekday default from config file, if available:
+.nf
+.RS 4
diary
-
-# remove config file
-rm ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg
-
-# start with \'weekday\' default value from source code (1=Mon)
+.fi
+.RE
+.P
+Remove config file:
+.nf
+.RS 4
+rm ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg
+.fi
+.RE
+.P
+Start with weekday default value from source code (1=Mon):
+.nf
+.RS 4
diary
.fi
-
-.SH DEVELOPMENT
-Contributions are always welcome! All source code is available
-at https://codeberg.org/in0rdr/diary.
-
-.TP
-For question and support visit https://web.libera.chat/gamja/#diary.
-\ No newline at end of file
+.RE
+.P
+.SH DEVELOPMENT AND SUPPORT
+.P
+Contributions are always welcome! All source code is available at
+https://codeberg.org/in0rdr/diary.
+.P
+For question and support visit https://web.libera.chat/gamja/#diary.
+.P
+.SH AUTHORS
+.P
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Andreas Gruhler (https://codeberg.org/in0rdr/diary)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Matthias Beyer (https://github.com/matthiasbeyer)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Johnathan Jenkins (https://github.com/shaggytwodope)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Yu-Jie Lin (https://github.com/livibetter)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Balduin Dettling (https://github.com/mbjd)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Avindra Goolcharan (https://github.com/avindra)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Oliver Blanthorn (https://github.com/bovine3dom)
+.RE
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.IP \(bu 4
+.\}
+Jonny Burger (https://github.com/JonnyBurger)
+.RE
diff --git a/man1/diary.1.html b/man1/diary.1.html
@@ -1,8 +1,13 @@
<!DOCTYPE html>
<html>
+<!-- This is an automatically generated file. Do not edit.
+ Generated by scdoc 1.10.1
+ Complete documentation for this program is not available as a GNU info page
+ -->
<head>
<meta charset="utf-8"/>
- <link rel="stylesheet" href="https://soju.im/doc/man-style.css" type="text/css" media="all"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+ <link rel="stylesheet" href="style.css" type="text/css" media="all"/>
<title>DIARY(1)</title>
</head>
<body>
@@ -14,246 +19,214 @@
</tr>
</table>
<div class="manual-text">
-<h1 class="Sh" title="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
-diary - Text-based journaling program
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
-<b>diary</b> [ <i>OPTION</i>]... [<i>DIRECTORY</i>]...
-<div> </div>
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-<b>diary</b> is a text-based program for managing journal entries.
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
-<dl class="Bl-tag">
- <dt><b>-v</b>, <b>--version</b></dt>
- <dd>Print diary version</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-h</b>, <b>--help</b></dt>
- <dd>Show diary help text</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-d</b>, <b>--dir</b>=<i>DIARY_DIR</i></dt>
- <dd>Diary storage directory DIARY_DIR</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-e</b>, <b>--editor</b>=<i>EDITOR</i></dt>
- <dd>EDITOR is the text editor used for opening the journal files.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-f</b>, <b>--fmt</b>=<i>FMT</i></dt>
- <dd>FMT is a custom date and file format. Change with care, because the diary
- reads and writes to files with file name FMT. The new FMT is only applied
- to newly saved entries. Existing entries with the old FMT are not
- automatically migrated to the new FMT and do not show up with a new FMT
- specifier. Consequently, a change in FMT shows an empty diary at first.
- Rename all files in the DIARY_DIR to migrate to a new FMT.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-F</b>, <b>--fmt-cmd</b>=<i>FMT_CMD</i></dt>
- <dd>Journal entries are formatted with this command. If not set (default), the
- characters are printed to the preview screen character by character
- (without word wrap). For example, to enable word wrap after 75 characters,
- use "fmt -s" as FMT_CMD. To format markdown, use "mdcat
- -c" or similar, see <b>Custom Formatting</b>.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-p</b>, <b>--no-pty</b></dt>
- <dd>No pseudo terminal (pty) for entry preview. Only effective in combination
- with <b>--fmt-cmd</b>. If set, the output of <b>--fmt-cmd</b> is displayed
- with Ncurses. If not set (default), the result of <b>--fmt-cmd</b>
- (journal entry preview) is printed on a pseudo-terminal (pty) and not
- processed with Ncurses. The pty supports the ANSI escape sequences (e.g.
- colors, font types, etc.) of the native terminal.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-m</b>, <b>--no-mouse</b></dt>
- <dd>Disable mouse, don't listen for mouse events. Mouse events are enabled by
- default. Without <b>--no-mouse</b> flag (default), native text selection
- and right-click in the preview window requires holding down the <b>SHIFT
- key</b>, see <b>MOUSE EVENTS</b>.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-r</b>, <b>--range</b>=<i>RANGE</i></dt>
- <dd>RANGE is the number of years to show before/after todays date. Defaults to
- 1 year.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><b>-f</b>, <b>--weekday</b>=<i>DAY</i></dt>
- <dd>First day of the week. DAY is an integer in range (0..6), interpreted as 0
- or 7 = Sun, 1 = Mon, ..., 6 = Sat. If glibc is installed, the first day of
- the week is derived from the current locale setting
- (´$LANG´, see man locale). Without glibc, the first weekday
- defaults to 1 (Monday), unless specified otherwise with this option.
- <div class="Pp"></div>
- </dd>
-</dl>
-<h1 class="Sh" title="Sh" id="NAVIGATION"><a class="permalink" href="#NAVIGATION">NAVIGATION</a></h1>
-Navigation is done using the following vim-inspired keyboard shortcuts:
-<div class="Pp"></div>
-<table class="tbl">
+<section class="Sh">
+<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
+<p class="Pp">diary - text-based journaling program</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
+<p class="Pp"><b>diary</b> [OPTION]... [DIARY_DIR]...</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
+<p class="Pp">Open the <b>diary</b> journal for entries stored in DIARY_DIR.</p>
+<p class="Pp">DIARY_DIR is required, if not set as environment variable or
+ defined in the configuration file.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
+<p class="Pp"><b>-v, --version</b></p>
+<p class="Pp"></p>
+<div class="Bd-indent">Print diary version</div>
+<p class="Pp"><b>-h, --help</b></p>
+<p class="Pp"></p>
+<div class="Bd-indent">Show diary help text</div>
+<p class="Pp"><b>-d, --dir</b>=DIARY_DIR</p>
+<p class="Pp"></p>
+<div class="Bd-indent">Directory with the journal text files</div>
+<p class="Pp"><b>-e, --editor</b>=EDITOR</p>
+<p class="Pp"></p>
+<div class="Bd-indent">Text editor used for opening the journal files</div>
+<p class="Pp"><b>-f, --fmt</b>=FMT</p>
+<p class="Pp"></p>
+<div class="Bd-indent">FMT is a custom date and file format. Change with care,
+ because the diary reads and writes to files with file name FMT. The new FMT is
+ only applied to newly saved entries. Existing entries with the old FMT are not
+ automatically migrated to the new FMT and do not show up with a new FMT
+ specifier. Consequently, a change in FMT shows an empty diary at first. Rename
+ all files in the <b>DIARY_DIR</b> to migrate to a new FMT.</div>
+<p class="Pp"><b>-F, --fmt-cmd</b>=FMT_CMD</p>
+<p class="Pp"></p>
+<div class="Bd-indent">Journal entries are formatted with this command. If not
+ set (default), the characters are printed to the preview screen character by
+ character (without word wrap). For example, to enable word wrap after 75
+ characters, use "fmt -s" as FMT_CMD. To format markdown, use
+ "mdcat -c" or similar, see <b>CUSTOM FORMATTING</b>.</div>
+<p class="Pp"><b>-p, --no-pty</b></p>
+<p class="Pp"></p>
+<div class="Bd-indent">No pseudo terminal (pty) for entry preview. Only
+ effective in combination with <b>--fmt-cmd</b>. If set, the output of
+ <b>--fmt-cmd</b> is displayed with Ncurses. If not set (default), the result
+ of <b>--fmt-cmd</b> (journal entry preview) is printed on a pseudo-terminal
+ (pty) and not processed with Ncurses. The pty supports the ANSI escape
+ sequences (e.g. colors, font types, etc.) of the native terminal.</div>
+<p class="Pp"><b>-m, --no-mouse</b></p>
+<p class="Pp"></p>
+<div class="Bd-indent">Disable mouse, don't listen for mouse events. Mouse
+ events are enabled by default. Without <b>--no-mouse</b> flag (default),
+ native text selection and right-click in the preview window requires holding
+ down the SHIFT key, see <b>MOUSE EVENTS</b>.</div>
+<p class="Pp"><b>-r, --range</b>=RANGE</p>
+<p class="Pp"></p>
+<div class="Bd-indent">The number of years to show before/after today. Defaults
+ to 1 year.</div>
+<p class="Pp"><b>-f, --weekday</b>=DAY</p>
+<p class="Pp"></p>
+<div class="Bd-indent">First day of the week. DAY is an integer in range (0..6),
+ interpreted as 0 or 7 = Sun, 1 = Mon, ..., 6 = Sat. If glibc is installed, the
+ first day of the week is derived from the current locale setting ($LANG, see
+ man locale). Without glibc, the first weekday defaults to 1 (Monday), unless
+ specified otherwise with this option.</div>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="NAVIGATION"><a class="permalink" href="#NAVIGATION">NAVIGATION</a></h1>
+<p class="Pp">Navigation is done using the following vim-inspired keyboard
+ shortcuts:</p>
+<p class="Pp"></p>
+<table class="tbl" border="1" style="border-style: solid;">
<tr>
- <td>Key(s) </td>
- <td> Action</td>
+ <td><b>Key(s)</b></td>
+ <td>Action</td>
</tr>
<tr>
- <td>====== </td>
- <td> ======</td>
+ <td><b>e, Enter</b></td>
+ <td>edit current entry</td>
</tr>
<tr>
- <td>e, Enter </td>
- <td> edit current entry</td>
+ <td><b>d, x</b></td>
+ <td>delete current entry</td>
</tr>
<tr>
- <td>d, x </td>
- <td> delete current entry</td>
+ <td><b>t</b></td>
+ <td>jump to today</td>
</tr>
<tr>
- <td>s </td>
- <td> sync current entry with CalDAV server (ALPHA)</td>
+ <td><b>f</b></td>
+ <td>jump to or find specific day</td>
</tr>
<tr>
- <td>S </td>
- <td> sync all entries with CalDAV server (ALPHA)</td>
+ <td><b>j, down</b></td>
+ <td>go forward by 1 week</td>
</tr>
<tr>
- <td>i </td>
- <td> import entries from .ics file (ALPHA)</td>
+ <td><b>k, up</b></td>
+ <td>go backward by 1 week</td>
</tr>
<tr>
- <td>E </td>
- <td> export entries to .ics file (ALPHA)</td>
+ <td><b>h, left</b></td>
+ <td>go left by 1 day</td>
</tr>
<tr>
- <td></td>
- <td></td>
+ <td><b>l, right</b></td>
+ <td>go right by 1 day</td>
</tr>
<tr>
- <td>t </td>
- <td> jump to today</td>
+ <td><b>J</b></td>
+ <td>go forward by 1 month</td>
</tr>
<tr>
- <td>f </td>
- <td> jump to or find specific day</td>
+ <td><b>K</b></td>
+ <td>go backward by 1 month</td>
</tr>
<tr>
- <td></td>
- <td></td>
+ <td><b>N</b></td>
+ <td>go to the previous journal entry</td>
</tr>
<tr>
- <td>j, down </td>
- <td> go forward by 1 week</td>
+ <td><b>n</b></td>
+ <td>go to the next journal entry</td>
</tr>
<tr>
- <td>k, up </td>
- <td> go backward by 1 week</td>
+ <td><b>g</b></td>
+ <td>go to start of journal</td>
</tr>
<tr>
- <td>h, left </td>
- <td> go left by 1 day</td>
+ <td><b>G</b></td>
+ <td>go to end of journal</td>
</tr>
<tr>
- <td>l, right </td>
- <td> go right by 1 day</td>
- </tr>
- <tr>
- <td>J </td>
- <td> go forward by 1 month</td>
- </tr>
- <tr>
- <td>K </td>
- <td> go backward by 1 month</td>
- </tr>
- <tr>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td>N </td>
- <td> go to the previous journal entry</td>
- </tr>
- <tr>
- <td>n </td>
- <td> go to the next journal entry</td>
+ <td><b>q</b></td>
+ <td>quit the program</td>
</tr>
+</table>
+<p class="Pp"></p>
+<p class="Pp">Alpha features:</p>
+<p class="Pp"></p>
+<table class="tbl" border="1" style="border-style: solid;">
<tr>
- <td>g </td>
- <td> go to start of journal</td>
+ <td><b>Key(s)</b></td>
+ <td>Action</td>
</tr>
<tr>
- <td>G </td>
- <td> go to end of journal</td>
+ <td><b>s, S</b></td>
+ <td>sync selected/all with CalDAV server</td>
</tr>
<tr>
- <td></td>
- <td></td>
+ <td><b>i</b></td>
+ <td>import entries from .ics file</td>
</tr>
<tr>
- <td>q </td>
- <td> quit the program</td>
+ <td><b>e</b></td>
+ <td>export entries to .ics file</td>
</tr>
</table>
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1>
-<dl class="Bl-tag">
- <dt>DIARY_DIR</dt>
- <dd>If this variable is set to a directory that can be opened, <b>diary</b>
- will use it to store diary files. Diary files are simple text files named
- after their date, formatted according to FMT (see
- ´-f´/´--fmt´ options and ´fmt´
- config key). The format defaults to "%Y-%m-%d", which is
- "YYYY-MM-DD" (see man strftime). All other files different from
- FMT are ignored.
- <div class="Pp"></div>
- </dd>
-</dl>
-<dl class="Bl-tag">
- <dt>EDITOR</dt>
- <dd>The program used to edit journal entries.
- <div class="Pp"></div>
- </dd>
-</dl>
-<dl class="Bl-tag">
- <dt>LANG</dt>
- <dd>The default locale used to display the first day of the week.
- <div class="Pp"></div>
- </dd>
-</dl>
-<h1 class="Sh" title="Sh" id="ARGUMENTS"><a class="permalink" href="#ARGUMENTS">ARGUMENTS</a></h1>
-If the argument <i>DIRECTORY</i> is given, diary files are read from and stored
- to that directory, ignoring the DIARY_DIR environment variable, any
- ´-d´/´--dir´ options or the ´dir´
- value set in the config file.
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
-<dl class="Bl-tag">
- <dt><i>${PREFIX:-/usr/local/bin}/diary</i></dt>
- <dd>The diary binary</dd>
-</dl>
-<dl class="Bl-tag">
- <dt><i>${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg</i></dt>
- <dd>An optional diary configuration file
- <div class="Pp"></div>
- </dd>
-</dl>
-<h1 class="Sh" title="Sh" id="CONFIGURATION_FILE"><a class="permalink" href="#CONFIGURATION_FILE">CONFIGURATION
+<p class="Pp"></p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1>
+<p class="Pp"><b>DIARY_DIR</b></p>
+<div class="Bd-indent">If this variable is set to a directory that can be
+ opened, diary will use it to store diary files. Diary files are simple text
+ files named after their date, formatted according to <b>FMT</b> (see
+ <b>--fmt</b> option). The format defaults to "%Y-%m-%d", which is
+ "YYYY-MM-DD" (see man strftime). All other files different from FMT
+ are ignored.</div>
+<p class="Pp"><b>EDITOR</b></p>
+<div class="Bd-indent">The program used to edit journal entries inside
+ <b>DIARY_DIR</b>.</div>
+<p class="Pp"><b>LANG</b></p>
+<div class="Bd-indent">The default locale used to display the first day of the
+ week, see <b>--weekday</b> option.</div>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="ARGUMENTS"><a class="permalink" href="#ARGUMENTS">ARGUMENTS</a></h1>
+<p class="Pp">If the argument <b>DIARY_DIR</b> is given, diary files are read
+ from and stored to that directory, ignoring the $DIARY_DIR environment
+ variable, any <b>--dir</b> option or the <b>dir</b> value set in the
+ <b>CONFIGURATION FILE</b>.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
+<p class="Pp">${PREFIX:-/usr/local/bin}/<b>diary</b></p>
+<div class="Bd-indent">The diary binary</div>
+<p class="Pp">${XDG_CONFIG_HOME:-~/.config}/diary/<b>diary.cfg</b></p>
+<div class="Bd-indent">An optional diary <b>CONFIGURATION FILE</b></div>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="CONFIGURATION_FILE"><a class="permalink" href="#CONFIGURATION_FILE">CONFIGURATION
FILE</a></h1>
-The diary.cfg configuration file can optionally be used to persist diary
- configuration. Use the ´#´ or ´;´ characters to
- comment lines.
-<div class="Pp"></div>
-Create default config location:
-<div class="Pp"></div>
-<pre>
- mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary
-</pre>
-<div class="Pp"></div>
-Install an example config file with defaults:
-<div class="Pp"></div>
-<br/>
-<pre>
-tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
+<p class="Pp">The <b>diary.cfg</b> configuration file can optionally be used to
+ persist diary configuration. Use the "#" or ";"
+ characters to comment lines.</p>
+<p class="Pp">Create default configuration location:</p>
+<p class="Pp"></p>
+<div class="Bd-indent">
+<pre>mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary</pre>
+</div>
+<p class="Pp">Install an example configuration file with defaults:</p>
+<p class="Pp"></p>
+<div class="Bd-indent">
+<pre>tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
# Path that holds the journal text files
#dir = ~/diary
# Number of years to show before/after todays date
@@ -277,112 +250,140 @@ editor =
#google_secretid =
# Google OAuth2 tokenfile
#google_tokenfile = ~/.diary-token
-EOF
-</pre>
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="Custom_Formatting"><a class="permalink" href="#Custom_Formatting">Custom
- Formatting</a></h1>
-The preview of the journal entries can be processed with a custom
- <b>--fmt-cmd</b>, <b>-F</b> or <b>fmt_cmd</b> in the configuration file.
-<div class="Pp"></div>
-The result of this formatting command is printed to a pseudo-terminal (pty) by
- default (behavior can be changed with the <b>--no-pty</b> flag).
-<div class="Pp"></div>
-The output processed on the pty (not with Ncurses, without <b>--no-pty</b> flag)
- includes all ANSI escape characters supported by the terminal (colors, font
- types, etc.).
-<div class="Pp"></div>
-Thus, formatters like <b>fmt</b> or any "cat like program" such as
- mdcat to process Markdown can be plugged in for <b>--fmt-cmd</b>.
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="MOUSE_EVENTS"><a class="permalink" href="#MOUSE_EVENTS">MOUSE
+EOF</pre>
+</div>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="CUSTOM_FORMATTING"><a class="permalink" href="#CUSTOM_FORMATTING">CUSTOM
+ FORMATTING</a></h1>
+<p class="Pp">The preview of the journal entries can be processed with a custom
+ <b>--fmt-cmd</b>. The result of this formatting command is printed to a
+ pseudo-terminal (pty) by default. This behavior can be changed with the
+ <b>--no-pty</b> flag. The output processed on the pty (without Ncurses)
+ includes all ANSI escape characters supported by the terminal (colors, font
+ types, etc.). Thus, formatters like "fmt", or any "cat like
+ program" ("mdcat" to process Markdown) can be plugged in for
+ <b>--fmt-cmd</b>.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="MOUSE_EVENTS"><a class="permalink" href="#MOUSE_EVENTS">MOUSE
EVENTS</a></h1>
-Mouse events are listened for by default (no_mouse=false). This behavior can be
- disabled with the <b>--no-mouse</b> flag or in the configuration file
- (no_mouse=true).
-<div class="Pp"></div>
-With no_mouse=false (default), use the <b>SHIFT key</b> for native text
- selection and right-click in the preview window.
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="PRECEDENCE_RULES"><a class="permalink" href="#PRECEDENCE_RULES">PRECEDENCE
+<p class="Pp">Mouse events are listened for by default (<b>no_mouse</b>=false
+ configuration). This behavior can be disabled with the <b>--no-mouse</b>
+ flag or in the configuration file (<b>no_mouse</b>=true). With
+ <b>no_mouse</b>=false (default), use the SHIFT key for native text selection
+ and right-click in the preview window.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="PRECEDENCE_RULES"><a class="permalink" href="#PRECEDENCE_RULES">PRECEDENCE
RULES</a></h1>
-The default variables, for instance, for the configuration variables
- ´editor´, ´dir´ and ´weekday´, are
- populated with values in the following order:
-<div class="Pp"></div>
-<dl class="Bl-tag">
- <dt>1.</dt>
- <dd>No default for ´DIARY_DIR´. Defaults for
- ´range´, ´weekday´, ´fmt´ and
- ´editor´ are provided in ´diary.h´. If
- ´EDITOR´ is unset and no editor is provided in the config
- file or via the ´-e´ option, the <b>diary</b> works
- read-only. Journal files cannot be opened. If ´DIARY_DIR´ is
- not provided, the <b>diary</b> won't open.</dd>
-</dl>
-<dl class="Bl-tag">
- <dt>2.</dt>
- <dd><b>Config file</b> (empty default for ´editor´, no default
- for ´dir´)</dd>
-</dl>
-<dl class="Bl-tag">
- <dt>3.</dt>
- <dd><b>Environment</b> variables ´$DIARY_DIR´,
- ´$EDITOR´ and ´$LANG´ for locale
- (´weekday´)</dd>
-</dl>
-<dl class="Bl-tag">
- <dt>4.</dt>
- <dd><b>Option</b> arguments, see section <b>OPTIONS</b></dd>
-</dl>
-<dl class="Bl-tag">
- <dt>5.</dt>
- <dd>First non-option argument <i>DIRECTORY</i> is interpreted as
- ´DIARY_DIR´
- <div class="Pp"></div>
- </dd>
-</dl>
-<h1 class="Sh" title="Sh" id="PRECEDENCE_EXAMPLE:_LOCALE_AND_FIRST_DAY_OF_WEEK"><a class="permalink" href="#PRECEDENCE_EXAMPLE:_LOCALE_AND_FIRST_DAY_OF_WEEK">PRECEDENCE
+<p class="Pp">The default variables, for instance, for the configuration
+ variables "editor", "dir" and "weekday", are
+ populated with values in the following order:</p>
+<p class="Pp"></p>
+<table class="tbl" border="1" style="border-style: solid;">
+ <tr>
+ <td><b>Priority</b></td>
+ <td><b>Description</b></td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>No default for <b>DIARY_DIR</b>. Defaults for "range",
+ "weekday", "fmt" and "editor" are provided
+ in "diary.h". If <b>EDITOR</b> is unset and no editor is
+ provided in the configuration file or <b>--editor</b> option, the diary
+ works read-only. Journal files cannot be opened. If <b>DIARY_DIR</b> is
+ not provided, the diary won't open.</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td><b>CONFIGURATION FILE</b> (empty default for "editor", no
+ default for "dir")</td>
+ </tr>
+ <tr>
+ <td>3</td>
+ <td>Environment variables $DIARY_DIR, $EDITOR and $LANG for locale
+ ("weekday")</td>
+ </tr>
+ <tr>
+ <td>4</td>
+ <td>Option arguments, see section <b>OPTIONS</b></td>
+ </tr>
+ <tr>
+ <td>5</td>
+ <td>First non-option argument is interpreted as <b>DIARY_DIR</b></td>
+ </tr>
+</table>
+<p class="Pp"></p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="PRECEDENCE_EXAMPLE:_LOCALE_AND_FIRST_DAY_OF_WEEK"><a class="permalink" href="#PRECEDENCE_EXAMPLE:_LOCALE_AND_FIRST_DAY_OF_WEEK">PRECEDENCE
EXAMPLE: LOCALE AND FIRST DAY OF WEEK</a></h1>
-If glibc is installed, the first weekday defaults to the locale defined in the
- current shell environment ($LANG, see man locale), unless specified otherwise
- via the ´--weekday´/´-w´.
-<div class="Pp"></div>
-<pre>
-# start with weekday=3(Wed), overrule any other configuration value
-diary -w3
-<div class="Pp"></div>
-# start with glibc derived weekday=1, regardless of ´weekday´ in config file
-LANG=de_CH diary
-<div class="Pp"></div>
-# if glibc is installed, start with glibc derived base date (weekday=0)
-LANG= diary
-<div class="Pp"></div>
-# disable environment variable, default to value from config file
-unset LANG
-<div class="Pp"></div>
-# start with ´weekday´ default from config file, if available
-diary
-<div class="Pp"></div>
-# remove config file
-rm ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg
-<div class="Pp"></div>
-# start with ´weekday´ default value from source code (1=Mon)
-diary
-</pre>
-<div class="Pp"></div>
-<h1 class="Sh" title="Sh" id="DEVELOPMENT"><a class="permalink" href="#DEVELOPMENT">DEVELOPMENT</a></h1>
-Contributions are always welcome! All source code is available at
- https://codeberg.org/in0rdr/diary.
-<div class="Pp"></div>
-<dl class="Bl-tag">
- <dt>For question and support visit https://web.libera.chat/gamja/#diary.</dt>
- <dd></dd>
-</dl>
+<p class="Pp">If glibc is installed, the first weekday defaults to the locale
+ defined in the current shell environment ($LANG, see man locale), unless
+ specified otherwise with the <b>--weekday</b> option.</p>
+<p class="Pp">Start with weekday=3(Wed), overrule any other configuration
+ value:</p>
+<div class="Bd-indent">
+<pre>diary -w3</pre>
+</div>
+<p class="Pp">Start with glibc derived weekday=1, regardless of weekday in
+ config file:</p>
+<div class="Bd-indent">
+<pre>LANG=de_CH diary</pre>
+</div>
+<p class="Pp">If glibc is installed, start with glibc derived base date
+ (weekday=0):</p>
+<div class="Bd-indent">
+<pre>LANG= diary</pre>
+</div>
+<p class="Pp">Disable environment variable, default to value from config
+ file:</p>
+<div class="Bd-indent">
+<pre>unset LANG</pre>
+</div>
+<p class="Pp">Start with weekday default from config file, if available:</p>
+<div class="Bd-indent">
+<pre>diary</pre>
+</div>
+<p class="Pp">Remove config file:</p>
+<div class="Bd-indent">
+<pre>rm ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg</pre>
+</div>
+<p class="Pp">Start with weekday default value from source code (1=Mon):</p>
+<div class="Bd-indent">
+<pre>diary</pre>
+</div>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="DEVELOPMENT_AND_SUPPORT"><a class="permalink" href="#DEVELOPMENT_AND_SUPPORT">DEVELOPMENT
+ AND SUPPORT</a></h1>
+<p class="Pp">Contributions are always welcome! All source code is available at
+ https://codeberg.org/in0rdr/diary.</p>
+<p class="Pp">For question and support visit
+ https://web.libera.chat/gamja/#diary.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
+<div class="Bd-indent">•Andreas Gruhler
+ (https://codeberg.org/in0rdr/diary)</div>
+<div class="Bd-indent">•Matthias Beyer
+ (https://github.com/matthiasbeyer)</div>
+<div class="Bd-indent">•Johnathan Jenkins
+ (https://github.com/shaggytwodope)</div>
+<div class="Bd-indent">•Yu-Jie Lin (https://github.com/livibetter)</div>
+<div class="Bd-indent">•Balduin Dettling (https://github.com/mbjd)</div>
+<div class="Bd-indent">•Avindra Goolcharan
+ (https://github.com/avindra)</div>
+<div class="Bd-indent">•Oliver Blanthorn
+ (https://github.com/bovine3dom)</div>
+<div class="Bd-indent">•Jonny Burger
+ (https://github.com/JonnyBurger)</div>
+</section>
</div>
<table class="foot">
<tr>
- <td class="foot-date"></td>
+ <td class="foot-date">2022-01-08</td>
<td class="foot-os"></td>
</tr>
</table>
diff --git a/man1/diary.1.scd b/man1/diary.1.scd
@@ -0,0 +1,299 @@
+DIARY(1)
+
+# NAME
+
+diary - text-based journaling program
+
+# SYNOPSIS
+
+*diary* [OPTION]... [DIARY_DIR]...
+
+# DESCRIPTION
+Open the *diary* journal for entries stored in DIARY_DIR.
+
+DIARY_DIR is required, if not set as environment variable or defined in the
+configuration file.
+
+# OPTIONS
+
+*-v, --version*
+
+ Print diary version
+
+*-h, --help*
+
+ Show diary help text
+
+*-d, --dir*=DIARY_DIR
+
+ Directory with the journal text files
+
+*-e, --editor*=EDITOR
+
+ Text editor used for opening the journal files
+
+*-f, --fmt*=FMT
+
+ FMT is a custom date and file format. Change with care, because the
+ diary reads and writes to files with file name FMT. The new FMT is only
+ applied to newly saved entries. Existing entries with the old FMT are
+ not automatically migrated to the new FMT and do not show up with a new
+ FMT specifier. Consequently, a change in FMT shows an empty diary at
+ first. Rename all files in the *DIARY_DIR* to migrate to a new FMT.
+
+*-F, --fmt-cmd*=FMT_CMD
+
+ Journal entries are formatted with this command. If not set (default),
+ the characters are printed to the preview screen character by character
+ (without word wrap). For example, to enable word wrap after 75
+ characters, use "fmt -s" as FMT_CMD. To format markdown, use "mdcat -c"
+ or similar, see *CUSTOM FORMATTING*.
+
+*-p, --no-pty*
+
+ No pseudo terminal (pty) for entry preview. Only effective in
+ combination with *--fmt-cmd*. If set, the output of *--fmt-cmd* is displayed
+ with Ncurses. If not set (default), the result of *--fmt-cmd* (journal
+ entry preview) is printed on a pseudo-terminal (pty) and not processed
+ with Ncurses. The pty supports the ANSI escape sequences (e.g. colors,
+ font types, etc.) of the native terminal.
+
+*-m, --no-mouse*
+
+ Disable mouse, don't listen for mouse events. Mouse events are enabled
+ by default. Without *--no-mouse* flag (default), native text selection and
+ right-click in the preview window requires holding down the SHIFT key,
+ see *MOUSE EVENTS*.
+
+*-r, --range*=RANGE
+
+ The number of years to show before/after today. Defaults to 1 year.
+
+*-f, --weekday*=DAY
+
+ First day of the week. DAY is an integer in range (0..6), interpreted as
+ 0 or 7 = Sun, 1 = Mon, ..., 6 = Sat. If glibc is installed, the first
+ day of the week is derived from the current locale setting ($LANG, see
+ man locale). Without glibc, the first weekday defaults to 1 (Monday),
+ unless specified otherwise with this option.
+
+# NAVIGATION
+
+Navigation is done using the following vim-inspired keyboard shortcuts:
+
+[[ *Key(s)*
+:< Action
+| *e, Enter*
+: edit current entry
+| *d, x*
+: delete current entry
+| *t*
+: jump to today
+| *f*
+: jump to or find specific day
+| *j, down*
+: go forward by 1 week
+| *k, up*
+: go backward by 1 week
+| *h, left*
+: go left by 1 day
+| *l, right*
+: go right by 1 day
+| *J*
+: go forward by 1 month
+| *K*
+: go backward by 1 month
+| *N*
+: go to the previous journal entry
+| *n*
+: go to the next journal entry
+| *g*
+: go to start of journal
+| *G*
+: go to end of journal
+| *q*
+: quit the program
+
+
+Alpha features:
+
+[[ *Key(s)*
+:< Action
+| *s, S*
+: sync selected/all with CalDAV server
+| *i*
+: import entries from .ics file
+| *e*
+: export entries to .ics file
+
+
+# ENVIRONMENT
+
+*DIARY_DIR*
+ If this variable is set to a directory that can be opened, diary will
+ use it to store diary files. Diary files are simple text files named
+ after their date, formatted according to *FMT* (see *--fmt* option). The
+ format defaults to "%Y-%m-%d", which is "YYYY-MM-DD" (see man strftime).
+ All other files different from FMT are ignored.
+
+*EDITOR*
+ The program used to edit journal entries inside *DIARY_DIR*.
+
+*LANG*
+ The default locale used to display the first day of the week, see
+ *--weekday* option.
+
+
+
+# ARGUMENTS
+
+If the argument *DIARY_DIR* is given, diary files are read from and stored to
+that directory, ignoring the $DIARY_DIR environment variable, any *--dir* option
+or the *dir* value set in the *CONFIGURATION FILE*.
+
+# FILES
+
+${PREFIX:-/usr/local/bin}/*diary*
+ The diary binary
+
+${XDG_CONFIG_HOME:-~/.config}/diary/*diary.cfg*
+ An optional diary *CONFIGURATION FILE*
+
+# CONFIGURATION FILE
+
+The *diary.cfg* configuration file can optionally be used to persist diary
+configuration. Use the "#" or ";" characters to comment lines.
+
+Create default configuration location:
+
+```
+mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary
+```
+
+Install an example configuration file with defaults:
+
+```
+tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
+# Path that holds the journal text files
+#dir = ~/diary
+# Number of years to show before/after todays date
+range = 1
+# 0 = Sunday, 1 = Monday, ..., 6 = Saturday
+weekday = 1
+# Date and file format, change with care
+fmt = %Y-%m-%d
+# Text format command for entry preview
+fmt_cmd =
+# Use pseudo terminal (pty) to view result of fmt_cmd
+#no_pty = false
+# Listen for mouse events
+#no_mouse = false
+# Editor to open journal files with
+editor =
+# Google calendar name for CalDAV sync
+#google_calendar =
+# Google OAuth2 clientid and secretid
+#google_clientid =
+#google_secretid =
+# Google OAuth2 tokenfile
+#google_tokenfile = ~/.diary-token
+EOF
+```
+
+# CUSTOM FORMATTING
+
+The preview of the journal entries can be processed with a custom *--fmt-cmd*.
+The result of this formatting command is printed to a pseudo-terminal (pty) by
+default. This behavior can be changed with the *--no-pty* flag. The output
+processed on the pty (without Ncurses) includes all ANSI escape characters
+supported by the terminal (colors, font types, etc.). Thus, formatters like
+"fmt", or any "cat like program" ("mdcat" to process Markdown) can be plugged in
+for *--fmt-cmd*.
+
+# MOUSE EVENTS
+
+Mouse events are listened for by default (*no_mouse*=false configuration). This
+behavior can be disabled with the *--no-mouse* flag or in the configuration file
+(*no_mouse*=true). With *no_mouse*=false (default), use the SHIFT key for native
+text selection and right-click in the preview window.
+
+# PRECEDENCE RULES
+
+The default variables, for instance, for the configuration variables "editor",
+"dir" and "weekday", are populated with values in the following order:
+
+[[ *Priority*
+:< *Description*
+| 1
+: No default for *DIARY_DIR*. Defaults for "range", "weekday", "fmt" and
+ "editor" are provided in "diary.h". If *EDITOR* is unset and no editor is
+ provided in the configuration file or *--editor* option, the diary works
+ read-only. Journal files cannot be opened. If *DIARY_DIR* is not provided, the
+ diary won't open.
+| 2
+: *CONFIGURATION FILE* (empty default for "editor", no default for "dir")
+| 3
+: Environment variables $DIARY_DIR, $EDITOR and $LANG for locale ("weekday")
+| 4
+: Option arguments, see section *OPTIONS*
+| 5
+: First non-option argument is interpreted as *DIARY_DIR*
+
+# PRECEDENCE EXAMPLE: LOCALE AND FIRST DAY OF WEEK
+
+If glibc is installed, the first weekday defaults to the locale defined in the
+current shell environment ($LANG, see man locale), unless specified otherwise
+with the *--weekday* option.
+
+Start with weekday=3(Wed), overrule any other configuration value:
+```
+diary -w3
+```
+
+Start with glibc derived weekday=1, regardless of weekday in config file:
+```
+LANG=de_CH diary
+```
+
+If glibc is installed, start with glibc derived base date (weekday=0):
+```
+LANG= diary
+```
+
+Disable environment variable, default to value from config file:
+```
+unset LANG
+```
+
+Start with weekday default from config file, if available:
+```
+diary
+```
+
+Remove config file:
+```
+rm ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg
+```
+
+Start with weekday default value from source code (1=Mon):
+```
+diary
+```
+
+# DEVELOPMENT AND SUPPORT
+
+Contributions are always welcome! All source code is available at
+https://codeberg.org/in0rdr/diary.
+
+For question and support visit https://web.libera.chat/gamja/#diary.
+
+# AUTHORS
+
+- Andreas Gruhler (https://codeberg.org/in0rdr/diary)
+- Matthias Beyer (https://github.com/matthiasbeyer)
+- Johnathan Jenkins (https://github.com/shaggytwodope)
+- Yu-Jie Lin (https://github.com/livibetter)
+- Balduin Dettling (https://github.com/mbjd)
+- Avindra Goolcharan (https://github.com/avindra)
+- Oliver Blanthorn (https://github.com/bovine3dom)
+- Jonny Burger (https://github.com/JonnyBurger)
diff --git a/man1/style.css b/man1/style.css
@@ -0,0 +1,47 @@
+body {
+ max-width: 100ex;
+
+ font-family: monospace;
+ font-size: 14px;
+}
+
+.manual-text {
+ padding: 0 9ex 1ex 4ex;
+}
+
+.head, .foot {
+ width: 100%;
+ color: #999;
+}
+.head-vol {
+ text-align: center;
+}
+.head-rtitle {
+ text-align: right;
+}
+
+h1 {
+ font-size: 16px;
+}
+
+p {
+ text-align: justify;
+}
+.Bd-indent {
+ padding-left: 4ex;
+}
+
+.tbl {
+ border-collapse: collapse;
+}
+
+.tbl td {
+ border: 1px solid #999;
+ padding: 5px;
+}
+
+pre {
+ padding: 10px;
+ background: #434241;
+ color: #efefef;
+}
