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
Received on Mon Aug 31 2020 - 17:45:52 UTC