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

From: eric vidal <eric_at_obarun.org>
Date: Sun, 30 Aug 2020 20:10:34 +1100

On Sun, 30 Aug 2020 18:30:16 +1000
Alexis <flexibeast_at_gmail.com> wrote:

>
> Hi all,
>
> i recently started using 66 instead of runit on Void - thanks to
> _at_Obarun, @mobinmob and @teldra for their work and help!

You're welcome. Thank at you to use 66.

> Consequently, and further to
> https://www.mail-archive.com/supervision_at_list.skarnet.org/msg02278.html
> :
>
> > if people like man pages, they should have man pages, so it's
> > been a
> > few years that I have appealed to the community for this ... I
> > want
> > s6 to be accessible, but I figure that if people really wanted
> > man
> > pages, they'd write man pages
>
> i've spent the last couple of weeks porting the s6 documentation
> to mdoc(7) format:
>
> https://github.com/flexibeast/s6-man-pages
>
> since i really want man pages, and much prefer them to HTML for
> system-level software. :-)
>
> i don't consider the current state of the repo to be 'ready' in a
> general sense, but i do feel it's mostly done, and certainly
> amenable to review. i think this might be a good time to give
> myself a short break from working on it, so i can then come back
> and do a review pass with fresher eyes.
>
> The porting has been done manually, with no automation involved;
> this has allowed me to use semantic markup as much as possible,
> which of course also facilitates searching for content with
> `apropos(1)`.
>
> Several things to note:
>
> * i've changed page layouts to fit mdoc(7) conventions.
>
> * During the porting process, i developed ideas about what might
> be the best way to do things, so documentation ported earlier
> might not follow the same style as the documentation ported more
> recently. This is something i hope to check in my review pass.
>
> * 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.
>
> * 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.
>
> * i've corrected a number of typos and grammatical issues, and
> discovered what i believe might be couple of errors:
>
> * 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"?
>
> That said, although i've tried to be careful, i might have
> introduced new errors, or made mistakes in my choice of macros, so
> proofreading would be appreciated. :-)
>
>
> Alexis.

This is really a hard job to do. Many thanks to make it. A lot of user will appreciate it.
Well, i'm not really good at English, so my help will not be usefull about grammatical issues. But i will do some publicizes about your work that be visible by user.

-- 
eric vidal <eric_at_obarun.org>
Received on Sun Aug 30 2020 - 09:10:34 UTC

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