[GRASS-dev] Re: GRASS documentation

GRASS GIS GRASS GIS developer
1

Ravinder Singh Bhalla wrote:

Dear Michael,
I'd be happy to contribute some time for the documentation. It would really help if someone coordinated the effort - pointing to specific modules needing work.
Cheers,
Ravi

Thanks very much for the offer of help. Coordination would be very helpful of course. However, anyone can look at modules they know well and work to update them.

Here are somethings to know about doing this (Markus might want to add more suggestions).

1. The doc/help file needs to be retrieved from the source code. If you don't compile GRASS yourself and don't want to deal with cvs, you can download this from the web access to the GRASS source tree. This will move to a new location fairly soon. But for now, it is at <http://freegis.org/cgi-bin/viewcvs.cgi/grass6/&gt;

2. The doc page is located inside the directory/folder for the module source code. For example, the doc file for r.info is found inside the grass6/raster/r.info folder

3. The doc page for a normal module or script is named description.html. Hence, to see and download the doc page for r.info, go to <http://freegis.org/cgi-bin/viewcvs.cgi/grass6/raster/r.info/&gt;\.

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/&gt;\. Make sure you turn OFF cascading style sheets in the preferences.

5. In the description.html file, you will notice that the name and basic name of the module/script and basic list of its options are missing. It is SUPPOSED to be that way. DON'T add this information back in. It is automatically generated from the module itself.

6. The doc file starts with the description of how the module/script works. This is where it will be really nice to have some input. Richer description, fix typos and grammatical errors, add graphics, add examples, etc. Any graphics should be in PNG format and pre-scaled to the proper size. Make them legible, but not too big. GIMP does a good job of scaling (use the cubic convolution resampling method, as it looks better). ImageMagic also works well if you like the command line. The image reference should be entered with the assumption that the image is in the same directory as the doc file.

7. How to get the updated help file into GRASS. This is where a coordinator would be very helpful. Until someone volunteers for this, maybe Markus will suggest a way to do this that does not make too much work for him. There is probably a way/place to submit such updates so that member of the development team with CVS access can get it into GRASS (e.g., the current bug tracker, though like the CVS, this too is slated to change soon).

Thanks again for helping.

Michael

--

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

Phone: 480-965-6262
Fax: 480-965-7671
WWW: http://www.public.asu.edu/~cmbarton

2

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/&gt;\. 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.

Also:

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

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.

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. Emacs' html-mode or psgml-mode).

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

3

Thanks for the clarifications Glynn.

On 11/5/07 12:09 AM, "Glynn Clements" <glynn@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/&gt;\. 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. 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

4

Michael Barton wrote:

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.

FWIW, I think KompoZer could do a nicer job of adding in some whitespace.

eg gis.m/docs/gm_*.html files are a bit dense & hard to work on without adding
in some newlines. Otherwise they seem ok.

I wasn't going to mention this before as it is just a minor complaint (typical
html editor cruft would be grounds for complaint though), but in the context of
the current thread...

As for anyone getting ideas about fancy html tricks, please employ the K.I.S.S.
principal. content >> flash

thanks,
Hamish

__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com

5

Michael Barton wrote:

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

From a brief look at the g.html2man source, the following all appear

to be understood to some extent:

<A> <B> <BLINK> <BODY> <BR> <CODE> <DD> <DL> <DT> <EM> <H2> <H3> <H4>
<HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P> <PRE> <SUP> <TABLE> <TD>
<TH> <TITLE> <TR> <UL>

However, g.html2man just uses regexp matching; it doesn't include a
proper HTML parser. Consequently, there will be other restrictions on
the precise format, e.g. I wouldn't expect line breaks between
attributes to work.

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

If there are many "genuine" changes, then you would expect to see a
substantial diff. The point is that changes shouldn't result in excess
diff output because unchanged sections have been reformatted (or
rather, regenerated) by the editor.

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

6

Glynn Clements wrote on 11/05/2007 01:10 PM:

Michael Barton wrote:
  

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?
    
From a brief look at the g.html2man source, the following all appear
to be understood to some extent:

<A> <B> <BLINK> <BODY> <BR> <CODE> <DD> <DL> <DT> <EM> <H2> <H3> <H4>
<HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P> <PRE> <SUP> <TABLE> <TD>
<TH> <TITLE> <TR> <UL>

However, g.html2man just uses regexp matching; it doesn't include a
proper HTML parser. Consequently, there will be other restrictions on
the precise format, e.g. I wouldn't expect line breaks between
attributes to work.

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.
    
If there are many "genuine" changes, then you would expect to see a
substantial diff. The point is that changes shouldn't result in excess
diff output because unchanged sections have been reformatted (or
rather, regenerated) by the editor.
  
I have started a new file
SUBMITTING_DOCS
in the main source code directory. Hints should be collected there.

See also:
http://freegis.org/cgi-bin/viewcvs.cgi/grass6/SUBMITTING_DOCS?rev=HEAD&content-type=text/vnd.viewcvs-markup

Markus

7

On 11/5/07 1:17 AM, "Hamish" <hamish_nospam@yahoo.com> wrote:

Michael Barton wrote:

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.

FWIW, I think KompoZer could do a nicer job of adding in some whitespace.

eg gis.m/docs/gm_*.html files are a bit dense & hard to work on without adding
in some newlines. Otherwise they seem ok.

I wasn't going to mention this before as it is just a minor complaint (typical
html editor cruft would be grounds for complaint though), but in the context
of
the current thread...

In this case, one should blame the workman (me) not the tool. I followed
existing formats without thinking about white space, etc. a lot.

As for anyone getting ideas about fancy html tricks, please employ the
K.I.S.S.
principal. content >> flash

Definitely! Some PNG graphic examples would be nice *where appropriate*. But
we shouldn't have animations or flying labels.

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

8

Thanks very much. This is a good guideline. This is a place where a doc
coordinator could put this on the WIKI.

Michael

On 11/5/07 5:10 AM, "Glynn Clements" <glynn@gclements.plus.com> wrote:

Michael Barton wrote:

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?

From a brief look at the g.html2man source, the following all appear
to be understood to some extent:

<A> <B> <BLINK> <BODY> <BR> <CODE> <DD> <DL> <DT> <EM> <H2> <H3> <H4>
<HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P> <PRE> <SUP> <TABLE> <TD>
<TH> <TITLE> <TR> <UL>

However, g.html2man just uses regexp matching; it doesn't include a
proper HTML parser. Consequently, there will be other restrictions on
the precise format, e.g. I wouldn't expect line breaks between
attributes to work.

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.

If there are many "genuine" changes, then you would expect to see a
substantial diff. The point is that changes shouldn't result in excess
diff output because unchanged sections have been reformatted (or
rather, regenerated) by the editor.

__________________________________________
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

9

Michael Barton wrote:

> As for anyone getting ideas about fancy html tricks, please employ the
> K.I.S.S.
> principal. content >> flash

Definitely! Some PNG graphic examples would be nice *where appropriate*. But
we shouldn't have animations or flying labels.

Also, bear in mind that images won't show up in the manual pages
(which are generated from the HTML), so they shouldn't be considered a
substitute for an adequate textual description.

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

10

Thanks very much. This is a good guideline. This is a place where a doc
coordinator could put this on the WIKI.

Michael

Done. I've added Glynn's suggestions to the Updating Documentation how-to:
http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation

~ Eric.

--
View this message in context: http://www.nabble.com/Re%3A-GRASS-documentation-tf4748983.html#a13632882
Sent from the Grass - Dev mailing list archive at Nabble.com.