diary.1.scd (15282B)
1 DIARY(1) 2 3 # NAME 4 diary - text-based journaling program 5 6 # SYNOPSIS 7 *diary* [OPTION]... [DIARY_DIR]... 8 9 # DESCRIPTION 10 Open the *diary* journal for entries stored in *DIARY_DIR*. 11 12 *DIARY_DIR* is required, if not set as environment variable or defined in the 13 *CONFIGURATION FILE*. 14 15 # OPTIONS 16 *-v, --version* 17 18 Print diary version 19 20 *-h, --help* 21 22 Show diary help text 23 24 *-d, --dir*=DIARY_DIR 25 26 Directory with the journal text files 27 28 *-e, --editor*=EDITOR 29 30 Text editor used for opening the journal files 31 32 *-f, --fmt*=FMT 33 34 FMT is a custom date and file format. Change with care, because the 35 diary reads and writes to files with file name FMT. The new FMT is only 36 applied to newly saved entries. Existing entries with the old FMT are 37 not automatically migrated to the new FMT and do not show up with a new 38 FMT specifier. Consequently, a change in FMT shows an empty diary at 39 first. Rename all files in the *DIARY_DIR* to migrate to a new FMT. 40 41 *-F, --fmt-cmd*=FMT_CMD 42 43 Journal entries are formatted with this command. If not set (default), 44 the characters are printed to the preview screen character by character 45 (without word wrap). For example, to enable word wrap after 75 46 characters, use "fmt -s" as FMT_CMD. To format markdown, use "mdcat -c" 47 or similar, see *CUSTOM FORMATTING*. 48 49 *-p, --no-pty* 50 51 No pseudo terminal (pty) for entry preview. Only effective in 52 combination with *--fmt-cmd*. If set, the output of *--fmt-cmd* is displayed 53 with Ncurses. If not set (default), the result of *--fmt-cmd* (journal 54 entry preview) is printed on a pseudo-terminal (pty) and not processed 55 with Ncurses. The pty supports the ANSI escape sequences (e.g. colors, 56 font types, etc.) of the native terminal. 57 58 *-m, --no-mouse* 59 60 Disable mouse, don't listen for mouse events. Mouse events are enabled 61 by default. Without *--no-mouse* flag (default), native text selection and 62 right-click in the preview window requires holding down the SHIFT key, 63 see *MOUSE EVENTS*. 64 65 *-r, --range*=RANGE 66 67 The number of years to show before/after today. Defaults to 1 year. 68 69 *-w, --weekday*=DAY 70 71 First day of the week. DAY is an integer in range (0..6), interpreted as 72 0 or 7 = Sun, 1 = Mon, ..., 6 = Sat. If glibc is installed, the first 73 day of the week is derived from the current locale setting ($LANG, see 74 man locale). Without glibc, the first weekday defaults to 1 (Monday), 75 unless specified otherwise with this option. 76 77 # NAVIGATION 78 Navigation is done using the following vim-inspired keyboard shortcuts: 79 80 [[ *Key(s)* 81 :< Action 82 | *e, Enter* 83 : edit current entry 84 | *d, x* 85 : delete current entry 86 | *t* 87 : jump to today 88 | *f* 89 : jump to or find specific day 90 | *j, down* 91 : go forward by 1 week 92 | *k, up* 93 : go backward by 1 week 94 | *h, left* 95 : go left by 1 day 96 | *l, right* 97 : go right by 1 day 98 | *J* 99 : go forward by 1 month 100 | *K* 101 : go backward by 1 month 102 | *N* 103 : go to the previous journal entry 104 | *n* 105 : go to the next journal entry 106 | *g* 107 : go to start of journal 108 | *G* 109 : go to end of journal 110 | *s, S* 111 : sync selected day/Month with CalDAV server 112 | *i* 113 : import entries from .ics file 114 | *E* 115 : export entries to .ics file 116 | *q* 117 : quit the program 118 119 120 # ENVIRONMENT 121 *DIARY_DIR* 122 If this variable is set to a directory that can be opened, diary will 123 use it to store diary files. Diary files are simple text files named 124 after their date, formatted according to *FMT* (see *--fmt* option). The 125 format defaults to "%Y-%m-%d", which is "YYYY-MM-DD" (see man strftime). 126 All other files different from FMT are ignored. 127 128 *EDITOR* 129 The program used to edit journal entries inside *DIARY_DIR*. 130 131 *LANG* 132 The default locale used to display the first day of the week, see 133 *--weekday* option. 134 135 136 # ARGUMENTS 137 If the argument *DIARY_DIR* is given, diary files are read from and stored to 138 that directory, ignoring the $DIARY_DIR environment variable, any *--dir* option 139 or the *dir* value set in the *CONFIGURATION FILE*. 140 141 # FILES 142 ${PREFIX:-/usr/local/bin}/*diary* 143 The diary binary 144 145 ${XDG_CONFIG_HOME:-~/.config}/diary/*diary.cfg* 146 An optional diary *CONFIGURATION FILE* 147 148 # CONFIGURATION FILE 149 The *diary.cfg* configuration file can optionally be used to persist diary 150 configuration. Use the "#" or ";" characters to comment lines. 151 152 Create default configuration location: 153 154 ``` 155 mkdir -p ${XDG_CONFIG_HOME:-~/.config}/diary 156 ``` 157 158 Install an example configuration file with defaults: 159 160 ``` 161 tee ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg <<EOF 162 # https://code.in0rdr.ch/diary/file/config/diary.cfg.html 163 # Path that holds the journal text files 164 #dir = ~/diary 165 # Number of years to show before/after todays date 166 range = 1 167 # 0 = Sunday, 1 = Monday, ..., 6 = Saturday 168 weekday = 1 169 # Date and file format, change with care 170 fmt = %Y-%m-%d 171 # Text format command for entry preview 172 fmt_cmd = 173 # Use pseudo terminal (pty) to view result of fmt_cmd 174 #no_pty = false 175 # Listen for mouse events 176 #no_mouse = false 177 # Editor to open journal files with 178 editor = 179 # CalDAV server URI 180 #caldav_server = 181 # Calendar name for CalDAV sync 182 #caldav_calendar = 183 # CalDAV server username 184 #caldav_username = 185 # CalDAV server password 186 #caldav_password = 187 # OAuth command to fetch access token. For example, "oama access" 188 #oauth_eval_cmd = 189 EOF 190 ``` 191 192 To copy the sample file from the source repository: 193 194 ``` 195 cp config/diary.cfg ${XDG_CONFIG_HOME:-~/.config}/diary/ 196 ``` 197 198 The file "${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg" should adhere to a 199 basic "key = value" format. The value is read until the end of the line '\\n'. 200 Lines can be commented with the special characters "#"or ";". 201 202 The following configuration keys are currently supported: 203 204 [[ *Command Line Option* 205 :< *Config Key* 206 :< *Example Config Value* 207 :< *Default Config Value* 208 :< *Description* 209 | "--dir", "-d", or first non-option argument 210 : dir 211 : ~/diary 212 : n/a 213 : Diary directory. Path that holds the journal text files. If unset, defaults 214 to environment variable "$DIARY_DIR". 215 | "--editor" or "-e" 216 : editor 217 : vim 218 : (empty) 219 : Editor to open journal files with. If unset, defaults to environment 220 variable "$EDITOR". If no editor is provided, the diary is opened read-only. 221 | "--fmt" or "-f" 222 : fmt 223 : %d_%b_%y 224 : %Y-%m-%d 225 : Date format and file name for the files inside the "dir". For the format 226 specifiers, see "man strftime". Be careful: If you change this, you might no 227 longer find your existing diary entries, because the diary assumes to find the 228 journal files under another file name. Hence, a change in FMT shows an empty 229 diary, at first. Rename all files in the DIARY_DIR to migrate to a new FMT. 230 | "--fmt-cmd" or "-F" 231 : fmt_cmd 232 : "fmt -w75 -s", "mdcat -c" or "mdcat" 233 : (empty) 234 : Journal entries are formatted with this command. If not set (default), the 235 characters are printed to the preview screen character by character (without 236 word wrap). For example, to enable word wrap after 75 characters, use "fmt -s" 237 as FMT_CMD. See also [Custom Formatting](#Custom-Formatting). 238 | "--no-pty" or "-p" 239 : no_pty 240 : "true" 241 : false (or 0) 242 : No pseudo terminal (pty) for entry preview. Only effective in combination 243 with "--fmt-cmd". If set to true (or 1), the output of "--fmt-cmd" is displayed 244 with Ncurses. If set to false (or 0), the result of "--fmt-cmd" (journal entry 245 preview) is printed on a pseudo-terminal (pty) and not processed with Ncurses. 246 The pty supports the ANSI escape sequences (e.g. colors, font types, etc.) of 247 the native terminal. 248 | "--no-mouse" or "-m" 249 : no_mouse 250 : "true" 251 : false (or 0) 252 : Don't listen for *MOUSE EVENTS*. With no_mouse=0 (default), native 253 text selection and right-click in the preview window requires holding down the 254 "SHIFT" key. 255 | "--range" or "-r" 256 : range 257 : 10 258 : 1 259 : Number of years to show before/after todays date 260 | "--weekday" or "-w" 261 : weekday 262 : 0 263 : 1 264 : First weekday, "7" = Sunday, "1" = Monday, ..., "6" = Saturday. Use "7" (or 265 "0") to display week beginning at Sunday ("S-M-T-W-T-F-S"), or "1" for 266 "M-T-W-T-F-S-S". If "glibc" is installed, the first day of the week is derived 267 from the current locale setting ("$LANG", see "man locale"). Without "glibc", 268 the first weekday defaults to 1 (Monday), unless specified otherwise with this 269 option. 270 | n/a 271 : caldav_server 272 : Google calendar "https://apidata.googleusercontent.com/caldav/v2", Yahoo 273 calendar "https://caldav.calendar.yahoo.com", GMX "https://caldav.gmx.net" or 274 other CalDAV compatible provider. 275 : (empty) 276 : CalDAV server for *CALDAV SYNC* (required). 277 | n/a 278 : caldav_calendar 279 : diary 280 : (empty) 281 : Calendar name for *CALDAV SYNC* (required). 282 | n/a 283 : caldav_username 284 : 285 : (empty) 286 : CalDAV server username for *CALDAV SYNC* (optional). 287 | n/a 288 : caldav_password 289 : 290 : (empty) 291 : CalDAV server password for *CALDAV SYNC* (optional). 292 | n/a 293 : oauth_eval_cmd 294 : "oama access <email>" or "pass" 295 : (empty) 296 : OAuth command to fetch access token for *CALDAV SYNC* (optional). 297 298 # CUSTOM FORMATTING 299 The preview of the journal entries can be processed with a custom *--fmt-cmd*. 300 The result of this formatting command is printed to a pseudo-terminal (pty) by 301 default. This behavior can be changed with the *--no-pty* flag. The output 302 processed on the pty (without Ncurses) includes all ANSI escape characters 303 supported by the terminal (colors, font types, etc.). Thus, formatters like 304 "fmt", or any "cat like program" ("mdcat" to process Markdown) can be plugged in 305 for *--fmt-cmd*. 306 307 # MOUSE EVENTS 308 Mouse events are listened for by default (*no_mouse*=false configuration). This 309 behavior can be disabled with the *--no-mouse* flag or in the *CONFIGURATION 310 FILE* (*no_mouse*=true). With *no_mouse*=false (default), use the SHIFT key for 311 native text selection and right-click in the preview window. 312 313 # IMPORT 314 The import functionality can be triggered by pressing *i* and expects a path to 315 an ics file. Files in the *DIARY_DIR* are overwritten with the entries from the 316 imported ics file. 317 318 # EXPORT 319 The export functionality can be triggered by pressing *E* and asks for a file 320 path to an ics file for storing the journal entries. The ics file will be 321 created if it does not exist. Existing ics files are overwritten. 322 323 # CALDAV SYNC 324 The journal files can be synced via CalDAV by pressing *s*. Pressing *S* syncs 325 all journal entries of the active month. 326 327 The most recently modified entry is considered up to date and is automatically 328 replaced on the remote side. If the remote file is more recent, the local file 329 can be replaced with the remote content after confirmation. 330 331 No sync is performed, when both files (local/remote) have the same modification 332 timestamp or no files exists on the server and on disk at all (i.e., no entry 333 for that date). 334 335 The diary creates a full-day calendar entry. It's advised to use a separate 336 calendar for syncing purposes and not to have multiple events for a day on the 337 remote calendar. The diary only considers the first event of a given day. 338 339 The calender for synchronization can be defined with the configuration key 340 "caldav_calendar". This key is empty by default. It is required to configure at 341 least following parameters in the *CONFIGURATION FILE*: 342 343 - caldav_server: Calendar server API 344 - caldav_calendar: Calendar name for CalDAV sync 345 346 In addition, it is required to specifiy either "caldav_username" and 347 "caldav_password" for basicauth (takes precedence) OR the "oauth_eval_cmd" to 348 retreive an OAuth access token from a password manager or tool that prints the 349 token to stdout. Leave username/password empty if you intend to use OAuth 350 ("oauth_eval_cmd"). 351 352 Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server. Other 353 CalDAV servers and APIs that are secured with OAuth2 might work as well 354 (untested). 355 356 Use the EXPORT/IMPORT functionality for more batch oriented processing. Making 357 a network request and deciding the most recently modified entry (local/remote) 358 takes quite some time for large batches. 359 360 # GOOGLE CALENDAR OAUTH2 361 To synchronize with the Google calendar, it is required to setup a project in 362 the cloud console and enable the CalDAV API (not the Google Calendar API): 363 364 https://console.cloud.google.com/apis/api/caldav.googleapis.com 365 366 The Google Calendar CalDAV API is protected with OAuth2: 367 368 https://developers.google.com/identity/protocols/oauth2 369 370 The "application", the "consent screen" and the "credentials" (client id and 371 secret) need to be defined in the Google cloud console. Client id and secret 372 should be stored in an utility application that can fetch and refresh the OAuth 373 access token (e.g., "oama"). The command to access the access token 374 ("oauth_eval_cmd") should be configured in the *CONFIGURATION FILE*. 375 376 The application requires two OAuth2 scopes 377 (https://developers.google.com/calendar/api/auth) for CalDAV requests: 378 379 - "https://www.googleapis.com/auth/calendar": read/share access to Calendars, 380 required to discover the unique hyperlink/URI for the calendar specified by 381 config key "caldav_calendar" 382 - "https://www.googleapis.com/auth/calendar.events": read/write access to 383 Events owned by the user, allows diary to create/read/update/delete events in 384 "caldav_calendar" 385 386 The user is asked for consent during the first CALDAV SYNC. 387 388 # PRECEDENCE RULES 389 The default variables, for instance, for the configuration variables "editor", 390 "dir" and "weekday", are populated with values in the following order, where 391 earlier entries are overwritten by subsequent ones if they exist: 392 393 [[ 394 :< *Description* 395 | 1 396 : No default for *DIARY_DIR*. Defaults for "range", "weekday", "fmt" and 397 "editor" are provided in "diary.h". If *EDITOR* is unset and no editor is 398 provided in the *CONFIGURATION FILE* or *--editor* option, the diary works 399 read-only. Journal files cannot be opened. If *DIARY_DIR* is not provided, the 400 diary won't open. 401 | 2 402 : *CONFIGURATION FILE* (empty default for "editor", no default for "dir") 403 | 3 404 : Environment variables $DIARY_DIR, $EDITOR and $LANG for locale ("weekday") 405 | 4 406 : Option arguments, see section *OPTIONS* 407 | 5 408 : First non-option argument is interpreted as *DIARY_DIR* 409 410 # PRECEDENCE EXAMPLE: LOCALE AND FIRST DAY OF WEEK 411 If glibc is installed, the first weekday defaults to the locale defined in the 412 current shell environment ($LANG, see man locale), unless specified otherwise 413 with the *--weekday* option. 414 415 Start with weekday=3(Wed), overrule any other configuration value: 416 ``` 417 diary -w3 418 ``` 419 420 Start with glibc derived weekday=1, regardless of weekday in config file: 421 ``` 422 LANG=de_CH diary 423 ``` 424 425 If glibc is installed, start with glibc derived base date (weekday=0): 426 ``` 427 LANG= diary 428 ``` 429 430 Disable environment variable, default to value from config file: 431 ``` 432 unset LANG 433 ``` 434 435 Start with weekday default from config file, if available: 436 ``` 437 diary 438 ``` 439 440 Remove config file: 441 ``` 442 rm ${XDG_CONFIG_HOME:-~/.config}/diary/diary.cfg 443 ``` 444 445 Start with weekday default value from source code (1=Mon): 446 ``` 447 diary 448 ``` 449 450 # DEVELOPMENT AND SUPPORT 451 Contributions are always welcome! All source code is available at 452 https://code.in0rdr.ch/diary. 453 454 For question and support visit https://web.libera.chat/gamja/#p0c. 455 456 # AUTHORS 457 - Andreas Gruhler 458 - Matthias Beyer 459 - Johnathan Jenkins 460 - Yu-Jie Lin 461 - Balduin Dettling 462 - Avindra Goolcharan 463 - Oliver Blanthorn 464 - Jonny Burger 465 466 # LICENSE 467 MIT License, https://code.in0rdr.ch/diary/file/LICENSE.html