.TH AGENDA 1 "2024-06-07" "agenda 0.2.0" \#============================================================================= .SH NAME agenda \- Manage daily tasks and notes in any plain text format. \#============================================================================= .SH SYNOPSIS \fBagenda\fP [-bcE] [-e ] [-t ] [] .sp 0 \fBagenda\fP edit [-bcE] [-e ] [-t ] [] .sp 0 \fBagenda\fP list [-ac] [-u ] [-t ] [] \#============================================================================= .SH DESCRIPTION Manage collections of daily plain text notes. \#----------------------------------------------------------------------------- .SS edit Edit a single agenda note file. This is the default and can be omitted. .sp 1 \# \fB\-b\fP .RS 4 Edit a backlog file (use the date argument as backlog name). Backlog files are not associated with a date but with a name. If the date argument is omitted this will default to `backlog`. .PP .RE \# \fB\-c\fP .RS 4 Create the file if it does not exist. .PP .RE \# \fB\-E\fP .RS 4 Instead of editing the file, print its path to STDOUT. .PP .RE \# \fB\-e\fP .RS 4 Specify the file extension. Otherwise this will fall back to the value of \fBAGENDA_EXTENSION\fP. .PP .RE \# \fB\-t\fP .RS 4 Specify which agenda to edit. Otherwise this will fall back to the value of \fBAGENDA_DEFAULT\fP. .PP .RE \# .RS 4 The date of the agenda note file. Falls back to `today` if omitted. If the \fI-b\fP flag is used this takes a name instead. .PP .RE \#----------------------------------------------------------------------------- .SS list List a range of agenda note files. .sp 1 \# \fB\-a\fP .RS 4 Print the files' absolute path. .PP .RE \# \fB\-c\fP .RS 4 Print the files' content. .PP .RE \# \fB\-u\fP .RS 4 Stop listing at \fI\fP. Falls back to `next week` if omitted. .PP .RE \# \fB\-t\fP .RS 4 Specify which agenda to list. .PP .RE \# .RS 4 Start listing agenda note files at \fI\fB. Falls back to `last week` if omitted. .PP .RE \#============================================================================= .SH ENVIRONMENT \# \fBAGENDA_EDITOR\fP .RS 4 The editor used by the \fBedit\fP subcommand. If this is empty, the value of either \fBVISUAL\fP or \fBEDITOR\fP are used respectively. If neither is defined \fBvi(1)\fP is used. The editor process has access to certain environment variables. .PP .RE \# \fBAGENDA_DIR\fP .RS 4 The home of all agenda note files read and written by agenda. If this is empty \fBXDG_DATA_HOME\fP\fI/agenda\fP will be used. .PP .RE \# \fBAGENDA_DATA_DIRS\fP .RS 4 Colon delimited Paths to additional files that come with an agenda installation and custom overrides. Currently only used for template programs (located in the \fItemplate/\fP sub-directory). If a file is searched in these paths the first file that is found is used. .nr PI 2n If this variable is not set or empty it is set to include (in order) .IP \[bu] \fBXDG_CONFIG_HOME\fP\fI/agenda\fP .IP \[bu] \fI/usr/local/share/agenda\fP .IP \[bu] \fI/usr/share/agenda\fP .PP .RE \# \fBAGENDA_EXTENSION\fP .RS 4 The default extension if the \fI-e\fP option is omitted. This falls back to \fImd\fP. .PP .RE \# \fBAGENDA_DEFAULT\fP .RS 4 The default agenda name if the \fI-t\fP option is omitted. This falls back to \fIagenda\fP. .PP .RE \# \fBAGENDA_TEMPLATE\fP .RS 4 If this variable is not empty the value is interpreted as a command and executed when creating a new agenda note with the \fI-c\fP flag. Any std output of the command is written to the new file. The template process has access to certain environment variables. .PP If this variable is unset or empty \fBAGENDA_DATA_DIRS\fP is searched for an executable in the \fItemplates\fP sub-directory that is named either like the corresponding extension or "default". .sp 1 The following example will copy the last agenda note to the new agenda note file. .sp 1 .RS .EX .eo export AGENDA_TEMPLATE=my_agenda_template export -f my_agenda_template my_agenda_template() { if [ -e "$AGENDA_LAST" ]; then cat "$AGENDA_LAST" fi } .ec .EE .RE .PP Note however that this example is specific to \fBbash(1)\fP, since only bash can export functions this way. In general you should write your template as a script, save it, and set it as executable. .PP To set/override a template for a certain extension (e.g. markdown), save the program to one of the \fBAGENDA_DATA_DIRS\fP, e.g. \fI\fBXDG_CONFIG_HOME\fP/agenda/templates/md\fP. .PP \#----------------------------------------------------------------------------- .SS "Templates and editor" The template command and editor processes have access to certain environment variables. .sp 1 \# \fBAGENDA_DATE\fP .RS 4 The date of the agenda note. .PP .RE \# \fBAGENDA_NAME\fP .RS 4 The agenda name of the agenda note. .PP .RE \# \fBAGENDA_SLUG\fP .RS 4 The agenda name slug of the agenda note. .PP .RE \# \fBAGENDA_FILE\fP .RS 4 The file path of the agenda note. .PP .RE \# \fBAGENDA_LAST\fP .RS 4 The last agenda file. Can be empty if no previous agenda note exists. .PP .RE .SS "Other" \# \fBXDG_CONFIG_HOME\fP .RS 4 The default user configuration path. If this is not set the default of \fBHOME\fP\fI/.config\fP is assumed. .PP .RE \# \fBXDG_DATA_HOME\fP .RS 4 The default user data path. If this is not set the default of \fBHOME\fP\fI/.local/share\fP is assumed. .PP .RE \#============================================================================= .SH "SEE ALSO" \fBdate(1)\fP .RS 4 Your installation of date determines which date formats for the \fI\fP options and arguments are recognized. .PP .RE .SS "Common plain text formats" .TP .BR AsciiDoc .sp 0 .UR https://asciidoc.org/ .UE .TP .BR CommonMark .sp 0 .UR https://commonmark.org/ .UE .TP .BR [x]it! .sp 0 .UR https://xit.jotaen.net/ .UE \#============================================================================= .SH BUGS .UR https://git.rkcsd.com/jonas/agenda/issues .UE \# vi:ft=groff noet