| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116 |
- NOTE: Please improve this list!
- Dear (new) GRASS developer,
- when submitting documentation to GRASS SVN repository, please take
- care of following rules:
- [ see SUBMITTING for C hints ]
- [ 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/gis/*.c and lib/gis/gislib.dox for examples
- - 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.
- 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
- HTML editor for editing.
- 2. Module manual page:
- Place the documentation in HTML format into '<module>.html', where
- <module> is the name of the module. E.g. if the module is named
- r.example, the documentation file should be named r.example.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/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 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.
- Examples (please add some) should be coded like this:
- <div class="code"><pre>
- v.to.db map=soils type=area option=area column=area_size unit=h
- </pre></div>
-
- The online WWW man pages is updated every Saturday (from SVN
- repository).
- 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>
- 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,
- names, values, etc. should use <tt>. Empahsized phrases should use
- italics <i>. The SEE ALSO section of each page should also be
- alphabetized.
- 5. When submitting new files to the repository set SVN properties,
- e.g. for HTML file
-
- svn:mime-type : text/html
- svn:keywords : Author Date Id
- svn:eol-style : native
- See
- http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
- 6. See also
- http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
- ...
- [please add further hints if required]
- "Your attention to detail is appreciated."
|
