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

From: Alexis <flexibeast_at_gmail.com>
Date: Tue, 01 Sep 2020 21:55:24 +1000

Laurent Bercot <ska-supervision_at_skarnet.org> writes:

> I'm totally willing to use a HTML schema we can negotiate, to
> write
> future documentation in. What I don't want to do is:
> - Touch existing documentation, unless I have to rewrite the
> content of
> a page for some reason. Of course, if the conversion work is
> done by
> somebody else, I have no objection to upstreaming the new
> documents.

In terms of automating such a conversion, here are a few of the
things the automation would need to do:

* Determine whether some text is an environment
  variable. Environment variables in the current HTML aren't
  marked up. You might think that you could say "Well, if it's all
  caps it's an env var", but that won't work, because will catch
  things like SIGTERM and SO_REUSEADDR. You could special-case
  'SIG*', but i'm not sure what could be done about things like
  SO_REUSEADDR.

* Parse things like "s6-envuidgid [ -u | -g | -B ] [ -n ] [ -i |
  -D uid:gid:gidlist ] account prog..." appropriately, so that
  mdoc/roff using Op, Fl and Ar can be produced. The parsing will
  also need keep track of the fact that further uses of "account"
  in the mdoc/roff might need to be preceded by an Fl macro. Of
  course, the word "account" is not necessarily referring to the
  "account" argument, but also to the notion of an account in
  general: in "s6-envuidgid looks account up by name in the
  account database", the first "account" should be preceded by Fl,
  but the second shouldn't. So this sort of thing would somehow
  need to be handled as well.

Note that "-D uid:gid:gidlist" will require special handling, as
that seems to also need use of Ns to produce the correct output,
i.e. ".Op Fl i | D Ar uid Ns : Ns Ar gid Ns : Ns Ar
gidlist". Although, `mandoc -T lint` currently produces a warning
about the use of Ns there; if mdoc/roff experts have any
suggestions as to The Correct Way to do this, i'm all ears. :-)

* In accessrules.html, <tt> is used to indicate file paths,
  function types, variable types and the accessrules library
  itself; these cases will somehow need to be
  distinguished. (There are currently places in s6-accessrules.7
  where, in my first pass, i've used Ql when i should actually be
  using Vt; that's one of the things i still need to fix.)

So my guess is that trying to automate a conversion will be much
more work than simply doing a conversion manually.


Alexis.
Received on Tue Sep 01 2020 - 11:55:24 UTC