[Nagiosplug-help] Plug-ins Documentation

[Karl DeBisschop]

On Sat, 27 Mar 2004 12:42:03 -0500
"Warrick FitzGerald" <wfitzgerald at LiveTechnology.com> wrote:

> How are you with docbook?
> 
> [Warrick FitzGerald] 
> I don't have any practical experience myself, however there's no time
> like the present to learn (Seems pretty straight forward). My approach
> would be:
> 
> - Pick a plug-in (My Preference would be check_http to start)
> - Write a basic man page in plain ASCII
> - Decide on a standard docbook format for all docs to come. Although
> docbook is a standard we should try to keep all the docs structured
> the same.

There is a docbook template for man pages. I think we'd want to use
that.

> - Convert it to docbook
> - Submit it to group ... where you can point out bad docbook syntax if
> necessary. Correct syntax and move onto the next.

The way I look at it, 50% or more of what would be a man page is already
in the --help from the plugin. So I'd like to extract that into SGML
entities that could be referenced into the remaining part of the docs.
For my point of view, there's a flaw in the process if we have to write
the description of the command line options twice, or manually copy them
from one document to another.

For instance, all the command-line options are translated strings, so
the are ALL marked up like _("Text Here") - we can leverage that
translation markup to extract the text at make time, so when the plugin
changes we only need change the docs in one place.

Couple that with things to check an make sure 1) every option has help
text and 2) every help-text item for the options shows up in the getopt
array, then you got a fairly powerful system that reduces the chance of
making errors.

I also like to keep the text and the plugin together so as to try and
encourgae the programmers to comment their code in a meaningful way, so
my prefernce would be to puch the text of a man page back into comments
in the code.

For a look at the way I'm thinking of this whole problem, take a peek at
check_pgsql. At one point, prior to i18n and prior to replacing #define
with enum in several places, you could run this though a script and come
out with a detailed man page. Ever nicer, the man page used the actual
#define to find the value of things like timeout and default port. So if
you changed the default time out, the man page would automatically pick
up the change. [BTW - in the case of check_pgsql, I marked things that
should be translated and also should be pulled into docbook with S_() -
I'll leave it to someone else to determine if this means that
completing the i18n work could get us man pages in multiple languages
for the same effort.]

It was rough in spots, but it worked. I'd really like to have people
sign on to an embedded docbook format, and help develop the raminaing
parts for it. So far I've had little help, so most of what you see in
check_pgsql is waht I've been able to do betwwen other things like
perfdata and i18n work.

--
Karl