extend user documentation

docs/lcdproc-user/configuration.docbook

@@ -23,10 +23,75 @@ The format of the <filename>/etc/LCDd.conf</filename> is INI-file like.
 </para>
 
 <para>
-It is divided into sections that start at markers that look like
+It is divided into sections that start at declarations that look like
-<code>[<replaceable>section</replaceable>]</code>.
+<code>[<replaceable>section</replaceable>]</code>; i.e. an opening square bracket, followed
-Comments are all line-based comments,
+by the section name, and terminated by a closing square bracket, on a line by itself.
-and are lines that start with '<literal>#</literal>' or '<literal>;</literal>'.
+Section names are case insensitive.
+</para>
+
+<para>
+Parameters are grouped into sections and have the form
+<code><replaceable>key</replaceable>=<replaceable>value</replaceable></code>;
+i.e. a key, also known as the configuration option, followed by an equality sign and
+finally the value for the option.
+All three elements must occur together on one line.
+The <replaceable>key</replaceable>, which is case insensitive, may be surrounded by spaces,
+but is must be one word (i.e. a sequence of non-space characters) not containing the equality sign.
+A similar rule applies to the <replaceable>value</replaceable>: it may be surrounded by spaces,
+but it must be either one word or enclosed within double quotes (<literal>"</literal>),
+which are not considered as part of <replaceable>value</replaceable>.
+When quoted, the following character sequences are evaluated as in literal C strings:
+<informaltable>
+<tgroup cols="2">
+  <thead>
+  </thead>
+    <row>
+      <entry>escape sequence</entry>
+      <entry>character</entry>
+    </row>
+  <tbody>
+    <row>
+      <entry><literal>\a</literal></entry>
+      <entry>alert (bell) character</entry>
+    </row>
+    <row>
+      <entry><literal>\b</literal></entry>
+      <entry>backspace</entry>
+    </row>
+    <row>
+      <entry><literal>\f</literal></entry>
+      <entry>formfeed</entry>
+    </row>
+    <row>
+      <entry><literal>\n</literal></entry>
+      <entry>newline</entry>
+    </row>
+    <row>
+      <entry><literal>\r</literal></entry>
+      <entry>carriage return</entry>
+    </row>
+    <row>
+      <entry><literal>\t</literal></entry>
+      <entry>horizontal tab</entry>
+    </row>
+    <row>
+      <entry><literal>\v</literal></entry>
+      <entry>vertical tab</entry>
+    </row>
+    <row>
+      <entry><literal>\\</literal></entry>
+      <entry>backslash</entry>
+    </row>
+  </tbody>
+</tgroup>
+</informaltable>
+All other occurences of <literal>\</literal> within quoted values will be ignored.
+</para>
+
+<para>
+Comments are all line-based, and may start with '<literal>#</literal>' or '<literal>;</literal>'.
+Everything including and behind the character starting the comment up to the end
+of the line is ignored.
 </para>
 
 <para>
@@ -46,40 +111,16 @@ line in the server section, like:
 [Server]
 Driver=curses
 </programlisting>
-</example>
-
 <para>
 This tells <application>LCDd</application> to use the <literal>curses</literal> driver.
-The first driver specified here that is capable of output functionality
-will be used as <emphasis>the</emphasis> output driver.
-All other drivers can only serve as input drivers.
-The default driver to use is <literal>curses</literal>.
 </para>
-
+</example>
-<warning>
-<para>
-If LCDd is started automatically by an init-script using the curses driver,
-it will lock <filename>/dev/tty1</filename>! So, be careful about what you are
-doing here.
-</para>
-</warning>
 
 <para>
 The drivers read their own options from the config file.
 For this purpose they use the config sections that are named like the driver.
 </para>
 
-<para>
-<command>LCDd -d driver</command>
-</para>
-
-<note>
-<para>
-If <option>-d</option> is specified on the command line, the
-<code>Driver=</code> options in the configuration file are ignored.
-</para>
-</note>
-
 <sect2 id="server-section">
 <title id="server-section.title"><filename>LCDd.conf</filename>: The <code>[Server]</code> Section</title>
 
@@ -100,7 +141,7 @@ settings for the LCDproc server <application>LCDd</application>.
     If not specified <replaceable>DRIVERPATH</replaceable>
     defaults to the empty string, resulting in drivers being
     searched
-    in the directory LCDd is started in.
+    in the directory <application>LCDd</application> is started in.
   </para></listitem>
 </varlistentry>
 
@@ -109,13 +150,25 @@ settings for the LCDproc server <application>LCDd</application>.
     <command>Driver=</command>
     <arg choice="plain"><replaceable>DRIVERNAME</replaceable></arg>
   </term>
-  <listitem><para>
+  <listitem>
-    Tells the server which driver(s) to use. See
+    <para>
-    <link linkend="which-driver">above</link> for details.
+      Tells the server which driver(s) to use.
+      The first driver specified here that is capable of output functionality
+      will be used as the <emphasis>master</emphasis> output driver, defining
+      display properties and capabilities.
+      All other drivers specified can only serve as input drivers
+      or slave output drivers.
       If not specified <replaceable>DRIVERNAME</replaceable>
       defaults to <literal>curses</literal>, a driver that is supposed
       to work on any half-way decent UNIX console.
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line using the <option>-d <replaceable>DRIVER</replaceable></option> option.
+      When the command line option is used, only the one driver given there
+      will be loaded, and all drivers specified in the configuration file are ignored.
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -123,11 +176,18 @@ settings for the LCDproc server <application>LCDd</application>.
     <command>Bind=</command>
     <arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
   </term>
-  <listitem><para>
+  <listitem>
+    <para>
       Tells the server to bind to the given local IP address and listen for incoming client connections.
       The default value for <replaceable>ADDRESS</replaceable> is <literal>127.0.0.1</literal>, which
-    is actually the safest variant.
+      is actually the safest variant, as it allows connections only from the local machine and forbids
-  </para></listitem>
+      connections from remote systems.
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line using the <option>-a <replaceable>ADDRESS</replaceable></option> option.
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -135,10 +195,16 @@ settings for the LCDproc server <application>LCDd</application>.
     <command>Port=</command>
     <arg choice="plain"><replaceable>PORTNUMBER</replaceable></arg>
   </term>
-  <listitem><para>
+  <listitem>
+    <para>
       Tells the server to listen to this specified port.
       If not specified <replaceable>PORTNUMBER</replaceable> defaults to <literal>13666</literal>.
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line using the <option>-p <replaceable>PORTNUMBER</replaceable></option> option.
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -146,12 +212,18 @@ settings for the LCDproc server <application>LCDd</application>.
     <command>ReportLevel=</command>
     <arg choice="plain"><replaceable>LEVEL</replaceable></arg>
   </term>
-  <listitem><para>
+  <listitem>
+    <para>
       Sets the reporting level.
       Legal values for <replaceable>LEVEL</replaceable> range from <literal>0</literal>
       (only critical errors) to <literal>5</literal> (everything including debugging information).
       If not specified it defaults to <literal>2</literal> (warnings and errors only).
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line using the <option>-r <replaceable>LEVEL</replaceable></option> option.
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -164,10 +236,27 @@ settings for the LCDproc server <application>LCDd</application>.
     </group>
     </arg>
   </term>
-  <listitem><para>
+  <listitem>
-    Should we report to <filename>syslog</filename> instead of <filename>stderr</filename>?
+    <para>
+      Should we report to <filename>syslog</filename> (<literal>yes</literal>)
+      instead of <filename>stderr</filename> (<literal>no</literal>)?
       Default value is <literal>no</literal>.
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line using the <option>-s <replaceable>NUMBER</replaceable></option> option.
+      Passing <option>-s 1</option> on the command line enables reporting to <filename>syslog</filename>
+      while <option>-s 0</option> disables it.
+    </para>
+    <warning>
+      <para>
+        If <application>LCDd</application> is started automatically by an init script
+        using the <literal>curses</literal> driver, it will lock <filename>/dev/tty1</filename>!
+        So, be careful about what you are doing here.
+      </para>
+    </warning>
+
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -177,18 +266,13 @@ settings for the LCDproc server <application>LCDd</application>.
   </term>
   <listitem>
     <para>
-    User to run as. When started as root LCDd will drop its privileges,
+    User to run as. When started as root <application>LCDd</application> will drop its privileges,
-    and run as this user instead. Defaults to <literal>nobody</literal>.
+    and run as <replaceable>USER</replaceable> instead. Defaults to <literal>nobody</literal>.
     </para>
-    <!--
-    <note>
     <para>
-      If you want to use the server menu, to shutdown or reboot your system,
+      This setting can be overridden on <application>LCDd</application>'s
-       you will have to set this to root. Otherwise LCDd does not have the
+      command line using the <option>-u <replaceable>USER</replaceable></option> option.
-       privileges to run commands like <command>init 6</command>.
     </para>
-    </note>
-    -->
   </listitem>
 </varlistentry>
 
@@ -202,11 +286,17 @@ settings for the LCDproc server <application>LCDd</application>.
     </group>
     </arg>
   </term>
-  <listitem><para>
+  <listitem>
+    <para>
       The server will stay in the foreground if set to true.
       Otherwise the server will fork to background and report
       to syslog. Defaults to <literal>no</literal>.
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line with the <option>-f</option> option that forces foreground mode. 
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -217,7 +307,7 @@ settings for the LCDproc server <application>LCDd</application>.
   <listitem>
     <para>
       Define the startup message printed on the screen when LCDd starts.
-      This message will stay on the screen until a client connects.
+      This message will stay on the screen until the first client connects.
       If not given, it defaults to the builtin server screen that tells
       how many clients are connected and how many screens these clients
       are using in total.
@@ -279,10 +369,16 @@ settings for the LCDproc server <application>LCDd</application>.
     <command>WaitTime=</command>
     <arg choice="plain"><replaceable>SECONDS</replaceable></arg>
   </term>
-  <listitem><para>
+  <listitem>
+    <para>
       Sets the default time in seconds to display a screen.
       If not specified the default value for <replaceable>SECONDS</replaceable> is <literal>4</literal>.
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line with the <option>-w <replaceable>SECONDS</replaceable></option> option.
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>
@@ -295,11 +391,19 @@ settings for the LCDproc server <application>LCDd</application>.
     </group>
     </arg>
   </term>
-  <listitem><para>
+  <listitem>
+    <para>
       Include the server screen, that shows the number of active clients and screens,
       into the screen rotation scheme when other screens exist.
       Defaults to <literal>yes</literal>.
-  </para></listitem>
+    </para>
+    <para>
+      This setting can be overridden on <application>LCDd</application>'s
+      command line using the <option>-i <replaceable>NUMBER</replaceable></option> option.
+      Passing <option>-i 1</option> on the command line enables server screen rotation,
+      while <option>-i 0</option> disables it.
+    </para>
+  </listitem>
 </varlistentry>
 
 <varlistentry>