update developer documentaton

docs/lcdproc-dev/add-your-driver.docbook

@@ -15,7 +15,7 @@ This chapter will explain you the major steps and few gotchas of adding your own
 </sect1>
 
 <sect1 id="autoconfautomake">
-<title>Autoconf, automake, b&ouml;rk b&ouml;rk b&ouml;rk!</title>
+<title>Autoconf, automake, and Everything!</title>
 
 <para>How I Learned to Stop Worrying and Love the Configure Script</para>
 
@@ -148,7 +148,11 @@ myDriver_LDADD = @SOMESTRANGELIB@
 <sect3 id="automake-step3">
 <title>Step 3</title>
 
-<para>Last but not least, you need to specify which source files should be associated with your driver. You put your driver name followed by _SOURCES and egal this to a space separated list of the source and header files. See below for an example.</para>
+<para>
+Last but not least, you need to specify which source files should be
+associated with your driver. You put your driver name followed by
+<literal>_SOURCES</literal> and egal this to a space separated list
+of the source and header files. See below for an example.</para>
 
 <screen>
 myDriver_SOURCES =  lcd.h myDriver.c myDriver.h report.h
@@ -161,9 +165,151 @@ myDriver_SOURCES =  lcd.h myDriver.c myDriver.h report.h
 <sect2 id="autoconfautomake-test">
 <title>Test your setup</title>
 
-<para>You're almost done! You only need to check out if you didn't made any mistake. Just run sh autogen.sh to regenerate the configure script and Makefiles, then run ./configure --enable-drivers=myDriver and type make. If your driver compiles without error, then congratulations, you've just added your driver to LCDproc! Remember to submit a patch to the mailing list so that we can add it to the standard distribution.</para>
+<para>
+You're almost done! You only need to check out if you didn't made any mistake.
+Just run sh autogen.sh to regenerate the configure script and Makefiles,
+then run ./configure --enable-drivers=myDriver and type make.
+If your driver compiles without error, then congratulations, you've just added
+your driver to LCDproc! Remember to submit a patch to the mailing list so that
+we can add it to the standard distribution, but do not forget the documentation.
+</para>
 
-<para>If you had an error, just send us an email describing it to the mailing list and we'll try to help you.</para>
+<para>
+If you had an error, just send us an email describing it to the mailing list and we'll try to help you.
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="documentation">
+<title>It's all about documentation</title>
+
+<para>
+Please do not forget to also add the required documentation,
+so that your driver can be used from others as well.
+</para>
+
+<sect2 id="documentation-LCDd.conf">
+<title>The configuration file, LCDd.conf</title>
+
+<para>
+Extend the LCDproc server's configuration file with a section that holds
+a standard configuration for your driver together with short descriptions
+of the options used.
+</para>
+
+<screen>
+&hellip;
+<emphasis>
+## MyDriver for MyDevice ##
+[MyDriver]
+
+# Select the output device to use [default: /dev/lcd]
+Device=/dev/ttyS0
+
+# Set the display size [default: 20x4]
+Size=20x4
+</emphasis>
+&hellip;
+</screen>
+
+</sect2>
+
+
+<sect2 id="documentation-manpage">
+<title>The daemon's manual page, LCDd.8</title>
+
+<para>
+Append your driver to the list of drivers in <filename>docs/LCDd.conf</filename>,
+the manual page of LCD, so that users can find your driver when doing <userinput>man LCDd</userinput>.
+</para>
+
+<screen>
+&hellip;
+.TP
+.B ms6931
+MSI-6931 displays in 1U rack servers by MSI
+.TP
+.B mtc_s16209x
+MTC_S16209x LCD displays by Microtips Technology Inc
+.TP
+.B MtxOrb
+Matrix Orbital displays (except Matrix Orbital GLK displays)
+<emphasis>.TP</emphasis>
+<emphasis>.B MyDriver</emphasis>
+<emphasis>displays connected using MyDevice</emphasis>
+.TP
+.B NoritakeVFD
+Noritake VFD Device CU20045SCPB-T28A
+.TP
+.B pylcd
+LCD displays from Pyramid (http://www.pyramid.de)
+.TP
+.B sed1330
+SED1330/SED1335 (aka S1D13300/S1D13305) based graphical displays
+&hellip;
+</screen>
+
+</sect2>
+
+<sect2 id="documentation-userdocbook">
+<title>The user guide</title>
+
+<sect3 id="userdocbook-file">
+<title>Step 1</title>
+
+<para>
+Please add a file <filename><emphasis>myDriver</emphasis>.docbook</filename>,
+that describes the configuration of your driver and the hard/software needed,
+to the directory <filename>docs/lcdproc-user/drivers/</filename>.
+</para>
+
+</sect3>
+
+<sect3 id="userdocbook-defentity">
+<title>Step 2</title>
+
+<para>
+Define a Docbook entity for your driverfile in <filename>lcdproc-user.docbook</filename>.
+</para>
+
+<screen>
+&hellip;
+&lt;!ENTITY ms6931 SYSTEM "drivers/ms6931.docbook"&gt;
+&lt;!ENTITY mtc_s16209x SYSTEM "drivers/mtc_s16209x.docbook"&gt;
+&lt;!ENTITY MtxOrb SYSTEM "drivers/mtxorb.docbook"&gt;
+<emphasis>&lt;!ENTITY MyDriver SYSTEM "drivers/MyDriver.docbook"&gt;</emphasis>
+&lt;!ENTITY NoritakeVFD SYSTEM "drivers/NoritakeVFD.docbook"&gt;
+&lt;!ENTITY pylcd SYSTEM "drivers/pylcd.docbook"&gt;
+&lt;!ENTITY sed1330 SYSTEM "drivers/sed1330.docbook"&gt;
+&hellip;
+</screen>
+
+</sect3>
+
+<sect3 id="userdocbook-useentity">
+<title>Step 3</title>
+
+<para>
+Add the freshly defined entity to <filename>drivers.docbook</filename>
+to include the documentation of your driver into the
+<emphasis>LCDproc User's Guide</emphasis>.
+</para>
+
+<screen>
+&hellip;
+&amp;ms6931;
+&amp;mtc_s16209x;
+&amp;MtxOrb;
+<emphasis>&amp;MyDriver;</emphasis>
+&amp;NoritakeVFD;
+&amp;pylcd;
+&amp;sed1330;
+&hellip;
+</screen>
+
+</sect3>
 
 </sect2>
 

docs/lcdproc-dev/driver-api.docbook

@@ -256,70 +256,72 @@ typedef struct my_driver_private {
 <sect1 id="function-details">
   <title>FUNCTIONS IN DETAIL</title>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*init)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  The init function
+  The init() function.
-  Starts up the LCD, initializes all vars. Allocates private data space
+  It starts up the LCD, initializes all variables, allocates private data space
   and stores the pointer by calling store_private_ptr();
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*close)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Shuts down the connection with the LCD.
+  Shut down the connection with the LCD.
   Called just before unloading the driver.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*width)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Get the screen width.
