add readme + manpage

1 files changed, 95 insertions, 0 deletions

diff --git a/man/dppt.1 b/man/dppt.1
new file mode 100644
index 0000000..857d32e
--- /dev/null
+++ b/man/dppt.1
@@ -0,0 +1,95 @@
+\# vim: ft=groff
+.TH dppt 1
+
+.SH NAME
+dppt \- daemonless posix pomodoro timer
+
+.SH SYNPOSIS
+dppt [-h] [action] [action options]
+
+.SH DESCRIPTION
+A stupid simple pomodoro timer written in POSIX sh without any dependencies.
+
+This program acts as a timer with preset durations (referred to as \fIlaps\fP).
+By default, the following rules are used to determine lap duration:
+.IP \[bu]
+By default, a lap is 25 minutes long
+.IP \[bu]
+Every second lap is 5 minutes (short break)
+.IP \[bu]
+Every sixth lap (third break) is 15 minutes (long break)
+.P
+This behavior can be changed by creating a user plugin named \fBlap\fP (see
+PLUGINS section).
+
+.SH OPTIONS
+.TP
+\fB-h\fP
+Call \f[CR]help\fP.
+
+.SH ACTIONS
+.TP
+start
+Resume a paused timer. If the timer is currently running, this command will
+output an error.
+.TP
+stop, reset
+Pause the timer, reset the lap counter to 0 and reset the default lap duration.
+.TP
+state
+Print timer lap count, state and remaining time.
+.TP
+help
+Print help.
+.TP
+toggle
+Call \f[CR]pause\fP if the timer is running, or \f[CR]start\fP if it is paused.
+.TP
+pause
+Set the timer state to paused, and save the remaining time.
+.TP
+lap
+Calculate the duration of a lap by index.
+
+.P
+If \f[CR]dppt\fP is called without an action, it defaults to \f[CR]state\fP.
+
+.SH PLUGINS
+User plugins are placed in \f[CR]$XDG_DATA_HOME/dppt\fP
+(\f[CR]~/.local/share/dppt\fP on most distributions).
+.IP \[bu]
+If a plugin file has executable permissions, it can be called through
+\f[CR]dppt <plugin name>\fP (e.g. \f[CR]dppt foo\fP calls
+\f[CR]~/.local/share/dppt/foo\fP if it is executable).
+.IP \[bu]
+In order to appear in the list of actions in \f[CR]dppt --help\fP, a plugin
+should print its description and exit with code 2 when called with
+`\f[CR]info\fP' as its first argument. This can be accomplished (for sh
+scripts) by adding the following line to the top of the plugin:
+
+.EX
+[ "$1" = "info" ] && echo "description" && exit 2
+.EE
+
+.P
+Plugins in POSIX sh are preferred, as these can use \f[CR]dppt\fP's internal
+functions. Regular executables also work, though these only have access to
+environment variables defined by \f[CR]dppt\fP's library scripts.
+
+All of \f[CR]dppt\fP's internal commands are implemented as plugins, which
+allows the end-user to change the default behavior easily.
+
+.SH FILES
+.TP
+\f[CR]/usr/lib/dppt-core\fP
+Core (built-in) plugins.
+.TP
+\f[CR]$XDG_DATA_HOME/dppt\fP (usually \f[CR]~/.local/share/dppt\fP)
+User plugins.
+.TP
+\f[CR]$POMODORO_STATE_PATH\fP (default \f[CR]$XDG_CACHE_HOME/dppt\fP, i.e. \f[CR]~/.cache/dppt\fP)
+Timer state storage.
+
+.SH AUTHOR
+\f[CR]dppt\fP was written by Loek Le Blansch. The source code is available at
+<https://git.pipeframe.xyz/lonkaars/dppt>.