1 files changed, 49 insertions, 0 deletions
diff --git a/man/man1/timespan.1 b/man/man1/timespan.1
new file mode 100644
index 0000000..0e3ad94
--- /dev/null
+++ b/man/man1/timespan.1
@@ -0,0 +1,49 @@
+.TH timespan 1 2024-07-25 util
+
+.SH NAME
+timespan \- compute the duration between clock times
+
+.SH SYNOPSIS
+.SY timespan
+.IB <time> - <time>
+.YS
+
+.SH DESCRIPTION
+.B timespan
+computes the time span between two clock times.
+For example, the time between midday and noon would be
+.B timespan 12:00-12:00
+\(em which is no time at all.
+
+.SH OPTIONS
+.B timespan
+has no options.
+It accepts only times, separated by a hyphen.
+
+.SH EXIT STATUS
+.B timespan
+always exits with 0.
+.SH NOTES
+.B timespan
+is implemented using
+.BR sed (1)
+as a parser and
+.BR bc (1)
+as an interpreter.
+.SH BUGS
+Lines that fail to parse are passed to
+.B bc (1),
+which allows arbitrary code execution.
+.P
+The error messages are not helpful.
+.SH EXAMPLES
+.HP
+.BR timespan\  10:00-12:30
+will output 2h30m.
+.HP
+.BR timespan\  8:00- $(date\ +%R)
+will print the duration since 8:00 o'clock,
+which may be a negative amount if it is very early.
+
+.SH SEE ALSO
+.BR sed (1),\  bc (1),\  date (1)