Having documentation in ReStructured Text has the following benefits

1. The addition of common functionality (options, config files, etc.) can be documented once and then included in documents for multiple tools.

   1a) Documentation source is more straight forward and writers can

   concentrate on the features which are unique to each tool.

2. Documentation can be generated into multiple formats (man, html) not just man pages.
3. Documentation for any individual tool is complete within that page. (There is no referencing of other documents and guessing which "common" options apply.)

Place main rst files in the rst directory. common include rst files should be in rst/common.

"git add" should _only be run on the rst source files themselves.

The best way to update generated documentation after changes is to [re]run configure. autoconf will run the generate script if rst2man is available on your system. If rst2man is not available, tarball and source rpm distributions contain the doc/man/*.in files and can be built from those files a users system without rst2man. Of course they will not get any changes made to the rst files. Therefore developers are required to have rst2man[*] installed.

[*] rst2man is available in the python-docutils package.

Common documents should be placed in the rst/common directory. Common files should not be put in the 'main' rst directory. The automated conversion script will try and make documents out of them.

There are 2 types of common files

1. common options

   The common options are text which describes a common option. The naming conventions is:

   opt<option>.rst

2. common sections

   A common section contains a section header and documents a more advanced feature such as a config file. The naming convention for the common section is:

   sec<section>.rst.

Common documents should actually document features which are intended to be common across multiple tools. Within the code these features are contained in ibdiag_common or a sub library such as ibnetdisc or an external library such as the node name map feature.

The "man" page text is:

::

<text>

<text>

The common option "L" is:

::

-L The address specified is a LID

And the common Section is:

::

CONFIG FILE

@IBDIAG_CONFIG_PATH@/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.