[[TOC]] = Submitting Documentation = There are three types of documentation * '''Library programmer's manual''': we [http://grass.osgeo.org/programming7/ use doxygen and document the functions] directly in the source code. See lib/gis/*.c and lib/gis/gislib.dox for examples * '''User manual''': each command ("module") comes with its own page. We write it in simple HTML, storing the manual in a file '.html' within the subdirectory of the module. The file contains no header nor footer. The complete HTML file is autogenerated during the compilation process (indeed, it is generated in a virtual session directly after compilation of the module). In this virtual session the module is called internally with --html-description which generates the parameters/flags list in HTML format, along with '.html', HTML header and footer the final HTML manual page is created and stored in the target binaries directory. In a separate process, the MAN format is generated from the complete HTML files. * '''Python documentation''': written in Markdown which is compiled with Sphinx (see [http://grass.osgeo.org/grass71/manuals/libpython/pygrass_index.html PyGRASS documentation]) See also on the main Web site: http://grass.osgeo.org/wiki/Updating_GRASS_Documentation == HTML Pages == To avoid insertion of overly complicated HTML tags (see also below), we strongly suggest to use a plain text editor rather than a HTML editor for editing. === Module Manual Pages === Place the documentation in HTML format into '.html', where 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. [source:grass/trunk/vector/v.to.db/v.to.db.html 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 [source:grass/trunk/raster/r.terraflow/r.terraflow.html raster/r.terraflow/r.terraflow.html] for an example. A number of major sections should be present in each help page. R = Required [[br]] S = Suggested [[br]] O = Optional [[br]] In recommended order: R:

DESCRIPTION

[[br]] S:

NOTE

,

NOTES

[[br]] S:

EXAMPLE

,

EXAMPLES

[[br]] O:

TODO

[[br]] O:

BUGS

[[br]] O:

REFERENCE

,

REFERENCES

[[br]] R:

SEE ALSO

[[br]] R:

AUTHOR

,

AUTHORS

[[br]] Note that the parameter manual section is auto-generated upon compilation. This is done by running the 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. Examples (please add some more) should be coded like this: {{{ 
v.to.db map=soils type=area option=area column=area_size unit=h
}}} The [http://grass.osgeo.org/grass70/manuals/ online WWW manual pages] are updated every Saturday (from SVN repository). === Supported HTML Tags === Since the MAN conversion of g.html2man is limited, please use no other HTML tags than: {{{ 

    •   
       
         <tr> <ul>
}}}
   
 * Note that all tags have a closing tag except for <hr/>, <br/> and <p>.
 * Use lower case forms.
 * Do not insert <p> after <h2>...</h2> or <h3>...</h3>

Note that HTML is converted to MAN pages by [source:grass/trunk/tools/g.html2man/ tools/g.html2man/]

=== Markup style guide ===

Module names (i.e., v.category) should be emphasized with <em>,
and boldface <b> for flags and parameter names. Shell commands, 
names, values, etc. should use <tt>. Emphasized phrases should use 
italics <i>. The SEE ALSO section of each page should also be 
alphabetized.

=== Break long lines ===

To avoid SVN merge conflicts, please break a line at approximately 70-80 chars.

Hints:
 * "geany" editor can format a paragraph with CTRL-j
 * "kate": activate it in Settings -> Kate -> Editing -> General -> enable static word-wrap, set 72

== SVN Properties ==

When submitting new files to the repository set SVN properties, e.g. for HTML file
    
       svn:mime-type : text/html [[br]]
       svn:keywords : Author Date Id [[br]]
       svn:eol-style : native [[br]]

See http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html

You can also simply use this script:
http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh <filename>|*

Example:
{{{
sh grass-addons/tools/module_svn_propset.sh vector/mymodule/*
}}}

== Images ==

Naming convention: module_name_keyword.png

Examples:

 * d_geodesic.png
 * r_resamp_stats_6m_20m.png
 * g_gui_rlisetup_8.png
 * v_clean_rmsa.png

Please compress PNG images with:
{{{
optipng -o5 file.png
}}}