docs(man): add manpage

.gitignore

@@ -0,0 +1 @@
+agenda.1.gz

Makefile

@@ -1,9 +1,18 @@
 PREFIX := /usr/local
 
+./agenda.1.gz: ./agenda.1
+	gzip -fk ./agenda.1
+
 .PHONY: install
-install:
+install: ./agenda.1.gz
 	install -m 755 -D ./agenda $(PREFIX)/bin/agenda
+	install -m 644 -D ./agenda.1.gz $(PREFIX)/share/man/man1/agenda.1.gz
 
 .PHONY: uninstall
 uninstall:
 	rm $(PREFIX)/bin/agenda
+	rm $(PREFIX)/share/man/man1/agenda.1.gz
+
+.PHONY: clean
+clean:
+	rm -f ./agenda.1.gz

README.md

@@ -1,5 +1,11 @@
 # Agenda
 
+> agenda - Manage daily tasks and notes in any plain text format.
+
+## Usage
+
+See `agenda --help` and `man agenda`.
+
 ## Install
 
 Use the make `install` and `uninstall` targets to install or remove the script.

agenda

@@ -1,25 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# The editor used to edit agenda note files.
 AGENDA_EDITOR=${VISUAL:-${EDITOR:-vi}}
 
 # The home of all files read and written by agenda.
 #
-# If this is left empty, this will default to the xdg user DOCUMENTS directory (in a
-# child agenda directory), if `xdg-user-dir` is in PATH. Otherwise it will default
-# to `~/.agenda`.
-#
 # ```
 # $AGENDA_DIR
 # ├── {agenda-name}
-# │   ├── 0000-{backlog-name}.md
+# │   ├── 0000-{backlog-name}.{agenda-ext}
-# │   ├── 1970-01-01.md
+# │   └── {agenda-date}.{agenda-ext}
-# │   ├── 1970-01-02.md
-# │   └── 1970-01-03.md
 # └── {agenda-name}
-#     ├── 1970-01-01.md
+#     └── {agenda-date}.{agenda-ext}
-#     ├── 1970-01-02.md
-#     └── 1970-01-03.md
 # ```
 #
 AGENDA_DIR=${AGENDA_DIR:-}
@@ -31,24 +24,6 @@ AGENDA_EXTENSION=${AGENDA_EXTENSION:-"md"}
 AGENDA_DEFAULT=${AGENDA_DEFAULT:-"agenda"}
 
 # Command that provides the initial contents of new agenda files.
-#
-# The value is executed as a single binary, meaning that it is not possible to
-# define any arguments for the given value. The command has access to the following
-# env vars:
-#
-# - `AGENDA_DATE`
-#   The date of the agenda that will be created
-# - `AGENDA_NAME`
-#   The agenda name of the agenda file that will be created.
-# - `AGENDA_SLUG`
-#   The slugged AGENDA_NAME.
-# - `AGENDA_FILE`
-#   The agenda file that will be created.
-# - `AGENDA_LAST`
-#   The last agenda file dated previous to AGENDA_FILE if one exists.
-# - `AGENDA_NEXT`
-#   The next agenda file dated next to AGENDA_FILE if one exists.
-#
 AGENDA_TEMPLATE=${AGENDA_TEMPLATE:-"__agenda_default_template"}
 
 __usage() {
@@ -56,17 +31,18 @@ __usage() {
 	Usage: ${0##*/} [-bcE] [-e <extension>] [-t <name>] [<date>]
 	       ${0##*/} <subcommand>
 
-	Organize and edit your agenda in any plain text format.
+	Manage daily tasks and notes in any plain text format.
 
-	  -b             Backlog (use the date argument as backlog name)
+	  -b             Edit a backlog file (use the date argument as backlog name)
 	  -c             Create the file if it does not exist
-	  -E             Instead of editing the file, print the path to STDOUT
+	  -E             Instead of editing the file, print its path to STDOUT
 	  -e <extension> Specify the file extension
 	  -t <name>      Specify which agenda to edit
 
 	Subcommands:
-	  edit           The default, if subcommand is omitted.
+	  edit           Edit a single agenda note file. This is the default and can be
-	  list           List a range of agenda files.
+	                 omitted.
+	  list           List a range of agenda note files.
 	USAGE
 }
 
@@ -100,11 +76,11 @@ __edit_usage() {
 	fold -w <<-USAGE
 	Usage: ${0##*/} edit [-bcE] [-e <extension>] [-t <name>] [<date>]
 
-	Edit an agenda file.
+	Edit a single agenda note file.
 
-	  -b             Backlog (use the date argument as backlog name)
+	  -b             Edit a backlog file (use the date argument as backlog name)
 	  -c             Create the file if it does not exist
-	  -E             Instead of editing the file, print the path to STDOUT
+	  -E             Instead of editing the file, print its path to STDOUT
 	  -e <extension> Specify the file extension
 	  -t <name>      Specify which agenda to edit
 	USAGE
@@ -194,7 +170,7 @@ __list_usage() {
 	fold -w <<-USAGE
 	Usage: ${0##*/} list [-ac] [-u <date>] [-t <name>] [<date>]
 
-	List a range of agenda files.
+	List a range of agenda note files.
 
 	  -a        Print the files' absolute path
 	  -c        Print the files' content

agenda.1

@@ -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