Changes between Version 4 and Version 5 of Submitting/Docs


Ignore:
Timestamp:
Jun 21, 2014, 1:14:26 PM (10 years ago)
Author:
annakrat
Comment:

improve formatting

Legend:

Unmodified
Added
Removed
Modified

  • Submitting/Docs

    v4 v5  
    22= Submitting Documentation =
    33
    4 When submitting documentation to GRASS SVN repository, please take
    5 care of following rules:
     4There are two types of documentation
     5 * Libraries programmers docs: 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
    66
    7    There are two types of documentation
    8    - Libraries programmers docs: 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
     7 * User manual: we write it in simple HTML, storing the manual in a file '<module>.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 '<module>.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.
    98
    10    - User manual: we write it in simple HTML, storing the manual in a file '<module>.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 '<module>.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.
    11 
    12 See also
    13    http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
     9See also http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
    1410
    1511== HTML Pages ==
    1612
    17 Editing of HTML pages
    18    To avoid insertion of too complicated HTML tags (see also below),
    19    we strongly suggest to use a plain text editor rather than a
    20    HTML editor for editing.
     13To avoid insertion of too complicated HTML tags (see also below),
     14we strongly suggest to use a plain text editor rather than a
     15HTML editor for editing.
    2116
    2217=== Module Manual Pages ===
    2318
    24 Module manual page:
    25    Place the documentation in HTML format into '<module>.html', where
    26    <module> is the name of the module. E.g. if the module is named
    27    r.example, the documentation file should be named r.example.html.
     19Place the documentation in HTML format into '<module>.html', where
     20<module> is the name of the module. E.g. if the module is named
     21r.example, the documentation file should be named r.example.html.
    2822
    29    The easiest way to do this is to study an existing HTML page
    30    (to get the page style, e.g. vector/v.to.db/v.to.db.html).
    31    With a few exceptions, header and footer are NOT allowed.
    32    You can add figures (PNG format); the figure name prefix should be the
    33    module name. See raster/r.terraflow/r.terraflow.html for an example.
     23The easiest way to do this is to study an existing HTML page
     24(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]).
     25With a few exceptions, header and footer are NOT allowed.
     26You can add figures (PNG format); the figure name prefix should be the
     27module name. See [source:grass/trunk/raster/r.terraflow/r.terraflow.html raster/r.terraflow/r.terraflow.html] for an example.
    3428
    35    A number of major sections should be present in each help page.
     29A number of major sections should be present in each help page.
    3630
    37    * = Required
    38    ! = Suggested
    39    . = Optional
     31   R = Required [[br]]
     32   S = Suggested [[br]]
     33   O = Optional [[br]]
    4034
    41    In recommended order
    42    --------------------
     35   In recommended order:
    4336
    44    * <h2>DESCRIPTION</h2>
    45    ! <h2>NOTE</H2>, <h2>NOTES</h2>
    46    ! <h2>EXAMPLE</h2>, <h2>EXAMPLES</h2>
    47    . <h2>TODO</h2>
    48    . <h2>BUGS</h2>
    49    . <h2>REFERENCE</h2>, <h2>REFERENCES</h2>
    50    * <h2>SEE ALSO</h2>
    51    * <h2>AUTHOR</h2>, <h2>AUTHORS</h2>
     37   R: <h2>DESCRIPTION</h2>[[br]]
     38   S: <h2>NOTE</H2>, <h2>NOTES</h2>[[br]]
     39   S: <h2>EXAMPLE</h2>, <h2>EXAMPLES</h2>[[br]]
     40   O: <h2>TODO</h2>[[br]]
     41   O: <h2>BUGS</h2>[[br]]
     42   O: <h2>REFERENCE</h2>, <h2>REFERENCES</h2>[[br]]
     43   R: <h2>SEE ALSO</h2>[[br]]
     44   R: <h2>AUTHOR</h2>, <h2>AUTHORS</h2>[[br]]
    5245
    53    Note that the parameter information is auto-generated upon
    54    compilation. This is done by running the module in a virtual session
    55    after compilation (see the output of 'make'). To subsequently
    56    verify the final HTML page, check the resulting HTML pages which
    57    will be stored with the name of the module.
     46Note that the parameter information is auto-generated upon
     47compilation. This is done by running the module in a virtual session
     48after compilation (see the output of 'make'). To subsequently
     49verify the final HTML page, check the resulting HTML pages which
     50will be stored with the name of the module.
    5851
    59    Examples (please add some) should be coded like this:
    60 
    61    <div class="code"><pre>
    62    v.to.db map=soils type=area option=area column=area_size unit=h
    63    </pre></div>
     52Examples (please add some) should be coded like this:
     53{{{
     54<div class="code"><pre>
     55v.to.db map=soils type=area option=area column=area_size unit=h
     56</pre></div>
     57}}}
    6458 
    65    The online WWW man pages is updated every Saturday (from SVN
    66    repository).
     59The online WWW man pages are updated every Saturday (from SVN repository).
    6760
    6861=== Supported HTML Tags ===
    6962
    70 Usage of limited HTML tags
    71    Since the MAN conversion of g.html2man is limited, please use
    72    no other HTML tags than:
     63Since the MAN conversion of g.html2man is limited, please use
     64no other HTML tags than:
     65{{{
    7366   <a> <b> <body> <br> <code> <dd> <dl> <dt> <em>
    7467   <h2> <h3> <h4> <head> <hr> <i> <img> <li> <ol> <p>
    7568   <pre> <sup> <table> <td> <th> <title> <tr> <ul>
     69}}}
     70   
     71Note that all tags have a closing tag except for <hr/>, <br/> and <p>.
     72Use lower case forms.
    7673
    77    Note that all tags has a closing tag except for <hr/>, <br/> and <p>.
    78    Use lower case forms.
    79 
    80    (The MAN converter is here: tools/g.html2man/)
     74Note that HTML is converted to man pages by [source:grass/trunk/tools/g.html2man/ tools/g.html2man/]
    8175
    8276=== Markup Protocol ===
    8377
    84 Suggested HTML markup protocol:
    85    Module names (i.e., v.category) should be emphsized with <em>,
    86    and boldface <b> for flags and parameter names. Shell commands,
    87    names, values, etc. should use <tt>. Empahsized phrases should use
    88    italics <i>. The SEE ALSO section of each page should also be
    89    alphabetized.                       
     78Module names (i.e., v.category) should be emphasized with <em>,
     79and boldface <b> for flags and parameter names. Shell commands,
     80names, values, etc. should use <tt>. Emphasized phrases should use
     81italics <i>. The SEE ALSO section of each page should also be
     82alphabetized.                   
    9083
    9184== SVN Properties ==
    9285
    93 When submitting new files to the repository set SVN properties,
    94    e.g. for HTML file
     86When submitting new files to the repository set SVN properties, e.g. for HTML file
    9587   
    96        svn:mime-type : text/html
    97        svn:keywords : Author Date Id
    98        svn:eol-style : native
     88       svn:mime-type : text/html [[br]]
     89       svn:keywords : Author Date Id [[br]]
     90       svn:eol-style : native [[br]]
    9991
    100    See
    101    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
     92See http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
    10293
    103    You can also simply use this script:
    104    http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh
     94You can also simply use this script:
     95http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh
    10596
    10697== Images ==
    10798
    108 Compress PNG images with
    109        optipng -o5 file.png
     99Compress PNG images with:
     100{{{
     101optipng -o5 file.png
     102}}}