diary.1 (17519B)
1 .\" Generated by scdoc 1.11.3 2 .\" Complete documentation for this program is not available as a GNU info page 3 .ie \n(.g .ds Aq \(aq 4 .el .ds Aq ' 5 .nh 6 .ad l 7 .\" Begin generated content: 8 .TH "DIARY" "1" "2024-09-14" 9 .PP 10 .SH NAME 11 diary - text-based journaling program 12 .PP 13 .SH SYNOPSIS 14 \fBdiary\fR [OPTION].\&.\&.\& [DIARY_DIR].\&.\&.\& 15 .PP 16 .SH DESCRIPTION 17 Open the \fBdiary\fR journal for entries stored in \fBDIARY_DIR\fR.\& 18 .PP 19 \fBDIARY_DIR\fR is required, if not set as environment variable or defined in the 20 \fBCONFIGURATION FILE\fR.\& 21 .PP 22 .SH OPTIONS 23 \fB-v, --version\fR 24 .PP 25 .RS 4 26 Print diary version 27 .PP 28 .RE 29 \fB-h, --help\fR 30 .PP 31 .RS 4 32 Show diary help text 33 .PP 34 .RE 35 \fB-d, --dir\fR=DIARY_DIR 36 .PP 37 .RS 4 38 Directory with the journal text files 39 .PP 40 .RE 41 \fB-e, --editor\fR=EDITOR 42 .PP 43 .RS 4 44 Text editor used for opening the journal files 45 .PP 46 .RE 47 \fB-f, --fmt\fR=FMT 48 .PP 49 .RS 4 50 FMT is a custom date and file format.\& Change with care, because the 51 diary reads and writes to files with file name FMT.\& The new FMT is only 52 applied to newly saved entries.\& Existing entries with the old FMT are 53 not automatically migrated to the new FMT and do not show up with a new 54 FMT specifier.\& Consequently, a change in FMT shows an empty diary at 55 first.\& Rename all files in the \fBDIARY_DIR\fR to migrate to a new FMT.\& 56 .PP 57 .RE 58 \fB-F, --fmt-cmd\fR=FMT_CMD 59 .PP 60 .RS 4 61 Journal entries are formatted with this command.\& If not set (default), 62 the characters are printed to the preview screen character by character 63 (without word wrap).\& For example, to enable word wrap after 75 64 characters, use "fmt -s" as FMT_CMD.\& To format markdown, use "mdcat -c" 65 or similar, see \fBCUSTOM FORMATTING\fR.\& 66 .PP 67 .RE 68 \fB-p, --no-pty\fR 69 .PP 70 .RS 4 71 No pseudo terminal (pty) for entry preview.\& Only effective in 72 combination with \fB--fmt-cmd\fR.\& If set, the output of \fB--fmt-cmd\fR is displayed 73 with Ncurses.\& If not set (default), the result of \fB--fmt-cmd\fR (journal 74 entry preview) is printed on a pseudo-terminal (pty) and not processed 75 with Ncurses.\& The pty supports the ANSI escape sequences (e.\&g.\& colors, 76 font types, etc.\&) of the native terminal.\& 77 .PP 78 .RE 79 \fB-m, --no-mouse\fR 80 .PP 81 .RS 4 82 Disable mouse, don'\&t listen for mouse events.\& Mouse events are enabled 83 by default.\& Without \fB--no-mouse\fR flag (default), native text selection and 84 right-click in the preview window requires holding down the SHIFT key, 85 see \fBMOUSE EVENTS\fR.\& 86 .PP 87 .RE 88 \fB-r, --range\fR=RANGE 89 .PP 90 .RS 4 91 The number of years to show before/after today.\& Defaults to 1 year.\& 92 .PP 93 .RE 94 \fB-w, --weekday\fR=DAY 95 .PP 96 .RS 4 97 First day of the week.\& DAY is an integer in range (0.\&.\&6), interpreted as 98 0 or 7 = Sun, 1 = Mon, .\&.\&.\&, 6 = Sat.\& If glibc is installed, the first 99 day of the week is derived from the current locale setting ($LANG, see 100 man locale).\& Without glibc, the first weekday defaults to 1 (Monday), 101 unless specified otherwise with this option.\& 102 .PP 103 .RE 104 .SH NAVIGATION 105 Navigation is done using the following vim-inspired keyboard shortcuts: 106 .PP 107 .TS 108 allbox;l lx 109 l lx 110 l lx 111 l lx 112 l lx 113 l lx 114 l lx 115 l lx 116 l lx 117 l lx 118 l lx 119 l lx 120 l lx 121 l lx 122 l lx 123 l lx 124 l lx 125 l lx 126 l lx. 127 T{ 128 \fBKey(s)\fR 129 T} T{ 130 Action 131 T} 132 T{ 133 \fBe, Enter\fR 134 T} T{ 135 edit current entry 136 T} 137 T{ 138 \fBd, x\fR 139 T} T{ 140 delete current entry 141 T} 142 T{ 143 \fBt\fR 144 T} T{ 145 jump to today 146 T} 147 T{ 148 \fBf\fR 149 T} T{ 150 jump to or find specific day 151 T} 152 T{ 153 \fBj, down\fR 154 T} T{ 155 go forward by 1 week 156 T} 157 T{ 158 \fBk, up\fR 159 T} T{ 160 go backward by 1 week 161 T} 162 T{ 163 \fBh, left\fR 164 T} T{ 165 go left by 1 day 166 T} 167 T{ 168 \fBl, right\fR 169 T} T{ 170 go right by 1 day 171 T} 172 T{ 173 \fBJ\fR 174 T} T{ 175 go forward by 1 month 176 T} 177 T{ 178 \fBK\fR 179 T} T{ 180 go backward by 1 month 181 T} 182 T{ 183 \fBN\fR 184 T} T{ 185 go to the previous journal entry 186 T} 187 T{ 188 \fBn\fR 189 T} T{ 190 go to the next journal entry 191 T} 192 T{ 193 \fBg\fR 194 T} T{ 195 go to start of journal 196 T} 197 T{ 198 \fBG\fR 199 T} T{ 200 go to end of journal 201 T} 202 T{ 203 \fBs, S\fR 204 T} T{ 205 sync selected day/Month with CalDAV server 206 T} 207 T{ 208 \fBi\fR 209 T} T{ 210 import entries from .\&ics file 211 T} 212 T{ 213 \fBE\fR 214 T} T{ 215 export entries to .\&ics file 216 T} 217 T{ 218 \fBq\fR 219 T} T{ 220 quit the program 221 T} 222 .TE 223 .sp 1 224 .PP 225 .SH ENVIRONMENT 226 \fBDIARY_DIR\fR 227 .RS 4 228 If this variable is set to a directory that can be opened, diary will 229 use it to store diary files.\& Diary files are simple text files named 230 after their date, formatted according to \fBFMT\fR (see \fB--fmt\fR option).\& The 231 format defaults to "%Y-%m-%d", which is "YYYY-MM-DD" (see man strftime).\& 232 All other files different from FMT are ignored.\& 233 .PP 234 .RE 235 \fBEDITOR\fR 236 .RS 4 237 The program used to edit journal entries inside \fBDIARY_DIR\fR.\& 238 .PP 239 .RE 240 \fBLANG\fR 241 .RS 4 242 The default locale used to display the first day of the week, see 243 \fB--weekday\fR option.\& 244 .PP 245 .PP 246 .RE 247 .SH ARGUMENTS 248 If the argument \fBDIARY_DIR\fR is given, diary files are read from and stored to 249 that directory, ignoring the $DIARY_DIR environment variable, any \fB--dir\fR option 250 or the \fBdir\fR value set in the \fBCONFIGURATION FILE\fR.\& 251 .PP 252 .SH FILES 253 ${PREFIX:-/usr/local/bin}/\fBdiary\fR 254 .RS 4 255 The diary binary 256 .PP 257 .RE 258 ${XDG_CONFIG_HOME:-~/.\&config}/diary/\fBdiary.\&cfg\fR 259 .RS 4 260 An optional diary \fBCONFIGURATION FILE\fR 261 .PP 262 .RE 263 .SH CONFIGURATION FILE 264 The \fBdiary.\&cfg\fR configuration file can optionally be used to persist diary 265 configuration.\& Use the "#" or ";" characters to comment lines.\& 266 .PP 267 Create default configuration location: 268 .PP 269 .nf 270 .RS 4 271 mkdir -p ${XDG_CONFIG_HOME:-~/\&.config}/diary 272 .fi 273 .RE 274 .PP 275 Install an example configuration file with defaults: 276 .PP 277 .nf 278 .RS 4 279 tee ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg <<EOF 280 # https://code\&.in0rdr\&.ch/diary/file/config/diary\&.cfg\&.html 281 # Path that holds the journal text files 282 #dir = ~/diary 283 # Number of years to show before/after todays date 284 range = 1 285 # 0 = Sunday, 1 = Monday, \&.\&.\&., 6 = Saturday 286 weekday = 1 287 # Date and file format, change with care 288 fmt = %Y-%m-%d 289 # Text format command for entry preview 290 fmt_cmd = 291 # Use pseudo terminal (pty) to view result of fmt_cmd 292 #no_pty = false 293 # Listen for mouse events 294 #no_mouse = false 295 # Editor to open journal files with 296 editor = 297 # CalDAV server URI 298 #caldav_server = 299 # Calendar name for CalDAV sync 300 #caldav_calendar = 301 # CalDAV server username 302 #caldav_username = 303 # CalDAV server password 304 #caldav_password = 305 # OAuth command to fetch access token\&. For example, "oama access" 306 #oauth_eval_cmd = 307 EOF 308 .fi 309 .RE 310 .PP 311 To copy the sample file from the source repository: 312 .PP 313 .nf 314 .RS 4 315 cp config/diary\&.cfg ${XDG_CONFIG_HOME:-~/\&.config}/diary/ 316 .fi 317 .RE 318 .PP 319 The file "${XDG_CONFIG_HOME:-~/.\&config}/diary/diary.\&cfg" should adhere to a 320 basic "key = value" format.\& The value is read until the end of the line '\&\en'\&.\& 321 Lines can be commented with the special characters "#"or ";".\& 322 .PP 323 The following configuration keys are currently supported: 324 .PP 325 .TS 326 allbox;l lx lx lx lx 327 l lx lx lx lx 328 l lx lx lx lx 329 l lx lx lx lx 330 l lx lx lx lx 331 l lx lx lx lx 332 l lx lx lx lx 333 l lx lx lx lx 334 l lx lx lx lx 335 l lx lx lx lx 336 l lx lx lx lx 337 l lx lx lx lx 338 l lx lx lx lx 339 l lx lx lx lx. 340 T{ 341 \fBCommand Line Option\fR 342 T} T{ 343 \fBConfig Key\fR 344 T} T{ 345 \fBExample Config Value\fR 346 T} T{ 347 \fBDefault Config Value\fR 348 T} T{ 349 \fBDescription\fR 350 T} 351 T{ 352 "--dir", "-d", or first non-option argument 353 T} T{ 354 dir 355 T} T{ 356 ~/diary 357 T} T{ 358 n/a 359 T} T{ 360 Diary directory.\& Path that holds the journal text files.\& If unset, defaults to environment variable "$DIARY_DIR".\& 361 T} 362 T{ 363 "--editor" or "-e" 364 T} T{ 365 editor 366 T} T{ 367 vim 368 T} T{ 369 (empty) 370 T} T{ 371 Editor to open journal files with.\& If unset, defaults to environment variable "$EDITOR".\& If no editor is provided, the diary is opened read-only.\& 372 T} 373 T{ 374 "--fmt" or "-f" 375 T} T{ 376 fmt 377 T} T{ 378 %d_%b_%y 379 T} T{ 380 %Y-%m-%d 381 T} T{ 382 Date format and file name for the files inside the "dir".\& For the format specifiers, see "man strftime".\& 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.\& 383 T} 384 T{ 385 "--fmt-cmd" or "-F" 386 T} T{ 387 fmt_cmd 388 T} T{ 389 "fmt -w75 -s", "mdcat -c" or "mdcat" 390 T} T{ 391 (empty) 392 T} T{ 393 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.\& See also [Custom Formatting](#Custom-Formatting).\& 394 T} 395 T{ 396 "--no-pty" or "-p" 397 T} T{ 398 no_pty 399 T} T{ 400 "true" 401 T} T{ 402 false (or 0) 403 T} T{ 404 No pseudo terminal (pty) for entry preview.\& Only effective in combination with "--fmt-cmd".\& If set to true (or 1), the output of "--fmt-cmd" is displayed with Ncurses.\& If set to false (or 0), the result of "--fmt-cmd" (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.\& 405 T} 406 T{ 407 "--no-mouse" or "-m" 408 T} T{ 409 no_mouse 410 T} T{ 411 "true" 412 T} T{ 413 false (or 0) 414 T} T{ 415 Don'\&t listen for \fBMOUSE EVENTS\fR.\& With no_mouse=0 (default), native text selection and right-click in the preview window requires holding down the "SHIFT" key.\& 416 T} 417 T{ 418 "--range" or "-r" 419 T} T{ 420 range 421 T} T{ 422 10 423 T} T{ 424 1 425 T} T{ 426 Number of years to show before/after todays date 427 T} 428 T{ 429 "--weekday" or "-w" 430 T} T{ 431 weekday 432 T} T{ 433 0 434 T} T{ 435 1 436 T} T{ 437 First weekday, "7" = Sunday, "1" = Monday, .\&.\&.\&, "6" = Saturday.\& Use "7" (or "0") to display week beginning at Sunday ("S-M-T-W-T-F-S"), or "1" for "M-T-W-T-F-S-S".\& 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.\& 438 T} 439 T{ 440 n/a 441 T} T{ 442 caldav_server 443 T} T{ 444 Google calendar "https://apidata.\&googleusercontent.\&com/caldav/v2", Yahoo calendar "https://caldav.\&calendar.\&yahoo.\&com", GMX "https://caldav.\&gmx.\&net" or other CalDAV compatible provider.\& 445 T} T{ 446 (empty) 447 T} T{ 448 CalDAV server for \fBCALDAV SYNC\fR (required).\& 449 T} 450 T{ 451 n/a 452 T} T{ 453 caldav_calendar 454 T} T{ 455 diary 456 T} T{ 457 (empty) 458 T} T{ 459 Calendar name for \fBCALDAV SYNC\fR (required).\& 460 T} 461 T{ 462 n/a 463 T} T{ 464 caldav_username 465 T} T{ 466 467 T} T{ 468 (empty) 469 T} T{ 470 CalDAV server username for \fBCALDAV SYNC\fR (optional).\& 471 T} 472 T{ 473 n/a 474 T} T{ 475 caldav_password 476 T} T{ 477 478 T} T{ 479 (empty) 480 T} T{ 481 CalDAV server password for \fBCALDAV SYNC\fR (optional).\& 482 T} 483 T{ 484 n/a 485 T} T{ 486 oauth_eval_cmd 487 T} T{ 488 "oama access <email>" or "pass" 489 T} T{ 490 (empty) 491 T} T{ 492 OAuth command to fetch access token for \fBCALDAV SYNC\fR (optional).\& 493 T} 494 .TE 495 .sp 1 496 .SH CUSTOM FORMATTING 497 The preview of the journal entries can be processed with a custom \fB--fmt-cmd\fR.\& 498 The result of this formatting command is printed to a pseudo-terminal (pty) by 499 default.\& This behavior can be changed with the \fB--no-pty\fR flag.\& The output 500 processed on the pty (without Ncurses) includes all ANSI escape characters 501 supported by the terminal (colors, font types, etc.\&).\& Thus, formatters like 502 "fmt", or any "cat like program" ("mdcat" to process Markdown) can be plugged in 503 for \fB--fmt-cmd\fR.\& 504 .PP 505 .SH MOUSE EVENTS 506 Mouse events are listened for by default (\fBno_mouse\fR=false configuration).\& This 507 behavior can be disabled with the \fB--no-mouse\fR flag or in the \fBCONFIGURATION 508 FILE\fR (\fBno_mouse\fR=true).\& With \fBno_mouse\fR=false (default), use the SHIFT key for 509 native text selection and right-click in the preview window.\& 510 .PP 511 .SH IMPORT 512 The import functionality can be triggered by pressing \fBi\fR and expects a path to 513 an ics file.\& Files in the \fBDIARY_DIR\fR are overwritten with the entries from the 514 imported ics file.\& 515 .PP 516 .SH EXPORT 517 The export functionality can be triggered by pressing \fBE\fR and asks for a file 518 path to an ics file for storing the journal entries.\& The ics file will be 519 created if it does not exist.\& Existing ics files are overwritten.\& 520 .PP 521 .SH CALDAV SYNC 522 The journal files can be synced via CalDAV by pressing \fBs\fR.\& Pressing \fBS\fR syncs 523 all journal entries of the active month.\& 524 .PP 525 The most recently modified entry is considered up to date and is automatically 526 replaced on the remote side.\& If the remote file is more recent, the local file 527 can be replaced with the remote content after confirmation.\& 528 .PP 529 No sync is performed, when both files (local/remote) have the same modification 530 timestamp or no files exists on the server and on disk at all (i.\&e.\&, no entry 531 for that date).\& 532 .PP 533 The diary creates a full-day calendar entry.\& It'\&s advised to use a separate 534 calendar for syncing purposes and not to have multiple events for a day on the 535 remote calendar.\& The diary only considers the first event of a given day.\& 536 .PP 537 The calender for synchronization can be defined with the configuration key 538 "caldav_calendar".\& This key is empty by default.\& It is required to configure at 539 least following parameters in the \fBCONFIGURATION FILE\fR: 540 .PP 541 .PD 0 542 .IP \(bu 4 543 caldav_server: Calendar server API 544 .IP \(bu 4 545 caldav_calendar: Calendar name for CalDAV sync 546 .PD 547 .PP 548 In addition, it is required to specifiy either "caldav_username" and 549 "caldav_password" for basicauth (takes precedence) OR the "oauth_eval_cmd" to 550 retreive an OAuth access token from a password manager or tool that prints the 551 token to stdout.\& Leave username/password empty if you intend to use OAuth 552 ("oauth_eval_cmd").\& 553 .PP 554 Read GOOGLE CALENDAR OAUTH2 to setup authorization with the Google server.\& Other 555 CalDAV servers and APIs that are secured with OAuth2 might work as well 556 (untested).\& 557 .PP 558 Use the EXPORT/IMPORT functionality for more batch oriented processing.\& Making 559 a network request and deciding the most recently modified entry (local/remote) 560 takes quite some time for large batches.\& 561 .PP 562 .SH GOOGLE CALENDAR OAUTH2 563 To synchronize with the Google calendar, it is required to setup a project in 564 the cloud console and enable the CalDAV API (not the Google Calendar API): 565 .PP 566 https://console.\&cloud.\&google.\&com/apis/api/caldav.\&googleapis.\&com 567 .PP 568 The Google Calendar CalDAV API is protected with OAuth2: 569 .PP 570 https://developers.\&google.\&com/identity/protocols/oauth2 571 .PP 572 The "application", the "consent screen" and the "credentials" (client id and 573 secret) need to be defined in the Google cloud console.\& Client id and secret 574 should be stored in an utility application that can fetch and refresh the OAuth 575 access token (e.\&g.\&, "oama").\& The command to access the access token 576 ("oauth_eval_cmd") should be configured in the \fBCONFIGURATION FILE\fR.\& 577 .PP 578 The application requires two OAuth2 scopes 579 (https://developers.\&google.\&com/calendar/api/auth) for CalDAV requests: 580 .PP 581 .PD 0 582 .IP \(bu 4 583 "https://www.\&googleapis.\&com/auth/calendar": read/share access to Calendars, 584 required to discover the unique hyperlink/URI for the calendar specified by 585 config key "caldav_calendar" 586 .IP \(bu 4 587 "https://www.\&googleapis.\&com/auth/calendar.\&events": read/write access to 588 Events owned by the user, allows diary to create/read/update/delete events in 589 "caldav_calendar" 590 .PD 591 .PP 592 The user is asked for consent during the first CALDAV SYNC.\& 593 .PP 594 .SH PRECEDENCE RULES 595 The default variables, for instance, for the configuration variables "editor", 596 "dir" and "weekday", are populated with values in the following order, where 597 earlier entries are overwritten by subsequent ones if they exist: 598 .PP 599 .TS 600 allbox;l lx 601 l lx 602 l lx 603 l lx 604 l lx 605 l lx. 606 T{ 607 608 T} T{ 609 \fBDescription\fR 610 T} 611 T{ 612 1 613 T} T{ 614 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.\& 615 T} 616 T{ 617 2 618 T} T{ 619 \fBCONFIGURATION FILE\fR (empty default for "editor", no default for "dir") 620 T} 621 T{ 622 3 623 T} T{ 624 Environment variables $DIARY_DIR, $EDITOR and $LANG for locale ("weekday") 625 T} 626 T{ 627 4 628 T} T{ 629 Option arguments, see section \fBOPTIONS\fR 630 T} 631 T{ 632 5 633 T} T{ 634 First non-option argument is interpreted as \fBDIARY_DIR\fR 635 T} 636 .TE 637 .sp 1 638 .SH PRECEDENCE EXAMPLE: LOCALE AND FIRST DAY OF WEEK 639 If glibc is installed, the first weekday defaults to the locale defined in the 640 current shell environment ($LANG, see man locale), unless specified otherwise 641 with the \fB--weekday\fR option.\& 642 .PP 643 Start with weekday=3(Wed), overrule any other configuration value: 644 .nf 645 .RS 4 646 diary -w3 647 .fi 648 .RE 649 .PP 650 Start with glibc derived weekday=1, regardless of weekday in config file: 651 .nf 652 .RS 4 653 LANG=de_CH diary 654 .fi 655 .RE 656 .PP 657 If glibc is installed, start with glibc derived base date (weekday=0): 658 .nf 659 .RS 4 660 LANG= diary 661 .fi 662 .RE 663 .PP 664 Disable environment variable, default to value from config file: 665 .nf 666 .RS 4 667 unset LANG 668 .fi 669 .RE 670 .PP 671 Start with weekday default from config file, if available: 672 .nf 673 .RS 4 674 diary 675 .fi 676 .RE 677 .PP 678 Remove config file: 679 .nf 680 .RS 4 681 rm ${XDG_CONFIG_HOME:-~/\&.config}/diary/diary\&.cfg 682 .fi 683 .RE 684 .PP 685 Start with weekday default value from source code (1=Mon): 686 .nf 687 .RS 4 688 diary 689 .fi 690 .RE 691 .PP 692 .SH DEVELOPMENT AND SUPPORT 693 Contributions are always welcome!\& All source code is available at 694 https://code.\&in0rdr.\&ch/diary.\& 695 .PP 696 For question and support visit https://web.\&libera.\&chat/gamja/#p0c.\& 697 .PP 698 .SH AUTHORS 699 .PD 0 700 .IP \(bu 4 701 Andreas Gruhler 702 .IP \(bu 4 703 Matthias Beyer 704 .IP \(bu 4 705 Johnathan Jenkins 706 .IP \(bu 4 707 Yu-Jie Lin 708 .IP \(bu 4 709 Balduin Dettling 710 .IP \(bu 4 711 Avindra Goolcharan 712 .IP \(bu 4 713 Oliver Blanthorn 714 .IP \(bu 4 715 Jonny Burger 716 .PD 717 .PP 718 .SH LICENSE 719 MIT License, https://code.\&in0rdr.\&ch/diary/file/LICENSE.\&html