On 8/31/20 11:08 AM, J. Lewis Muir wrote:
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
I'm just happy someone is creating manual pages, so I'm not going to
"look a gift horse in the mouth". ;-)
With that said I believe Laurent mentioned in the past that he
considered a suggestion from someone to use the scdoc utility (links
below), as long as someone else did the initial work to port to that
format? It's a simplified markup format, so although much easier to
read probably not as powerful as mdoc.
https://drewdevault.com/2018/05/13/scdoc.html
https://git.sr.ht/~sircmpwn/scdoc
