[GRASS-dev] Re: GRASS documentation

[Michael Barton]

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

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

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.

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