commit 0141b441b3a42126458f6f7d7014cfcf6cd59dac
parent f22d3cf4a68156752702e049a94f48f3ef5c836c
Author: Andreas Gruhler <agruhl@gmx.ch>
Date: Sun, 2 Jan 2022 01:41:53 +0100
update docs
Diffstat:
4 files changed, 127 insertions(+), 41 deletions(-)
diff --git a/README.md b/README.md
@@ -118,8 +118,9 @@ The file `${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg` should adhere to a basi
| `--dir`, `-d`, or first non-option argument | `dir` | ~/diary | n/a | Diary directory. Path that holds the journal text files. If unset, defaults to environment variable `$DIARY_DIR`.|
| `--editor` or `-e` | `editor` | vim | (empty) | Editor to open journal files with. If unset, defaults to environment variable `$EDITOR`. If no editor is provided, the diary is opened read-only. |
| `--fmt` or `-f` | `fmt` | %d_%b_%y | %Y-%m-%d | Date format and file name for the files inside the `dir`. For the format specifiers, see [`man strftime`](https://man7.org/linux/man-pages/man3/strftime.3.html). Be careful: If you change this, you might no longer find your existing diary entries, because the diary assumes to find the journal files under another file name. Hence, a change in FMT shows an empty diary, at first. Rename all files in the DIARY_DIR to migrate to a new FMT. |
-| `--fmt-cmd` or `-F` | `fmt_cmd` | `fmt -w75 -s`, `mdcat -c` or `mdcat` | (empty) | 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. |
+| `--fmt-cmd` or `-F` | `fmt_cmd` | `fmt -w75 -s`, `mdcat -c` or `mdcat` | (empty) | 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. See also [Custom Formatting](#Custom-Formatting). |
| `--no-pty` or `-p` | `no_pty` | `true` | false (or 0) | No pseudo terminal (pty) for entry preview. Only effective in combination with `--fmt-cmd`. If set to true (or 1), the output of `--fmt-cmd` is displayed with Ncurses. If set to false (or 0), 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. |
+| `--no-mouse` or `-m` | `no_mouse` | `true` | false (or 0) | Don't listen for mouse events. With `no_mouse=false` (default), native text selection and right-click in the preview window requires holding down the `SHIFT` key, see [Mouse Events](#Mouse-Events). |
| `--range` or `-r` | `range` | 10 | 1 | Number of years to show before/after todays date |
| `--weekday` or `-w` | `weekday` | 0 | 1 | First weekday, `7` = Sunday, `1` = Monday, ..., `6` = Saturday. Use `7` (or `0`) to display week beginning at Sunday ("S-M-T-W-T-F-S"), or `1` for "M-T-W-T-F-S-S". 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. |
| n/a | `google_calendar` | diary | (empty) | Displayname of Google Calendar for [CalDAV sync](#CalDAV-sync) |
@@ -168,7 +169,7 @@ $ diary
## Custom Formatting
-The preview of the journal entries can be processed with a custom `--fmt-cmd`, `-F` or `fmt_cmd` in the [configuration file](#configuration-file).
+The preview of the journal entries can be processed with a custom `--fmt-cmd`, `-F` or `fmt_cmd` in the [configuration file](#Configuration-File).
The result of this formatting command is printed to a pseudo-terminal (pty) by default (behavior can be changed with the `--no-pty` flag).
@@ -176,6 +177,12 @@ The output processed on the pty (not with Ncurses, without `--no-pty` flag) incl
Thus, formatters like `fmt` or any "cat like program" such as [`mdcat`](https://github.com/lunaryorn/mdcat) to process Markdown can be plugged in for `--fmt-cmd`.
+## Mouse Events
+
+Mouse events are listened for by default ([`no_mouse=false`](#Configuration-File)). This behavior can be disabled with the [`--no-mouse` flag](#Configuration-File) or in the [configuration file](#Configuration-File).
+
+With `no_mouse=false` (default), use the `SHIFT` key for native text selection and right-click in the preview window.
+
## Import/Export (alpha)
> ⚠️ Alpha feature: Available only in `diary-nightly` (see [Installation Instructions](#Install)). Don't use this with "production" data.
diff --git a/config/diary.cfg b/config/diary.cfg
@@ -10,6 +10,8 @@ fmt = %Y-%m-%d
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
diff --git a/man1/diary.1 b/man1/diary.1
@@ -37,7 +37,8 @@ Rename all files in the DIARY_DIR to migrate to a new FMT.
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.
+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
@@ -47,13 +48,18 @@ 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
+from the current locale setting (\'$LANG\', see man locale). Without glibc, the
first weekday defaults to 1 (Monday), unless specified otherwise with this option.
.SH NAVIGATION
@@ -95,8 +101,8 @@ q | quit the program
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"
+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
@@ -109,7 +115,7 @@ The default locale used to display the first day of the week.
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.
+any \'-d\'/\'--dir\' options or the \'dir\' value set in the config file.
.SH FILES
.TP
@@ -121,7 +127,7 @@ An optional diary configuration file
.SH CONFIGURATION FILE
The diary.cfg configuration file can optionally be used to persist diary
-configuration. Use the '#' or ';' characters to comment lines.
+configuration. Use the \'#\' or \';\' characters to comment lines.
Create default config location:
@@ -146,6 +152,8 @@ fmt = %Y-%m-%d
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
@@ -158,16 +166,40 @@ editor =
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.
+
+.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.
+
.SH PRECEDENCE RULES
-The default variables, for instance, for the configuration variables 'editor', 'dir' and 'weekday', are populated with values in the following order:
+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
+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
+works read-only. Journal files cannot be opened. If \'DIARY_DIR\' is not provided, the
.B
diary
won't open.
@@ -175,12 +207,12 @@ won't open.
2.
.B
Config file
-(empty default for 'editor', no default for 'dir')
+(empty default for \'editor\', no default for \'dir\')
.TP
3.
.B
Environment
-variables '$DIARY_DIR', '$EDITOR' and '$LANG' for locale ('weekday')
+variables \'$DIARY_DIR\', \'$EDITOR\' and \'$LANG\' for locale (\'weekday\')
.TP
4.
.B
@@ -190,17 +222,18 @@ arguments, see section
OPTIONS
.TP
5.
-First non-option argument \fIDIRECTORY\fR is interpreted as 'DIARY_DIR'
+First non-option argument \fIDIRECTORY\fR is interpreted as \'DIARY_DIR\'
.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'.
+environment ($LANG, see man locale), unless specified otherwise via the \'--weekday\'/\'-w\'.
.nf
# start with weekday=3(Wed), overrule any other configuration value
diary -w3
-# start with glibc derived weekday=1, regardless of 'weekday' in config file
+# 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)
@@ -209,13 +242,13 @@ LANG= diary
# disable environment variable, default to value from config file
unset LANG
-# start with 'weekday' default from config file, if available
+# 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)
+# start with \'weekday\' default value from source code (1=Mon)
diary
.fi
diff --git a/man1/diary.1.html b/man1/diary.1.html
@@ -67,7 +67,7 @@ diary - Text-based journaling program
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.</dd>
+ -c" or similar, see <b>Custom Formatting</b>.</dd>
</dl>
<dl class="Bl-tag">
<dt><b>-p</b>, <b>--no-pty</b></dt>
@@ -79,6 +79,13 @@ diary - Text-based journaling program
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>
@@ -87,9 +94,9 @@ diary - Text-based journaling program
<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.
+ 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>
@@ -204,8 +211,11 @@ Navigation is done using the following vim-inspired keyboard shortcuts:
<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
- (see man strftime). All other files different from FMT are ignored.
+ 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>
@@ -224,7 +234,8 @@ Navigation is done using the following vim-inspired keyboard shortcuts:
<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.
+ ´-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">
@@ -240,7 +251,8 @@ If the argument <i>DIRECTORY</i> is given, diary files are read from and stored
<h1 class="Sh" title="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.
+ configuration. Use the ´#´ or ´;´ characters to
+ comment lines.
<div class="Pp"></div>
Create default config location:
<div class="Pp"></div>
@@ -265,6 +277,8 @@ fmt = %Y-%m-%d
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
@@ -277,27 +291,56 @@ editor =
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
+ 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
RULES</a></h1>
-The default variables, for instance, for the configuration variables 'editor',
- 'dir' and 'weekday', are populated with values in the following order:
+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>
+ <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>
+ <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>
+ <dd><b>Environment</b> variables ´$DIARY_DIR´,
+ ´$EDITOR´ and ´$LANG´ for locale
+ (´weekday´)</dd>
</dl>
<dl class="Bl-tag">
<dt>4.</dt>
@@ -305,7 +348,8 @@ The default variables, for instance, for the configuration variables 'editor',
</dl>
<dl class="Bl-tag">
<dt>5.</dt>
- <dd>First non-option argument <i>DIRECTORY</i> is interpreted as 'DIARY_DIR'
+ <dd>First non-option argument <i>DIRECTORY</i> is interpreted as
+ ´DIARY_DIR´
<div class="Pp"></div>
</dd>
</dl>
@@ -313,13 +357,13 @@ The default variables, for instance, for the configuration variables 'editor',
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'.
+ 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
+# 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)
@@ -328,13 +372,13 @@ LANG= diary
# disable environment variable, default to value from config file
unset LANG
<div class="Pp"></div>
-# start with 'weekday' default from config file, if available
+# 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)
+# start with ´weekday´ default value from source code (1=Mon)
diary
</pre>
<div class="Pp"></div>
