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