initial commit

1 files changed, 338 insertions, 0 deletions

diff --git a/timer.1 b/timer.1
new file mode 100644
index 0000000..57f84bb
--- /dev/null
+++ b/timer.1
@@ -0,0 +1,338 @@
+.TH TIMER 1 "ttym 2.0"
+.SH NAME
+timer \- terminal countdown and stopwatch
+.SH SYNOPSIS
+.B timer
+.RB [ \-qs ]
+.RB [ \-c
+.IR text ]
+.RB [ \-\-no\-persist ]
+.RB [ \-\-flash
+.BR on | off ]
+.RB [ \-\-bar
+.IR style ]
+.RB [ \-\- ]
+.RI [ duration ]
+.RI [ message
+.IR ... ]
+.PP
+.B timer \-r
+.RB [ \-n
+.IR N ]
+.RB [ \-\-raw ]
+.PP
+.B timer \-\-stats
+.RB [ today | week | month | all ]
+.SH DESCRIPTION
+.B timer
+is a small terminal countdown timer and stopwatch inspired by suckless philosophy.
+A single argument is parsed as a duration and the program counts down.
+With no duration argument it runs as a stopwatch.
+The progress bar, current elapsed time and time remaining
+are redrawn on the same line ten times per second.
+.PP
+The binary is intentionally small and modular.
+Beyond the base build (countdown, stopwatch, ASCII progress bar,
+pause/resume, one\-shot terminal bell on completion) every feature is
+an optional patch under
+.IR patches/ .
+Each section below describing a non\-base feature is annotated with
+.RI [patch: name ];
+those options and behaviours are only present if the corresponding
+patch has been applied at build time.
+.B timer \-h
+always reflects the actual build.
+.SH OPTIONS
+.SS Base
+.TP
+.B \-q
+Suppress the one\-shot completion bell.
+Persistent alert loops, if enabled by a patch, still ring the bell.
+.TP
+.B \-s
+Silent. No bell, no notification, no alert loop.
+Equivalent to combining every silencing flag.
+.TP
+.B \-h
+Print usage and exit. Reflects the actual build.
+.TP
+.B \-\-
+End of options. Subsequent arguments are treated as positional even if
+they begin with
+.BR \- .
+.SS Optional, added by patches
+.TP
+.BR \-c \ \fItext\fR
+.RI [patch: logging,
+.RI hooks]
+Comment associated with this session. With the
+.B logging
+patch, it is written as the third TSV field and any
+.BI + tag
+tokens within it are picked up by
+.BR "timer \-\-stats" .
+With the
+.B hooks
+patch, it is passed as the fourth argument to each hook script.
+.TP
+.B \-\-no\-persist
+.RI [patch: persist\-alert]
+Skip the alert\-until\-keypress loop.
+.B timer
+emits one bell and one notification, then exits.
+.TP
+.BR \-\-flash \ \fBon\fR | \fBoff\fR
+.RI [patch: flash]
+Toggle the reverse\-video terminal flash that runs during the
+persistent alert loop. Accepts
+.BR on / off / true / false / 1 / 0 / yes / no .
+Default is build\-dependent.
+.TP
+.BR \-\-bar \ \fIstyle\fR
+.RI [patch: bar\-styles]
+Progress bar style. One of
+.BR unicode ,
+.BR ascii ,
+.BR hash ,
+.BR dots ,
+.BR line ,
+.BR block ,
+.BR arrow ,
+.BR minimal .
+With no patch applied the bar uses the compile\-time
+.B BAR_FILL
+and
+.B BAR_EMPTY
+glyphs from
+.IR config.h .
+.SH SUBCOMMANDS
+.SS timer \-r [\-n N] [\-\-raw]
+.RI [patch: logging]
+Read the session log.
+.B \-n N
+limits output to the last
+.I N
+entries.
+.B \-\-raw
+prints the underlying TSV instead of the formatted table, suitable for
+piping through
+.BR awk (1),
+.BR grep (1)
+or
+.BR sort (1).
+.SS timer \-\-stats [\fIperiod\fR]
+.RI [patch: logging]
+Print aggregate statistics. Period is one of
+.BR today
+(default),
+.BR week ,
+.BR month ,
+.BR all .
+Entries are summed in total and broken down by
+.BI + tag
+tokens extracted from comments. Untagged sessions are reported as
+.BR (untagged) .
+.SH DURATION FORMAT
+A duration is either a colon notation or a unit notation. Examples:
+.PP
+.RS
+.nf
+25m         twenty\-five minutes
+90s         ninety seconds
+2h          two hours
+1h30m       one and a half hours
+01:30:00    one and a half hours
+25:00       twenty\-five minutes
+.fi
+.RE
+.PP
+Colon notation expects
+.IR H:M:S
+or
+.IR M:S .
+Unit notation is a concatenation of one or more
+.IR Nh ,
+.IR Nm ,
+.IR Ns
+groups in any order.
+.SH MESSAGE
+.RI [patch: notify]
+Any positional arguments after
+.I duration
+are joined into the message used for the one\-shot completion
+notification. The message is expanded into the
+.B notify_cmd
+template via the
+.B {msg}
+placeholder.
+.SH KEYS
+While the timer is running:
+.TP
+.B space
+Pause or resume the countdown or stopwatch.
+.TP
+.B q
+Quit immediately. Logs the partial session if logging is enabled.
+.TP
+.B Ctrl+C
+Same as
+.BR q .
+.SH ALERT LOOP
+.RI [patch: persist\-alert]
+When a countdown reaches zero, instead of emitting one bell and
+exiting, the program rings the bell every \(ti1.5 s and polls for a
+keypress. Any key acknowledges and exits.
+.PP
+The loop runs only when
+.B timer
+is in the foreground.
+Background jobs
+.RB ( timer
+.IR ... \ &)
+get one bell and exit normally, leaving the shell quiet.
+.PP
+If the
+.B flash
+patch is also applied, each beat of the loop briefly inverts the
+terminal colours (reverse\-video). The flash can be suppressed without
+disabling the loop via
+.BR "\-\-flash off" .
+.SH HOOKS
+.RI [patch: hooks]
+On state transitions
+.B timer
+invokes optional executables under
+.IR ~/.config/ttym/hooks/ :
+.TP
+.B on_start
+Called when a session begins.
+.TP
+.B on_done
+Called when a countdown completes normally.
+.TP
+.B on_quit
+Called when a session is interrupted with
+.BR q
+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 .
+.SH FILES
+.TP
+.I ~/.config/ttym/config
+.RI [patch: config\-file]
+Runtime configuration. Auto\-generated on first run with all keys
+commented out.
+.TP
+.I ~/.config/ttym/ttym.log
+.RI [patch: logging]
+Session log. TSV with three fields per line:
+.RS
+.PP
+.RS
+.nf
+YYYY\-MM\-DD HH:MM:SS<TAB>SECONDS<TAB>COMMENT
+.fi
+.RE
+.PP
+Designed to be processed with
+.BR awk (1)
+and
+.BR grep (1)
+rather than re\-rendered by the binary.
+.RE
+.TP
+.I ~/.config/ttym/hooks/
+.RI [patch: hooks]
+Directory containing the
+.BR on_start ,
+.BR on_done ,
+.B on_quit
+executables described in
+.BR HOOKS .
+.SH EXAMPLES
+A twenty\-five minute work session, tagged for later stats:
+.PP
+.RS
+.nf
+timer \-c "+work coding" 25m
+.fi
+.RE
+.PP
+A countdown that pops a notification with custom text:
+.PP
+.RS
+.nf
+timer 10m Lunch
+.fi
+.RE
+.PP
+Total hours logged this week:
+.PP
+.RS
+.nf
+timer \-r \-\-raw | awk \-F'\\t' '{s+=$2} END {printf "%dh\\n", s/3600}'
+.fi
+.RE
+.PP
+Count
+.BR +work
+sessions ever:
+.PP
+.RS
+.nf
+timer \-r \-\-raw | grep '+work' | wc \-l
+.fi
+.RE
+.PP
+Stopwatch with no notifications:
+.PP
+.RS
+.nf
+timer \-s
+.fi
+.RE
+.SH DESIGN
+The binary does one thing: time intervals and, optionally, log them.
+Reports
+.RB ( "timer \-r" ,
+.BR "timer \-\-stats" )
+are read\-only views over the same TSV log. For any other view, pipe
+.B "timer \-r \-\-raw"
+through
+.BR awk (1),
+.BR grep (1)
+or
+.BR sort (1).
+No daemon, no IPC, no plugin system, no embedded TUI. Hooks are
+git\-style: executables you write yourself.
+.PP
+Compile\-time options live in
+.IR config.h ;
+runtime overrides (when the
+.B config\-file
+patch is applied) live in
+.IR ~/.config/ttym/config .
+.SH AUTHORS
+.B timer
+is maintained by \(/Lukasz Kasprzak.
+Distributed under the MIT license; see
+.B LICENSE
+in the source tree.
+.SH SEE ALSO
+.BR awk (1),
+.BR grep (1),
+.BR notify\-send (1),
+.BR paplay (1),
+.BR patch (1)