RE: DOCBOOK: Code markup.

["Dave Pawson" <dave.pawson@virgin.net>]

Norm wrote:
     Without more context, I have to admit I'm a little confused. For the
     functiony parts, I'd say:

     <funcdef>Bool <function>xf86GetFlipPixels</function></funcdef>

     But from the description of -flippixels, I think it should be a simple
     parameter or option, not a funcparam since it's not a parameter to a
     function.

The context is a series of instructions to users building the xfree
software.
Its a case of 'call this function with these parameters, or
set the configuration file X item Y to this value.

Yes, it could be left as plain text, but the authors have chosen to identify
almost each and every item which is not plain text. Some need to be in-line
to make the para 'flow' others can be seen as code extracts.

I've included a couple more examples below.
It appears to almost flow as text, but is actually code/data.

Is that clearer?

Regards, DaveP

 <p>    <tt>CARD8 readAttr(vgaHWPtr hwp, CARD8 index)</tt></p>

  <p>      Return the value read from Attribute Controller register
      <tt>index</tt>.  When writing out the index value this
      function should set bit 5 (<tt>0x20</tt>) according to the
      setting of <tt>hwp-&gt;paletteEnabled</tt> in order to
      preserve the palette access state.  It should be cleared when
      <tt>hwp-&gt;paletteEnabled</tt> is <tt>TRUE</tt>
      and set when it is <tt>FALSE</tt>.</p>

<sect1>
  <heading>Include files</heading>
<p>
  All drivers normally include the following headers:</p>

  <p>    <tt>"xf86.h"
    "xf86_OSproc.h"
    "xf86_ansic.h"
    "xf86Resources.h"</tt></p>

  <p>  Wherever inb/outb (and related things) are used the following should
be
  included:</p>

  <p>    <tt>"compiler.h"</tt></p>

  <p>  Note: in drivers, this must be included after
<tt>"xf86_ansic.h"</tt>.</p>

  <p>  Drivers that need to access PCI vendor/device definitions need
this:</p>

  <p>    <tt>"xf86PciInfo.h"</tt></p>

  <p>  Drivers that need to access the PCI config space need this:</p>

  <p>    <tt>"xf86Pci.h"</tt></p>

  <p>  Drivers using the mi banking wrapper need:</p>

  <p>    <tt>"mibank.h"</tt></p>

  <p>  Drivers that initialise a SW cursor need this:</p>

  <p>    <tt>"mipointer.h"</tt></p>

  <p>  All drivers implementing backing store need this:</p>

  <p>    <tt>"mibstore.h"</tt></p>

  <p>  All drivers using the mi colourmap code need this:</p>

  <p>    <tt>"micmap.h"</tt></p>

  <p>  If a driver uses the vgahw module, it needs this:</p>

  <p>    <tt>"vgaHW.h"</tt></p>

  <p>  Drivers supporting VGA or Hercules monochrome screens need:</p>

  <p>    <tt>"xf1bpp.h"</tt></p>

  <p>  Drivers supporting VGA or EGC 16-colour screens need:</p>

  <p>    <tt>"xf4bpp.h"</tt></p>

  <p>  Drivers using cfb need:</p>

  <p>    <tt>#define PSZ 8
    #include "cfb.h"
    #undef PSZ</tt></p>

  <p>  Drivers supporting bpp 16, 24 or 32 with cfb need one or more of:</p>

  <p>    <tt>"cfb16.h"
    "cfb24.h"
    "cfb32.h"</tt></p>

  <p>  The driver's own header file:</p>

  <p>    <tt>"zzz.h"</tt></p>

  <p>  Drivers must NOT include the following:</p>

  <p>    <tt>"xf86Priv.h"
    "xf86Privstr.h"
    "xf86_libc.h"
    "xf86_OSlib.h"
    "Xos.h"</tt>
    any OS header
 </p>

 </sect1>