docs(man): add manpage
This commit is contained in:
233
agenda.1
Normal file
233
agenda.1
Normal file
@@ -0,0 +1,233 @@
|
||||
.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
|
||||
\#
|
||||
\fBAGENDA_NEXT\fP
|
||||
.RS 4
|
||||
The next agenda file. Can be empty if no next 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
|
||||
Reference in New Issue
Block a user