forked from OSGeo/grass
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathSUBMITTING_DOCS
124 lines (91 loc) · 4.25 KB
/
SUBMITTING_DOCS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
NOTE: Please improve this list!
Dear (new) GRASS GIS Developer,
When submitting documentation to GRASS SVN repository, please take
care of following rules:
[ see SUBMITTING for C hints ]
[ see SUBMITTING_WXGUI for wxPython GUI code 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> <body> <br> <code> <dd> <dl> <dt> <em>
<h2> <h3> <h4> <head> <hr> <i> <img> <li> <ol> <p>
<pre> <sup> <table> <td> <th> <title> <tr> <ul>
Note that all tags has a closing tag except for <hr/>, <br/> and <p>.
Use lower case forms.
(The MAN converter is here: tools/g.html2man/)
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
You can also simply use this script:
http://svn.osgeo.org/grass/grass-addons/tools/module_svn_propset.sh
6. Compress PNG images with
optipng -o5 file.png
7. See also
http://grass.osgeo.org/wiki/Updating_GRASS_Documentation
...
[please add further hints if required]
"Your attention to detail is appreciated."