Changes between Initial Version and Version 1 of Submitting/Docs


Ignore:
Timestamp:
06/21/14 05:15:38 (10 years ago)
Author:
martinl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Submitting/Docs

    v1 v1  
     1= Submitting Documentation ==
     2
     3When submitting documentation to GRASS SVN repository, please take
     4care of following rules:
     5
     6   There are two types of documentation
     7   - Libraries programmers docs: we use doxygen and document the functions
     8      directly in the source code. See lib/gis/*.c and lib/gis/gislib.dox for examples
     9
     10   - User manual: we write it in simple HTML, storing the manual in a
     11      file '<module>.html' within the subdirectory of the module.
     12      The file contains no header nor footer. The complete HTML file is
     13      autogenerated during the compilation process (indeed, it is generated
     14      in a virtual session directly after compilation of the module).
     15      In this virtual session the module is called internally with
     16      --html-description which generates the parameters/flags list in
     17      HTML format, along with '<module>.html', HTML header and footer
     18      the final HTML manual page is created and stored in the target
     19      binaries directory. In a separate process the MAN format is
     20      generated from the complete HTML files.
     21
     22See also
     23   http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
     24
     25== HTML Pages ==
     26
     27Editing of HTML pages
     28   To avoid insertion of too complicated HTML tags (see also below),
     29   we strongly suggest to use a plain text editor rather than a
     30   HTML editor for editing.
     31
     32=== Module Manual Pages ===
     33
     34Module manual page:
     35   Place the documentation in HTML format into '<module>.html', where
     36   <module> is the name of the module. E.g. if the module is named
     37   r.example, the documentation file should be named r.example.html.
     38
     39   The easiest way to do this is to study an existing HTML page
     40   (to get the page style, e.g. vector/v.to.db/v.to.db.html).
     41   With a few exceptions, header and footer are NOT allowed.
     42   You can add figures (PNG format); the figure name prefix should be the
     43   module name. See raster/r.terraflow/r.terraflow.html for an example.
     44
     45   A number of major sections should be present in each help page.
     46
     47   * = Required
     48   ! = Suggested
     49   . = Optional
     50
     51   In recommended order
     52   --------------------
     53
     54   * <h2>DESCRIPTION</h2>
     55   ! <h2>NOTE</H2>, <h2>NOTES</h2>
     56   ! <h2>EXAMPLE</h2>, <h2>EXAMPLES</h2>
     57   . <h2>TODO</h2>
     58   . <h2>BUGS</h2>
     59   . <h2>REFERENCE</h2>, <h2>REFERENCES</h2>
     60   * <h2>SEE ALSO</h2>
     61   * <h2>AUTHOR</h2>, <h2>AUTHORS</h2>
     62
     63   Note that the parameter information is auto-generated upon
     64   compilation. This is done by running the module in a virtual session
     65   after compilation (see the output of 'make'). To subsequently
     66   verify the final HTML page, check the resulting HTML pages which
     67   will be stored with the name of the module.
     68
     69   Examples (please add some) should be coded like this:
     70
     71   <div class="code"><pre>
     72   v.to.db map=soils type=area option=area column=area_size unit=h
     73   </pre></div>
     74 
     75   The online WWW man pages is updated every Saturday (from SVN
     76   repository).
     77
     78=== Supported HTML Tags ===
     79
     80Usage of limited HTML tags
     81   Since the MAN conversion of g.html2man is limited, please use
     82   no other HTML tags than:
     83   <a> <b> <body> <br> <code> <dd> <dl> <dt> <em>
     84   <h2> <h3> <h4> <head> <hr> <i> <img> <li> <ol> <p>
     85   <pre> <sup> <table> <td> <th> <title> <tr> <ul>
     86
     87   Note that all tags has a closing tag except for <hr/>, <br/> and <p>.
     88   Use lower case forms.
     89
     90   (The MAN converter is here: tools/g.html2man/)
     91
     92=== Markup Protocol ===
     93
     94Suggested HTML markup protocol:
     95   Module names (i.e., v.category) should be emphsized with <em>,
     96   and boldface <b> for flags and parameter names. Shell commands,
     97   names, values, etc. should use <tt>. Empahsized phrases should use
     98   italics <i>. The SEE ALSO section of each page should also be
     99   alphabetized.                       
     100
     101== SVN Properties ==
     102
     103When submitting new files to the repository set SVN properties,
     104   e.g. for HTML file
     105   
     106       svn:mime-type : text/html
     107       svn:keywords : Author Date Id
     108       svn:eol-style : native
     109
     110   See
     111   http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
     112
     113   You can also simply use this script:
     114   http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh
     115
     116== Images ==
     117
     118Compress PNG images with
     119       optipng -o5 file.png