diary

Text-based journaling program
git clone https://git.in0rdr.ch/diary.git
Log | Files | Refs | README | LICENSE

commit 4cbf55e91ccb904bf2ee58e70d380d83ca00905c
parent 96af8efff171b26c099b694ce3e91c46cb1d4baa
Author: Andreas Gruhler <andreas.gruhler@adfinis.com>
Date:   Sun, 16 Jun 2024 07:03:20 +0200

doc(google): update api scopes

Scopes seem to have changed slightly:
https://developers.google.com/calendar/api/auth

Diffstat:
Mman1/diary.1 | 240++++++++++++++++++++++++++++---------------------------------------------------
Mman1/diary.1.html | 42+++++++++++++++++++++---------------------
Mman1/diary.1.scd | 8++++----
3 files changed, 111 insertions(+), 179 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-03-26" -.P +.TH "DIARY" "1" "2024-06-16" +.PP .SH NAME diary - text-based journaling program -.P +.PP .SH SYNOPSIS \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 \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 @@ -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.\& -.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 @@ -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.\& -.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-w, --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 Navigation is done using the following vim-inspired keyboard shortcuts: -.P +.PP .TS allbox;l lx l lx @@ -221,7 +221,7 @@ quit the program T} .TE .sp 1 -.P +.PP .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.\& -.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 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 ${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 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 @@ -304,21 +304,21 @@ editor = EOF .fi .RE -.P +.PP To copy the sample file from the source repository: -.P +.PP .nf .RS 4 cp config/diary\&.cfg ${XDG_CONFIG_HOME:-~/\&.config}/diary/ .fi .RE -.P +.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 +.PP The following configuration keys are currently supported: -.P +.PP .TS allbox;l lx lx lx lx l lx lx lx lx @@ -486,96 +486,83 @@ 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 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 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 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 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 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 +.PP https://console.\&cloud.\&google.\&com/apis/api/caldav.\&googleapis.\&com -.P +.PP 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 \{\ -.IP 1. 4 -.\} -"https://www.\&googleapis.\&com/auth/calendar": read/write access to Calendars - +(https://developers.\&google.\&com/calendar/api/auth) for CalDAV requests: +.PP +.PD 0 +.IP \(bu 4 +"https://www.\&googleapis.\&com/auth/calendar": read/share 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 +.IP \(bu 4 +"https://www.\&googleapis.\&com/auth/calendar.\&events": 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 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 @@ -619,136 +606,81 @@ 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.\& -.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 Contributions are always welcome!\& All source code is available at https://code.\&in0rdr.\&ch/diary.\& -.P -For question and support visit https://web.\&libera.\&chat/gamja/#diary.\& -.P +.PP +For question and support visit https://web.\&libera.\&chat/gamja/#p0c.\& +.PP .SH AUTHORS -.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 +.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 @@ -452,16 +452,16 @@ EOF</pre> Google API is stored in the file specified by &quot;google_tokenfile&quot; and renewed automatically.</p> <p class="Pp">The application requires two OAuth2 scopes - (https://developers.google.com/calendar/auth) for CalDAV requests:</p> + (https://developers.google.com/calendar/api/auth) for CalDAV requests:</p> <p class="Pp"></p> -<div class="Bd-indent">1.&quot;https://www.googleapis.com/auth/calendar&quot;: - read/write access to Calendars - required to discover the unique hyperlink/URI - for the calendar specified by config key &quot;google_calendar&quot;</div> -<div class="Bd-indent">2.&quot;https://www.googleapis.com/auth/calendar.events.owned&quot;: - read/write access to Events owned by the user - allows diary to - create/read/update/delete events in &quot;google_calendar&quot; -<p class="Pp"></p> -</div> +<ul class="Bl-bullet"> + <li>&quot;https://www.googleapis.com/auth/calendar&quot;: read/share access to + Calendars, required to discover the unique hyperlink/URI for the calendar + specified by config key &quot;google_calendar&quot;</li> + <li>&quot;https://www.googleapis.com/auth/calendar.events&quot;: read/write + access to Events owned by the user, allows diary to + create/read/update/delete events in &quot;google_calendar&quot;</li> +</ul> <p class="Pp">The user is asked for consent during the first CALDAV SYNC.</p> </section> <section class="Sh"> @@ -552,20 +552,20 @@ EOF</pre> <p class="Pp">Contributions are always welcome! All source code is available at https://code.in0rdr.ch/diary.</p> <p class="Pp">For question and support visit - https://web.libera.chat/gamja/#diary.</p> + https://web.libera.chat/gamja/#p0c.</p> </section> <section class="Sh"> <h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<div class="Bd-indent">&#x2022;Andreas Gruhler</div> -<div class="Bd-indent">&#x2022;Matthias Beyer</div> -<div class="Bd-indent">&#x2022;Johnathan Jenkins</div> -<div class="Bd-indent">&#x2022;Yu-Jie Lin</div> -<div class="Bd-indent">&#x2022;Balduin Dettling</div> -<div class="Bd-indent">&#x2022;Avindra Goolcharan</div> -<div class="Bd-indent">&#x2022;Oliver Blanthorn</div> -<div class="Bd-indent">&#x2022;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> @@ -574,7 +574,7 @@ EOF</pre> </div> <table class="foot"> <tr> - <td class="foot-date">2023-03-26</td> + <td class="foot-date">2024-06-16</td> <td class="foot-os"></td> </tr> </table> diff --git a/man1/diary.1.scd b/man1/diary.1.scd @@ -350,13 +350,13 @@ 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://developers.google.com/calendar/api/auth) for CalDAV requests: -. "https://www.googleapis.com/auth/calendar": read/write access to Calendars - +- "https://www.googleapis.com/auth/calendar": read/share 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 +- "https://www.googleapis.com/auth/calendar.events": 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.