+  Get the screen width in characters.
+  The result is 1-based.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*height)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Get the screen height.
+  Get the screen height in lines.
+  The result is 1-based.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*clear)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Clears the framebuffer
+  Clear the framebuffer.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*flush)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Flushes the framebuffer to the LCD.
+  Flush the framebuffer to the LCD.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*string)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -327,14 +329,17 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>y</parameter></paramdef>
 	<paramdef>char *<parameter>str</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Places a string in the framebuffer
+  Place string <replaceable>str</replaceable> into position
-  All coordinates are 1-based, (1,1) is top left.
+  (<replaceable>x</replaceable>,<replaceable>y</replaceable>) in the framebuffer.
-  Driver should check for overflows
+  All coordinates are 1-based, i.e. (1,1) is top left.
+  The driver should check for overflows, i.e. that the positional parameters
+  are within the screen's boundaries and cut off the part of the string
+  that is out of bounds.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*chr)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -342,13 +347,16 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>y</parameter></paramdef>
 	<paramdef>char <parameter>c</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Places a char in the framebuffer
+  Place a single character <replaceable>c</replaceable> into position
-  Driver should check for overflows
+  (<replaceable>x</replaceable>,<replaceable>y</replaceable>) in the framebuffer.
+  The driver should check for overflows, i.e. that the positional parameters
+  are within the screen's boundaries and ignore the request if 
+  the character is out of bounds.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*vbar)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -358,12 +366,14 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>promille</parameter></paramdef>
 	<paramdef>int <parameter>options</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Draws a vertical bar at horizontal position x and with length len.
+  Draw a vertical bar at position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
+  that has maximal length <replaceable>len</replaceable>, where a fraction of
+  (<replaceable>promille</replaceable> / 1000) is filled.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*hbar)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -373,30 +383,32 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>promille</parameter></paramdef>
 	<paramdef>int <parameter>options</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Draws a horizontal bar at position x,y and with length len.
+  Draw a horizontal bar at position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
+  that has maximal length <replaceable>len</replaceable>, where a fraction of
+  (<replaceable>promille</replaceable> / 1000) is filled.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*num)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
 	<paramdef>int <parameter>x</parameter></paramdef>
 	<paramdef>int <parameter>num</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
-  Displays a big number at position x.
+  Display big number <replaceable>num</replaceable> at horizontal position <replaceable>x</replaceable>.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*heartbeat)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
 	<paramdef>int <parameter>state</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Sets the heartbeat to the indicated state.
   0=off 1=graph1 2=graph2
