[GRASS-dev] Manpage HTML markup consistency

[Hamish]

Hi,

Dylan:
> 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. As it is a
structured text markup language there are many tools to cleanly convert
it to other document formats. We need a clear text markup language with
access to links, and that's exactly what HTML provides. I've never felt
limited by it.

If there's a problem with the help pages it has to do with out of date
content, not the markup structure. And Eric has stepped up to help
tackle the out-of-date problem. Perhaps some dead-link-checking tool
could be helpful to highlight SEE ALSOs to unported GRASS 5 modules?


> It would be nice to have the option of converting the base manual
> into one's favorite format: Man pages, HTML, LateX, PDF, etc.

we can already do that.

as discussed, the default `make` creates man pages

to get PDF versions just run:
 make html2pdfdoc
   or
 make html2pdfdoccomplete

The above two require the htmldoc program (-> PS, PDF)
If LaTeX is wanted, there is gnuhtml2latex, LyX, probably many others.


In Frank's message fwd'd by Helena, he mentions reStructured text.
Perhaps good for writing a book but not for help pages IMO. (I used it
in a script to create the PDF book version of
galleryofmapprojections.com; but still needed to hack in raw LaTeX to
the result to get what I wanted)


The current issue with g.html2man is just a tiny coding bug, easily
fixed. The perl dependency and the brittleness of it are not nice, but
99% of the description.html files do not use advanced tags and so it
suffices. Also it is already written and tested, which counts for a
lot.


FWIW:
$ apt-cache search html2
gnuhtml2latex - A Perl script that converts html files to latex
html2ps - HTML to PostScript converter
html2text - An advanced HTML to text converter
html2wml - converts HTML pages to WML (WAP) or i-mode pages
libgtkhtml2-0 - HTML rendering/editing library (for GNOME2)
libgtkhtml2-dev - HTML rendering/editing library  for (GNOME2)
libgtkhtml2-ruby - GtkHTML bindings for the Ruby language
lyx - High Level Word Processor
stx2any - Converter from structured plain text to other formats
sylpheed-claws-gtk2-html2-viewer - HTML mail/attachment viewer for
Sylpheed-Claws GTK2 mailer
xhtml2ps - HTML to PostScript converter (Tcl/Tk GUI frontend)


2c,
Hamish




      ____________________________________________________________________________________
Be a better friend, newshound, and 
know-it-all with Yahoo! Mobile.  Try it now.  http://mobile.yahoo.com/;_ylt=Ahu06i62sR8HDtDypao8Wcj9tAcJ