[GRASS-dev] Re: GRASS documentation

Mon Nov 5 02:27:42 EST 2007

Thanks for the clarifications Glynn.

On 11/5/07 12:09 AM, "Glynn Clements" <glynn at gclements.plus.com> wrote:

> 
> Michael Barton wrote:
> 
>> 4. The doc page is just plain ASCII text with html tags. You can look at
>> it in any text editor or an html editor. BUT CAUTION. Many slick html
>> editors will try to add in extra tags (CSS or other). MS Word is
>> especially notorioius for this. If you want to use an html editor, I can
>> recommend KompoZer. It is an open source WYSIWYG html editor (successor
>> to NVU) and located at <http://kompozer.sourceforge.net/>. Make sure you
>> turn OFF cascading style sheets in the preferences.
> 
> Have you actually tried using an HTML editor on those files? They
> aren't valid HTML, and aren't supposed to be. In particular, they lack
> the DOCTYPE declaration, the <head>...</head> section, and the opening
> <html> and <body> tags (but include the closing tags).
> 
> Anything which tries to save anything resembling valid HTML will have
> to have its output edited manually. Those files *must not* contain any
> of the parts which are output by the --html-description option.
> 

I've mainly created new files rather than edited old ones, using both plain
text editor for some and more recently KompoZer for some others with
graphics. You're comments make it clear that one must be careful in
formatting with an HTML editor.

Such a program is very helpful, however, for placing graphics, links, and
simple text enhancements (level 1, bold, italics, etc).

> Also:
> 
> 1. They must not contain tags or entities which are not understood by
> the g.html2man script (tools/g.html2man/g.html2man).

Can you or someone specify what these are?

> 
> 2. Any portions which are not modified must not be re-formatted during
> the editing process, as this will make the output from "cvs diff"
> useless.
> 

Maybe one way to do this is to work with a copy of the description.html
file, then use a simple text editor to cut out the edited/enhanced section
and paste it into the original--leaving other areas untouched.

However, any significant changes, including adding images, could put a bunch
of stuff into a cvs diff.

> IOW: do not use a "WYSYWIG" HTML editor on those files, but either a
> normal text editor or something which is designed for editing HTML
> *source* (e.g. [X]Emacs' html-mode or psgml-mode).

When I used KompoZer, I did a lot of switching back and forth between the
'normal' mode and source mode. This worked OK, but would not be the best way
to go for simple enhancements to the text.

In any case, one needs to follow these guidelines to have a useful file that
will work in the autogenerated help system.

Michael
__________________________________________
Michael Barton, Professor of Anthropology
Director of Graduate Studies
School of Human Evolution & Social Change
Center for Social Dynamics & Complexity
Arizona State University

phone: 480-965-6213
fax: 480-965-7671
www: http://www.public.asu.edu/~cmbarton