diff options
Diffstat (limited to 'timer.1')
| -rw-r--r-- | timer.1 | 89 |
1 files changed, 78 insertions, 11 deletions
@@ -254,17 +254,79 @@ or .BR Ctrl+C , or when a stopwatch is stopped. .PP -Each hook is executed synchronously with three arguments: -.IR mode , -.IR duration_seconds , -.IR comment . -The first is -.BR countdown -or -.BR stopwatch ; -the others come from the running session. Hooks must be marked -executable. Standard streams are redirected to -.IR /dev/null . +A hook is any executable file at that name; there is nothing to enable. +A file that is missing or not marked executable is skipped silently. +.SS Arguments +Each hook is run with exactly three positional arguments. +.TP +.B $1 +.BR countdown " or " stopwatch . +.TP +.B $2 +Seconds. The meaning depends on the hook: +.RS +.IP \(bu 2 +.BR on_start : +the requested duration of a countdown, or +.B 0 +for a stopwatch. +.IP \(bu 2 +.BR on_done : +the full duration that elapsed. +.IP \(bu 2 +.BR on_quit : +the time actually elapsed, excluding any time spent paused. A countdown +abandoned after two seconds reports +.BR 2 , +not the duration that was asked for. +.RE +.TP +.B $3 +The +.B \-c +text, or an empty string. Always passed, so +.B $3 +is never unset. +.SS Execution +Hooks run synchronously: +.B timer +forks, executes the hook and waits for it. A slow hook delays the timer +\(em +.B on_start +delays the first frame, and +.B on_done +delays the completion bell and the alert loop. Background anything slow +with +.BR & . +.PP +Standard input, output and error are all redirected to +.IR /dev/null , +so a hook cannot print to the terminal and cannot corrupt the redrawn +progress line. Write to a file, to +.BR logger (1), +or to a notification daemon instead. The exit status is discarded: a +failing hook cannot abort the timer. +.PP +Hooks are executed with +.BR execvp (3), +so a script needs a +.B #! +line like any other. +.SS Examples +Three commented, working examples ship with the source and are installed +to +.IR PREFIX/share/doc/ttym/hooks/ . +They set the terminal title, send a desktop notification and play a +sound on completion, and record abandoned sessions to a TSV file. Copy +the ones you want and edit: +.PP +.RS +.nf +mkdir \-p ~/.config/ttym/hooks +cp /usr/local/share/doc/ttym/hooks/on_done ~/.config/ttym/hooks/ +chmod +x ~/.config/ttym/hooks/on_done +.fi +.RE .SH EXIT STATUS .TP .B 0 @@ -340,6 +402,11 @@ Directory containing the .B on_quit executables described in .BR HOOKS . +.TP +.I PREFIX/share/doc/ttym/hooks/ +Commented example hooks, installed by +.BR "make install" . +Copy them into the directory above to use them. .SH EXAMPLES A twenty\-five minute work session, tagged for later stats: .PP |