diff --git a/.gitignore b/.gitignore index e69de29..ffa146b 100644 --- a/.gitignore +++ b/.gitignore @@ -0,0 +1 @@ +agenda.1.gz diff --git a/Makefile b/Makefile index 1ed1285..07e2f64 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index a0df8af..8063305 100644 --- a/README.md +++ b/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. diff --git a/agenda b/agenda index 871aafe..004b973 100644 --- a/agenda +++ b/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 ] [-t ] [] ${0##*/} - 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 Specify the file extension -t 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 ] [-t ] [] - 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 Specify the file extension -t Specify which agenda to edit USAGE @@ -194,7 +170,7 @@ __list_usage() { fold -w <<-USAGE Usage: ${0##*/} list [-ac] [-u ] [-t ] [] - List a range of agenda files. + List a range of agenda note files. -a Print the files' absolute path -c Print the files' content diff --git a/agenda.1 b/agenda.1 new file mode 100644 index 0000000..6f4b2d9 --- /dev/null +++ b/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 ] [-t ] [] +.sp 0 +\fBagenda\fP edit [-bcE] [-e ] [-t ] [] +.sp 0 +\fBagenda\fP list [-ac] [-u ] [-t ] [] +\#============================================================================= +.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 +.RS 4 +Specify the file extension. Otherwise this will fall back to the value of +\fBAGENDA_EXTENSION\fP. +.PP +.RE +\# +\fB\-t\fP +.RS 4 +Specify which agenda to edit. Otherwise this will fall back to the value of +\fBAGENDA_DEFAULT\fP. +.PP +.RE +\# + +.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 +.RS 4 +Stop listing at \fI\fP. Falls back to `next week` if omitted. +.PP +.RE +\# +\fB\-t\fP +.RS 4 +Specify which agenda to list. +.PP +.RE +\# + +.RS 4 +Start listing agenda note files at \fI\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\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