Hi again all,
i've now completed the linting pass for the s6 man pages. The few
remaining lint issues are either commented in the sources, or
aren't actually an issue in this context.
As per Laurent's request, i've also added a Makefile to facilitate
installation; details in the repo README:
https://github.com/flexibeast/s6-man-pages/
The main thing still left to do is work out how to deal with
certain types of links.
Laurent, you wrote:
> I think that solely depends on the number of such links. If
> there
> are just a few, it's fine. If there are a lot of links in a
> page, it
> would make reading pretty unwieldy. Because I think there are
> a few
> pages with too many links, maybe it would be best, for
> consistency, to
> just use footnotes?
>
> < a CDB file[1] cdbfile then exits 0.
> <
> < (...)
> <
> < SEE ALSO
> <
> < [1]: http://en.wikipedia.org/wiki/Cdb_(software)
>
> Maybe mdoc even has a mechanism for footnotes? I don't know.
As far as i'm aware, mdoc has no built-in mechanism for footnotes
(certainly the word isn't used in the mdoc(7) man page).
Most of the links in the man pages are cross-references to other
pages in the s6-man-pages collection, so they're already handled
by the Xr macro. The remaining links aren't particularly numerous,
and can basically be divided into two groups:
* links to other skarnet.org documentation which does not yet have
man pages: s6-networking (s6-tcpserver-access, s6-tcpserver,
s6-tcpserver4, s6-tcpserver6), execline (execline and execlineb,
maybe others as well?), and skalibs stuff. For an example of a
page referring to s6-networking software,
cf. s6-connlimit.1.in. If that documentation was available as
man pages, these could just be made cross-references too.
* links to non-skarnet.org sites, such as djb's site. These
certainly seem amenable to use of the footnoting style you
described above.
Alexis.
Received on Wed Sep 09 2020 - 04:11:14 UTC