Updating GRASS Documentation: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
(→‎Overview: move examples)
(add historic template)
 
(32 intermediate revisions by 7 users not shown)
Line 1: Line 1:
= How-to for Updating GRASS Manual Pages =
= How-to for Updating GRASS Manual Pages =


* [http://freegis.org/cgi-bin/viewcvs.cgi/*checkout*/grass6/doc/html_documentation.txt?rev=HEAD&content-type=text/plain doc/html_documentation.txt] from the GRASS source code
{{Historic}}
 
* '''GRASS 7: please see http://trac.osgeo.org/grass/wiki/Submitting/Docs'''
* GRASS 6: [http://trac.osgeo.org/grass/browser/grass/trunk/doc/html_documentation.txt doc/html_documentation.txt] from the GRASS source code


== Overview ==
== Overview ==
Line 7: Line 10:
Module manual page:
Module manual page:


Place the documentation in HTML format into 'description.html'.
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
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).
(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.
With a few exceptions header and footer are NOT allowed.
You can add figures (PNG format), the figure name prefix should be the  
You can add figures (PNG format), the figure name prefix should be the  
module name. See raster/r.terraflow/description.html for an example.
module name. See raster/r.terraflow/r.terraflow.html for an example.


Note that the parameter information is auto-generated upon
Note that the parameter information is auto-generated upon
Line 21: Line 27:




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


== Instructions ==
== 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 [http://freegis.org/cgi-bin/viewcvs.cgi/grass6/SUBMITTING_DOCS?rev=HEAD&content-type=text/vnd.viewcvs-markup SUBMITTING_DOCS] in the source code.
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 [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_DOCS SUBMITTING_DOCS] in the source code.




Line 33: Line 39:
== Getting the latest source ==
== 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 [http://grass.itc.it/faq/cvs_howto.html here.]
* To begin, you must obtain the latest GRASS source code from the Subversion repositories. Detailed instructions on how to do so can be found [http://trac.osgeo.org/grass/wiki/DownloadSource 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:
* 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:
  cd /your_cvs_directory/grass6/vector/v.in.ascii
  cd /your_svn_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.


* 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 ==
== Help page sections ==
Line 49: Line 54:
Modules using the parser interface will have these sections automatically generated from '<tt>g.module&nbsp;--html-description</tt>'
Modules using the parser interface will have these sections automatically generated from '<tt>g.module&nbsp;--html-description</tt>'
<pre>
<pre>
<H2>NAME</H2>
<h2>NAME</h2>
<H2>KEYWORDS</H2>
<h2>KEYWORDS</h2>
<H2>SYNOPSIS</H2>
<h2>SYNOPSIS</h2>
</pre>
</pre>


=== Found in description.html ===
=== Found in <module>.html ===
A number of major sections should be present in each help page.
A number of major sections should be present in each help page.


Line 65: Line 70:
--------------------
--------------------


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


== Images ==
== Images ==
Line 84: Line 87:


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
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
<tt>pngcrush</tt> to compress them further.
<tt>pngcrush</tt> or <tt>optipng</tt> to compress them further, e.g.:


optipng -o5 file.png


== Examples ==
== 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.
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:
  &lt;div class="code"&gt;&lt;pre&gt;
  v.to.db map=soils type=area option=area col=area_size unit=h
  &lt;/pre&gt;&lt;/div&gt;


== HTML codes ==
== HTML codes ==
Line 101: Line 112:




== Creating a patch ==
== Creating and submitting a patch ==
 
* See the [[Patches]] wiki page
 
== Translations ==


* 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:
''See the main page [[GRASS manual translation]].''


  cvs diff -u description.html > v.in.ascii.description.patch
Currently there is no framework yet for translating the full help ("man") pages (implementation wanted!).


There is good support for GRASS module, library, and GUI message translations though:
* Translation support pages:
: - [[GRASS messages translation]]
: - [[GRASS Translation Glossary]]
: - [http://grass.osgeo.org/devel/i18n.php#statistics Project translation statistics]


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.


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


The output of the diff -u should look <i>something</i> like this (the exact contents will of course depend on whatever changes you made to the file):
: 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.
<pre>
: 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.
Index: description.html
: ?
===================================================================
 
RCS file: /home/grass/grassrepository/grass6/vector/v.in.ascii/description.html,v
 
retrieving revision 1.35
Examples of live whole-page translations for GRASS 6.4 help pages:
diff -u -r1.35 description.html
* Chinese- Simplified [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_zh&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Czh-CN&hl=en&ie=UTF8 Google]
--- description.html   31 May 2006 13:03:57 -0000      1.35
* Chinese- Traditional [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_zt&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Czh-TW&hl=en&ie=UTF8 Google]
+++ description.html    26 Sep 2006 14:35:21 -0000
* Dutch [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_nl&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cnl&hl=en&ie=UTF8 Google]
@@ -35,6 +35,10 @@
* French [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_fr&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cfr&hl=en&ie=UTF8 Google]
* German [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_de&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cde&hl=en&ie=UTF8 Google]
* Greek [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_el&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cel&hl=en&ie=UTF8 Google]
* Italian [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_it&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cit&hl=en&ie=UTF8 Google]
* Japanese [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_ja&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cja&hl=en&ie=UTF8 Google]
* Korean [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_ko&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cko&hl=en&ie=UTF8 Google]
* Portuguese [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_pt&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cpt&hl=en&ie=UTF8 Google]
* Russian [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_ru&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Cru&hl=en&ie=UTF8 Google]
* Spanish [http://babelfish.yahoo.com/translate_url?doit=done&tt=url&intl=1&fr=bf-home&lp=en_es&btnTrUrl=Translate&trurl=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass64%2Fmanuals%2Fhtml64_user%2Findex.html&langpair=en%7Ces&hl=en&ie=UTF8 Google]
 
=== Ideas for a translation framework ===
 
The above idea really sucks IMHO. Better not to have translated documentation at all than babelfish. --[[User:Steko|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 '''[http://translate.sourceforge.net/wiki/pootle/index pootle]''', to make contributions easy also for non-tech people (gettext, html, etc). For a working system, see https://transifex.net/projects/p/grass6/
* for documentation use '''[http://po4a.alioth.debian.org/ po4a]''', that can be integrated with pootle.
* see also http://trac.osgeo.org/grass/ticket/846
 
== 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 [http://openjade.sourceforge.net/ OpenSP/OpenJade], you can validate an HTML file with
e.g.:
 
<pre>nsgmls -s -c /usr/share/sgml/openjade-1.3.2/pubtext/HTML4.soc <filename>.html</pre>
 
[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. &lt;div>,
&lt;pre>, &lt;p>) in contexts where only inline elements are allowed
(e.g. &lt;dt>).
 
The definitive reference of which elements are allowed where is the
'''[http://www.w3.org/TR/1998/REC-html40-19980424/sgml/loosedtd.html HTML 4.0 Transitional DTD]'''
 
E.g. the definition:
 
<code><!ELEMENT DT - O (%inline;)*          -- definition term --></code>


Use the <b>-z</b> flag to convert ASCII data into a 3D binary vector map.
indicates that only inline elements are allowed inside DT, while e.g.:


+Any edits you make to description.html will show up like this after you run diff -u!
<code><!ELEMENT DD - O (%flow;)*            -- definition description --></code>
+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
indicates that both block and inline elements are allowed inside DD.
primitive code, the total number of vectors in the series, and the number
</pre>


If you don't want to read the DTD, here's a rough summary:


== Submitting patches ==
Entity classes:
<pre>
%StyleSheet = <CSS stylesheet>
%Script = <JavaScript code>
%html.content = HEAD, BODY
%head.content = TITLE, ISINDEX, BASE
%heading = H1, H2, H3, H4, H5, H6
%fontstyle = TT, I, B, U, S, STRIKE, BIG, SMALL
%phrase = EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ABBR,
  ACRONYM
%special = A, IMG, APPLET, OBJECT, FONT, BASEFONT, BR, SCRIPT,
  MAP, Q, SUB, SUP, SPAN, BDO, IFRAME
%formctrl = INPUT, SELECT, TEXTAREA, LABEL, BUTTON
%list = UL, OL,  DIR, MENU
%head.misc = SCRIPT, STYLE, META, LINK, OBJECT
%pre.exclusion = IMG, OBJECT, APPLET, BIG, SMALL, SUB, SUP,
  FONT, BASEFONT
%preformatted = PRE
%block = P, DL, DIV, CENTER, NOSCRIPT, NOFRAMES,
  BLOCKQUOTE, FORM, ISINDEX, HR, TABLE, FIELDSET,
  ADDRESS, %heading, %list, %preformatted
%inline = #PCDATA, %fontstyle, %phrase, %special, %formctrl
%flow = %block, %inline
</pre>


* Email a [http://grass.itc.it/community/team.php GRASS developer] your description.html.patch for review <b><i>as an attachment</i></b>, along with a brief explanation why it is required. Please post a general message about your documentation update to the [http://grass.itc.it/devel/index.php#list GRASS Developer's List] before sending your patch to anyone in particular.
The immediate children permitted for each element are:
<pre>
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
</pre>
Some elements don't allow certain elements as descendents:
<pre>
A: A
BUTTON: %formctrl, A, FORM, ISINDEX, FIELDSET, IFRAME
DIR: %block
FORM: FORM
LABEL: LABEL
MENU: %block
PRE: %pre.exclusion
TITLE: %head.misc
</pre>
Notes:


* So it doesn't get lost, please post patches to the documentation area of the [http://wald.intevation.org/tracker/?group_id=21 GRASS tracker system].
* 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.


== Translations ==
* <nowiki>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.</nowiki>


Currently there is no framework for translating the help pages.
* <nowiki>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>.</nowiki>


Idea: use an online translator such as AltaVista's Babelfish service.
* <nowiki>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).</nowiki>


example of live translations for GRASS 6.3 help pages:
* 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).
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_zh&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Chinese- Simplified]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_zt&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Chinese- Traditional]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_nl&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Dutch]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_fr&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html French]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_de&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html German]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_el&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Greek]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_it&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Italian]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_ja&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Japanese]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_ko&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Korean]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_pt&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Portuguese]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_ru&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Russian]
* [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_es&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html Spanish]




