[GRASS-dev] Manpage HTML markup consistency

[Glynn Clements]

Hamish wrote:

> > DocBook, custom XML, or even some kind of LaTeX hybrid (like the R
> > manual system) might be useful. Moving thing between HTML and Man
> > page format would be another story-- but probably doable with some
> > kind of simple parser/converter.
> 
> HTML is Hyper *TEXT Markup Language*. XML is anything Markup Language.
> HTML is clearer & native for our need, and much more well known.
> 
> What we need is a text markup language and that's exactly what we've
> got, I don't see any point in moving away from it.

HTML may be a text markup language, but it isn't a very good one. It
provides far too many features which are intended to directly control
appearance. That makes it unsuitable for conversion to other formats
which don't have exactly the same display model as HTML.

In short, it's much easier to generate HTML than it is to convert HTML
to another format.

> If there's a problem with the help pages it has to do with out of date
> content, not the markup structure.

No, there's a real problem with people assuming that the files are
just normal HTML files. They aren't normal HTML files; they're
g.html2man source files. The two aren't the same thing.

> The current issue with g.html2man is just a tiny coding bug, easily
> fixed.

Fixing the "tiny coding bug" only fixes the symptoms; fixing the real
problem is harder. The real problem is that the format of those files
isn't documented anywhere. Generic HTML documentation doesn't help,
because g.html2man doesn't understand arbitrary HTML, nor will any
replacement.

If you're going to settle on some subset of HTML as the source
language, you need to specify exactly which subset that is.

-- 
Glynn Clements <glynn at gclements.plus.com>