wiki:Submitting/Docs

Version 16 (modified by neteler, 8 years ago) ( diff )

color quantization with pngnq

Table of Contents

  1. HTML Pages
    1. Module Manual Pages
    2. Supported HTML Tags
    3. Markup style guide
    4. Break long lines
  2. SVN Properties
  3. Images

Submitting Documentation

There are three types of documentation

  • 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. See below for details on the structure.

See also on the main Web site: ​http://grass.osgeo.org/wiki/Updating_GRASS_Documentation

HTML Pages

The manual pages are not only fundamental for the users but also the "business card" of the respective module. An ideal page comes with clear descriptions, hints on the implemented algorithm and example(s).

  • Note: Do not upload broken or even empty HTML manual pages. This breaks things in various places.
  • To avoid the 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.

Important: The HTML 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.

Module Manual Pages

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.

R = Required
S = Suggested
O = Optional

In recommended order (in bold the required entries):

R: <h2>DESCRIPTION</h2>
S: <h2>NOTE</H2>, <h2>NOTES</h2>
S: <h2>EXAMPLE</h2>, <h2>EXAMPLES</h2>
O: <h2>TODO</h2>
O: <h2>KNOWN ISSUES</h2>
O: <h2>REFERENCE</h2>, <h2>REFERENCES</h2>
R: <h2>SEE ALSO</h2>
R: <h2>AUTHOR</h2>, <h2>AUTHORS</h2>

Note that the parameter manual section 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 more) 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 manual pages are updated every Saturday (from SVN repository).

Supported 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 have a closing tag except for <hr/>, <br/> and <p>.
  • Use lower case forms.
  • Do not insert <p> after <h2>...</h2> or <h3>...</h3>

Note that HTML is converted to MAN pages by tools/g.html2man/

Markup style guide

  • Module names (i.e., v.category) should be emphasized with <em>module</em>.
  • Flags and parameter names written in boldface like <b>-f</b> and <b>input</b>.
  • Shell commands, names, values, etc. should use <tt>42</tt>.
  • Emphasized phrases <i>should use italics</i>.

The <h2>SEE ALSO</h2> section of each page should also be alphabetized.

Break long lines

To avoid SVN merge conflicts, please break a line at approximately 70-80 chars.

Hints:

  • "geany" editor can format a paragraph with CTRL-j
  • "kate": activate it in Settings -> Kate -> Editing -> General -> enable static word-wrap, set 72

SVN Properties

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 <filename>|*

Example: 

sh grass-addons/tools/module_svn_propset.sh vector/mymodule/*

Images

Naming convention: module_name.png or module_name_keyword.png (in both cases, dots in module name are replaced by underscores)

Examples:

  • d_geodesic.png
  • r_resamp_stats_6m_20m.png
  • g_gui_rlisetup_8.png
  • v_clean_rmsa.png

Image size: 600 pixel width (height depends on that), use e.g. ImageMagic: 

mogrify -resize 600x file.png

Smaller images are also possible when appropriate, e.g. when a lot of images are included or they are something special, e.g. equations, icons or simple diagrams.

Please compress PNG images with: 

# optionally, but usually worth it (careful color quantization):
pngnq -n 128 -s 3 file.png

# shuffle original and quantitized image names
mv file.png file_ORIG.png
mv file-nq8.png file.png

# compress better (lossless)
optipng -o5 file.png

Format: Images should be ideally in PNG (well, JPG and GIF is allowed as well when appropriate but usually it is not!). Vector data should be included in pages as raster images (i.e. PNGs) but the original format (preferably SVG) should be committed to the repository as well.

Note: See TracWiki for help on using the wiki.