Changes between Version 4 and Version 5 of Submitting/Docs
- Timestamp:
- 06/21/14 13:14:26 (10 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Submitting/Docs
v4 v5 2 2 = Submitting Documentation = 3 3 4 When submitting documentation to GRASS SVN repository, please take 5 care of following rules: 4 There 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 6 6 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. 9 8 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 9 See also http://grass.osgeo.org/wiki/Updating_GRASS_Documentation 14 10 15 11 == HTML Pages == 16 12 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. 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. 21 16 22 17 === Module Manual Pages === 23 18 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. 19 Place the documentation in HTML format into '<module>.html', where 20 <module> is the name of the module. E.g. if the module is named 21 r.example, the documentation file should be named r.example.html. 28 22 29 30 (to get the page style, e.g. vector/v.to.db/v.to.db.html).31 32 33 module name. See raster/r.terraflow/r.terraflow.htmlfor an example.23 The 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]). 25 With a few exceptions, header and footer are NOT allowed. 26 You can add figures (PNG format); the figure name prefix should be the 27 module name. See [source:grass/trunk/raster/r.terraflow/r.terraflow.html raster/r.terraflow/r.terraflow.html] for an example. 34 28 35 29 A number of major sections should be present in each help page. 36 30 37 * = Required38 ! = Suggested39 . = Optional31 R = Required [[br]] 32 S = Suggested [[br]] 33 O = Optional [[br]] 40 34 41 In recommended order 42 -------------------- 35 In recommended order: 43 36 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]] 52 45 53 54 55 56 57 46 Note that the parameter information is auto-generated upon 47 compilation. This is done by running the module in a virtual session 48 after compilation (see the output of 'make'). To subsequently 49 verify the final HTML page, check the resulting HTML pages which 50 will be stored with the name of the module. 58 51 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> 52 Examples (please add some) should be coded like this: 53 {{{ 54 <div class="code"><pre> 55 v.to.db map=soils type=area option=area column=area_size unit=h 56 </pre></div> 57 }}} 64 58 65 The online WWW man pages is updated every Saturday (from SVN 66 repository). 59 The online WWW man pages are updated every Saturday (from SVN repository). 67 60 68 61 === Supported HTML Tags === 69 62 70 Usage of limited HTML tags 71 Since the MAN conversion of g.html2man is limited, please use 72 no other HTML tags than: 63 Since the MAN conversion of g.html2man is limited, please use 64 no other HTML tags than: 65 {{{ 73 66 <a> <b> <body> <br> <code> <dd> <dl> <dt> <em> 74 67 <h2> <h3> <h4> <head> <hr> <i> <img> <li> <ol> <p> 75 68 <pre> <sup> <table> <td> <th> <title> <tr> <ul> 69 }}} 70 71 Note that all tags have a closing tag except for <hr/>, <br/> and <p>. 72 Use lower case forms. 76 73 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/) 74 Note that HTML is converted to man pages by [source:grass/trunk/tools/g.html2man/ tools/g.html2man/] 81 75 82 76 === Markup Protocol === 83 77 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. 78 Module names (i.e., v.category) should be emphasized with <em>, 79 and boldface <b> for flags and parameter names. Shell commands, 80 names, values, etc. should use <tt>. Emphasized phrases should use 81 italics <i>. The SEE ALSO section of each page should also be 82 alphabetized. 90 83 91 84 == SVN Properties == 92 85 93 When submitting new files to the repository set SVN properties, 94 e.g. for HTML file 86 When submitting new files to the repository set SVN properties, e.g. for HTML file 95 87 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]] 99 91 100 See 101 http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html 92 See http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html 102 93 103 104 94 You can also simply use this script: 95 http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh 105 96 106 97 == Images == 107 98 108 Compress PNG images with 109 optipng -o5 file.png 99 Compress PNG images with: 100 {{{ 101 optipng -o5 file.png 102 }}}
