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 42ad8964..3edca6b8 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>