Updating GRASS Documentation
How-to for Updating GRASS Manual Pages
- doc/html_documentation.txt from the GRASS source code
Module manual page:
Place the documentation in HTML format into '<module>.html', where <module> is the name of the module. E.g. if the module is named r.example, the documentation file should be named r.example.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/v.to.db.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/r.terraflow.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 SVN.
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 Subversion repositories. Detailed instructions on how to do so can be found here.
- Once you have downloaded the SVN source code, open a terminal and change directory to where the source for a specific GRASS module is located - in this example, something like:
- Open a text editor and make your edits to <module>.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 <module>.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.
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 <module>.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 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.
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>
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 and submitting a patch
- See the Patches wiki page
Currently there is no framework for translating the help pages.
- Translation support 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 we should not be attempting to automatically translate 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 <module>.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 bablefish URL.
Examples 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
Ideas for a translation framework
The above idea really sucks IMHO. Better not to have translated documentation at all than babelfish. --Steko 13:12, 18 February 2008 (CET)
A true translation framework for translation of both interface and documentation would be structured like this:
- web interface based on pootle, to make contributions easy also for non-tech people (gettext, html, etc)
- for documentation use po4a, that can be integrated with pootle.
A brief guide to valid HTML
While web browsers will happily accept invalid HTML, the tools used to convert HTML documentation to Unix manual pages won't. For that reason, please try to ensure that the documentation is valid HTML, not just whatever your browser accepts.
If you have OpenSP/OpenJade, you can validate an HTML file with e.g.:
nsgmls -s -c /usr/share/sgml/openjade-1.3.2/pubtext/HTML4.soc <filename>.html
[The program may be called nsgmls or onsgmls, and the exact location where the catalogues are installed will vary.]
This needs to be done on the completed HTML file in dist.<arch>/docs/html; the <module>.html files in the module directories won't normally validate, as they lack the header which is added by running the module with the --html-description.
The most common error is using block elements (e.g. <div>, <pre>, <p>) in contexts where only inline elements are allowed (e.g. <dt>).
The definitive reference of which elements are allowed where is the HTML 4.0 Transitional DTD
E.g. the definition:
<!ELEMENT DT - O (%inline;)* -- definition term -->
indicates that only inline elements are allowed inside DT, while e.g.:
<!ELEMENT DD - O (%flow;)* -- definition description -->
indicates that both block and inline elements are allowed inside DD.
If you don't want to read the DTD, here's a rough summary:
The immediate children permitted for each element are:
A: %inline ABBR: %inline ACRONYM: %inline ADDRESS: %inline, P APPLET: %flow, PARAM B: %inline BDO: %inline BIG: %inline BLOCKQUOTE: %flow BODY: %flow, INS, DEL BUTTON: %flow CAPTION: %inline CENTER: %flow CITE: %inline CODE: %inline COLGROUP: COL DD: %flow DEL: %flow DFN: %inline DIR: LI DIV: %flow DL: DT, DD DT: %inline EM: %inline FIELDSET: %flow, LEGEND FONT: %inline FORM: %flow FRAMESET: FRAMESET, FRAME, NOFRAMES H1: %inline H2: %inline H3: %inline H4: %inline H5: %inline H6: %inline HEAD: %head.content, %head.misc HTML: %html.content I: %inline IFRAME: %flow INS: %flow KBD: %inline LABEL: %inline LEGEND: %inline LI: %flow MAP: %block, AREA MENU: LI NOFRAMES: %flow NOSCRIPT: %flow OBJECT: %flow, PARAM OL: LI OPTGROUP: OPTION OPTION: #PCDATA P: %inline PRE: %inline Q: %inline S: %inline SAMP: %inline SCRIPT: %Script SELECT: OPTGROUP, OPTION SMALL: %inline SPAN: %inline STRIKE: %inline STRONG: %inline STYLE: %StyleSheet SUB: %inline SUP: %inline TABLE: CAPTION, COL, COLGROUP, THEAD, TFOOT, TBODY TBODY: TR TD: %flow TEXTAREA: #PCDATA TFOOT: TR TH: %flow THEAD: TR TITLE: #PCDATA TR: TH, TD TT: %inline U: %inline UL: LI VAR: %inline
Some elements don't allow certain elements as descendents:
A: A BUTTON: %formctrl, A, FORM, ISINDEX, FIELDSET, IFRAME DIR: %block FORM: FORM LABEL: LABEL MENU: %block PRE: %pre.exclusion TITLE: %head.misc
- The children of DIR/MENU are LI, which is a block element, but those LI can't contain block elements. UL/OL don't have this restriction.
- DT cannot contain block elements, but DD can. This means that you can't use <div class="code"><pre> in a DT; use <span class="code"><tt> instead. DIV and PRE are block elements; SPAN and TT are inline.
- TABLE cannot have TR as a child. But TBODY can have TR, and TBODY allows both the start and end tags to be omitted, so <table><tr>....</tr></table> is really just a shorthand for <table><tbody><tr>.... </tr></tbody></table>.
- P cannot contain blocks. So <p>...<div> is actually shorthand for <p>...</p><div>. But <p>...<div>...</div>...</p> is an error, as the </p> doesn't match any open element (the <div> implicitly closed the original <p>, and P doesn't allow the start tag to be omitted).
- HTML, HEAD, BODY, and TBODY allow the start tag to be omitted. With the exception of TBODY, this feature shouldn't be used (it's a nuisance to implement if the number of valid child tags is large).
- Job offer Documentation manager