docs(man): add manpage
This commit is contained in:
1
.gitignore
vendored
1
.gitignore
vendored
@@ -0,0 +1 @@
|
||||
agenda.1.gz
|
||||
|
||||
11
Makefile
11
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
|
||||
|
||||
@@ -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.
|
||||
|
||||
52
agenda
52
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
|
||||
# │ ├── 1970-01-01.md
|
||||
# │ ├── 1970-01-02.md
|
||||
# │ └── 1970-01-03.md
|
||||
# │ ├── 0000-{backlog-name}.{agenda-ext}
|
||||
# │ └── {agenda-date}.{agenda-ext}
|
||||
# └── {agenda-name}
|
||||
# ├── 1970-01-01.md
|
||||
# ├── 1970-01-02.md
|
||||
# └── 1970-01-03.md
|
||||
# └── {agenda-date}.{agenda-ext}
|
||||
# ```
|
||||
#
|
||||
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.
|
||||
list List a range of agenda files.
|
||||
edit Edit a single agenda note file. This is the default and can be
|
||||
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
|
||||
|
||||
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