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

[eric vidal <eric@obarun.org>]

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

> 
> Hi all,
> 
> i recently started using 66 instead of runit on Void - thanks to 
> @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@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@obarun.org>