commit d07e1f31f1666981659a2e27cf5c01f2431571c8
parent 23fa3f038fd09507195b6eea89234e383d95a62d
Author: Andreas Gruhler <agruhl@gmx.ch>
Date: Mon, 20 Feb 2023 19:20:54 +0100
docs: reformat long lines and man page
Diffstat:
| M | AUTHORS.md | | | 1 | - |
| M | CHANGELOG.md | | | 13 | +++++++++---- |
| M | README.md | | | 217 | +++++++++++++++++++------------------------------------------------------------ |
| M | docs/OBS.md | | | 68 | ++++++++++++++++++++++++++++++++++++++++---------------------------- |
| M | docs/TESTING.md | | | 51 | +++++++++++++++++++++++++++++---------------------- |
| M | man1/diary.1 | | | 409 | ++++++++++++++++++++++++++++++++++++++++++++++++------------------------------- |
| M | man1/diary.1.html | | | 174 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------- |
| M | man1/diary.1.scd | | | 121 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------- |
8 files changed, 632 insertions(+), 422 deletions(-)
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -1,5 +1,4 @@
# Authors
-
- Andreas Gruhler (https://code.in0rdr.ch/diary)
- Matthias Beyer (https://github.com/matthiasbeyer)
- Johnathan Jenkins (https://github.com/shaggytwodope)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,19 +14,23 @@
## [0.6] - 2022-02-02
### Changed
-* Changed "s" shortcut logic: "s" no longer jumps to specific day (search), use "f" to "find" date (drop-in replacement). Use "s" to "sync" entries to Google calendar (CalDAV sync).
+* Changed "s" shortcut logic: "s" no longer jumps to specific day (search), use
+ "f" to "find" date (drop-in replacement). Use "s" to "sync" entries to Google
+ calendar (CalDAV sync).
* Move source code from GitHub to Codeberg
* Simplify man page generation with [scdoc](https://sr.ht/~sircmpwn/scdoc/)
* Fix segfault at a first run (#1)
### Added
* External text format command (#68, #80) `--fmt-cmd`
-* Pseudo-terminal to support ANSI escape characters (colors, font types, etc.) and `--no-pty` option (#6, #44, #5)
+* Pseudo-terminal to support ANSI escape characters (colors, font types, etc.)
+ and `--no-pty` option (#6, #44, #5)
* Mouse support for selecting dates (#60)
* Documentation of Open Build Service (OBS) jobs (`docs/OBS.md`)
* Documentation of testing and debugging procedures (`docs/TESTING.md`)
* Add `debug` target to `Makefile`
-* CalDAV sync: "s"/"S" shortcuts to sync selected day/Month with Google calendar
+* CalDAV sync: "s"/"S" shortcuts to sync selected day/Month with Google
+ calendar
* Import (#76, #77): "i" shortcut to import entries from .ics
* Export (#78): "E" shortcut to export entries to .ics
@@ -71,5 +75,6 @@
## [0.1] - 2016-11-24
### Notes
-* There is still a bug which appends '/' to the diary directory even if the trailing '/' is already given.
+* There is still a bug which appends '/' to the diary directory even if the
+ trailing '/' is already given.
* Removing entries not yet possible
diff --git a/README.md b/README.md
@@ -1,13 +1,9 @@
# Diary
+This is a text-based diary, inspired by [khal](https://github.com/pimutils/khal).
+Journal entries are stored in text files.
-This is a text-based diary, inspired by [khal](https://github.com/pimutils/khal). Journal entries are stored in text files.
+## Quickstart
-## Demo
-
-
-[Quickstart Tutorial](https://diary.in0rdr.ch)
-
-## Usage
1. Set the EDITOR environment variable to your favourite text editor:
```
export EDITOR=vim
@@ -18,11 +14,11 @@ This is a text-based diary, inspired by [khal](https://github.com/pimutils/khal)
diary ~/.diary
```
- Instead of this, you can also set the environment variable `DIARY_DIR`
- to the desired directory. If both an argument and the environment
- variable are given, the argument takes precedence (see [Variable Precedence Rules](#precedence_rules)).
+ Instead of this, you can also set the environment variable `DIARY_DIR` to
+ the desired directory. If both an argument and the environment variable are
+ given, the argument takes precedence.
- The text files in this folder will be named 'yyyy-mm-dd'.
+ The text files in this folder will be named `yyy-mm-dd`.
3. Use the keypad or VIM-like shortcuts to move between dates:
@@ -52,49 +48,62 @@ This is a text-based diary, inspired by [khal](https://github.com/pimutils/khal)
q quit the program
```
-Keybinding Cheat Sheet:
-
-
+## Detailed Usage, Configuration and End-User Documentation
+See [man diary](https://diary.in0rdr.ch/man) for the complete documentation.
-## Install
+Demo and Keybinding Cheat Sheet available at https://diary.in0rdr.ch
-Pre-built packages can be installed from the [Open Build Service (OBS)](https://software.opensuse.org/download.html?project=home%3Ain0rdr&package=diary)
+## Install from Package
+Pre-built packages can be installed from the [Open Build Service
+(OBS)](https://software.opensuse.org/download.html?project=home%3Ain0rdr&package=diary)
* Install the `diary` package for a stable release
-* Install the `diary-nightly` build to use a more recent but possibly unstable version from the master branch
+* Install the `diary-nightly` build to use a more recent but possibly unstable
+ version from the master branch
### Arch Linux OBS Repository Bug
+The Arch Linux repository on the OBS is broken, see
+[#69](https://github.com/in0rdr/diary/issues/69) and
+[#9953](https://github.com/openSUSE/open-build-service/issues/9953).
-The Arch Linux repository on the OBS is broken, see [#69](https://github.com/in0rdr/diary/issues/69) and [#9953](https://github.com/openSUSE/open-build-service/issues/9953).
+To use the repository on Arch Linux, use `downloadcontent.opensuse.org` instead
+of the [suggested](https://software.opensuse.org/download.html?project=home%3Ain0rdr&package=diary)
+name `download.opensuse.org` in the `/etc/pacman.conf`:
-To use the repository on Arch Linux, use `downloadcontent.opensuse.org` instead of the [suggested](https://software.opensuse.org/download.html?project=home%3Ain0rdr&package=diary) name `download.opensuse.org` in the `/etc/pacman.conf`:
```
[home_in0rdr_Arch]
Server = https://downloadcontent.opensuse.org/repositories/home:/in0rdr/Arch/$arch
```
## Build from Source
+1. Define [OAuth2 application credentials](https://developers.google.com/identity/protocols/oauth2)
+ if CalDAV sync should be effective:
-1. Define [OAuth2 application credentials](https://developers.google.com/identity/protocols/oauth2) if CalDAV sync should be effective:
- ```
- export GOOGLE_OAUTH_CLIENT_ID=""
- export GOOGLE_OAUTH_CLIENT_SECRET=""
- ```
+ ```
+ export GOOGLE_OAUTH_CLIENT_ID=""
+ export GOOGLE_OAUTH_CLIENT_SECRET=""
+ ```
- Alternatively, leave these two variables unset and [define the clientid/secret in the configuration file](#Google-Calendar-OAuth2) at run-time.
+ Alternatively, leave these two variables unset and define the
+ clientid/secret in the configuration file at run-time (see diary man page).
-2. The compilation step requires development libraries for `ncurses`, `libcurl` and `liblttng-ust`. These packages might have a slightly different naming scheme depending on the distribution. To compile, run:
- ```
- make
- ```
-Note: for *BSD users run gmake.
+2. The compilation step requires development libraries for `ncurses`, `libcurl`
+ and `liblttng-ust`. These packages might have a slightly different naming
+ scheme depending on the distribution. To compile, run:
+
+ ```
+ make
+ ```
+
+ Note: for \*BSD users run gmake.
3. Install the binary (optional):
- ```
- sudo make install
- ```
- By default this will copy the binary to /usr/local/bin. To use a different
- path prefix, type `sudo make PREFIX=/usr install` to use /usr/bin for example.
+ ```
+ sudo make install
+ ```
+
+ By default this will copy the binary to `/usr/local/bin`. To use a different
+ path prefix, type `sudo make PREFIX=/usr install` to use `/usr/bin` for example.
You can uninstall diary with `sudo make uninstall`.
## OBS Build Documentation
@@ -103,140 +112,16 @@ Note: for *BSD users run gmake.
## Test Documentation
[./docs/TESTING.md](./docs/TESTING.md)
-## Configuration File
-
-The [`diary.cfg`](./config/diary.cfg) configuration file can optionally be used to persist diary configuration. To install the sample from this repository:
-```bash
-mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary
-cp config/diary.cfg ${XDG_CONFIG_HOME:-~/.config}/diary/
-```
-
-The file `${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg` should adhere to a basic `key = value` format. Lines can be commented with the special characters `#` or `;`. The following configuration keys are currently supported:
-
-| Command Line Option | Config Key | Example Config Value | Default Config Value | Description |
-| --- | --- | --- | --- | --- |
-| `--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. 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) |
-| n/a | `google_clientid` | 123-123.apps.googleusercontent.com | [built-in](#Build) / (empty) | Google Calendar for [Google Calendar OAuth2](#Google-Calendar-OAuth2) clientid |
-| n/a | `google_secretid` | 321 | [built-in](#Build) / (empty) | Google Calendar for [Google Calendar OAuth2](#Google-Calendar-OAuth2) secretid |
-| n/a | `google_tokenfile` | ~/.diary-token | ~/.diary-token | Displayname of Google Calendar for [Google Calendar OAuth2](#Google-Calendar-OAuth2) API token file|
-
-## Precedence Rules
-<a name="precedence_rules"></a>
-
-The default variables, for instance, for the configuration variables `editor`, `dir` and `weekday`, are populated with values in the following order, where earlier entries are overwritten by subsequent ones if they exist:
-1. No default for `DIARY_DIR`. Defaults for `range`, `weekday`, `fmt` and `editor` are provided in [diary.h](diary.h). If `EDITOR` is unset and no editor is provided in the config file or via the `-e` 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** `-d` / `-e` / `-w`
-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 via the `--weekday` / `-w` command line options. For example:
-
-```bash
-# 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
-```
-
-## 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 result of this formatting command is printed to a pseudo-terminal (pty) by default (behavior can be changed with the `--no-pty` flag).
-
-The output processed on the pty (not with Ncurses, without `--no-pty` flag) includes all ANSI escape characters supported by the terminal (colors, font types, etc.).
-
-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
-* The import functionality can be triggered by pressing `i`.
-* The export functionality can be triggered by pressing `E`.
-
-## CalDAV Sync
-The journal files can be synced via CalDAV by pressing `s`. Pressing `S` syncs all journal entries of the active month.
-
-Use the export/import functionality for more batch oriented processing. Making a network request and deciding the most recently modified entry (local/remote) takes quite some time for larger batches of entries.
-
-The most recently modified entry is considered up to date and is automatically replaced on the remote side. If the remote file is more recent, the local file can be replaced with the remote content after confirmation.
-
-No sync is performed, when both files (local/remote) have the same last modified timestamp or no files exists on the server and on disk at all (i.e., no entry for that date).
-
-Currently, only the Google Calendar is supported as remote provider.
-
-The calender for synchronization can be defined with the [configuration](#Configuration-File) key `google_calendar`:
-```
-# Google calendar name for CalDAV sync
-google_calendar = example
-```
-
-This key is empty by default.
-
-### Google Calendar OAuth2
-
-The Google Calendar [CalDAV API is protected with OAuth2](https://developers.google.com/identity/protocols/oauth2).
-
-The credentials and the consent screen can be redefined at [compile time](#Build) or with the following keys in the [configuration file](#Configuration-File):
-
-```
-# Google OAuth2 clientid and secretid
-google_clientid = 123-123.apps.googleusercontent.com
-google_secretid = 321
-```
-
-The token used to authenticate with the Google API is stored in the file specified by `google_tokenfile` (defaults to `~/.diary-token`) and renewed automatically:
-```
-# Google OAuth2 tokenfile
-google_tokenfile = ~/.diary-token
-```
-
-The application requires two [OAuth2 scopes](https://developers.google.com/calendar/auth) for CalDAV requests:
-
-1. `https://www.googleapis.com/auth/calendar`: read/write access to Calendars - required to discover the unique hyperlink/URI for the calendar specified by the [configuration key](#Configuration-File) `google_calendar`
-2. `https://www.googleapis.com/auth/calendar.events.owned`: read/write access to Events owned by the user - allows diary to create/read/update/delete events in `google_calendar`
-
-## License
-
-This work uses the MIT License. See [LICENSE](./LICENSE) for details.
-
## Contributors
-
-All source code is available in this repository. Contributions are always welcome!
+All source code is available in this repository. Contributions are always
+welcome!
For a list of contributors see the [AUTHORS.md](./AUTHORS.md).
## Community and Support
+For question and support visit
+[#diary/libera](https://web.libera.chat/gamja/#diary) on IRC.
+
+## License
+This work uses the MIT License. See [LICENSE](./LICENSE) for details.
-For question and support visit [#diary/libera](https://web.libera.chat/gamja/#diary) on IRC.
diff --git a/docs/OBS.md b/docs/OBS.md
@@ -1,19 +1,23 @@
# Documentation for OBS Builds
-
-The OBS project [`home:in0rdr`](https://build.opensuse.org/project/show/home:in0rdr) comprises following `diary` packages:
+The OBS project [`home:in0rdr`](https://build.opensuse.org/project/show/home:in0rdr)
+comprises following `diary` packages:
* `diary`: Latest stable release built from tar.gz statically placed in the source
-* `diary-nightly`: Latest unstable build, re-built sporadically (manual action) from the code on the master branch
-
-> ℹ️ `diary-nightly` is not branched from `diary`, it has a completely separate build config.
+* `diary-nightly`: Latest unstable build, re-built sporadically (manual action)
+ from the code on the master branch
-Additionally, these packages are being used as dependency for `diary-nightly`, to download the latest diary source code from the master branch:
-* [`openSUSE:Tools/obs-service-tar_scm`](https://github.com/openSUSE/obs-service-tar_scm): Use `obs_scm` to fetch latest sources
+> ℹ️ `diary-nightly` is not branched from `diary`, it has a completely separate
+> build config.
-* [`openSUSE:Tools/obs-service-recompress`](https://github.com/openSUSE/obs-service-recompress): Re-compress downloaded source files
-* [`openSUSE:Tools/obs-service-set_version`](https://github.com/openSUSE/obs-service-set_version): Set dynamic version based on information (`.obsinfo` file) from the GitHub checkout
+Additionally, these packages are being used as dependency for `diary-nightly`,
+to download the latest diary source code from the master branch:
+* [`openSUSE:Tools/obs-service-tar_scm`](https://github.com/openSUSE/obs-service-tar_scm):
+ Use `obs_scm` to fetch latest sources
+* [`openSUSE:Tools/obs-service-recompress`](https://github.com/openSUSE/obs-service-recompress):
+ Re-compress downloaded source files
+* [`openSUSE:Tools/obs-service-set_version`](https://github.com/openSUSE/obs-service-set_version):
+ Set dynamic version based on information (`.obsinfo` file) from the Git checkout
## OBS Project Configuration
-
```
# Disable obs_scm_testsuite for obs-service-set_version:
# https://github.com/openSUSE/obs-service-set_version/issues/64
@@ -27,18 +31,17 @@ Prefer: libzstd
```
## OBS Source Services (`obs-service-`) Documentation
-
The documentation on how to use source services is sparse and scattered:
* https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.source_service.html
* https://github.com/openSUSE/obs-service-tar_scm/issues/238
* https://github.com/openSUSE/obs-service-tar_scm/issues/223
-* https://build.opensuse.org/package/view_file/OBS:Server:Unstable/obs-service-tar_scm/_service?expand=1
+* https://build.opensuse.org/package/view_file/OBS:Server:Unstable/obs-service-tar_scm/\_service?expand=1
-The purpose of the source services and how they are used for the `diary-nightly` build (dependencies) is documented below.
+The purpose of the source services and how they are used for the
+`diary-nightly` build (dependencies) is documented below.
### `openSUSE:Tools/obs-service-tar_scm`
-
Fix build for CentOS 8 by applying this patch in `obs-service-tar_scm.spec`:
* https://github.com/openSUSE/obs-service-tar_scm/issues/374
* https://github.com/olegantonyan/obs-service-tar_scm/commit/6a454aa71395ca03a737d795551ba027a5f8a9e3
@@ -73,21 +76,24 @@ Applying the latest version fixes the following issue:
[ 2s] failed to prepare sources
```
-The following patch might be related (needs to be applied OBS server-side, nothing left to do):
+The following patch might be related (needs to be applied OBS server-side,
+nothing left to do):
https://github.com/openSUSE/obs-build/pull/696
### `openSUSE:Tools/obs-service-recompress`
-
https://github.com/openSUSE/obs-service-recompress
-Branched package from [`openSUSE:Tools/obs-service-recompress`](https://build.opensuse.org/package/show/openSUSE:Tools/obs-service-recompress).
+Branched package from
+[`openSUSE:Tools/obs-service-recompress`](https://build.opensuse.org/package/show/openSUSE:Tools/obs-service-recompress).
-If this package is not made available in the local project `home:in0rdr`, following error message will occur:
+If this package is not made available in the local project `home:in0rdr`,
+following error message will occur:
```
nothing provides obs-service-recompress
```
-No further modifications needed, but needs to be available for the `diary-nightly` for compression services:
+No further modifications needed, but needs to be available for the
+`diary-nightly` for compression services:
```bash
# home:in0rdr/diary-nightly/_service
<services>
@@ -99,18 +105,20 @@ No further modifications needed, but needs to be available for the `diary-nightl
</services>
```
-This service is used in combination with the service [`tar_scm`](https://github.com/openSUSE/obs-service-tar_scm).
+This service is used in combination with the service
+[`tar_scm`](https://github.com/openSUSE/obs-service-tar_scm).
### `openSUSE:Tools/obs-service-set_version`
-
-This service sets the version in the RPM spec or Debian changelog according to the latest downloaded source files:
+This service sets the version in the RPM spec or Debian changelog according to
+the latest downloaded source files:
https://github.com/openSUSE/obs-service-set_version
### `openSUSE:Factory/zstd` OBS Package
+> ℹ️ This OBS package is not strictly required (no branching needed) with
+> `tar.gz` compression in the source service (`_service`).
-> ℹ️ This OBS package is not strictly required (no branching needed) with `tar.gz` compression in the source service (`_service`).
-
-Patch `zstd.spec`, such that RHEL build require `glibc-static` and openSUSE builds require `glibc-devel-static`:
+Patch `zstd.spec`, such that RHEL build require `glibc-static` and openSUSE
+builds require `glibc-devel-static`:
```diff
- BuildRequires: (glibc-static or glibc-devel-static)
+ %if 0%{?rhel} || 0%{?fedora}
@@ -121,8 +129,9 @@ Patch `zstd.spec`, such that RHEL build require `glibc-static` and openSUSE buil
```
## `zstd` Compression in the ArchLinux PKGBUILD
-
-If `diary-nightly` for ArchLinux is built with `tar.gz` compression, the build will not be shown on the [download page](https://software.opensuse.org//download.html?project=home%3Ain0rdr&package=diary-nightly) and the download button for ArchLinux is missing, see also:
+If `diary-nightly` for ArchLinux is built with `tar.gz` compression, the build
+will not be shown on the [download page](https://software.opensuse.org//download.html?project=home%3Ain0rdr&package=diary-nightly)
+and the download button for ArchLinux is missing, see also:
* https://github.com/in0rdr/diary/issues/64
* https://github.com/openSUSE/software-o-o/issues/844
* https://github.com/openSUSE/open-build-service/pull/10570
@@ -135,7 +144,10 @@ Therefore, build the ArchLinux package with the `.pkg.tar.zst` extension/compres
PKGEXT='.pkg.tar.zst'
```
-If the ZST compression (new defacto standard since [2020-01-04](https://archlinux.org/news/now-using-zstandard-instead-of-xz-for-package-compression)) does not work, use the xz compression as an alternative as described in [openSUSE/software-o-o/#844](https://github.com/openSUSE/software-o-o/issues/844):
+If the ZST compression (new defacto standard since
+[2020-01-04](https://archlinux.org/news/now-using-zstandard-instead-of-xz-for-package-compression))
+does not work, use the xz compression as an alternative as described in
+[openSUSE/software-o-o/#844](https://github.com/openSUSE/software-o-o/issues/844):
```
PKGEXT='.pkg.tar.xz'
diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -1,16 +1,14 @@
# Testing
-
This file holds notes for testing purposes.
## Compile with Debug Symbols
-
-To make a build with debug symbols (for example, required to run [Valgrind](#valgrind) below) use the `debug` target:
+To make a build with debug symbols (for example, required to run
+[Valgrind](#valgrind) below) use the `debug` target:
```bash
make debug
```
## Valgrind
-
Use Valgrind on a build with debug symbols to discover memory issues:
```bash
mkdir -p tmp-journal
@@ -24,8 +22,8 @@ Don't use `--show-leak-kinds=all` with Ncurses:
https://invisible-island.net/ncurses/ncurses.faq.html#config_leaks
## Compile with Clang Compiler
-
-As pointed out in [#82](https://github.com/in0rdr/diary/issues/82) the clang compiler is a lot more useful when it comes to debugging.
+As pointed out in [#82](https://github.com/in0rdr/diary/issues/82) the clang
+compiler is a lot more useful when it comes to debugging.
To compile the program with clang:
```
@@ -33,10 +31,13 @@ make CC=clang
```
## Linux Trace Toolkit (LTTng)
+> :information_source: For rapid debugging, use an LTTng live session, see
+> [LTTng Live Tracing](#lttng-live-tracing). This section is especially useful
+> for exporting the traces (in plain text) from a failed instance for support
+> (e.g., attach to issue).
-> :information_source: For rapid debugging, use an LTTng live session, see [LTTng Live Tracing](#lttng-live-tracing). This section is especially useful for exporting the traces (in plain text) from a failed instance for support (e.g., attach to issue).
-
-Logs from the debug build can be recorded in a [LTTng tracing session](https://lttng.org/docs/v2.13/#doc-start-sessiond).
+Logs from the debug build can be recorded in a [LTTng tracing
+session](https://lttng.org/docs/v2.13/#doc-start-sessiond).
Start the daemon in the background:
```
@@ -48,18 +49,21 @@ To start a new session use:
lttng create
```
-Create channel to capture the traces. The recording event rule below matches all user space tracepoint events of which the name starts with `diary:*`:
+Create channel to capture the traces. The recording event rule below matches
+all user space tracepoint events of which the name starts with `diary:*`:
```bash
lttng enable-event --userspace 'diary:*'
```
-To only show traces at least as severe as `--loglevel` or for a specific log level only:
+To only show traces at least as severe as `--loglevel` or for a specific log
+level only:
```bash
lttng enable-event --userspace 'diary:*' --loglevel=WARNING
lttng enable-event --userspace 'diary:*' --loglevel-only=INFO
```
-Build the debug diary with the [tracepoint provider package (tpp) shared object](https://lttng.org/docs/v2.13/#doc-building-tracepoint-providers-and-user-application):
+Build the debug diary with the [tracepoint provider package (tpp) shared
+object](https://lttng.org/docs/v2.13/#doc-building-tracepoint-providers-and-user-application):
```bash
make debug
...
@@ -89,15 +93,17 @@ Cleanup the session daemon once done:
killall lttng-sessiond
```
-An example (script) for viewing the traces is also given in [./trace.sh](./trace.sh).
+An example (script) for viewing the traces is also given in
+[./trace.sh](./trace.sh).
## LTTng Live Tracing
-
-[Live tracing](https://lttng.org/docs/v2.13/#doc-lttng-live) is more convenient for rapid debugging.
+[Live tracing](https://lttng.org/docs/v2.13/#doc-lttng-live) is more convenient
+for rapid debugging.
There is no need to stop the sessions to observe the logs.
-The setup is similar to the generic instructions above, but the session is created with the `--live` flave.
+The setup is similar to the generic instructions above, but the session is
+created with the `--live` flave.
```bash
lttng-sessiond -b
@@ -106,14 +112,16 @@ lttng start
lttng enable-event --userspace 'diary:*'
```
-Then start the diary with the shared object file in a new terminal to view the logs:
+Then start the diary with the shared object file in a new terminal to view the
+logs:
```bash
LD_PRELOAD=./libtpp.so ./diary
```
## Send stderr to File
-
-> :information_source: For proper tracing and logging, start diary with the LTTng tracepoint provider package (tpp) shared object file, see [LTTng](#linux-trace-toolkit-lttng).
+> :information_source: For proper tracing and logging, start diary with the
+> LTTng tracepoint provider package (tpp) shared object file, see
+> [LTTng](#linux-trace-toolkit-lttng).
Send stderr to a file for debugging:
```bash
@@ -126,7 +134,6 @@ diary 2>/dev/null
```
## Render Documentation / Man Page
-
### Generate Runoff
Install [scdoc](https://git.sr.ht/~sircmpwn/scdoc).
@@ -142,7 +149,8 @@ tbl diary.1 | nroff -man | less
```
### `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):
+Install [`mandoc`](https://en.wikipedia.org/wiki/Mandoc) >= [1.14.6 (helps to
+format paragraphs with CSS)](https://mandoc.bsd.lv/NEWS):
```bash
curl -sO https://mandoc.bsd.lv/snapshots/mandoc-1.14.6.tar.gz
tar -xf mandoc-1.14.6.tar.gz
@@ -157,7 +165,6 @@ Generate HTML page from runoff:
```
### `groff` HTML (Alternative)
-
Limitation: `groff` produces unstyled output (no CSS).
Install [`groff`](https://www.gnu.org/software/groff):
diff --git a/man1/diary.1 b/man1/diary.1
@@ -5,50 +5,47 @@
.nh
.ad l
.\" Begin generated content:
-.TH "DIARY" "1" "2022-08-21"
-.P
+.TH "DIARY" "1" "2023-02-20"
+.PP
.SH NAME
-.P
diary - text-based journaling program
-.P
+.PP
.SH SYNOPSIS
-.P
\fBdiary\fR [OPTION].\&.\&.\& [DIARY_DIR].\&.\&.\&
-.P
+.PP
.SH DESCRIPTION
Open the \fBdiary\fR journal for entries stored in \fBDIARY_DIR\fR.\&
-.P
+.PP
\fBDIARY_DIR\fR is required, if not set as environment variable or defined in the
\fBCONFIGURATION FILE\fR.\&
-.P
+.PP
.SH OPTIONS
-.P
\fB-v, --version\fR
-.P
+.PP
.RS 4
Print diary version
-.P
+.PP
.RE
\fB-h, --help\fR
-.P
+.PP
.RS 4
Show diary help text
-.P
+.PP
.RE
\fB-d, --dir\fR=DIARY_DIR
-.P
+.PP
.RS 4
Directory with the journal text files
-.P
+.PP
.RE
\fB-e, --editor\fR=EDITOR
-.P
+.PP
.RS 4
Text editor used for opening the journal files
-.P
+.PP
.RE
\fB-f, --fmt\fR=FMT
-.P
+.PP
.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
@@ -56,20 +53,20 @@ 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
+.PP
.RE
\fB-F, --fmt-cmd\fR=FMT_CMD
-.P
+.PP
.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.\&
-.P
+.PP
.RE
\fB-p, --no-pty\fR
-.P
+.PP
.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
@@ -77,37 +74,36 @@ 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.\&
-.P
+.PP
.RE
\fB-m, --no-mouse\fR
-.P
+.PP
.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
+.PP
.RE
\fB-r, --range\fR=RANGE
-.P
+.PP
.RS 4
The number of years to show before/after today.\& Defaults to 1 year.\&
-.P
+.PP
.RE
\fB-f, --weekday\fR=DAY
-.P
+.PP
.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
+.PP
.RE
.SH NAVIGATION
-.P
Navigation is done using the following vim-inspired keyboard shortcuts:
-.P
+.PP
.TS
allbox;l lx
l lx
@@ -225,9 +221,8 @@ quit the program
T}
.TE
.sp 1
-.P
+.PP
.SH ENVIRONMENT
-.P
\fBDIARY_DIR\fR
.RS 4
If this variable is set to a directory that can be opened, diary will
@@ -235,56 +230,54 @@ 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
+.PP
.RE
\fBEDITOR\fR
.RS 4
The program used to edit journal entries inside \fBDIARY_DIR\fR.\&
-.P
+.PP
.RE
\fBLANG\fR
.RS 4
The default locale used to display the first day of the week, see
\fB--weekday\fR option.\&
-.P
-.P
+.PP
+.PP
.RE
.SH ARGUMENTS
-.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
+.PP
.SH FILES
-.P
${PREFIX:-/usr/local/bin}/\fBdiary\fR
.RS 4
The diary binary
-.P
+.PP
.RE
${XDG_CONFIG_HOME:-~/.\&config}/diary/\fBdiary.\&cfg\fR
.RS 4
An optional diary \fBCONFIGURATION FILE\fR
-.P
+.PP
.RE
.SH CONFIGURATION FILE
-.P
The \fBdiary.\&cfg\fR configuration file can optionally be used to persist diary
configuration.\& Use the "#" or ";" characters to comment lines.\&
-.P
+.PP
Create default configuration location:
-.P
+.PP
.nf
.RS 4
mkdir -p ${XDG_CONFIG_HOME:-~/\&.config}/diary
.fi
.RE
-.P
+.PP
Install an example configuration file with defaults:
-.P
+.PP
.nf
.RS 4
tee ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg <<EOF
+# https://code\&.in0rdr\&.ch/diary/file/config/diary\&.cfg\&.html
# Path that holds the journal text files
#dir = ~/diary
# Number of years to show before/after todays date
@@ -311,9 +304,181 @@ editor =
EOF
.fi
.RE
-.P
+.PP
+To copy the sample file from the source repository:
+.PP
+.nf
+.RS 4
+cp config/diary\&.cfg ${XDG_CONFIG_HOME:-~/\&.config}/diary/
+.fi
+.RE
+.PP
+The file "${XDG_CONFIG_HOME:-~/.\&config}/diary/diary.\&cfg" should adhere to a
+basic "key = value" format.\& Lines can be commented with the special characters
+"#"or ";".\&
+.PP
+The following configuration keys are currently supported:
+.PP
+.TS
+allbox;l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx
+l lx lx lx lx.
+T{
+\fBCommand Line Option\fR
+T} T{
+\fBConfig Key\fR
+T} T{
+\fBExample Config Value\fR
+T} T{
+\fBDefault Config Value\fR
+T} T{
+\fBDescription\fR
+T}
+T{
+"--dir", "-d", or first non-option argument
+T} T{
+dir
+T} T{
+~/diary
+T} T{
+n/a
+T} T{
+Diary directory.\& Path that holds the journal text files.\& If unset, defaults to environment variable "$DIARY_DIR".\&
+T}
+T{
+"--editor" or "-e"
+T} T{
+editor
+T} T{
+vim
+T} T{
+(empty)
+T} T{
+Editor to open journal files with.\& If unset, defaults to environment variable "$EDITOR".\& If no editor is provided, the diary is opened read-only.\&
+T}
+T{
+"--fmt" or "-f"
+T} T{
+fmt
+T} T{
+%d_%b_%y
+T} T{
+%Y-%m-%d
+T} T{
+Date format and file name for the files inside the "dir".\& For the format specifiers, see "man strftime".\& 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.\&
+T}
+T{
+"--fmt-cmd" or "-F"
+T} T{
+fmt_cmd
+T} T{
+"fmt -w75 -s", "mdcat -c" or "mdcat"
+T} T{
+(empty)
+T} T{
+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).\&
+T}
+T{
+"--no-pty" or "-p"
+T} T{
+no_pty
+T} T{
+"true"
+T} T{
+false (or 0)
+T} T{
+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.\&
+T}
+T{
+"--no-mouse" or "-m"
+T} T{
+no_mouse
+T} T{
+"true"
+T} T{
+false (or 0)
+T} T{
+Don'\&t listen for \fBMOUSE EVENTS\fR.\& With no_mouse=0 (default), native text selection and right-click in the preview window requires holding down the "SHIFT" key.\&
+T}
+T{
+"--range" or "-r"
+T} T{
+range
+T} T{
+10
+T} T{
+1
+T} T{
+Number of years to show before/after todays date
+T}
+T{
+"--weekday" or "-w"
+T} T{
+weekday
+T} T{
+0
+T} T{
+1
+T} T{
+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.\&
+T}
+T{
+n/a
+T} T{
+google_calendar
+T} T{
+diary
+T} T{
+(empty)
+T} T{
+Displayname of Google Calendar for \fBCALDAV SYNC\fR
+T}
+T{
+n/a
+T} T{
+google_clientid
+T} T{
+123.\&com
+T} T{
+built-in at build time (see \fBGOOGLE CALENDAR OAUTH2\fR) or empty
+T} T{
+Google Calendar for \fBGOOGLE CALENDAR OAUTH2\fR clientid
+T}
+T{
+n/a
+T} T{
+google_secretid
+T} T{
+321
+T} T{
+built-in at build time (see \fBGOOGLE CALENDAR OAUTH2\fR) or empty
+T} T{
+Google Calendar for \fBGOOGLE CALENDAR OAUTH2\fR secretid
+T}
+T{
+n/a
+T} T{
+google_tokenfile
+T} T{
+~/.\&diary-token
+T} T{
+~/.\&diary-token
+T} T{
+\fBGOOGLE CALENDAR OAUTH2\fR API token file location
+T}
+.TE
+.sp 1
.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
@@ -321,97 +486,78 @@ 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
+.PP
.SH MOUSE EVENTS
-.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 \fBCONFIGURATION
FILE\fR (\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
+.PP
.SH IMPORT
-.P
The import functionality can be triggered by pressing \fBi\fR and expects a path to
an ics file.\& Files in the \fBDIARY_DIR\fR are overwritten with the entries from the
imported ics file.\&
-.P
+.PP
.SH EXPORT
-.P
The export functionality can be triggered by pressing \fBE\fR and asks for a file
path to an ics file for storing the journal entries.\& The ics file will be
created if it does not exist.\& Existing ics files are overwritten.\&
-.P
+.PP
.SH CALDAV SYNC
-.P
The journal files can be synced via CalDAV by pressing \fBs\fR.\& Pressing \fBS\fR syncs
all journal entries of the active month.\&
-.P
+.PP
The most recently modified entry is considered up to date and is automatically
replaced on the remote side.\& If the remote file is more recent, the local file
can be replaced with the remote content after confirmation.\&
-.P
+.PP
No sync is performed, when both files (local/remote) have the same modification
timestamp or no files exists on the server and on disk at all (i.\&e.\&, no entry
for that date).\&
-.P
+.PP
Use the EXPORT/IMPORT functionality for more batch oriented processing.\& Making
a network request and deciding the most recently modified entry (local/remote)
takes quite some time for large batches.\&
-.P
+.PP
Currently, only the Google Calendar is supported as remote provider.\&
-.P
+.PP
The calender for synchronization can be defined with the configuration key
"google_calendar", see \fBCONFIGURATION FILE\fR.\& This key is empty by default.\&
-.P
+.PP
Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server.\&
-.P
+.PP
.SH GOOGLE CALENDAR OAUTH2
-.P
The Google Calendar CalDAV API is protected with OAuth2:
-.P
+.PP
https://developers.\&google.\&com/identity/protocols/oauth2
-.P
+.PP
The credentials and the consent screen can be redefined at compile time (export
"GOOGLE_OAUTH_CLIENT_ID"/"GOOGLE_OAUTH_CLIENT_SECRET" to environment) or during
runtime with the keys "google_clientid"/"google_secretid" in the \fBCONFIGURATION
FILE\fR.\& The token used to authenticate with the Google API is stored in the file
specified by "google_tokenfile" and renewed automatically.\&
-.P
+.PP
The application requires two OAuth2 scopes
(https://developers.\&google.\&com/calendar/auth) for CalDAV requests:
-.P
-.RS 4
-.ie n \{\
-\h'-04'1.\h'+03'\c
-.\}
-.el \{\
+.PP
+.PD 0
.IP 1. 4
-.\}
"https://www.\&googleapis.\&com/auth/calendar": read/write access to Calendars -
required to discover the unique hyperlink/URI for the calendar specified by
config key "google_calendar"
-.RE
-.RS 4
-.ie n \{\
-\h'-04'2.\h'+03'\c
-.\}
-.el \{\
.IP 2. 4
-.\}
"https://www.\&googleapis.\&com/auth/calendar.\&events.\&owned": read/write access to
Events owned by the user - allows diary to create/read/update/delete events in
"google_calendar"
-
-.RE
-.P
+.PD
+.PP
The user is asked for consent during the first CALDAV SYNC.\&
-.P
+.PP
.SH PRECEDENCE RULES
-.P
The default variables, for instance, for the configuration variables "editor",
"dir" and "weekday", are populated with values in the following order, where
earlier entries are overwritten by subsequent ones if they exist:
-.P
+.PP
.TS
allbox;l lx
l lx
@@ -452,143 +598,84 @@ T}
.TE
.sp 1
.SH PRECEDENCE EXAMPLE: LOCALE AND FIRST DAY OF WEEK
-.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
+.PP
Start with weekday=3(Wed), overrule any other configuration value:
.nf
.RS 4
diary -w3
.fi
.RE
-.P
+.PP
Start with glibc derived weekday=1, regardless of weekday in config file:
.nf
.RS 4
LANG=de_CH diary
.fi
.RE
-.P
+.PP
If glibc is installed, start with glibc derived base date (weekday=0):
.nf
.RS 4
LANG= diary
.fi
.RE
-.P
+.PP
Disable environment variable, default to value from config file:
.nf
.RS 4
unset LANG
.fi
.RE
-.P
+.PP
Start with weekday default from config file, if available:
.nf
.RS 4
diary
.fi
.RE
-.P
+.PP
Remove config file:
.nf
.RS 4
rm ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg
.fi
.RE
-.P
+.PP
Start with weekday default value from source code (1=Mon):
.nf
.RS 4
diary
.fi
.RE
-.P
+.PP
.SH DEVELOPMENT AND SUPPORT
-.P
Contributions are always welcome!\& All source code is available at
https://code.\&in0rdr.\&ch/diary.\&
-.P
+.PP
For question and support visit https://web.\&libera.\&chat/gamja/#diary.\&
-.P
+.PP
.SH AUTHORS
-.P
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
+.PD 0
.IP \(bu 4
-.\}
Andreas Gruhler
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Matthias Beyer
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Johnathan Jenkins
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Yu-Jie Lin
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Balduin Dettling
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Avindra Goolcharan
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Oliver Blanthorn
-.RE
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
.IP \(bu 4
-.\}
Jonny Burger
-
-.RE
-.P
-.SH License
-.P
+.PD
+.PP
+.SH LICENSE
MIT License, https://code.\&in0rdr.\&ch/diary/file/LICENSE.\&html
diff --git a/man1/diary.1.html b/man1/diary.1.html
@@ -219,6 +219,7 @@
<p class="Pp"></p>
<div class="Bd-indent">
<pre>tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
+# https://code.in0rdr.ch/diary/file/config/diary.cfg.html
# Path that holds the journal text files
#dir = ~/diary
# Number of years to show before/after todays date
@@ -244,6 +245,137 @@ editor =
#google_tokenfile = ~/.diary-token
EOF</pre>
</div>
+<p class="Pp">To copy the sample file from the source repository:</p>
+<p class="Pp"></p>
+<div class="Bd-indent">
+<pre>cp config/diary.cfg ${XDG_CONFIG_HOME:-~/.config}/diary/</pre>
+</div>
+<p class="Pp">The file "${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg"
+ should adhere to a basic "key = value" format. Lines can be
+ commented with the special characters "#"or ";".</p>
+<p class="Pp">The following configuration keys are currently supported:</p>
+<p class="Pp"></p>
+<table class="tbl" border="1" style="border-style: solid;">
+ <tr>
+ <td><b>Command Line Option</b></td>
+ <td><b>Config Key</b></td>
+ <td><b>Example Config Value</b></td>
+ <td><b>Default Config Value</b></td>
+ <td><b>Description</b></td>
+ </tr>
+ <tr>
+ <td>"--dir", "-d", or first non-option argument</td>
+ <td>dir</td>
+ <td>~/diary</td>
+ <td>n/a</td>
+ <td>Diary directory. Path that holds the journal text files. If unset,
+ defaults to environment variable "$DIARY_DIR".</td>
+ </tr>
+ <tr>
+ <td>"--editor" or "-e"</td>
+ <td>editor</td>
+ <td>vim </td>
+ <td>(empty) </td>
+ <td>Editor to open journal files with. If unset, defaults to environment
+ variable "$EDITOR". If no editor is provided, the diary is
+ opened read-only.</td>
+ </tr>
+ <tr>
+ <td>"--fmt" or "-f"</td>
+ <td>fmt</td>
+ <td>%d_%b_%y</td>
+ <td>%Y-%m-%d</td>
+ <td>Date format and file name for the files inside the "dir". For
+ the format specifiers, see "man strftime". 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.</td>
+ </tr>
+ <tr>
+ <td>"--fmt-cmd" or "-F"</td>
+ <td>fmt_cmd</td>
+ <td>"fmt -w75 -s", "mdcat -c" or "mdcat"</td>
+ <td>(empty)</td>
+ <td>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).</td>
+ </tr>
+ <tr>
+ <td>"--no-pty" or "-p"</td>
+ <td>no_pty</td>
+ <td>"true"</td>
+ <td>false (or 0)</td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td>"--no-mouse" or "-m"</td>
+ <td>no_mouse</td>
+ <td>"true"</td>
+ <td>false (or 0)</td>
+ <td>Don't listen for <b>MOUSE EVENTS</b>. With no_mouse=0 (default), native
+ text selection and right-click in the preview window requires holding down
+ the "SHIFT" key.</td>
+ </tr>
+ <tr>
+ <td>"--range" or "-r"</td>
+ <td>range</td>
+ <td>10</td>
+ <td>1</td>
+ <td>Number of years to show before/after todays date</td>
+ </tr>
+ <tr>
+ <td>"--weekday" or "-w"</td>
+ <td>weekday</td>
+ <td>0</td>
+ <td>1</td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td>n/a</td>
+ <td>google_calendar </td>
+ <td>diary </td>
+ <td>(empty)</td>
+ <td>Displayname of Google Calendar for <b>CALDAV SYNC</b></td>
+ </tr>
+ <tr>
+ <td>n/a</td>
+ <td>google_clientid</td>
+ <td>123.com</td>
+ <td>built-in at build time (see <b>GOOGLE CALENDAR OAUTH2</b>) or empty</td>
+ <td>Google Calendar for <b>GOOGLE CALENDAR OAUTH2</b> clientid</td>
+ </tr>
+ <tr>
+ <td>n/a</td>
+ <td>google_secretid</td>
+ <td>321</td>
+ <td>built-in at build time (see <b>GOOGLE CALENDAR OAUTH2</b>) or empty</td>
+ <td>Google Calendar for <b>GOOGLE CALENDAR OAUTH2</b> secretid</td>
+ </tr>
+ <tr>
+ <td>n/a</td>
+ <td>google_tokenfile</td>
+ <td>~/.diary-token</td>
+ <td>~/.diary-token</td>
+ <td><b>GOOGLE CALENDAR OAUTH2</b> API token file location</td>
+ </tr>
+</table>
+<p class="Pp"></p>
</section>
<section class="Sh">
<h1 class="Sh" id="CUSTOM_FORMATTING"><a class="permalink" href="#CUSTOM_FORMATTING">CUSTOM
@@ -318,14 +450,16 @@ EOF</pre>
<p class="Pp">The application requires two OAuth2 scopes
(https://developers.google.com/calendar/auth) for CalDAV requests:</p>
<p class="Pp"></p>
-<div class="Bd-indent">1."https://www.googleapis.com/auth/calendar":
- read/write access to Calendars - required to discover the unique hyperlink/URI
- for the calendar specified by config key "google_calendar"</div>
-<div class="Bd-indent">2."https://www.googleapis.com/auth/calendar.events.owned":
- read/write access to Events owned by the user - allows diary to
- create/read/update/delete events in "google_calendar"
-<p class="Pp"></p>
-</div>
+<dl class="Bl-tag">
+ <dt>1.</dt>
+ <dd>"https://www.googleapis.com/auth/calendar": read/write access to
+ Calendars - required to discover the unique hyperlink/URI for the calendar
+ specified by config key "google_calendar"</dd>
+ <dt>2.</dt>
+ <dd>"https://www.googleapis.com/auth/calendar.events.owned":
+ read/write access to Events owned by the user - allows diary to
+ create/read/update/delete events in "google_calendar"</dd>
+</dl>
<p class="Pp">The user is asked for consent during the first CALDAV SYNC.</p>
</section>
<section class="Sh">
@@ -420,25 +554,25 @@ EOF</pre>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
-<div class="Bd-indent">•Andreas Gruhler</div>
-<div class="Bd-indent">•Matthias Beyer</div>
-<div class="Bd-indent">•Johnathan Jenkins</div>
-<div class="Bd-indent">•Yu-Jie Lin</div>
-<div class="Bd-indent">•Balduin Dettling</div>
-<div class="Bd-indent">•Avindra Goolcharan</div>
-<div class="Bd-indent">•Oliver Blanthorn</div>
-<div class="Bd-indent">•Jonny Burger
-<p class="Pp"></p>
-</div>
+<ul class="Bl-bullet">
+ <li>Andreas Gruhler</li>
+ <li>Matthias Beyer</li>
+ <li>Johnathan Jenkins</li>
+ <li>Yu-Jie Lin</li>
+ <li>Balduin Dettling</li>
+ <li>Avindra Goolcharan</li>
+ <li>Oliver Blanthorn</li>
+ <li>Jonny Burger</li>
+</ul>
</section>
<section class="Sh">
-<h1 class="Sh" id="License"><a class="permalink" href="#License">License</a></h1>
+<h1 class="Sh" id="LICENSE"><a class="permalink" href="#LICENSE">LICENSE</a></h1>
<p class="Pp">MIT License, https://code.in0rdr.ch/diary/file/LICENSE.html</p>
</section>
</div>
<table class="foot">
<tr>
- <td class="foot-date">2022-08-21</td>
+ <td class="foot-date">2023-02-20</td>
<td class="foot-os"></td>
</tr>
</table>
diff --git a/man1/diary.1.scd b/man1/diary.1.scd
@@ -1,11 +1,9 @@
DIARY(1)
# NAME
-
diary - text-based journaling program
# SYNOPSIS
-
*diary* [OPTION]... [DIARY_DIR]...
# DESCRIPTION
@@ -15,7 +13,6 @@ Open the *diary* journal for entries stored in *DIARY_DIR*.
*CONFIGURATION FILE*.
# OPTIONS
-
*-v, --version*
Print diary version
@@ -78,7 +75,6 @@ Open the *diary* journal for entries stored in *DIARY_DIR*.
unless specified otherwise with this option.
# NAVIGATION
-
Navigation is done using the following vim-inspired keyboard shortcuts:
[[ *Key(s)*
@@ -122,7 +118,6 @@ Navigation is done using the following vim-inspired keyboard shortcuts:
# 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
@@ -139,13 +134,11 @@ Navigation is done using the following vim-inspired keyboard shortcuts:
# 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
@@ -153,7 +146,6 @@ ${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.
@@ -167,6 +159,7 @@ Install an example configuration file with defaults:
```
tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF
+# https://code.in0rdr.ch/diary/file/config/diary.cfg.html
# Path that holds the journal text files
#dir = ~/diary
# Number of years to show before/after todays date
@@ -193,8 +186,106 @@ editor =
EOF
```
-# CUSTOM FORMATTING
+To copy the sample file from the source repository:
+
+```
+cp config/diary.cfg ${XDG_CONFIG_HOME:-~/.config}/diary/
+```
+
+The file "${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg" should adhere to a
+basic "key = value" format. Lines can be commented with the special characters
+"#"or ";".
+
+The following configuration keys are currently supported:
+[[ *Command Line Option*
+:< *Config Key*
+:< *Example Config Value*
+:< *Default Config Value*
+:< *Description*
+| "--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". 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. 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=0 (default), native
+ text selection and right-click in the preview window requires holding down the
+ "SHIFT" key.
+| "--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*
+| n/a
+: google_clientid
+: 123.com
+: built-in at build time (see *GOOGLE CALENDAR OAUTH2*) or empty
+: Google Calendar for *GOOGLE CALENDAR OAUTH2* clientid
+| n/a
+: google_secretid
+: 321
+: built-in at build time (see *GOOGLE CALENDAR OAUTH2*) or empty
+: Google Calendar for *GOOGLE CALENDAR OAUTH2* secretid
+| n/a
+: google_tokenfile
+: ~/.diary-token
+: ~/.diary-token
+: *GOOGLE CALENDAR OAUTH2* API token file location
+
+# 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
@@ -204,26 +295,22 @@ supported by the terminal (colors, font types, etc.). Thus, formatters like
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.
# IMPORT
-
The import functionality can be triggered by pressing *i* and expects a path to
an ics file. Files in the *DIARY_DIR* are overwritten with the entries from the
imported ics file.
# EXPORT
-
The export functionality can be triggered by pressing *E* and asks for a file
path to an ics file for storing the journal entries. The ics file will be
created if it does not exist. Existing ics files are overwritten.
# CALDAV SYNC
-
The journal files can be synced via CalDAV by pressing *s*. Pressing *S* syncs
all journal entries of the active month.
@@ -247,7 +334,6 @@ The calender for synchronization can be defined with the configuration key
Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server.
# GOOGLE CALENDAR OAUTH2
-
The Google Calendar CalDAV API is protected with OAuth2:
https://developers.google.com/identity/protocols/oauth2
@@ -271,7 +357,6 @@ The application requires two OAuth2 scopes
The user is asked for consent during the first CALDAV SYNC.
# PRECEDENCE RULES
-
The default variables, for instance, for the configuration variables "editor",
"dir" and "weekday", are populated with values in the following order, where
earlier entries are overwritten by subsequent ones if they exist:
@@ -294,7 +379,6 @@ earlier entries are overwritten by subsequent ones if they exist:
: 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.
@@ -335,14 +419,12 @@ diary
```
# DEVELOPMENT AND SUPPORT
-
Contributions are always welcome! All source code is available at
https://code.in0rdr.ch/diary.
For question and support visit https://web.libera.chat/gamja/#diary.
# AUTHORS
-
- Andreas Gruhler
- Matthias Beyer
- Johnathan Jenkins
@@ -352,6 +434,5 @@ For question and support visit https://web.libera.chat/gamja/#diary.
- Oliver Blanthorn
- Jonny Burger
-# License
-
+# LICENSE
MIT License, https://code.in0rdr.ch/diary/file/LICENSE.html
