diff options
| -rw-r--r-- | man/dppt.1 | 95 | ||||
| -rw-r--r-- | readme.md | 22 |
2 files changed, 117 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>. diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..ec99416 --- /dev/null +++ b/readme.md @@ -0,0 +1,22 @@ +# daemonless posix pomodoro timer + +a stupid simple pomodoro timer + +features: + +- no dependencies +- no server / client architecture +- not written in a compiled language for "speed" +- inability to manage multiple timers +- no task management or list +- neither a GUI nor fancy TUI +- optionally BYOB<sup>1</sup> through plugins (see man dppt(1)) + +[1]\: *Bring Your Own Bloat* + +## installation + +``` +# make install +``` + |