.TH AGENDA 1 "2023-11-14" "agenda 0.0.1"
\#=============================================================================
.SH NAME
agenda \- Manage daily tasks and notes in any plain text format.
\#=============================================================================
.SH SYNOPSIS
\fBagenda\fP [-bcE] [-e <extension>] [-t <name>] [<date>]
.sp 0
\fBagenda\fP edit [-bcE] [-e <extension>] [-t <name>] [<date>]
.sp 0
\fBagenda\fP list [-ac] [-u <date>] [-t <name>] [<date>]
\#=============================================================================
.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 <extension>
.RS 4
Specify the file extension. Otherwise this will fall back to the value of
\fBAGENDA_EXTENSION\fP.
.PP
.RE
\#
\fB\-t\fP <name>
.RS 4
Specify which agenda to edit. Otherwise this will fall back to the value of
\fBAGENDA_DEFAULT\fP.
.PP
.RE
\#
<date>
.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 <date>
.RS 4
Stop listing at \fI<date>\fP. Falls back to `next week` if omitted.
.PP
.RE
\#
\fB\-t\fP <name>
.RS 4
Specify which agenda to list.
.PP
.RE
\#
<date>
.RS 4
Start listing agenda note files at \fI<date>\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
agenda will attempt to find the \fIxdg-user-dir DOCUMENTS\fP directory if
\fBxdg-user-dir(1)\fP is found in \fBPATH\fP. Otherwise `$HOME/.agenda` will be
used.
.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 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.
.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
\#-----------------------------------------------------------------------------
.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
\#=============================================================================
.SH "SEE ALSO"
\fBxdg-user-dir(1)\fP
.RS 4
Used to find the default \fBAGENDA_DIR\fP.
.PP
.RE
\fBdate(1)\fP
.RS 4
Your installation of date determines which date formats for the \fI<date>\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
\# vi:ft=groff noet