commit 00dff3af022f04bd3bea9f0a1dbd1337e6bd227a
parent 2bff0783e9ab583e151826f3a19018d59565b795
Author: Andreas Gruhler <agruhl@gmx.ch>
Date: Mon, 17 Jan 2022 01:28:38 +0100
feat(caldav): update documentation
Diffstat:
5 files changed, 277 insertions(+), 86 deletions(-)
diff --git a/README.md b/README.md
@@ -45,17 +45,13 @@ This is a text-based diary, inspired by [khal](https://github.com/pimutils/khal)
g go to start of journal
G go to end of journal
+ s, S sync selected day/Month with CalDAV server
+ i import entries from .ics file
+ E export entries to .ics file
+
q quit the program
```
-Alpha features:
-
-```
-s, S sync selected/all with CalDAV server
-i import entries from .ics file
-E export entries to .ics file
-```
-
Keybinding Cheat Sheet:
@@ -185,17 +181,20 @@ Mouse events are listened for by default ([`no_mouse=false`](#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.
-
+## Import/Export
* The import functionality can be triggered by pressing `i`.
* The export functionality can be triggered by pressing `E`.
-## CalDAV Sync (alpha)
-> ⚠️ Alpha feature: Available only in `diary-nightly` (see [Installation Instructions](#Install)). Don't use this with "production" data.
+## 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.
-The journal files can be synced via CalDAV by pressing `s`. Currently, only the Google Calendar is supported as remote provider. Please open an [issue](https://codeberg.org/in0rdr/diary/issues) to implement support for additional remote calendar servers.
+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. Please open an [issue](https://codeberg.org/in0rdr/diary/issues) to implement support for additional remote calendar servers.
The calender for synchronization can be defined with the [configuration](#Configuration-File) key `google_calendar`:
```
@@ -203,7 +202,7 @@ The calender for synchronization can be defined with the [configuration](#Config
google_calendar = example
```
-This key is empty by default and the only configuration key required for setting up synchronization.
+This key is empty by default.
### Google Calendar OAuth2
@@ -217,7 +216,7 @@ 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`):
+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
diff --git a/img/diary-cheat-sheet.png b/img/diary-cheat-sheet.png
Binary files differ.
diff --git a/man1/diary.1 b/man1/diary.1
@@ -5,7 +5,7 @@
.nh
.ad l
.\" Begin generated content:
-.TH "DIARY" "1" "2022-01-09"
+.TH "DIARY" "1" "2022-01-17"
.P
.SH NAME
.P
@@ -16,10 +16,10 @@ diary - text-based journaling program
\fBdiary\fR [OPTION]... [DIARY_DIR]...
.P
.SH DESCRIPTION
-Open the \fBdiary\fR journal for entries stored in DIARY_DIR.
+Open the \fBdiary\fR journal for entries stored in \fBDIARY_DIR\fR.
.P
-DIARY_DIR is required, if not set as environment variable or defined in the
-configuration file.
+\fBDIARY_DIR\fR is required, if not set as environment variable or defined in the
+\fBCONFIGURATION FILE\fR.
.P
.SH OPTIONS
.P
@@ -124,6 +124,9 @@ l lx
l lx
l lx
l lx
+l lx
+l lx
+l lx
l lx.
T{
\fBKey(s)\fR
@@ -201,29 +204,9 @@ T} T{
go to end of journal
T}
T{
-\fBq\fR
-T} T{
-quit the program
-T}
-.TE
-.sp 1
-.P
-Alpha features:
-.P
-.TS
-allbox;l lx
-l lx
-l lx
-l lx.
-T{
-\fBKey(s)\fR
-T} T{
-Action
-T}
-T{
\fBs, S\fR
T} T{
-sync selected/all with CalDAV server
+sync selected day/Month with CalDAV server
T}
T{
\fBi\fR
@@ -235,6 +218,11 @@ T{
T} T{
export entries to .ics file
T}
+T{
+\fBq\fR
+T} T{
+quit the program
+T}
.TE
.sp 1
.P
@@ -260,7 +248,6 @@ The default locale used to display the first day of the week, see
\fB--weekday\fR option.
.P
.P
-.P
.RE
.SH ARGUMENTS
.P
@@ -338,9 +325,88 @@ for \fB--fmt-cmd\fR.
.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 configuration file
-(\fBno_mouse\fR=true). With \fBno_mouse\fR=false (default), use the SHIFT key for native
-text selection and right-click in the preview window.
+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
+.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
+.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
+.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
+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
+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
+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
+Currently, only the Google Calendar is supported as remote provider. Please
+open an [issue](https://codeberg.org/in0rdr/diary/issues) to implement support
+for additional remote calendar servers.
+.P
+The calender for synchronization can be defined with the configuration key
+"google_calendar", see \fBCONFIGURATION FILE\fR. This key is empty by default.
+.P
+Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server.
+.P
+.SH GOOGLE CALENDAR OAUTH2
+.P
+The Google Calendar CalDAV API is protected with OAuth2:
+.P
+https://developers.google.com/identity/protocols/oauth2
+.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.
+.P
+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 \{\
+.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
+The user is asked for consent during the first CALDAV SYNC.
.P
.SH PRECEDENCE RULES
.P
@@ -363,7 +429,7 @@ T}
T{
1
T} T{
-No default for \fBDIARY_DIR\fR. Defaults for "range", "weekday", "fmt" and "editor" are provided in "diary.h". If \fBEDITOR\fR is unset and no editor is provided in the configuration file or \fB--editor\fR option, the diary works read-only. Journal files cannot be opened. If \fBDIARY_DIR\fR is not provided, the diary won't open.
+No default for \fBDIARY_DIR\fR. Defaults for "range", "weekday", "fmt" and "editor" are provided in "diary.h". If \fBEDITOR\fR is unset and no editor is provided in the \fBCONFIGURATION FILE\fR or \fB--editor\fR option, the diary works read-only. Journal files cannot be opened. If \fBDIARY_DIR\fR is not provided, the diary won't open.
T}
T{
2
@@ -522,4 +588,9 @@ Oliver Blanthorn
.IP \(bu 4
.\}
Jonny Burger
+
.RE
+.P
+.SH License
+.P
+MIT License, https://codeberg.org/in0rdr/diary/raw/branch/master/LICENSE
diff --git a/man1/diary.1.html b/man1/diary.1.html
@@ -29,9 +29,10 @@
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-<p class="Pp">Open the <b>diary</b> journal for entries stored in DIARY_DIR.</p>
-<p class="Pp">DIARY_DIR is required, if not set as environment variable or
- defined in the configuration file.</p>
+<p class="Pp">Open the <b>diary</b> journal for entries stored in
+ <b>DIARY_DIR</b>.</p>
+<p class="Pp"><b>DIARY_DIR</b> is required, if not set as environment variable
+ or defined in the <b>CONFIGURATION FILE</b>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1>
@@ -155,21 +156,8 @@
<td>go to end of journal</td>
</tr>
<tr>
- <td><b>q</b></td>
- <td>quit the program</td>
- </tr>
-</table>
-<p class="Pp"></p>
-<p class="Pp">Alpha features:</p>
-<p class="Pp"></p>
-<table class="tbl" border="1" style="border-style: solid;">
- <tr>
- <td><b>Key(s)</b></td>
- <td>Action</td>
- </tr>
- <tr>
<td><b>s, S</b></td>
- <td>sync selected/all with CalDAV server</td>
+ <td>sync selected day/Month with CalDAV server</td>
</tr>
<tr>
<td><b>i</b></td>
@@ -179,6 +167,10 @@
<td><b>E</b></td>
<td>export entries to .ics file</td>
</tr>
+ <tr>
+ <td><b>q</b></td>
+ <td>quit the program</td>
+ </tr>
</table>
<p class="Pp"></p>
</section>
@@ -270,11 +262,74 @@ EOF</pre>
EVENTS</a></h1>
<p class="Pp">Mouse events are listened for by default (<b>no_mouse</b>=false
configuration). This behavior can be disabled with the <b>--no-mouse</b>
- flag or in the configuration file (<b>no_mouse</b>=true). With
+ flag or in the <b>CONFIGURATION</b> <b>FILE</b> (<b>no_mouse</b>=true). With
<b>no_mouse</b>=false (default), use the SHIFT key for native text selection
and right-click in the preview window.</p>
</section>
<section class="Sh">
+<h1 class="Sh" id="IMPORT"><a class="permalink" href="#IMPORT">IMPORT</a></h1>
+<p class="Pp">The import functionality can be triggered by pressing <b>i</b> and
+ expects a path to an ics file. Files in the <b>DIARY_DIR</b> are overwritten
+ with the entries from the imported ics file.</p>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="EXPORT"><a class="permalink" href="#EXPORT">EXPORT</a></h1>
+<p class="Pp">The export functionality can be triggered by pressing <b>E</b> 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>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="CALDAV_SYNC"><a class="permalink" href="#CALDAV_SYNC">CALDAV
+ SYNC</a></h1>
+<p class="Pp">The journal files can be synced via CalDAV by pressing <b>s</b>.
+ Pressing <b>S</b> syncs all journal entries of the active month.</p>
+<p class="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>
+<p class="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>
+<p class="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>
+<p class="Pp">Currently, only the Google Calendar is supported as remote
+ provider. Please open an [issue](https://codeberg.org/in0rdr/diary/issues)
+ to implement support for additional remote calendar servers.</p>
+<p class="Pp">The calender for synchronization can be defined with the
+ configuration key "google_calendar", see <b>CONFIGURATION
+ FILE</b>. This key is empty by default.</p>
+<p class="Pp">Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google
+ server.</p>
+</section>
+<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">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
+ time (export
+ "GOOGLE_OAUTH_CLIENT_ID"/"GOOGLE_OAUTH_CLIENT_SECRET" to
+ environment) or during runtime with the keys
+ "google_clientid"/"google_secretid" in the
+ <b>CONFIGURATION</b> <b>FILE</b>. The token used to authenticate with the
+ Google API is stored in the file specified by "google_tokenfile"
+ and renewed automatically.</p>
+<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>
+<p class="Pp">The user is asked for consent during the first CALDAV SYNC.</p>
+</section>
+<section class="Sh">
<h1 class="Sh" id="PRECEDENCE_RULES"><a class="permalink" href="#PRECEDENCE_RULES">PRECEDENCE
RULES</a></h1>
<p class="Pp">The default variables, for instance, for the configuration
@@ -292,9 +347,9 @@ EOF</pre>
<td>No default for <b>DIARY_DIR</b>. Defaults for "range",
"weekday", "fmt" and "editor" are provided
in "diary.h". If <b>EDITOR</b> is unset and no editor is
- provided in the configuration file or <b>--editor</b> option, the diary
- works read-only. Journal files cannot be opened. If <b>DIARY_DIR</b> is
- not provided, the diary won't open.</td>
+ provided in the <b>CONFIGURATION FILE</b> or <b>--editor</b> option, the
+ diary works read-only. Journal files cannot be opened. If <b>DIARY_DIR</b>
+ is not provided, the diary won't open.</td>
</tr>
<tr>
<td>2</td>
@@ -373,12 +428,19 @@ EOF</pre>
<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</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>
+<p class="Pp">MIT License,
+ https://codeberg.org/in0rdr/diary/raw/branch/master/LICENSE</p>
</section>
</div>
<table class="foot">
<tr>
- <td class="foot-date">2022-01-09</td>
+ <td class="foot-date">2022-01-17</td>
<td class="foot-os"></td>
</tr>
</table>
diff --git a/man1/diary.1.scd b/man1/diary.1.scd
@@ -9,10 +9,10 @@ diary - text-based journaling program
*diary* [OPTION]... [DIARY_DIR]...
# DESCRIPTION
-Open the *diary* journal for entries stored in DIARY_DIR.
+Open the *diary* journal for entries stored in *DIARY_DIR*.
-DIARY_DIR is required, if not set as environment variable or defined in the
-configuration file.
+*DIARY_DIR* is required, if not set as environment variable or defined in the
+*CONFIGURATION FILE*.
# OPTIONS
@@ -111,20 +111,14 @@ Navigation is done using the following vim-inspired keyboard shortcuts:
: go to start of journal
| *G*
: go to end of journal
-| *q*
-: quit the program
-
-
-Alpha features:
-
-[[ *Key(s)*
-:< Action
| *s, S*
-: sync selected/all with CalDAV server
+: sync selected day/Month with CalDAV server
| *i*
: import entries from .ics file
| *E*
: export entries to .ics file
+| *q*
+: quit the program
# ENVIRONMENT
@@ -144,7 +138,6 @@ Alpha features:
*--weekday* option.
-
# ARGUMENTS
If the argument *DIARY_DIR* is given, diary files are read from and stored to
@@ -213,9 +206,71 @@ 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.
+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.
+
+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 modification
+timestamp or no files exists on the server and on disk at all (i.e., no entry
+for that date).
+
+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.
+
+Currently, only the Google Calendar is supported as remote provider. Please
+open an [issue](https://codeberg.org/in0rdr/diary/issues) to implement support
+for additional remote calendar servers.
+
+The calender for synchronization can be defined with the configuration key
+"google_calendar", see *CONFIGURATION FILE*. This key is empty by default.
+
+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
+
+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 *CONFIGURATION
+FILE*. The token used to authenticate with the Google API is stored in the file
+specified by "google_tokenfile" and renewed automatically.
+
+The application requires two OAuth2 scopes
+(https://developers.google.com/calendar/auth) for CalDAV requests:
+
+. "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"
+. "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"
+
+The user is asked for consent during the first CALDAV SYNC.
# PRECEDENCE RULES
@@ -228,7 +283,7 @@ 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". If *EDITOR* is unset and no editor is
- provided in the configuration file or *--editor* option, the diary works
+ provided in the *CONFIGURATION FILE* or *--editor* option, the diary works
read-only. Journal files cannot be opened. If *DIARY_DIR* is not provided, the
diary won't open.
| 2
@@ -298,3 +353,7 @@ For question and support visit https://web.libera.chat/gamja/#diary.
- Avindra Goolcharan
- Oliver Blanthorn
- Jonny Burger
+
+# License
+
+MIT License, https://codeberg.org/in0rdr/diary/raw/branch/master/LICENSE