Line 174: Line 331:
* Job offer [[Project_jobs#Documentation_manager_.28open.29|Documentation manager]]
* Job offer [[Project_jobs#Documentation_manager_.28open.29|Documentation manager]]


* [[Development#Documentation|Doxygen generated help]] from the source code for the [http://grass.itc.it/devel/index.php#prog Programmers' Manual].
* [[Development#Documentation|Doxygen generated help]] from the source code for the [http://grass.osgeo.org/programming6/ Programmers' Manual].
 
[[Category:Development]]

Latest revision as of 22:22, 6 October 2018

How-to for Updating GRASS Manual Pages

Overview

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.

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 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:
cd /your_svn_directory/grass6/vector/v.in.ascii
  • 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.

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

  • 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 or optipng to compress them further, e.g.:

optipng -o5 file.png

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 and submitting a patch

Translations

See the main page GRASS manual translation.

Currently there is no framework yet for translating the full help ("man") pages (implementation wanted!).

There is good support for GRASS module, library, and GUI message translations though:

  • Translation support pages:
- GRASS messages translation
- GRASS Translation Glossary
- Project translation statistics


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.4 help pages:

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:

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:

Entity classes:

	%StyleSheet	= <CSS stylesheet>
	%Script		= <JavaScript code>
	
	%html.content	= HEAD, BODY
	%head.content	= TITLE, ISINDEX, BASE
	%heading	= H1, H2, H3, H4, H5, H6
	%fontstyle	= TT, I, B, U, S, STRIKE, BIG, SMALL
	%phrase		= EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ABBR,
			  ACRONYM
	%special	= A, IMG, APPLET, OBJECT, FONT, BASEFONT, BR, SCRIPT,
			  MAP, Q, SUB, SUP, SPAN, BDO, IFRAME
	%formctrl	= INPUT, SELECT, TEXTAREA, LABEL, BUTTON
	%list		= UL, OL,  DIR, MENU
	%head.misc	= SCRIPT, STYLE, META, LINK, OBJECT
	%pre.exclusion	= IMG, OBJECT, APPLET, BIG, SMALL, SUB, SUP,
			  FONT, BASEFONT
	%preformatted	= PRE
	%block		= P, DL, DIV, CENTER, NOSCRIPT, NOFRAMES,
			  BLOCKQUOTE, FORM, ISINDEX, HR, TABLE, FIELDSET,
			  ADDRESS, %heading, %list, %preformatted
	%inline		= #PCDATA, %fontstyle, %phrase, %special, %formctrl
	%flow		= %block, %inline

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

Notes:

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


See also