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

["Casper Ti. Vector" <caspervector@gmail.com>]

On Mon, Aug 31, 2020 at 08:51:34PM +0000, Laurent Bercot wrote:
>  - Unless, of course, someone comes up with the perfect solution (adding
> a DocBook dependency is not a perfect solution, and neither is
> generating HTML from mandoc), in which case, obviously, they would have
> the time and willingness to do all the necessary work themself, and in
> doing so, actually meaningfully contribute to the community instead of
> only adding their drop to the useless sea of It's Easy You Just Have To
> Do This, Just Saying In Case You Had Not Considered.

Sorry if this adds to your boredom in this subject, but I wonder whether
you find the following acceptable:

* We negotiate a HTML schema your documentation can be written in, which
  is based on current documentation; existing HTML documentation will be
  converted to the schema, with minimised changes.  (The structuredness
  of HTML helps; now you also see why knowing some Lisp is beneficial :)

* I provide a Python script that validates the schema (and also helps
  to convert existing documentation) of your HTML documentation, and
  transforms it into an IR suitable for downstream conversion.  I am
  quite comfortable with writing code transformations, but it may take
  some time -- about 1 months in this case, since I have my daily job.

* Those who are fluent in roff-related formats (I *do* like manpages,
  but I cannot write them, at least for now) write a program that
  transforms the IR into one pre-chosen format (we do not like multiple
  standards differing from each other subtlely, right?).

This way, the changes to the current documentation will be minimised;
the downside is a soft dependency on Python, which is only necessary
when the amount of modification to the HTML is so big that you cannot
manually compute corresponding modification to the manpages.

-- 
My current OpenPGP key:
RSA4096/0x227E8CAAB7AA186C (expires: 2022.09.20)
7077 7781 B859 5166 AE07 0286 227E 8CAA B7AA 186C