Re: [request for review] Port of s6 documentation to mdoc(7)

["Laurent Bercot" <ska-supervision@skarnet.org>]

>i've spent the last couple of weeks porting the s6 documentation to mdoc(7) format:
>
>https://github.com/flexibeast/s6-man-pages

  Excellent, thank you. There is a lot of talk (especially on the #s6
IRC channel, but occasionally on the mailing-list too) about people
wanting to have s6 man pages, but very rarely people wanting to actually
do the *work*. This is clearly the most advanced conversion ever
performed, well done!

  Would you be willing to add a small Makefile that by default invokes
the mandoc commands to produce the formatted man pages, and with an
install target that installs the source to $(MANDIR), by default
/usr/share/man ? I would then be able to review them. Thanks :)
(AS you're aware if you've been here a while, I don't read mdoc source,
and I will. not. learn. it.)

  Related question: would you be willing to maintain that repository
for when I make changes to the s6 documentation? Changes should be few
and far between, except for fixes and new feature additions (which I
don't think there will be much of). If so, I would gladly add a link to
that repository in the official s6 home page, for people who, like you,
prefer man pages.


>* There are currently no cross-references to the execline suite or  skalibs. However, i'm willing to port that documentation as  well, together with the s6-rc documentation.

  That would be totally awesome. However, I'd hold off on s6-rc for now,
because I'm in the process of exploring a possible redesign (for better
integration of features that distributions want before packaging and
using s6-rc), so it's not improbable that all the documentation gets
rewritten in a not-too-distant future.


>* Inline links to things such as djb's software are not yet  included. The `Lk` macro allows one to supply link text as well  as the URL, but the resulting output would require changes to  the text to make it read satisfactorily. Regardless, i can add  the relevant links in "SEE ALSO" sections.

  What kind of changes to the text? if it's just the text of the link,
such as changing the name of a package to the full URL of the package,
then please go ahead and do what is needed. But relevant links in
SEE ALSO works too.


>* i've corrected a number of typos and grammatical issues, and  discovered what i believe might be couple of errors:

  If there are other typos or grammatical errors you've noticed, please
send them to me (maybe privately in order not to spam the list) and I'll
fix them. If the fixes need more explanation and interactive dialogue,
hop on #s6 some time during the week to discuss them. :)


>  * s6-softlimit: The "Options" section refers to "-r allmem"  rather than "-r res".
>
>  * s6-ftrig-listen: The "Options" section says: "By default,  s6-ftrig-listen1 waits indefinitely for a matching series of  events." Given the context, i presume this should be  "s6-ftrig-listen"?

  Fixed in the latest git head, thanks!

--
  Laurent