From: Alexis <flexibeast@gmail.com>
To: supervision@list.skarnet.org
Subject: s6-man-pages update
Date: Wed, 09 Sep 2020 14:11:14 +1000 [thread overview]
Message-ID: <875z8nd1y5.fsf@ada> (raw)
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.
next reply other threads:[~2020-09-09 4:11 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-09 4:11 Alexis [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=875z8nd1y5.fsf@ada \
--to=flexibeast@gmail.com \
--cc=supervision@list.skarnet.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).