\# 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>.