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

From: Casper Ti. Vector <>
Date: Tue, 1 Sep 2020 14:38:01 +0800

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
Received on Tue Sep 01 2020 - 06:38:01 UTC

This archive was generated by hypermail 2.3.0 : Sun May 09 2021 - 19:44:19 UTC