Re: s6-man-pages update

From: Laurent Bercot <ska-supervision_at_skarnet.org>
Date: Wed, 09 Sep 2020 08:19:23 +0000

>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/

  Nice work! If you feel they're ready enough, I can add a link to them
in the s6 main page right away.

  Two comments:
  - The skarnet.org site is accessible in https, and is preferred.
Intra-site links have no default protocol, so they will link in http
if the client uses http, and in https if the client uses https; but
for absolute URLS, it would probably be best to write them as https.
  - You should list yourself in the AUTHORS section: I wrote the content,
but you wrote the man pages.


>* 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.

  I don't want to be making suggestions on work I'm not going to do
myself and that I have no deep understanding of; but is there a way to
have an alternative in .Xr, as in "print as a cross-ref if the man
page exists, else print that text"? That would be ideal for placeholders
until the documentation for other packages is ported (which may very
well be "never").


>* links to non-skarnet.org sites, such as djb's site. These certainly seem amenable to use of the footnoting style you described above.

  Yes, I don't think it's reasonable to expect the whole Web to be
converted to man pages. ;)

--
  Laurent
Received on Wed Sep 09 2020 - 08:19:23 UTC

This archive was generated by hypermail 2.3.0 : Sun May 09 2021 - 19:44:19 UTC