commit 0ce6cba5af5a697dd1d021ec13730f133a507ab5
parent ff76d9f61d7ff135d872bd7bcefa77340ac02d03
Author: Andreas Gruhler <andreas.gruhler@adfinis.com>
Date: Sun, 26 Mar 2023 23:44:10 +0200
doc: refresh man page
Diffstat:
| M | man1/diary.1 | | | 229 | ++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------- |
| M | man1/diary.1.html | | | 46 | ++++++++++++++++++++++++---------------------- |
2 files changed, 175 insertions(+), 100 deletions(-)
diff --git a/man1/diary.1 b/man1/diary.1
@@ -5,47 +5,47 @@
.nh
.ad l
.\" Begin generated content:
-.TH "DIARY" "1" "2023-02-20"
-.PP
+.TH "DIARY" "1" "2023-03-26"
+.P
.SH NAME
diary - text-based journaling program
-.PP
+.P
.SH SYNOPSIS
\fBdiary\fR [OPTION].\&.\&.\& [DIARY_DIR].\&.\&.\&
-.PP
+.P
.SH DESCRIPTION
Open the \fBdiary\fR journal for entries stored in \fBDIARY_DIR\fR.\&
-.PP
+.P
\fBDIARY_DIR\fR is required, if not set as environment variable or defined in the
\fBCONFIGURATION FILE\fR.\&
-.PP
+.P
.SH OPTIONS
\fB-v, --version\fR
-.PP
+.P
.RS 4
Print diary version
-.PP
+.P
.RE
\fB-h, --help\fR
-.PP
+.P
.RS 4
Show diary help text
-.PP
+.P
.RE
\fB-d, --dir\fR=DIARY_DIR
-.PP
+.P
.RS 4
Directory with the journal text files
-.PP
+.P
.RE
\fB-e, --editor\fR=EDITOR
-.PP
+.P
.RS 4
Text editor used for opening the journal files
-.PP
+.P
.RE
\fB-f, --fmt\fR=FMT
-.PP
+.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
@@ -53,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.\&
-.PP
+.P
.RE
\fB-F, --fmt-cmd\fR=FMT_CMD
-.PP
+.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.\&
-.PP
+.P
.RE
\fB-p, --no-pty\fR
-.PP
+.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
@@ -74,36 +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.\&
-.PP
+.P
.RE
\fB-m, --no-mouse\fR
-.PP
+.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.\&
-.PP
+.P
.RE
\fB-r, --range\fR=RANGE
-.PP
+.P
.RS 4
The number of years to show before/after today.\& Defaults to 1 year.\&
-.PP
+.P
.RE
-\fB-f, --weekday\fR=DAY
-.PP
+\fB-w, --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.\&
-.PP
+.P
.RE
.SH NAVIGATION
Navigation is done using the following vim-inspired keyboard shortcuts:
-.PP
+.P
.TS
allbox;l lx
l lx
@@ -221,7 +221,7 @@ quit the program
T}
.TE
.sp 1
-.PP
+.P
.SH ENVIRONMENT
\fBDIARY_DIR\fR
.RS 4
@@ -230,50 +230,50 @@ 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.\&
-.PP
+.P
.RE
\fBEDITOR\fR
.RS 4
The program used to edit journal entries inside \fBDIARY_DIR\fR.\&
-.PP
+.P
.RE
\fBLANG\fR
.RS 4
The default locale used to display the first day of the week, see
\fB--weekday\fR option.\&
-.PP
-.PP
+.P
+.P
.RE
.SH ARGUMENTS
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.\&
-.PP
+.P
.SH FILES
${PREFIX:-/usr/local/bin}/\fBdiary\fR
.RS 4
The diary binary
-.PP
+.P
.RE
${XDG_CONFIG_HOME:-~/.\&config}/diary/\fBdiary.\&cfg\fR
.RS 4
An optional diary \fBCONFIGURATION FILE\fR
-.PP
+.P
.RE
.SH CONFIGURATION FILE
The \fBdiary.\&cfg\fR configuration file can optionally be used to persist diary
configuration.\& Use the "#" or ";" characters to comment lines.\&
-.PP
+.P
Create default configuration location:
-.PP
+.P
.nf
.RS 4
mkdir -p ${XDG_CONFIG_HOME:-~/\&.config}/diary
.fi
.RE
-.PP
+.P
Install an example configuration file with defaults:
-.PP
+.P
.nf
.RS 4
tee ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg <<EOF
@@ -304,21 +304,21 @@ editor =
EOF
.fi
.RE
-.PP
+.P
To copy the sample file from the source repository:
-.PP
+.P
.nf
.RS 4
cp config/diary\&.cfg ${XDG_CONFIG_HOME:-~/\&.config}/diary/
.fi
.RE
-.PP
+.P
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
+.P
The following configuration keys are currently supported:
-.PP
+.P
.TS
allbox;l lx lx lx lx
l lx lx lx lx
@@ -486,78 +486,96 @@ 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.\&
-.PP
+.P
.SH MOUSE EVENTS
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.\&
-.PP
+.P
.SH IMPORT
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.\&
-.PP
+.P
.SH EXPORT
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.\&
-.PP
+.P
.SH CALDAV SYNC
The journal files can be synced via CalDAV by pressing \fBs\fR.\& Pressing \fBS\fR syncs
all journal entries of the active month.\&
-.PP
+.P
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.\&
-.PP
+.P
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).\&
-.PP
+.P
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.\&
-.PP
+.P
Currently, only the Google Calendar is supported as remote provider.\&
-.PP
+.P
The calender for synchronization can be defined with the configuration key
"google_calendar", see \fBCONFIGURATION FILE\fR.\& This key is empty by default.\&
-.PP
+.P
Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server.\&
-.PP
+.P
.SH GOOGLE CALENDAR OAUTH2
+To synchronize with the Google calendar, it is required to setup a project in
+the cloud console and enable the CalDAV API (not the Google Calendar API):
+.P
+https://console.\&cloud.\&google.\&com/apis/api/caldav.\&googleapis.\&com
+.P
The Google Calendar CalDAV API is protected with OAuth2:
-.PP
+.P
https://developers.\&google.\&com/identity/protocols/oauth2
-.PP
+.P
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.\&
-.PP
+.P
The application requires two OAuth2 scopes
(https://developers.\&google.\&com/calendar/auth) for CalDAV requests:
-.PP
-.PD 0
+.P
+.RS 4
+.ie n \{\
+\h'-04'1.\h'+03'\c
+.\}
+.el \{\
.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"
-.PD
-.PP
+
+.RE
+.P
The user is asked for consent during the first CALDAV SYNC.\&
-.PP
+.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, where
earlier entries are overwritten by subsequent ones if they exist:
-.PP
+.P
.TS
allbox;l lx
l lx
@@ -601,81 +619,136 @@ T}
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.\&
-.PP
+.P
Start with weekday=3(Wed), overrule any other configuration value:
.nf
.RS 4
diary -w3
.fi
.RE
-.PP
+.P
Start with glibc derived weekday=1, regardless of weekday in config file:
.nf
.RS 4
LANG=de_CH diary
.fi
.RE
-.PP
+.P
If glibc is installed, start with glibc derived base date (weekday=0):
.nf
.RS 4
LANG= diary
.fi
.RE
-.PP
+.P
Disable environment variable, default to value from config file:
.nf
.RS 4
unset LANG
.fi
.RE
-.PP
+.P
Start with weekday default from config file, if available:
.nf
.RS 4
diary
.fi
.RE
-.PP
+.P
Remove config file:
.nf
.RS 4
rm ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg
.fi
.RE
-.PP
+.P
Start with weekday default value from source code (1=Mon):
.nf
.RS 4
diary
.fi
.RE
-.PP
+.P
.SH DEVELOPMENT AND SUPPORT
Contributions are always welcome!\& All source code is available at
https://code.\&in0rdr.\&ch/diary.\&
-.PP
+.P
For question and support visit https://web.\&libera.\&chat/gamja/#diary.\&
-.PP
+.P
.SH AUTHORS
-.PD 0
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
.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
-.PD
-.PP
+
+.RE
+.P
.SH LICENSE
MIT License, https://code.\&in0rdr.\&ch/diary/file/LICENSE.\&html
diff --git a/man1/diary.1.html b/man1/diary.1.html
@@ -81,7 +81,7 @@
<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"><b>-w, --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
@@ -437,6 +437,10 @@ EOF</pre>
<section class="Sh">
<h1 class="Sh" id="GOOGLE_CALENDAR_OAUTH2"><a class="permalink" href="#GOOGLE_CALENDAR_OAUTH2">GOOGLE
CALENDAR OAUTH2</a></h1>
+<p class="Pp">To synchronize with the Google calendar, it is required to setup a
+ project in the cloud console and enable the CalDAV API (not the Google
+ Calendar API):</p>
+<p class="Pp">https://console.cloud.google.com/apis/api/caldav.googleapis.com</p>
<p class="Pp">The Google Calendar CalDAV API is protected with OAuth2:</p>
<p class="Pp">https://developers.google.com/identity/protocols/oauth2</p>
<p class="Pp">The credentials and the consent screen can be redefined at compile
@@ -450,16 +454,14 @@ 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>
-<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>
+<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>
<p class="Pp">The user is asked for consent during the first CALDAV SYNC.</p>
</section>
<section class="Sh">
@@ -554,16 +556,16 @@ EOF</pre>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
-<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>
+<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>
</section>
<section class="Sh">
<h1 class="Sh" id="LICENSE"><a class="permalink" href="#LICENSE">LICENSE</a></h1>
@@ -572,7 +574,7 @@ EOF</pre>
</div>
<table class="foot">
<tr>
- <td class="foot-date">2023-02-20</td>
+ <td class="foot-date">2023-03-26</td>
<td class="foot-os"></td>
</tr>
</table>
