Commit graph

2 commits

Author SHA1 Message Date
sterni
b3f686995f feat(users/sterni/htmlman): hyperlink .Xr macro in output
We make use of the -O man=… option of mandoc(1) which allows to convert
cross references via the .Xr macro into actual hyperlinks in the output.
This can be disabled (by passing "none") or done in two modes:

* all: links all .Xr cross references as if they were in
  $out/%N.%S.html. This will lead to broken links of course.
* inManDir: only link to files in $out if the man page is found in
  manDir, use the template defined in linkXrFallback if not.

all is the default, since we don't require all man pages to be in
manDir, so it would be potentially confusing if the path attribute was
used in the pages list.

linkXrFallback uses the debian online man viewer by default currently,
since it can be decently hyperlinked and debian has a lot of packages.
Other options would be:

* https://manpages.ubuntu.com/manpages/latest/en/man%S/%N.%S.html
* https://man.archlinux.org/man/%N.%S.en
* https://man.openbsd.org/%N.%S
* https://www.man7.org/linux/man-pages/man%S/%N.%S.html

Change-Id: I1363b9dfdda25cb7383c7310b8115c335444bd3d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/2597
Tested-by: BuildkiteCI
Reviewed-by: sterni <sternenseemann@systemli.org>
2021-03-11 14:31:19 +00:00
sterni
2cd2b58a04 feat(users/sterni/htmlman): static site generator for manual pages
htmlman is a very simple nix based static site generator which is
intended for rendering HTML representations for man pages plus an index
page listing all available pages. For the sake of simplicity (and unlike
previous iterations of this piece of code) other documentation artifacts
and formats are not supported.

Usually web services like GitHub and depot's web interface are pretty
good at displaying "normal" documentation artifacts like markdown files,
but man pages are usually not rendered — with the additional problem
that it's source is virtually unreadable. htmlman should provide a
simple static site generator which can be plugged into GitHub actions or
the like to automatically generate rendered version of man pages tracked
in version control.

Change-Id: Ib53292964b3ff84c32d70c5fde257a2edb8c2122
Reviewed-on: https://cl.tvl.fyi/c/depot/+/2596
Tested-by: BuildkiteCI
Reviewed-by: tazjin <mail@tazj.in>
Reviewed-by: Profpatsch <mail@profpatsch.de>
Reviewed-by: sterni <sternenseemann@systemli.org>
2021-03-11 13:12:31 +00:00