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

[Alexis <flexibeast@gmail.com>]

Laurent Bercot <ska-supervision@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.