doc/error_funcref.txt: Some DocBook mark-up changes.

diff --git a/doc/error_funcref.txt b/doc/error_funcref.txt
index 58728023b5714b1062d31c5c622c9b93cc918db7..30edb9a12b10a13d92f2596dec3fc42836232e43 100644 (file)
--- a/doc/error_funcref.txt
+++ b/doc/error_funcref.txt
@@ -3,128 +3,143 @@ Function: comedi_errno -- number of last Comedilib error
 Retval: int
 Param: void
 Description:
 Retval: int
 Param: void
 Description:

- When a Comedilib function fails, it usually returns -1 or
- NULL, depending on the return type.  An internal library
- variable stores an error number, which can be retrieved with
- comedi_errno().  This error number can be converted to a
+ When a Comedilib function fails, it usually returns <literal>-1</literal> or
+ <constant>NULL</constant>, depending on the return type.  An internal library
+ variable stores an error number, which can be retrieved by calling
+ <function>comedi_errno</function>  This error number can be converted to a

  human-readable form by the functions
  human-readable form by the functions

- <link linkend="func-ref-comedi-perror"><function>comedi_perror</function></link>
+ <function><link linkend="func-ref-comedi-perror">comedi_perror</link></function>

  and
  and

- <link linkend="func-ref-comedi-strerror"><function>comedi_strerror</function></link>
- .
+ <function><link linkend="func-ref-comedi-strerror">comedi_strerror</link></function>.

 
  These functions are intended to mimic the behavior of the
 
  These functions are intended to mimic the behavior of the

- standard C library functions perror(), strerror(), and errno.
+ standard C library functions <function>perror</function>,
+ <function>strerror</function>, and <varname>errno</varname>.

  In particular, Comedilib functions sometimes return an error
  that is generated inside the C library; the comedi error
  message in this case is the same as the C library.
 
  In particular, Comedilib functions sometimes return an error
  that is generated inside the C library; the comedi error
  message in this case is the same as the C library.
 

- The function comedi_errno() returns an integer describing
- the most recent comedilib error.  This integer may be used
- as the errnum parameter for comedi_strerror().
+ The function <function>comedi_errno</function> returns an integer describing
+ the most recent Comedilib error.  This integer may be used
+ as the <parameter class="function">errnum</parameter> parameter for
+ <function>comedi_strerror</function>.

 
 Function: comedi_loglevel -- change Comedilib logging properties
 Retval: int
 Param: int loglevel
 Description:
  This function affects the output of debugging and error messages
 
 Function: comedi_loglevel -- change Comedilib logging properties
 Retval: int
 Param: int loglevel
 Description:
  This function affects the output of debugging and error messages

- from Comedilib.  By increasing the loglevel, additional debugging
+ from Comedilib.  By increasing the log level <parameter
+ class="function">loglevel</parameter>, additional debugging

  information will be printed.  Error and debugging messages are
  information will be printed.  Error and debugging messages are

- printed to the stream stderr.
+ printed to the standard error output stream <varname>stderr</varname>.

 
  The default loglevel can be set by using the environment variable
 
  The default loglevel can be set by using the environment variable

- COMEDI_LOGLEVEL.  The default loglevel is 1.
+ <envar>COMEDI_LOGLEVEL</envar>.  The default log level is 1.

 
  In order to conserve resources, some debugging information is
  disabled by default when Comedilib is compiled.
 
 
  In order to conserve resources, some debugging information is
  disabled by default when Comedilib is compiled.
 

- The meaning of the loglevels is as follows:
-       <table frame="box" rules="all">
-               <tr>
-                       <th>Loglevel</th>
-                       <th>Behavior</th>
-               </tr>
-               <tr>
-                       <td>0</td>
-                       <td>Comedilib prints nothing.</td>
-               </tr>
-               <tr>
-                       <td>1</td>
-                       <td>
-                               (default) Comedilib prints error messages when
-                               there is a self-consistency error (i.e., an internal bug.)
-                       </td>
-               </tr>
-               <tr>
-                       <td>2</td>
-                       <td>
-                               Comedilib prints an error message when an invalid
-                               parameter is passed.
-                       </td>
-               </tr>
-               <tr>
-                       <td>3</td>
-                       <td>
-                               Comedilib prints an error message whenever an
-                               error is generated in the Comedilib library or in the C library,
-                               when called by Comedilib.
-                       </td>
-               </tr>
-               <tr>
-                       <td>4</td>
-                       <td>Comedilib prints a lot of junk.</td>
-               </tr>
-       </table>
+ The meaning of the log levels is as follows:
+ <informaltable colsep="1" rowsep="1">
+  <tgroup cols="2" align="left">
+   <colspec colwidth="*"/>
+   <colspec colwidth="5*"/>
+   <thead>
+    <row>
+     <entry>Loglevel</entry>
+     <entry>Behavior</entry>
+    </row>
+   </thead>
+   <tbody>
+    <row>
+     <entry>0</entry>
+     <entry>Comedilib prints nothing.</entry>
+    </row>
+    <row>
+     <entry>1</entry>
+     <entry>
+      (default) Comedilib prints error messages when
+      there is a self-consistency error (i.e., an internal bug.)
+     </entry>
+    </row>
+    <row>
+     <entry>2</entry>
+     <entry>
+      Comedilib prints an error message when an invalid
+      parameter is passed.
+     </entry>
+    </row>
+    <row>
+     <entry>3</entry>
+     <entry>
+      Comedilib prints an error message whenever an
+      error is generated in the Comedilib library or in the C library,
+      when called by Comedilib.
+     </entry>
+    </row>
+    <row>
+     <entry>4</entry>
+     <entry>Comedilib prints a lot of junk.</entry>
+    </row>
+   </tbody>
+  </tgroup>
+ </informaltable>

 Returns:
 Returns:

