[GRASS-SVN] r57225 - grass-addons

Thu Jul 18 10:41:45 PDT 2013

Author: neteler
Date: 2013-07-18 10:41:45 -0700 (Thu, 18 Jul 2013)
New Revision: 57225

Modified:
   grass-addons/SUBMITTING_DOCS
Log:
SUBMITTING_DOCS: updated for PNG compression and svn propset script; cosmetics

Modified: grass-addons/SUBMITTING_DOCS
===================================================================

--- grass-addons/SUBMITTING_DOCS	2013-07-18 17:41:26 UTC (rev 57224)
+++ grass-addons/SUBMITTING_DOCS	2013-07-18 17:41:45 UTC (rev 57225)
@@ -1,8 +1,8 @@
-$Date: 2008-02-26 03:58:34 +0100 (Tue, 26 Feb 2008) $
+$Date: 2009-03-20 04:42:27 -0800 (Fri, 20 Mar 2009) $
 
 NOTE: Please improve this list!
 
-Dear (new) GRASS Developer,
+Dear (new) GRASS GIS Developer,
 
 When submitting documentation to GRASS SVN repository, please take
 care of following rules:
@@ -13,6 +13,24 @@
 [ see SUBMITTING_PYTHON for Python code hints ]
 
 
+0. Introduction
+
+   There are two types of documentation
+   - Libraries programmers docs: we use doxygen and document the functions 
+      directly in the source code. See lib/*/*.c and lib/*/*.dox for examples
+
+   - User manual: we write it in simple HTML, storing the manual in a 
+      file "description.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 "description.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.
+
 1. Editing of HTML pages
    To avoid insertion of too complicated HTML tags (see also below),
    we strongly suggest to use a plain text editor rather than a
@@ -22,13 +40,31 @@
 2. 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.
+   (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.
 
+   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>
+
    Note that the parameter information is auto-generated upon
-   compilation. This is done by running module in a virtual session
+   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.
@@ -46,11 +82,15 @@
 3. Usage of limited HTML tags
    Since the MAN conversion of g.html2man is limited, please use
    no other HTML tags than:
-   <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>
+   <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>
 
+   Note that all tags has a closing tag except for <hr/>, <br/> and <p>.
+   Use lower case forms.
 
+   (The MAN converter is here: tools/g.html2man/)
+
 4. Suggested HTML markup protocol:
    Module names (i.e., v.category) should be emphsized with <em>,
    and boldface <b> for flags and parameter names. Shell commands, 
@@ -69,9 +109,16 @@
    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
 
-6. See also
-   http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation
+6. Compress PNG images with
+       optipng -o5 file.png
 
+7. See also
+   http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
+
 ...
 [please add further hints if required]
+
+"Your attention to detail is appreciated."