@@ -406,7 +418,7 @@ typedef struct my_driver_private {
   The driver choose how to do it. See MtxOrb.c"
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*icon)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -414,110 +426,110 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>y</parameter></paramdef>
 	<paramdef>int <parameter>icon</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*set_char)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
 	<paramdef>char <parameter>ch</parameter></paramdef>
 	<paramdef>char *<parameter>dat</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*get_free_chars)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*cellwidth)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*cellheight)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*contrast)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
 	<paramdef>int <parameter>contrast</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Sets the contrast to the given value. Values should be 0 to 255.
   Many displays do not support software setting of contrast.
   Use -1 to get the current value returned.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*backlight)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
 	<paramdef>int <parameter>brightness</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Sets the backlight to brightness 'on'.
   Often hardware can only support on and off, in that case any value
   of on>0 will switch the backlight on.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*output)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
 	<paramdef>int <parameter>state</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Sets the output value. Some displays/wirings have a general purpose
   output, which can be controlled by calling this function. See the
   'output' command in the 'widget language'.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>char *<function>(*get_key)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Checks if a key has been pressed on the device.
   Returns NULL for "no key pressed", or a string describing the pressd key.
   These characters should match the keypad-layout.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>char *<function>(*get_info)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Returns a string describing the driver and its features.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>char <function>(*config_get_bool)</function></funcdef>
 	<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -525,7 +537,7 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>skip</parameter></paramdef>
 	<paramdef>char <parameter>default_value</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Call to server. Retrieve a bool from the config file.
   Sectionname should be the name of the driver (as in the struct).
@@ -534,7 +546,7 @@ typedef struct my_driver_private {
   identical keys, then increase skip to get every next value.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>(*config_get_int)</function></funcdef>
 	<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -542,12 +554,12 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>skip</parameter></paramdef>
 	<paramdef>int <parameter>default_value</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Call to server. Retrieve an integer from the config file.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>double <function>(*config_get_float)</function></funcdef>
 	<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -555,12 +567,12 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>skip</parameter></paramdef>
 	<paramdef>double <parameter>default_value</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Call to server. Retrieve a float from the config file.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>char *<function>(*config_get_string)</function></funcdef>
 	<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -568,7 +580,7 @@ typedef struct my_driver_private {
 	<paramdef>int <parameter>skip</parameter></paramdef>
 	<paramdef>char *<parameter>default</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Call to server. Retrieve a string from the config file.
   Fill result with a pointer to some available space. You can fill it
@@ -579,24 +591,24 @@ typedef struct my_driver_private {
   next call.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>config_has_section</function></funcdef>
 	<paramdef>char *<parameter>sectionname</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Returns wether a section exists. Does not need to be called prior
   to a call to a config_get_* function.
 </para>
 
-<funcsynopsis>	
+<funcsynopsis>
   <funcprototype>
 	<funcdef>int <function>config_has_key</function></funcdef>
 	<paramdef>char *<parameter>sectionname</parameter></paramdef>
 	<paramdef>char *<parameter>keyname</parameter></paramdef>
   </funcprototype>
-</funcsynopsis>	
+</funcsynopsis>
 <para>
   Returns the number of times a key exists. Does not need to be called
   prior to a call to a config_get_* function.

docs/lcdproc-dev/language.docbook

@@ -301,13 +301,13 @@
 		        <varlistentry>
 		          <term><literal>hidden</literal></term>
 			  <listitem><para>
-			      screen will never be visible
+			      The screen will never be visible
 			    </para></listitem>
 		        </varlistentry>
 		        <varlistentry>
 		          <term><literal>background</literal></term>
 			  <listitem><para>
-			      only visible when no normal info screens exist
+			      The screen is only visible when no normal info screens exists
 			    </para></listitem>
 		        </varlistentry>
 		        <varlistentry>
@@ -325,13 +325,13 @@
 		        <varlistentry>
 		          <term><literal>alert</literal></term>
 			  <listitem><para>
-			      screen has an important message for the user
+			      The screen has an important message for the user.
 			    </para></listitem>
 		        </varlistentry>
 		        <varlistentry>
 		          <term><literal>input</literal></term>
 			  <listitem><para>
-			      the client is doing interactive input
+			      The client is doing interactive input.
 			    </para></listitem>
 		        </varlistentry>
 		        <varlistentry>
@@ -388,7 +388,7 @@
 		  </term>
 		  <listitem><para>
 		      Changes the heartbeat setting for this screen.
-		      If the to <literal>open</literal>, the default,r
+		      If set to <literal>open</literal>, the default,
 		      the client's heartbeat setting will be used.
 		    </para></listitem>
 		</varlistentry>
@@ -480,7 +480,7 @@
 	      <arg choice="plain"><replaceable>screen_id</replaceable></arg>
 	      <arg choice="plain"><replaceable>new_widget_id</replaceable></arg>
 	      <arg choice="plain"><replaceable>widgettype</replaceable></arg>
-	      <arg>-in <replaceable>frame_id</replaceable></arg>]
+	      <arg>-in <replaceable>frame_id</replaceable></arg>
 	    </cmdsynopsis>
 	  </term>
 	  <listitem>