Jonas Kattendick
406ffb7c19
I first decided against this, but the old `~/.app-trash` is no more fitting than the XDG_DATA_HOME location. The xdg-user-dir DOCUMENTS fallback is too presumptuous and removing it makes things even simpler.
221 lines
4.7 KiB
Groff
221 lines
4.7 KiB
Groff
.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
|
|
`${XDG_DATA_HOME:-"$HOME/.local/share"}/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"
|
|
\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
|