commit c3a8a49446041de85bc88b82b9b044ef78e1c0d6
parent 4b4cd5b2743d2053a1b797d6e9ba19b940c9a0b6
Author: Andreas Gruhler <agruhl@gmx.ch>
Date: Thu, 7 Jan 2021 23:46:37 +0100
update man and defaults
Diffstat:
4 files changed, 64 insertions(+), 16 deletions(-)
diff --git a/README.md b/README.md
@@ -73,11 +73,9 @@ Note: for *BSD users run gmake.
## Configuration File
-(version `master`)
-
The [`diary.cfg`](./diary.cfg) configuration file can optionally be used to persist diary configuration. To install the sample from this repository:
```bash
-mkdir -p ~/.config/diary/
+mkdir -p ~/.config/diary
cp diary.cfg ~/.config/diary/
```
@@ -88,4 +86,4 @@ The file `~/.config/diary/diary.cfg` should adhere to a basic `key = value` form
| `--dir`, `-d`, or first non-option argument | `diary_dir` | ~/diary | n/a | Diary directory. Path that holds the journal text files. |
| `--year_range` or `-r` | `year_range` | 10 | 1 | Number of years to show before/after todays date |
| `--first_weekday` or `-w` | `first_weekday` | 0 | 1 | First weekday, `0` = Sunday, `1` = Monday, ..., `6` = Saturday. Use `0` to display week beginning at Sunday ("S-M-T-W-T-F-S"), or `1` for "M-T-W-T-F-S-S" (default) |
-| `--date_fmt` or `-f` | `date_fmt` | %d_%b_%y | %Y-%m-%d | Date format and file name for the files inside the `diary_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. |
-\ No newline at end of file
+| `--date_fmt` or `-f` | `date_fmt` | %d_%b_%y | %Y-%m-%d | Date format and file name for the files inside the `diary_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. |
+\ No newline at end of file
diff --git a/diary.1 b/diary.1
@@ -11,24 +11,50 @@ diary \- Simple text-based diary program
.B diary
is a simple text-based program for managing journal entries.
+.SH OPTIONS
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Print diary version
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show diary help text
+.TP
+\fB\-d\fR, \fB\-\-dir\fR=\fI\,DIARY_DIR\/\fR
+Diary storage directory DIARY_DIR
+.TP
+\fB\-r\fR, \fB\-\-year_range\fR=\fI\,RANGE\/\fR
+RANGE is the number of years to show before/after todays date
+.TP
+\fB\-f\fR, \fB\-\-date_weekday\fR=\fI\,DAY\/\fR
+First day of the week. DAY is an integer in range (0..6),
+interpreted as 0 = Sun, 1 = Mon, ..., 6 = Sat
+.TP
+\fB\-f\fR, \fB\-\-date_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.
+
.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 like YYYY-MM-DD. All other files are ignored.
+after their date, formatted like FMT (see '-f'/'--date_fmt' options and
+'date_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.
-
.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 or
-any '-d' or '--dir' options.
-
+stored to that directory, ignoring the DIARY_DIR environment variable,
+any '-d'/'--dir' options or the 'diary_dir' set in the config file.
.SH FILES
.TP
@@ -38,6 +64,30 @@ The diary binary
.I ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg
An optional diary configuration file
+.SH CONFIGURATION FILE
+The diary.cfg configuration file can optionally be used to persist diary configuration.
+
+Create default config location:
+
+.nf
+ $ mkdir -p ~/.config/diary
+.fi
+
+Install an example config file with defaults:
+
+.nf
+ $ echo '# Path that holds the journal text files
+ #diary_dir = ~/diary
+ # Number of years to show before/after todays date
+ year_range = 1
+ # 0 = Sunday, 1 = Monday, ..., 6 = Saturday
+ first_weekday = 1
+ # Date and file format, change with care
+ date_fmt = %Y-%m-%d' | sed 's/^[[:space:]]*//' > ~/.config/diary/diary.cfg
+.fi
+
+Use characters '#' or ';' for commenting lines.
+
.SH NAVIGATION
Navigation is done using the following vim-inspired keyboard shortcuts:
diff --git a/diary.c b/diary.c
@@ -342,8 +342,8 @@ void usage() {
printf("Options:\n");
printf(" -v, --version : Print diary version\n");
printf(" -h, --help : Show diary help text\n");
- printf(" -d, --dir DIARY_DIR : Diary storage directory (DIARY_DIR)\n");
- printf(" -r, --year_range RANGE : Number of years to show before/after todays date\n");
+ printf(" -d, --dir DIARY_DIR : Diary storage directory DIARY_DIR\n");
+ printf(" -r, --year_range RANGE : RANGE is the number of years to show before/after todays date\n");
printf(" -w, --first_weekday DAY : First day of the week, 0 = Sun, 1 = Mon, ..., 6 = Sat\n");
printf(" -f, --date_fmt FMT : Date and file format, change with care\n");
printf("\n");
diff --git a/diary.cfg b/diary.cfg
@@ -1,8 +1,8 @@
# Path that holds the journal text files
-diary_dir = ~/diary
+#diary_dir = ~/diary
# Number of years to show before/after todays date
-year_range = 2
+year_range = 1
# 0 = Sunday, 1 = Monday, ..., 6 = Saturday
-first_weekday = 0
+first_weekday = 1
# Date and file format, change with care
-date_fmt = %d_%b_%y
+date_fmt = %Y-%m-%d
