[GRASS-dev] Manpage HTML markup consistency

Dylan Beaudette dylan.beaudette at gmail.com
Wed Feb 27 02:25:10 EST 2008


On Tuesday 26 February 2008 12:04:10 pm Hamish wrote:
> 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.

Right-- HTML works well and is simple to author / maintain. 

> 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.

I agree 100%. I was just throwing out some ideas. Perhaps I became a little 
too interested in adding structure / complexity were it is not needed.

> 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.

I should have been more clear: I meant that (if we were to switch to some 
other markup/encoding of the core documentation) ... it would be nice to 
convert that into Man pages.

> 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.

Sure. Again, I was throwing out some ideas. 

>
> 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.

OK. What I had in mind when posting some of these last messages was some kind 
of base format (machine readable) in which the docs were stored / created at 
compile time, such that conversion to HTML, Man pages etc. could be improved 
by modern text processing (XSLT for XML, latex2man for latex, etc) 
approaches. 

However, if the docs are kept simple then the existing perl scrip should do 
the job.

>
> 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
>

Cheers,
Dylan





-- 
Dylan Beaudette
Soil Resource Laboratory
http://casoilresource.lawr.ucdavis.edu/
University of California at Davis
530.754.7341


More information about the grass-dev mailing list