On 08/31, Jason Lenz wrote:
> 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!
> > >
> > 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'm just happy someone is creating manual pages, so I'm not going to "look a
> gift horse in the mouth". ;-)
Yes, and I certainly didn't intend to do that if you're suggesting that
I have, and that's what I was trying to communicate when I said
> > I don't want to rain on anyone's parade, and I certainly would like to
> > see s6 man pages
but at the same time, I thought I'd make one last plea, if you will,
before too much time is invested since, like I said, it felt like such
a waste. I mean, if there were a source format that everyone could be
happy with, then Alexis could spend time on getting that working instead
of spending time on something that will require indefinite maintenance.
But if there is no such solution, and having two separately maintained
sets of documentation is the only way to get man pages, then yes, I
still would be very thankful for Alexis's work.
> 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
I had forgotten about that; thanks for the reminder. I don't have any
experience with scdoc either, but if Laurent is happy with it and it
could serve as the source documentation format from which HTML and man
pages could be generated, then it seems like a win to me.
Lewis
Received on Mon Aug 31 2020 - 19:14:33 UTC