[Pkg-nagios-devel] Bug#640070: nagios-plugins: some ideas on improving the package documentation

[Jan Wagner]

tags 640070 moreinfo
thanks

Hi Christoph,

many thanks for your bugreport.

On Thursday 01 September 2011 23:44:33 Christoph Anton Mitterer wrote:
> 1) For nearly all but the actuall main nagios packages it's IMHO
> not that important to repeate that large information on what Nagios is
> and it's features in the package description
> Especially with nagios-plugins* as this is also used by others (e.g.
> Icinga) which may have different feature sets.

Indeed, that description is a bit old and we have now some more compatible 
systems. :)

> 2) I'd rather like to read (in the package description), which plugins are
> acutally contained in the -basic and -standard packages and if not obvious
> what they roughly do.

I think it's a goot idea to list the plugins names there, as this also helps 
to find the correct package, if you are searching a plugin via apt-cache for 
example.
A description what each package can be used for will be too verbose for a 
package description. For this we have a "Homepage:" entry in the description 
and you can have a look there to get your information, if you want to know 
about the use of each plugin before installing the package.

> 3) In /usr/share/doc/nagios-plugins-basic/README you also mention the deps
> (which are not package dependencies) for the -standard package.

This is intentionally, as we had serveral complaints and bugreport by users 
which wanted to get rid of these dependencies but using the package. These 
dependencies are recommands and are installed automatically, if you didn't 
have disabled installing recommands, which is the default behavior.

> I guess this comes from using the same /u/s/d/ files in all the
> nagios-plugin packages.
> Using the same files here is some very very tiny bit confusing, as e.g.
> /usr/share/doc/nagios-plugins-standard/README.Debian.plugins does not
> necessarily exist on the system ;)

Sorry, you are a confusing me a bit as I don't understand what you want to 
tell me. /usr/share/doc/nagios-plugins-standard/README.Debian.plugins exists 
on all system which have the package nagios-plugins-standard installed.

> It should perhaps be noted, that the -basic plugins have no furhter deps,
> and all are already guaranteed via package dependencies, AFAIU.

I think "This package provides a basic set of plugins with minimal external 
dependencies." is sufficiant and this is part of the actual description of 
nagios-plugins-basic.

> 4) I personally would find it useful, if you add the dependencies of the
> -standard plugins to that package's description,.. similarly to what the
> devscripts package does.

I don't thing this makes really sense, as something like 'apt-cache show 
nagios-plugins-standard | grep "^[Depends|Recommends]"' gives you this 
information.
 
> 5) It might even be possible to do similar thing as in (4) with the plugins
> that require root right (to have this better documented).
> Or at least the list in README.Debian should be complete.

I think it wouldn't be so bad to either read the documentation of the plugin 
you want to use or know what you are doing.
Anyways ... the README.Debian.gz contains a section "plugins needing root 
privilege" at the end.

Please keep in mind, that it isn't usefull to bloat the package description, 
if you can get your informations from other places without too much extra 
work.

Cheers, Jan.
-- 
Never write mail to <waja at spamfalle.info>, you have been warned!
-----BEGIN GEEK CODE BLOCK-----
Version: 3.12
GIT d-- s+: a C+++ UL++++ P+ L+++ E--- W+++ N+++ o++ K++ w--- O M V- PS PE Y++
PGP++ t-- 5 X R tv- b+ DI D+ G++ e++ h---- r+++ y++++ 
------END GEEK CODE BLOCK------
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.alioth.debian.org/pipermail/pkg-nagios-devel/attachments/20110902/b3b9de68/attachment.pgp>