Updated docs to include comments, contrib->main, getopts_long and

verbose output levels


git-svn-id: https://nagiosplug.svn.sourceforge.net/svnroot/nagiosplug/nagiosplug/trunk@508 f882894a-f735-0410-b71e-b25c423dba1c

1 files changed, 79 insertions, 13 deletions

diff --git a/doc/developer-guidelines.sgml b/doc/developer-guidelines.sgml
index 42ad896..3edca6b 100644
--- a/doc/developer-guidelines.sgml
+++ b/doc/developer-guidelines.sgml
@@ -109,7 +109,42 @@
                 when it notifies contacts about potential problems. If you print
                 multiple lines, you're out of luck. Remember, keep it short and
                 to the point.</para>
-            </section>
+                </section>
+
+                <section><title>Verbose output</title>
+                <para>Use the -v flag for verbose output. You should allow multiple
+                -v options for additional verbosity, up to a maximum of 3. The standard
+                type of output should be:</para>
+
+                <table id="verbose_levels"><title>Verbose output levels</title>
+                        <tgroup cols="2">
+                                <thead>
+                                        <row>
+                                                <entry><para>Verbosity level</para></entry>
+                                                <entry><para>Type of output</para></entry>
+                                        </row>
+                                </thead>
+                                <tbody>
+                                        <row>
+                                                <entry align=center><para>0</para></entry>
+                                                <entry><para>Single line, minimal output. Summary</para></entry>
+                                        </row>
+                                        <row>
+                                                <entry align=center><para>1</para></entry>
+                                                <entry><para>Single line, additional information (eg list processes that fail)</para></entry>
+                                        </row>
+                                        <row>
+                                                <entry align=center><para>2</para></entry>
+                                                <entry><para>Multi line, configuration debug output (eg ps command used)</para></entry>
+                                        </row>
+                                        <row>
+                                                <entry align=center><para>3</para></entry>
+                                                <entry><para>Lots of detail for plugin problem diagnosis</para></entry>
+                                        </row>
+                                </tbody>
+                        </tgroup>
+                </table>
+                </section>
 
                 <section><title>Screen Output</title>
                 <para>The plug-in should print the diagnostic and just the
@@ -345,9 +380,8 @@
                 <section><title>Option Processing</title>
 
                 <para>For plugins written in C, we recommend the C standard
-                getopt library for short options. If using getopt_long, check to
-                be sure that HAVE_GETOPT_H is defined (configure checks this and
-                sets the #define in common/config.h).</para>
+                getopt library for short options. Getopt_long is always available.
+                </para>
 
                 <para>For plugins written in Perl, we recommend Getopt::Long module.</para>
 
@@ -363,6 +397,7 @@
           -w warning threshold (--warning)
           -c critical threshold (--critical)
           -H hostname (--hostname)
+          -v verbose (--verbose)
                 </literallayout>
 
                 <para>In addition to the reserved options above, some other standard options are:</para>
@@ -397,6 +432,9 @@
                 help. Help text should fit on an 80-character width display, but
                 may run as many lines as needed.</para>
 
+                <para>The option -v or --verbose should be present in all plugins.
+                The user should be allowed to specify -v multiple times to increase
+                the verbosity level, as described in <xref linkend="verbose_levels">.</para>
     </section>
 
     <section>
@@ -405,7 +443,7 @@
 
       <para>Old style was to do things like -ct for critical time and
       -cv for critical value. That goes out the window with POSIX
-      getopt. The allowable alternatves are:</para>
+      getopt. The allowable alternatives are:</para>
 
       <orderedlist>
         <listitem>
@@ -449,23 +487,51 @@
 
       <para>As always, comments are welcome - making this consistent
       without a host of long options was quite a hassle, and I would
-      suspect that there are flaws in this strategy. Perhaps clear
-      long-options is the most important of the above choices, but not
-      all POSIX systems have C libraries for long options, so the
-      short forms must exist as well.</para>
+      suspect that there are flaws in this strategy. 
+      </para>
     </section>
 </section>
 
+<section id="CodingGuidelines"><title>Coding guidelines</title>
+        <para>See <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU
+        Coding standards</ulink> for general guidelines.</para>
+        <section><title>Comments</title>
+        <para>You should use /* */ for comments and not // as some compilers
+        do not handle the latter form</para>
+        </section>
+</section>
+
 <section id="SubmittingChanges"><title>New submissions and patches</title>
 
-        <para>If you would like other to use your plugins and have it included in
-        the standard distribution, please include patches for the relavant
-        configuration files, in particular "configure.in" Otherwise submitted 
+        <para>If you would like others to use your plugins and have it included in
+        the standard distribution, please include patches for the relevant
+        configuration files, in particular "configure.in". Otherwise submitted 
         plugins will be included in the contrib directory.</para>
         
         <para>Plugins in the contrib directory are going to be migrated to the
         standard plugins/plugin-scripts directory as time permits and per user
-        requests</para>
+        requests. The minimum requirements are:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>The standard command options are supported (--help, --version,
+          --timeout, --warning, --critical)</para>
+        </listitem>
+        <listitem>
+          <para>It is determined to be not redundant (for instance, we would not 
+                add a new version of check_disk just because someone had provide 
+                a plugin that had perf checking - we would incorporate the features 
+                into an exisiting plugin)</para>
+        </listitem>
+        <listitem>
+          <para>One of the developers has had the time to audit the code and declare
+                it ready for core</para>
+        </listitem>
+        <listitem>
+          <para>It should also follow code format guidelines, and use functions from
+utils (perl or c or sh) rather than cooking it's own</para>
+        </listitem>
+      </orderedlist>
 
         <para>Patches should be submitted via the SourceForge and be announced to
         the mailing list.</para>