Changes between Version 6 and Version 7 of Submitting/Docs
- Timestamp:
- 10/21/14 05:59:51 (10 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Submitting/Docs
v6 v7 2 2 = Submitting Documentation = 3 3 4 There are t wotypes of documentation5 * 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 examples4 There are three types of documentation 5 * '''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 6 6 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.7 * '''User manual''': each command ("module") comes with its own page. 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. 8 8 9 See also http://grass.osgeo.org/wiki/Updating_GRASS_Documentation 9 * '''Python documentation''': written in Markdown which is compiled with Sphinx (see [http://grass.osgeo.org/grass71/manuals/libpython/pygrass_index.html PyGRASS documentation]) 10 11 See also on the main Web site: http://grass.osgeo.org/wiki/Updating_GRASS_Documentation 10 12 11 13 == HTML Pages == 12 14 13 To avoid insertion of too complicated HTML tags (see also below), 14 we strongly suggest to use a plain text editor rather than a 15 HTML editor for editing. 15 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. 16 16 17 17 === Module Manual Pages === … … 44 44 R: <h2>AUTHOR</h2>, <h2>AUTHORS</h2>[[br]] 45 45 46 Note that the parameter information is auto-generated upon46 Note that the parameter manual section is auto-generated upon 47 47 compilation. This is done by running the module in a virtual session 48 48 after compilation (see the output of 'make'). To subsequently … … 50 50 will be stored with the name of the module. 51 51 52 Examples (please add some ) should be coded like this:52 Examples (please add some more) should be coded like this: 53 53 {{{ 54 54 <div class="code"><pre> … … 57 57 }}} 58 58 59 The online WWW man pagesare updated every Saturday (from SVN repository).59 The [http://grass.osgeo.org/grass70/manuals/ online WWW manual pages] are updated every Saturday (from SVN repository). 60 60 61 61 === Supported HTML Tags === … … 69 69 }}} 70 70 71 Note that all tags have a closing tag except for <hr/>, <br/> and <p>. 72 Use lower case forms. 71 * Note that all tags have a closing tag except for <hr/>, <br/> and <p>. 72 * Use lower case forms. 73 * Do not insert <p> after <h2>...</h2> or <h3>...</h3> 73 74 74 Note that HTML is converted to manpages by [source:grass/trunk/tools/g.html2man/ tools/g.html2man/]75 Note that HTML is converted to MAN pages by [source:grass/trunk/tools/g.html2man/ tools/g.html2man/] 75 76 76 === Markup Protocol===77 === Markup style guide === 77 78 78 79 Module names (i.e., v.category) should be emphasized with <em>, … … 80 81 names, values, etc. should use <tt>. Emphasized phrases should use 81 82 italics <i>. The SEE ALSO section of each page should also be 82 alphabetized. 83 alphabetized. 84 85 === Break long lines === 86 87 To avoid SVN merge conflicts, please break a line at approximately 70-80 chars. 88 89 Hints: 90 * "geany" editor can format a paragraph with CTRL-j 91 * "kate": activate it in Settings -> Kate -> Editing -> General -> enable static word-wrap, set 72 83 92 84 93 == SVN Properties == … … 93 102 94 103 You can also simply use this script: 95 http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh 104 http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh <filename>|* 105 106 Example: 107 {{{ 108 sh grass-addons/tools/module_svn_propset.sh vector/mymodule/* 109 }}} 96 110 97 111 == Images == … … 110 124 optipng -o5 file.png 111 125 }}} 112 }}}
