supervision - discussion about system services, daemon supervision, init, runlevel management, and tools such as s6 and runit
 help / color / mirror / Atom feed
* s6-man-pages update
@ 2020-09-09  4:11 Alexis
  2020-09-09  8:19 ` Laurent Bercot
  0 siblings, 1 reply; 7+ messages in thread
From: Alexis @ 2020-09-09  4:11 UTC (permalink / raw)
  To: supervision


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.

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2020-09-09 14:55 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-09  4:11 s6-man-pages update Alexis
2020-09-09  8:19 ` Laurent Bercot
2020-09-09 13:12   ` Alexis
2020-09-09 13:16   ` Érico Nogueira
2020-09-09 13:42     ` Laurent Bercot
2020-09-09 14:08       ` Alexis
2020-09-09 14:55         ` Laurent Bercot

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).