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

["J. Lewis Muir" <jlmuir@imca-cat.org>]

On 08/30, Laurent Bercot wrote:
> > 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.

I don't want to rain on anyone's parade, and I certainly would like to
see s6 man pages, but it seems like such a waste of effort to maintain
two sets of documentation.  Laurent, isn't there a source format that
you'd be OK with that could be used to generate mdoc?

Have you considered docbook2mdoc?

  https://mandoc.bsd.lv/docbook2mdoc/

(I haven't used it myself; I'm just aware of its existence.)  I think
the existing s6 documentation is HTML, right?  So, DocBook is not too
far from that, and docbook2mdoc is a stand-alone ISO C utility with no
external dependencies that, barring any significant missing features,
would be able to generate the man pages from DocBook source.

Of course, you'd also have to convert the existing HTML documentation
into DocBook and then generate the mdoc and HTML from that.  I would
understand concern over adding a dependency on a potentially heavy
DocBook toolchain in order to generate the HTML.  One possible way
around this, though, would be to generate the mdoc from the DocBook
using docbook2mdoc, and then generate the HTML from the mdoc using
mandoc.  With this scheme, there would be no dependency on a heavy
DocBook toolchain.

I know the documentation has come up on the list before, so I don't want
to rehash that.  If I'm saying nothing new, then no need to discuss
further.

Lewis