Updating GRASS Documentation

How-to for Updating GRASS Manual Pages

• doc/html_documentation.txt from the GRASS source code

Overview

Module manual page:

Place the documentation in HTML format into 'description.html'. The easiest way to do this is to study an existing HTML page (to get the page style, e.g. vector/v.to.db/description.html). With a few exceptions header and footer are NOT allowed. You can add figures (PNG format), the figure name prefix should be the module name. See raster/r.terraflow/description.html for an example.

Note that the parameter information is auto-generated upon compilation. This is done by running module in a virtual session after compilation (see the output of 'make'). To subsequently verify the final HTML page, check the resulting HTML pages which will be stored with the name of the module.

The online WWW man pages will be updated every Saturday by CVS.

Instructions

This page will provide general step-by-step instructions for updating and improving GRASS manual pages. Feel free to update and improve this page as well! See also SUBMITTING_DOCS in the source code.

As an example, the vector program v.in.ascii will be used to illustrate the steps required to update its manual page. These steps can then be generalized for your case.

Getting the latest source

• To begin, you must obtain the latest GRASS source code from the CVS repositories. Detailed instructions on how to do so can be found here.
• Once you have downloaded the CVS source code, open a terminal and change directory to where the source for a specific GRASS module is located - in this example, something like:

cd /your_cvs_directory/grass6/vector/v.in.ascii

• Open a text editor and make your edits to description.html. 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). Save your edits by overwriting the original description.html.

Help page sections

Please use the following section list as a guideline. The intent is to promote a unified user experience, not to limit the flow of information. If exceptions are needed, please use them sparingly. Minor sections (<H3>, etc) may be free-form, as required.

Auto-generated

Modules using the parser interface will have these sections automatically generated from 'g.module --html-description'

<H2>NAME</H2>
<H2>KEYWORDS</H2>
<H2>SYNOPSIS</H2>

Found in description.html

A number of major sections should be present in each help page.

* = Required
! = Suggested
. = Optional

In recommended order
--------------------

* <H2>DESCRIPTION</H2>
! <H2>NOTE</H2>, <H2>NOTES</H2>
! <H2>EXAMPLE</H2>, <H2>EXAMPLES</H2>
. <H2>TODO</H2>
. <H2>BUGS</H2>
. <H2>REFERENCE</H2>, <H2>REFERENCES</H2>
* <H2>SEE ALSO</H2>
* <H2>AUTHOR</H2>, <H2>AUTHORS</H2>

Images

• Images can also be inserted in the html help page. See v.voronoi for an example. Note that images won't show up in the Grass man pages (which are generated from the HTML), so they shouldn't be considered a substitute for an adequate textual description. Be sure to also send the image (preferably png format) along with your documentation patch.

PNG files are best for figures with solid chunks of a single color. They can get rather large for imagery. In those cases JPEGs are a better choice. In general JPEG is a lossy format so the image quality will not be as good.

To help keep the source distribution size small, try and keep the images small and the files under 50kb or so. Save PNGs at a compression setting of "9" with a minimal color pallet, you can also use tools like pngcrush to compress them further.

Examples

For non trivial modules please provide an example of the command line usage. It is good to have this double as a mini-tutorial, so please use one of the sample datasets (Spearfish or the new North Carolina one) or common dataset such as NASA's WMS or SRTM data files.

Examples should be coded like this:

 <div class="code"><pre>
 v.to.db map=soils type=area option=area col=area_size unit=h
 </pre></div>

HTML codes

The g.html2man tool is used to generate man pages from the HTML help files.

• The following html codes are understood to some extent by g.html2man (brackets removed): 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.

• Others may be added to g.html2man as required.

Creating a patch

• Within a terminal, create a 'unified diff' (a standard way to show changes between two versions of a file) of the GRASS CVS repository version of description.html and your newly edited description.html:

 cvs diff -u description.html > v.in.ascii.description.patch

The "diff -u" command will create a report in v.in.ascii.description.patch which shows any differences between the version of description.html still on the CVS server and your edited version; a '+' at the beginning of each line denotes edits and additions you have made, and a '-' at the beginning of each line denotes lines removed from the original description.html. The exact name of your patch file is arbitrary, but should be as descriptive as possible as in the above example.

The output of the diff -u should look something like this (the exact contents will of course depend on whatever changes you made to the file):

Index: description.html
===================================================================
RCS file: /home/grass/grassrepository/grass6/vector/v.in.ascii/description.html,v
retrieving revision 1.35
diff -u -r1.35 description.html
--- description.html    31 May 2006 13:03:57 -0000      1.35
+++ description.html    26 Sep 2006 14:35:21 -0000
@@ -35,6 +35,10 @@

 Use the <b>-z</b> flag to convert ASCII data into a 3D binary vector map.

+Any edits you make to description.html will show up like this after you run diff -u!
+Three lines of the original description.html will surround each block of edits you made
+to provide context.
+
 A GRASS ASCII vector file (in <B>standard</B> mode) may contain a mix of
 primitives including points, lines, boundaries, centroids, areas, faces,
@@ -51,6 +55,8 @@
 <LI>'K': kernel (3D centroid)</LI>
 <LI>'A': area (boundary) - better use 'B'; kept only for backward compatibility</LI>
 </UL>
+
+This line is another edit made further along in description.html....

The coordinates are listed following the initial line containing the
 primitive code, the total number of vectors in the series, and the number

Submitting patches

• Email a GRASS developer your description.html.patch for review as an attachment, along with a brief explanation why it is required. Please post a general message about your documentation update to the GRASS Developer's List before sending your patch to anyone in particular.

• So it doesn't get lost, please post patches to the documentation area of the GRASS tracker system.

Translations

Currently there is no framework for translating the help pages.

Idea: use an online translator such as AltaVista's Babelfish service or Google Translate.

The top part of the page (generated by `g.module --html-description`) is translated by the $LANG variable and <grass/glocale.h>, so should not be automatically translating the option and modules names. The idea for a two part translation is to make a modified version of tools/mkhtml.sh which (if ./config'd --with-nls) loops through major languages and creates html pages like $GISBASE/docs/html/de/, $GISBASE/docs/html/es/,... but instead of just pasting the english description.html files to the bottom have it save those as g.module_descr_en.html in a common dir.

The translated help pages (generated with mkhtml_i18n.sh) would contain a lower frame which calls an online translation of the g.module_descr_en.html page from e.g. ibiblio.org/grass63/html_docs/en_descr/g.module_descr_en.html with the appropriate "lp=en_de" setting in the URL.

?

example of live whole-page translations for GRASS 6.3 help pages:

• Chinese- Simplified AltaVista - Google
• Chinese- Traditional AltaVista - Google
• Dutch AltaVista - Google
• French AltaVista - Google
• German AltaVista - Google
• Greek AltaVista - Google
• Italian AltaVista - Google
• Japanese AltaVista - Google
• Korean AltaVista - Google
• Portuguese AltaVista - Google
• Russian AltaVista - Google
• Spanish AltaVista - Google

See also

• Job offer Documentation manager

• Doxygen generated help from the source code for the Programmers' Manual.