[Nagiosplug-checkins] CVS: nagiosplug/doc developer-guidelines.sgml,1.1,1.2

[Ton Voon]

Update of /cvsroot/nagiosplug/nagiosplug/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv10673

Modified Files:
	developer-guidelines.sgml 
Log Message:
Updated docs to include comments, contrib->main, getopts_long and
verbose output levels


Index: developer-guidelines.sgml
===================================================================
RCS file: /cvsroot/nagiosplug/nagiosplug/doc/developer-guidelines.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** developer-guidelines.sgml	27 May 2002 02:05:55 -0000	1.1
--- developer-guidelines.sgml	13 May 2003 23:20:08 -0000	1.2
***************
*** 110,114 ****
  		multiple lines, you're out of luck. Remember, keep it short and
  		to the point.</para>
! 	    </section>
  
  		<section><title>Screen Output</title>
--- 110,149 ----
  		multiple lines, you're out of luck. Remember, keep it short and
  		to the point.</para>
! 		</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>
***************
*** 346,352 ****
  
  		<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>
  
  		<para>For plugins written in Perl, we recommend Getopt::Long module.</para>
--- 381,386 ----
  
  		<para>For plugins written in C, we recommend the C standard
! 		getopt library for short options. Getopt_long is always available.
! 		</para>
  
  		<para>For plugins written in Perl, we recommend Getopt::Long module.</para>
***************
*** 364,367 ****
--- 398,402 ----
            -c critical threshold (--critical)
            -H hostname (--hostname)
+           -v verbose (--verbose)
  		</literallayout>
  
***************
*** 398,401 ****
--- 433,439 ----
  		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>
  
***************
*** 406,410 ****
        <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>
  
        <orderedlist>
--- 444,448 ----
        <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 alternatives are:</para>
  
        <orderedlist>
***************
*** 450,470 ****
        <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>
      </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 
  	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>
  
  	<para>Patches should be submitted via the SourceForge and be announced to
--- 488,536 ----
        <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. 
!       </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 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. 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