[Nagiosplug-help] Plug-ins Documentation

[Warrick FitzGerald]

I also like the idea of keeping comments embedded in the code, but I
personally feel the biggest problem that most man pages have is the lack
of examples. People rarely have a problem with a specific parameter;
they normally have something they are trying to achieve and are not
really sure how to go about combining all the parameters to achieve it. 

I guess what I'm saying is that I like your idea, but would like to
expand it to include a general "introduction" to each plug-in, as well
as real examples.

I'll spend some time this weekend going through your check_pgsql code,
follow your examples there and see what I can come up with.

Thanks
Warrick 


-----Original Message-----
From: nagiosplug-help-admin at lists.sourceforge.net
[mailto:nagiosplug-help-admin at lists.sourceforge.net] On Behalf Of Karl
DeBisschop
Sent: Saturday, March 27, 2004 1:49 PM
To: Warrick FitzGerald
Cc: dmozingo at topechelon.com; amartins at embratel.net.br;
Nagiosplug-help at lists.sourceforge.net
Subject: Re: [Nagiosplug-help] Plug-ins Documentation

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


-------------------------------------------------------
This SF.Net email is sponsored by: IBM Linux Tutorials
Free Linux tutorial presented by Daniel Robbins, President and CEO of
GenToo technologies. Learn everything from fundamentals to system
administration.http://ads.osdn.com/?ad_id=1470&alloc_id=3638&op=click
_______________________________________________
Nagiosplug-help mailing list
Nagiosplug-help at lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/nagiosplug-help
::: Please include plugins version (-v) and OS when reporting any issue.

::: Messages without supporting info will risk being sent to /dev/null