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
