feat(sterni/dot-time-man-pages): mdoc port of dotti.me

More or less direct port of https://dotti.me to mdoc(7) with the
following changes:

* Add a RFC3339 column to the EXAMPLES table. RFC3339 is a well
  specified subset of ISO8601 whose specification is also more
  accessible so this could help someone out.

* Add a SEE ALSO section linking to the web site

* Add an AUTHORS section

Change-Id: I8db00bd402697aa52f6f651f28692617b487f832
Reviewed-on: https://cl.tvl.fyi/c/depot/+/2642
Tested-by: BuildkiteCI
Reviewed-by: edef <edef@edef.eu>
This commit is contained in:
sterni 2021-03-24 20:04:56 +01:00
parent b6818d3190
commit 108e19c906
2 changed files with 73 additions and 0 deletions

View file

@ -0,0 +1,3 @@
inherited: true
owners:
- edef

View file

@ -0,0 +1,70 @@
{ depot, lib, ... }:
let
# TODO(sterni): find a better place for this: is dot time //fun?
# get the email address of a depot user from //ops/users
findEmail = user:
let
res = builtins.filter ({ username, ... }: username == user) depot.ops.users;
len = builtins.length res;
in
if len == 1
then (builtins.head res).email
else builtins.throw "findEmail: got ${toString len} results instead of 1";
# dot-time(7) man page, ported from dotti.me
dot-time = rec {
name = "dot-time";
section = 7;
content = ''
.Dd $Mdocdate$
.Dt ${lib.toUpper name} ${toString section}
.Os
.Sh NAME
.Nm ${name}
.Nd a universal convention for conveying time
.Sh DESCRIPTION
For those of us who travel often or coordinate across many timezones,
working with local time is frequently impractical.
ISO8601, in all its wisdom, allows for time zone designators,
but still represents the hours and minutes as local time,
thus making it inconvenient for quickly comparing timestamps from
different locations.
.Pp
Dot time instead uses UTC for all date, hour, and minute indications,
and while it allows for time zone designators, they are optional
information that can be dropped without changing the indicated time.
It uses an alternate hour separator to make it easy to distinguish from
regular ISO8601.
When a time zone designator is provided, one can easily obtain
the matching local time by adding the UTC offset to the UTC time.
.Sh EXAMPLES
These timestamps all represent the same point in time.
.TS
allbox tab(|);
lb | lb | lb
l | l | l.
dot time|ISO8601|RFC3339
2019-06-19T22·13-04|2019-06-19T18:13-04|2019-06-19T18:13:00-04:00
2019-06-19T22·13+00|2019-06-19T22:13+00|2019-06-19T22:13:00Z
2019-06-19T22·13+02|2019-06-20T00:13+02|2019-06-20T00:13:00+02:00
.TE
.Sh SEE ALSO
.Lk https://dotti.me dotti.me
.Sh AUTHORS
.An -nosplit
.Sy dot time
has been proposed and documented by
.An edef Aq Mt ${findEmail "edef"}
and ported to
.Xr mdoc 7
by
.An sterni Aq Mt ${findEmail "sterni"} .
'';
};
in
depot.nix.buildManPages "dot-time" {} [
dot-time
]