- This function returns the previous loglevel.
+ This function returns the previous log level.

 
 Function: comedi_perror -- print a Comedilib error message
 Retval: void
 Param: const char * s
 Description:
 
 Function: comedi_perror -- print a Comedilib error message
 Retval: void
 Param: const char * s
 Description:

- When a Comedilib function fails, it usually returns -1 or
- NULL, depending on the return type.  An internal library
+ When a Comedilib function fails, it usually returns <literal>-1</literal> or
+ <constant>NULL</constant>, depending on the return type.  An internal library

  variable stores an error number, which can be retrieved with
  variable stores an error number, which can be retrieved with

- <link linkend="func-ref-comedi-errno"><function>comedi_errno</function></link>
- .  This error number can be converted to a
+ <function><link linkend="func-ref-comedi-errno">comedi_errno</link></function>.
+ This error number can be converted to a

  human-readable form by the functions
  human-readable form by the functions

- comedi_perror() or
- <link linkend="func-ref-comedi-strerror"><function>comedi_strerror</function></link>
- .
+ <function>comedi_perror</function> or
+ <function><link linkend="func-ref-comedi-strerror">comedi_strerror</link></function>.

 
  These functions are intended to mimic the behavior of the
 
  These functions are intended to mimic the behavior of the

- standard C library functions perror(), strerror(), and errno.
+ standard C library functions <function>perror</function>,
+ <function>strerror</function>, and <varname>errno</varname>.

  In particular, Comedilib functions sometimes return an error
  that is generated inside the C library; the comedi error
  message in this case is the same as the C library.
 
  In particular, Comedilib functions sometimes return an error
  that is generated inside the C library; the comedi error
  message in this case is the same as the C library.
 

- The function comedi_perror() prints an error message to stderr.
- The error message consists of the argument string, a colon, a
+ The function <function>comedi_perror</function> prints an error message to
+ the standard error output stream <varname>stderr</varname>.
+ The error message consists of the argument string
+ <parameter class="function">s</parameter>, a colon, a

  space, a description of the error condition, and a new line.
 
 Function: comedi_strerror -- return string describing Comedilib error code
 Retval: const char *
 Param: int errnum
 Description:
  space, a description of the error condition, and a new line.
 
 Function: comedi_strerror -- return string describing Comedilib error code
 Retval: const char *
 Param: int errnum
 Description:

- When a Comedilib function fails, it usually returns -1 or
- NULL, depending on the return type.  An internal library
+ When a Comedilib function fails, it usually returns <literal>-1</literal> or
+ <constant>NULL</constant>, depending on the return type.  An internal library

  variable stores an error number, which can be retrieved with
  variable stores an error number, which can be retrieved with

- comedi_errno().  This error number can be converted to a
+ <function><link linkend="func-ref-comedi-errno">comedi_errno</link></function>.
+ This error number can be converted to a

  human-readable form by the functions
  human-readable form by the functions

- <link linkend="func-ref-comedi-perror"><function>comedi_perror</function></link>
- or comedi_strerror().
+ <function><link linkend="func-ref-comedi-perror">comedi_perror</link></function>
+ or <function>comedi_strerror</function>.

 
  These functions are intended to mimic the behavior of the
 
  These functions are intended to mimic the behavior of the

- standard C library functions perror(), strerror(), and errno.
+ standard C library functions <function>perror</function>,
+ <function>strerror</function>, and <varname>errno</varname>.

  In particular, Comedilib functions sometimes return an error
  that is generated inside the C library; the comedi error
  message in this case is the same as the C library.
 
  In particular, Comedilib functions sometimes return an error
  that is generated inside the C library; the comedi error
  message in this case is the same as the C library.
 

- The function comedi_strerror() returns a pointer to a
+ The function <function>comedi_strerror</function> returns a pointer to a

  character string
  character string

- describing the Comedilib error <parameter>errnum</parameter>.
+ describing the Comedilib error <parameter class="function">errnum</parameter>.

  The returned string may be
  The returned string may be

- modified by a subsequent call to a strerr or perror function
- (either the libc or Comedilib versions).
+ modified by a subsequent call to a <function>strerr</function> or
+ <function>perror</function> function
+ (either the <systemitem class="library">libc</systemitem> or Comedilib versions).

  An unrecognized error number will
  An unrecognized error number will

- return a pointer to the string "undefined error", or similar.
+ return a pointer to the string <quote>undefined error</quote>, or similar.