Index: brlcad/doc/docbook/system/man3/en/libfb.xml
===================================================================
--- brlcad/doc/docbook/system/man3/en/libfb.xml	(revision 53848)
+++ brlcad/doc/docbook/system/man3/en/libfb.xml	(working copy)
@@ -1,496 +1,470 @@
+<?xml version="1.0"?>
 <!-- Converted by db4-upgrade version 1.0 -->
-
 <refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="libfb">
-
-<refmeta>
-  <refentrytitle>libfb - FrameBuffer Library</refentrytitle>
-  <manvolnum>3</manvolnum>
-  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
-  <refmiscinfo class="manual">BRL-CAD Libraries</refmiscinfo>
-</refmeta>
-
-<refnamediv xml:id="name">
-  <refname>libfb</refname>
-  <refpurpose>
-    multiple device, generic frame buffer library
-  </refpurpose>
-</refnamediv>
-
-<!-- body begins here -->
-
-<refsection xml:id="libfbgeneric"><info><title>Generic frame buffer routines</title></info>
-
-  <funcprototype>
-    <funcdef><function>FBIO</function> *fb_open</funcdef>
-    <paramdef>* <parameter>fbfile</parameter></paramdef>
-    <paramdef>int fb_close ( fbp ) FBIO * <parameter>fbp</parameter></paramdef>
-    <paramdef>int fb_read ( fbp , x , y , addr , count ) FBIO * <parameter>fbp</parameter></paramdef>
-  </funcprototype>
-  <funcsynopsisinfo>
-    RGBpixel *addr;
-    long count;
-
-  </funcsynopsisinfo>
-  <funcprototype>
-    <funcdef>int <function>fb_write</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>RGBpixel * <parameter>addr</parameter></paramdef>
-    <paramdef>long <parameter>count</parameter></paramdef>
-    <paramdef>int fb_rmap ( fbp , cmap ) FBIO * <parameter>fbp</parameter></paramdef>
-    <paramdef>ColorMap * <parameter>cmap</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_wmap</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>ColorMap * <parameter>cmap</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_clear</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>RGBpixel * <parameter>colorp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>char *<function>fb_gettype</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_getwidth</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_getheight</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-  </funcprototype>
-</refsection>
-
-<refsection xml:id="libfbhardware"><info><title>Hardware specific frame buffer routines</title></info>
-
-  <funcprototype>
-    <funcdef>int <function>fb_cursor</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>int fb_scursor ( fbp , mode , x , y ) FBIO * <parameter>fbp</parameter></paramdef>
-    <paramdef>int fb_setcursor ( fbp , bits , xbits , ybits , xorig , yorig ) FBIO * <parameter>fbp</parameter></paramdef>
-    <paramdef>unsigned char <parameter>bits</parameter>[]</paramdef>
-  </funcprototype>
-  <funcsynopsisinfo>
-    int xbits, ybits;
-    int xorig, yorig;
-
-  </funcsynopsisinfo>
-  <funcprototype>
-    <funcdef>int <function>fb_window</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>int fb_zoom ( fbp , x , y ) FBIO * <parameter>fbp</parameter></paramdef>
-    <paramdef>/ *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) FBIO * <parameter>fbp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_seek</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>void fb_tell ( fbp , xp , yp ) FBIO * <parameter>fbp</parameter></paramdef>
-    <paramdef>int *xp , * <parameter>yp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_rpixel</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>RGBpixel * <parameter>pixelp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_wpixel</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-    <paramdef>RGBpixel * <parameter>pixelp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>int <function>fb_flush</function></funcdef>
-    <paramdef>* <parameter>fbp</parameter></paramdef>
-  </funcprototype>
-
-  <funcprototype>
-    <funcdef>void <function>fb_log</function></funcdef>
-    <paramdef>format [ <parameter/></paramdef>
-    <paramdef>arg ] ... <parameter/></paramdef>
-  </funcprototype>
-</refsection>
-
-<refsection xml:id="description"><info><title>DESCRIPTION</title></info>
-
-  <para>
-    These routines are designed to provide a device-independent
-    method of using frame buffers or files containing frame buffer
-    images. The coordinate system used is first-quadrant (0..width-1,
-    0..height-1), with integer addressing.  Translation to hardware
-  coordinate systems is handled by the library.
-  </para>
-
-  <para>
-    This version of the library assumes that red, green, and blue
-    intensities are described by unsigned 8-bit bytes in the range (0..255).
-    The library interface uses arrays of <emphasis remap="B">RGBpixel</emphasis>s,
-    which is a typedef for an array of three unsigned chars (this was
-    done to avoid structure padding).  Note that a pointer to an
-    <emphasis remap="B">RGBpixel</emphasis>
-    is thus the name of the <emphasis remap="B">RGBpixel</emphasis>
-    itself, i.e. no ampersand is needed.
-  </para>
-
-  <para>
-    The exact interpretation of color maps tends to be somewhat device
-    specific. The three ColorMap arrays each have 256 entries of unsigned
-    16-bit values. In order to accommodate color maps with differing amounts
-    of output resolution, the color map entries are fixed-point fractions
-    in the range (0.0..1.0).  In integer notation, the range is (0..65525).
-    For devices with less than 16 bits of output from their color maps,
-    the left-most portion of each entry is used.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_open</emphasis> is used to open a frame buffer
-    file <emphasis remap="I">fbfile</emphasis>. The file may be either the
-    name of a supported frame buffer interface, referenced as "/dev/interface",
-    or the name of a UNIX file. The routine will try to determine if the
-    file opened was a real frame buffer by examining the name, and if so
-    will perform whatever initialization actions are necessary.
-    If the value of <emphasis remap="I">fbfile</emphasis> is
-    <!-- B elided -->
-    <acronym>NULL</acronym> and the environment variable
-    <!-- B elided -->
-    <envar>FB_FILE</envar> is set, then the value of <envar>FB_FILE</envar>
-    is used; otherwise the default frame buffer device for the system is used.
-    See below for more details. The <emphasis remap="I">width</emphasis>
-    and <emphasis remap="I">height</emphasis> parameters specify the initial
-    size of display desired. If these are zero the default sizes for that
-    device will be used. On a successful open, the frame buffer I/O (FBIO)
-    structure pointer is returned. This structure contains size you were
-    actually given, as well as the maximum possible size for the selected
-    device. A return of FBIO_NULL indicates failure.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_close</emphasis> simply closes the frame buffer.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_read</emphasis> reads
-    <emphasis remap="I">count</emphasis> pixels from the frame buffer
-    starting at the location specified by <emphasis remap="I">x</emphasis>
-    and <emphasis remap="I">y</emphasis>, and places them at program
-    memory address specified by <emphasis remap="I">addr</emphasis>.
-    <emphasis remap="I">Fb_read</emphasis> returns the number of
-    pixels actually read, or -1 on error.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_write</emphasis> writes
-    <emphasis remap="I">count</emphasis> pixels from program address
-    <emphasis remap="I">addr</emphasis> into the frame buffer starting
-    at the location specified by <emphasis remap="I">x</emphasis>
-    and <emphasis remap="I">y</emphasis>. <emphasis remap="I">Fb_write</emphasis>
-    returns the number of pixels actually written, or -1 on error.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_rmap</emphasis>
-    reads in the color map from the frame buffer and
-    leaves at the location pointed to by
-    <emphasis remap="I">cmap</emphasis>.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_wmap</emphasis>
-    writes the color map pointed to by
-    <emphasis remap="I">cmap</emphasis>
-    into the frame buffer.  If the value of
-    <emphasis remap="I">cmap</emphasis>
-    is
-    <!-- B elided -->
-    <acronym>NULL</acronym>
-    then a linear color map is used as the default.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_clear</emphasis>
-    erases the frame buffer by setting all pixels to the given
-    color. If the color pointer is NULL, black will be used.
-    On a UNIX file, this entails writing the entire file,
-    which is an expensive operation, whereas on most
-    frame buffer displays
-    this can be done in less than a second by a special command.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_gettype</emphasis>
-    returns a pointer to a string describing the frame buffer
-    specified by the FBIO pointer.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_getwidth</emphasis>
-    and <emphasis remap="I">Fb_getheight</emphasis>
-    returns the current size of the FBIO frame buffer.
-  </para>
-
-  <para>
-    The following routines work in conjunction with those described above
-    to provide functions which only apply if the frame buffer
-    file is actually a hardware frame buffer display.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_cursor</emphasis>
-    places the cursor at the image space coordinates given by
-    <emphasis remap="I">x</emphasis>
-    and
-    <emphasis remap="I">y</emphasis>.
-    If the mode is non-zero, the cursor is made visible, and
-    if mode is zero, the cursor is turned off.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_scursor</emphasis>
-    is the same as
-    <emphasis remap="I">fb_cursor</emphasis>
-    except that it
-    places the cursor at the
-    <emphasis remap="B">screen</emphasis>
-    space coordinates given by
-    <emphasis remap="I">x</emphasis>
-    and
-    <emphasis remap="I">y</emphasis>.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_setcursor</emphasis>
-    allows the user to set the bitmap used to represent the cursor,
-    thereby changing the cursor shape. This is not necessarily supported
-    by all hardware. The argument <emphasis remap="I">bits</emphasis>
-    is a pointer to an array of unsigned chars containing the bits of the cursor.
-    The arguments <emphasis remap="I">xbits</emphasis>
-    and <emphasis remap="I">ybits</emphasis>
-    specify the size of the cursor bitmap.  The number of bytes in the
-    <varname role="parameter">bits</varname> array will be the width rounded
-    up to a multiple of eight (so that the cursor "scanlines" are byte aligned)
-    times the height.
-    <varname role="parameter">bits</varname>[0]
-    is the lower left corner,
-    <varname role="parameter">bits</varname>[1]
-    is to the right of it, etc.  The next line of the
-    <varname role="parameter">bits</varname>
-    array goes above the current one.  Within a byte the most significant
-    bit is the leftmost.  The values
-    <emphasis remap="I">xorig</emphasis>
-    and <emphasis remap="I">yorig</emphasis>
-    specify which bit in the bitmap actually gets placed at the location
-    specified in the cursor move routines.  Again, a first quadrant coordinate
-    system is used.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_window</emphasis>
-    sets the frame buffer window center position to the image space coordinates
-    given by <emphasis remap="I">x</emphasis> and <emphasis remap="I">y</emphasis>.
-    This command is usually used in conjunction with the
-    <emphasis remap="I">fb_zoom</emphasis> routine.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_zoom</emphasis>
-    sets the zoom factor for the X coordinate to
-    <emphasis remap="I">x</emphasis>
-    and the zoom factor for the Y coordinate to
-    <emphasis remap="I">y</emphasis>.
-    Zooming is generally done by pixel replication in hardware.
-  </para>
-
-  <para>
-    The following routines work in conjunction with those described above
-    to provide buffered reading and writing of frame buffer images
-    either to a real frame buffer or a UNIX file.
-    The routines use a simple paging strategy to hold “bands” of
-    the image in core. Since horizontal bands are buffered, the
-    ideal motion is to scan left to right, then bottom to top.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_ioinit</emphasis>
-    should be called before using any of the other buffered I/O routines and
-    repeated whenever the frame buffer is reopened.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_seek</emphasis>
-    is used to position the current read/write pointer to
-    the location to the next position to be read or written.
-    It is not necessary to do a <emphasis remap="I">fb_seek</emphasis>
-    after every read or write since both <emphasis remap="I">fb_rpixel</emphasis>
-    and <emphasis remap="I">fb_wpixel</emphasis> imply an automatic move to
-    the next pixel. If you read or write the last pixel on a scan line,
-    the pointer will automatically move to the beginning
-    of the following scan line.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_tell</emphasis>
-    returns the current location of the read write pointer
-    in terms of (X,Y) coordinates on the frame buffer.
-    The X and Y values are returned into the integers pointed to
-    by <emphasis remap="I">xp</emphasis> and <emphasis remap="I">yp</emphasis>.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_rpixel</emphasis>
-    reads the pixel at the current frame buffer location
-    and returns it into the location specified
-    by <emphasis remap="I">pixelp</emphasis>.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_wpixel</emphasis>
-    writes the pixel pointed to by <emphasis remap="I">pixelp</emphasis>
-    at the current frame buffer location.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_flush</emphasis>
-    caused any current buffered frame buffer pages to be written out.
-    Unnecessary writes are avoided by the use of page reference bits.
-  </para>
-
-  <para>
-    The following is a printing routine which this library uses to
-    indicate errors.
-  </para>
-
-  <para>
-    <emphasis remap="I">Fb_log</emphasis> will convert, format and print its
-    <emphasis remap="I">args</emphasis> under control of
-    <emphasis remap="I">format</emphasis> to the standard error output.
-    For more detailed information on the specification of the control string,
-    see <citerefentry><refentrytitle>printf</refentrytitle>
-    <manvolnum>3S</manvolnum></citerefentry>.
-    This function may be supplied by the application if different behavior
-    is desired.
-  </para>
-</refsection>
-
-<refsection xml:id="fb_file_devices"><info><title>FB_FILE DEVICES</title></info>
-
-  <para>
-    The following devices are supported by the library; not all may
-    be available on any given system.  New device support can be
-  incorporated by the addition of a single module to the library.
-  </para>
-  <variablelist remap="TP">
-    <varlistentry>
-      <term><filename>/dev/debug</filename><emphasis remap="I">[num]</emphasis></term>
-      <listitem>
-	<para>The "/dev/debug" interface prints one line to logs each call
-	to the frame buffer library.
-	<!-- .br -->
-	<emphasis remap="I">num</emphasis>
-	is a bitvector indicating the levels of verbosity of the output.  See
-	<emphasis remap="B">fb.h</emphasis>
-	for the bit definitions.</para>
-      </listitem>
-    </varlistentry>
-    <varlistentry>
-      <term><emphasis remap="I">filename</emphasis></term>
-      <listitem>
-	<para>Disk file interface</para>
-      </listitem>
-    </varlistentry>
-    <varlistentry>
-      <term><emphasis remap="B">hostname:</emphasis><emphasis remap="I">[devicename]</emphasis></term>
-      <listitem>
-	<para>TCP-based network links to a remote framebuffer, where
-	<emphasis remap="I">devicename</emphasis>
-	is any from this list, for example,
-	fictitious.brlcad.org:/dev/ik0 or fictitious.brlcad.org:/dev/sgi.
-	A <emphasis remap="B">hostname</emphasis>
-	with a null<emphasis remap="I">devicename</emphasis>
-	will select the default display device on that host.
-	If explicitly specifying a remote device,
-	be careful not to omit the colon between the host and device name,
-	or you will be specifying a local disk file as the result.
-	Note that for security reasons, it is not permitted to access a
-	disk file via the remote interface.</para>
-      </listitem>
-    </varlistentry>
-  </variablelist>
-</refsection>
-
-<refsection xml:id="examples"><info><title>EXAMPLES</title></info>
-
-  <para>
-    <emphasis remap="I">Libfb</emphasis>
-    can be loaded with any C program:
-  </para>
-
-  <literallayout remap="RS" class="normal">
-<synopsis format="linespecific">
-$  <filename>/bin/cc  program.c  -lfb -l\&lt;system-library...\&gt;</filename>
-</synopsis>
-  </literallayout> <!-- remap='RE' -->
-
-  <para>
-    where <emphasis remap="I">&lt;system-library&gt;</emphasis>
-    denotes specific libraries necessary on a particular machine.  All machines
-    with networking will require the "-lpkg" option.  Machines which support the
-    X Windows(tm) system will require the "-lX11" option.
-  </para>
-</refsection>
-
-<refsection xml:id="return_values"><info><title>RETURN VALUES</title></info>
-
-  <para>
-    <emphasis remap="I">fb_close</emphasis>,
-    <emphasis remap="I">fb_write</emphasis>,
-    <emphasis remap="I">fb_read</emphasis>,
-    <emphasis remap="I">fb_wmap</emphasis>,
-    <emphasis remap="I">fb_rmap</emphasis>,
-    <emphasis remap="I">fb_clear</emphasis>,
-    <emphasis remap="I">fb_cursor</emphasis>,
-    <emphasis remap="I">fb_scursor</emphasis>,
-    <emphasis remap="I">fb_setcursor</emphasis>,
-    <emphasis remap="I">fb_window</emphasis>,
-    <emphasis remap="I">fb_zoom</emphasis>,
-    <emphasis remap="I">fb_ioinit</emphasis>,
-    <emphasis remap="I">fb_seek</emphasis>,
-    <emphasis remap="I">fb_wpixel</emphasis>,
-    <emphasis remap="I">fb_rpixel</emphasis>
-    and
-    <emphasis remap="I">fb_flush</emphasis>
-    return -1 to indicate failure.
-    <emphasis remap="I">Fb_open</emphasis>
-    returns FBIO_NULL to indicate failure, and a non-null FBIO structure pointer
-    upon success.
-    <emphasis remap="I">fb_read</emphasis>,
-    and
-    <emphasis remap="I">fb_write</emphasis>
-    return the number of pixels actually read or written.
-    <emphasis remap="I">fb_gettype</emphasis>
-    returns a pointer to a NULL terminated description string.
-  </para>
-</refsection>
-
-<refsection xml:id="see_also"><info><title>SEE ALSO</title></info>
-<para><citerefentry><refentrytitle>fbhelp</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>brlcad</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
-</refsection>
-
-<info><corpauthor>BRL-CAD Team</corpauthor></info>
-
-<refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
-
-  <para>
-    Reports of bugs or problems should be submitted via electronic
-    mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.
-  </para>
-</refsection>
+	<refmeta>
+		<refentrytitle>libfb - FrameBuffer Library</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo class="source">BRL-CAD</refmiscinfo>
+		<refmiscinfo class="manual">BRL-CAD Libraries</refmiscinfo>
+	</refmeta>
+	<refnamediv xml:id="name">
+		<refname>libfb</refname>
+		<refpurpose>
+			multiple device, generic frame buffer library
+		</refpurpose>
+	</refnamediv>
+	<!-- body begins here -->
+	<refsection xml:id="libfbgeneric">
+		<info>
+			<title>Generic frame buffer routines</title>
+		</info>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef><function>FBIO</function> *fb_open</funcdef>
+				<paramdef>* <parameter>fbfile</parameter></paramdef>
+				<paramdef>int fb_close ( fbp ) FBIO * <parameter>fbp</parameter></paramdef>
+				<paramdef>int fb_read ( fbp , x , y , addr , count ) FBIO * <parameter>fbp</parameter></paramdef>
+				<paramdef>RGBpixel <parameter>*addr;</parameter></paramdef>
+				<paramdef>long <parameter>count;</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef>int <function>fb_write</function></funcdef>
+				<paramdef>* <parameter>fbp</parameter></paramdef>
+				<paramdef>RGBpixel * <parameter>addr</parameter></paramdef>
+				<paramdef>long <parameter>count</parameter></paramdef>
+				<paramdef>int fb_rmap ( fbp , cmap ) FBIO * <parameter>fbp</parameter></paramdef>
+				<paramdef>ColorMap * <parameter>cmap</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef>int <function>fb_wmap</function></funcdef>
+				<paramdef>* <parameter>fbp</parameter></paramdef>
+				<paramdef>ColorMap * <parameter>cmap</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef>int <function>fb_clear</function></funcdef>
+				<paramdef>* <parameter>fbp</parameter></paramdef>
+				<paramdef>RGBpixel * <parameter>colorp</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef>char *<function>fb_gettype</function></funcdef>
+				<paramdef>* <parameter>fbp</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef>int <function>fb_getwidth</function></funcdef>
+				<paramdef>* <parameter>fbp</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+		<funcsynopsis>
+			<funcprototype>
+				<funcdef>int <function>fb_getheight</function></funcdef>
+				<paramdef>* <parameter>fbp</parameter></paramdef>
+			</funcprototype>
+		</funcsynopsis>
+	</refsection>
+	<refsection xml:id="libfbhardware">
+		<info>
+			<title>Hardware specific frame buffer routines</title>
+		</info>
+        <funcsynopsis>
+		<funcprototype>
+			<funcdef>int <function>fb_cursor</function></funcdef>
+			<paramdef>* <parameter>fbp</parameter></paramdef>
+			<paramdef>int fb_scursor ( fbp , mode , x , y ) FBIO * <parameter>fbp</parameter></paramdef>
+			<paramdef>int fb_setcursor ( fbp , bits , xbits , ybits , xorig , yorig ) FBIO * <parameter>fbp</parameter></paramdef>
+			<paramdef>unsigned char <parameter>bits</parameter>[]</paramdef>
+            <paramdef>int <parameter>xbits</parameter>, <parameter>ybits</parameter>;</paramdef>
+            <paramdef>int <parameter>xorig</parameter>, <parameter>yorig</parameter>;</paramdef>
+		</funcprototype>
+    </funcsynopsis>
+    <funcsynopsis>
+		<funcprototype>
+			<funcdef>int <function>fb_window</function></funcdef>
+			<paramdef>* <parameter>fbp</parameter></paramdef>
+			<paramdef>int fb_zoom ( fbp , x , y ) FBIO * <parameter>fbp</parameter></paramdef>
+			<paramdef>/ *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) FBIO * <parameter>fbp</parameter></paramdef>
+		</funcprototype>
+    </funcsynopsis>
+    <funcsynopsis>
+		<funcprototype>
+			<funcdef>int <function>fb_seek</function></funcdef>
+			<paramdef>* <parameter>fbp</parameter></paramdef>
+			<paramdef>void fb_tell ( fbp , xp , yp ) FBIO * <parameter>fbp</parameter></paramdef>
+			<paramdef>int *xp , * <parameter>yp</parameter></paramdef>
+		</funcprototype>
+    </funcsynopsis>
+    <funcsynopsis>
+		<funcprototype>
+			<funcdef>int <function>fb_rpixel</function></funcdef>
+			<paramdef>* <parameter>fbp</parameter></paramdef>
+			<paramdef>RGBpixel * <parameter>pixelp</parameter></paramdef>
+		</funcprototype>
+    </funcsynopsis>
+    <funcsynopsis>
+		<funcprototype>
+			<funcdef>int <function>fb_wpixel</function></funcdef>
+			<paramdef>* <parameter>fbp</parameter></paramdef>
+			<paramdef>RGBpixel * <parameter>pixelp</parameter></paramdef>
+		</funcprototype>
+    </funcsynopsis>
+    <funcsynopsis>
+		<funcprototype>
+			<funcdef>int <function>fb_flush</function></funcdef>
+			<paramdef>* <parameter>fbp</parameter></paramdef>
+		</funcprototype>
+    </funcsynopsis>
+    <funcsynopsis>
+		<funcprototype>
+			<funcdef>void <function>fb_log</function></funcdef>
+			<paramdef>format [ <parameter/></paramdef>
+			<paramdef>arg ] ... <parameter/></paramdef>
+		</funcprototype>
+    </funcsynopsis>
+	</refsection>
+	<refsection xml:id="description">
+		<info>
+			<title>DESCRIPTION</title>
+		</info>
+		<para>
+			These routines are designed to provide a device-independent
+			method of using frame buffers or files containing frame buffer
+			images. The coordinate system used is first-quadrant (0..width-1,
+			0..height-1), with integer addressing.  Translation to hardware
+			coordinate systems is handled by the library.
+		</para>
+		<para>
+			This version of the library assumes that red, green, and blue
+			intensities are described by unsigned 8-bit bytes in the range (0..255).
+			The library interface uses arrays of <emphasis remap="B">RGBpixel</emphasis>s,
+			which is a typedef for an array of three unsigned chars (this was
+			done to avoid structure padding).  Note that a pointer to an
+			<emphasis remap="B">RGBpixel</emphasis>
+			is thus the name of the <emphasis remap="B">RGBpixel</emphasis>
+			itself, i.e. no ampersand is needed.
+		</para>
+		<para>
+			The exact interpretation of color maps tends to be somewhat device
+			specific. The three ColorMap arrays each have 256 entries of unsigned
+			16-bit values. In order to accommodate color maps with differing amounts
+			of output resolution, the color map entries are fixed-point fractions
+			in the range (0.0..1.0).  In integer notation, the range is (0..65525).
+			For devices with less than 16 bits of output from their color maps,
+			the left-most portion of each entry is used.
+		</para>
+		<para><emphasis remap="I">Fb_open</emphasis> is used to open a frame buffer
+			file <emphasis remap="I">fbfile</emphasis>. The file may be either the
+			name of a supported frame buffer interface, referenced as "/dev/interface",
+			or the name of a UNIX file. The routine will try to determine if the
+			file opened was a real frame buffer by examining the name, and if so
+			will perform whatever initialization actions are necessary.
+			If the value of <emphasis remap="I">fbfile</emphasis> is
+			<!-- B elided -->
+			<acronym>NULL</acronym> and the environment variable
+			<!-- B elided -->
+			<envar>FB_FILE</envar> is set, then the value of <envar>FB_FILE</envar>
+			is used; otherwise the default frame buffer device for the system is used.
+			See below for more details. The <emphasis remap="I">width</emphasis>
+			and <emphasis remap="I">height</emphasis> parameters specify the initial
+			size of display desired. If these are zero the default sizes for that
+			device will be used. On a successful open, the frame buffer I/O (FBIO)
+			structure pointer is returned. This structure contains size you were
+			actually given, as well as the maximum possible size for the selected
+			device. A return of FBIO_NULL indicates failure.
+		</para>
+		<para><emphasis remap="I">Fb_close</emphasis> simply closes the frame buffer.
+		</para>
+		<para><emphasis remap="I">Fb_read</emphasis> reads
+			<emphasis remap="I">count</emphasis> pixels from the frame buffer
+			starting at the location specified by <emphasis remap="I">x</emphasis>
+			and <emphasis remap="I">y</emphasis>, and places them at program
+			memory address specified by <emphasis remap="I">addr</emphasis>.
+			<emphasis remap="I">Fb_read</emphasis> returns the number of
+			pixels actually read, or -1 on error.
+		</para>
+		<para><emphasis remap="I">Fb_write</emphasis> writes
+			<emphasis remap="I">count</emphasis> pixels from program address
+			<emphasis remap="I">addr</emphasis> into the frame buffer starting
+			at the location specified by <emphasis remap="I">x</emphasis>
+			and <emphasis remap="I">y</emphasis>. <emphasis remap="I">Fb_write</emphasis>
+			returns the number of pixels actually written, or -1 on error.
+		</para>
+		<para><emphasis remap="I">Fb_rmap</emphasis>
+			reads in the color map from the frame buffer and
+			leaves at the location pointed to by
+			<emphasis remap="I">cmap</emphasis>.
+		</para>
+		<para><emphasis remap="I">Fb_wmap</emphasis>
+			writes the color map pointed to by
+			<emphasis remap="I">cmap</emphasis>
+			into the frame buffer.  If the value of
+			<emphasis remap="I">cmap</emphasis>
+			is
+			<!-- B elided -->
+			<acronym>NULL</acronym>
+			then a linear color map is used as the default.
+		</para>
+		<para><emphasis remap="I">Fb_clear</emphasis>
+			erases the frame buffer by setting all pixels to the given
+			color. If the color pointer is NULL, black will be used.
+			On a UNIX file, this entails writing the entire file,
+			which is an expensive operation, whereas on most
+			frame buffer displays
+			this can be done in less than a second by a special command.
+		</para>
+		<para><emphasis remap="I">Fb_gettype</emphasis>
+			returns a pointer to a string describing the frame buffer
+			specified by the FBIO pointer.
+		</para>
+		<para><emphasis remap="I">Fb_getwidth</emphasis>
+			and <emphasis remap="I">Fb_getheight</emphasis>
+			returns the current size of the FBIO frame buffer.
+		</para>
+		<para>
+			The following routines work in conjunction with those described above
+			to provide functions which only apply if the frame buffer
+			file is actually a hardware frame buffer display.
+		</para>
+		<para><emphasis remap="I">Fb_cursor</emphasis>
+			places the cursor at the image space coordinates given by
+			<emphasis remap="I">x</emphasis>
+			and
+			<emphasis remap="I">y</emphasis>.
+			If the mode is non-zero, the cursor is made visible, and
+			if mode is zero, the cursor is turned off.
+		</para>
+		<para><emphasis remap="I">Fb_scursor</emphasis>
+			is the same as
+			<emphasis remap="I">fb_cursor</emphasis>
+			except that it
+			places the cursor at the
+			<emphasis remap="B">screen</emphasis>
+			space coordinates given by
+			<emphasis remap="I">x</emphasis>
+			and
+			<emphasis remap="I">y</emphasis>.
+		</para>
+		<para><emphasis remap="I">Fb_setcursor</emphasis>
+			allows the user to set the bitmap used to represent the cursor,
+			thereby changing the cursor shape. This is not necessarily supported
+			by all hardware. The argument <emphasis remap="I">bits</emphasis>
+			is a pointer to an array of unsigned chars containing the bits of the cursor.
+			The arguments <emphasis remap="I">xbits</emphasis>
+			and <emphasis remap="I">ybits</emphasis>
+			specify the size of the cursor bitmap.  The number of bytes in the
+			<varname role="parameter">bits</varname> array will be the width rounded
+			up to a multiple of eight (so that the cursor "scanlines" are byte aligned)
+			times the height.
+			<varname role="parameter">bits</varname>[0]
+			is the lower left corner,
+			<varname role="parameter">bits</varname>[1]
+			is to the right of it, etc.  The next line of the
+			<varname role="parameter">bits</varname>
+			array goes above the current one.  Within a byte the most significant
+			bit is the leftmost.  The values
+			<emphasis remap="I">xorig</emphasis>
+			and <emphasis remap="I">yorig</emphasis>
+			specify which bit in the bitmap actually gets placed at the location
+			specified in the cursor move routines.  Again, a first quadrant coordinate
+			system is used.
+		</para>
+		<para><emphasis remap="I">Fb_window</emphasis>
+			sets the frame buffer window center position to the image space coordinates
+			given by <emphasis remap="I">x</emphasis> and <emphasis remap="I">y</emphasis>.
+			This command is usually used in conjunction with the
+			<emphasis remap="I">fb_zoom</emphasis> routine.
+		</para>
+		<para><emphasis remap="I">Fb_zoom</emphasis>
+			sets the zoom factor for the X coordinate to
+			<emphasis remap="I">x</emphasis>
+			and the zoom factor for the Y coordinate to
+			<emphasis remap="I">y</emphasis>.
+			Zooming is generally done by pixel replication in hardware.
+		</para>
+		<para>
+			The following routines work in conjunction with those described above
+			to provide buffered reading and writing of frame buffer images
+			either to a real frame buffer or a UNIX file.
+			The routines use a simple paging strategy to hold &#x201C;bands&#x201D; of
+			the image in core. Since horizontal bands are buffered, the
+			ideal motion is to scan left to right, then bottom to top.
+		</para>
+		<para><emphasis remap="I">Fb_ioinit</emphasis>
+			should be called before using any of the other buffered I/O routines and
+			repeated whenever the frame buffer is reopened.
+		</para>
+		<para><emphasis remap="I">Fb_seek</emphasis>
+			is used to position the current read/write pointer to
+			the location to the next position to be read or written.
+			It is not necessary to do a <emphasis remap="I">fb_seek</emphasis>
+			after every read or write since both <emphasis remap="I">fb_rpixel</emphasis>
+			and <emphasis remap="I">fb_wpixel</emphasis> imply an automatic move to
+			the next pixel. If you read or write the last pixel on a scan line,
+			the pointer will automatically move to the beginning
+			of the following scan line.
+		</para>
+		<para><emphasis remap="I">Fb_tell</emphasis>
+			returns the current location of the read write pointer
+			in terms of (X,Y) coordinates on the frame buffer.
+			The X and Y values are returned into the integers pointed to
+			by <emphasis remap="I">xp</emphasis> and <emphasis remap="I">yp</emphasis>.
+		</para>
+		<para><emphasis remap="I">Fb_rpixel</emphasis>
+			reads the pixel at the current frame buffer location
+			and returns it into the location specified
+			by <emphasis remap="I">pixelp</emphasis>.
+		</para>
+		<para><emphasis remap="I">Fb_wpixel</emphasis>
+			writes the pixel pointed to by <emphasis remap="I">pixelp</emphasis>
+			at the current frame buffer location.
+		</para>
+		<para><emphasis remap="I">Fb_flush</emphasis>
+			caused any current buffered frame buffer pages to be written out.
+			Unnecessary writes are avoided by the use of page reference bits.
+		</para>
+		<para>
+			The following is a printing routine which this library uses to
+			indicate errors.
+		</para>
+		<para><emphasis remap="I">Fb_log</emphasis> will convert, format and print its
+			<emphasis remap="I">args</emphasis> under control of
+			<emphasis remap="I">format</emphasis> to the standard error output.
+			For more detailed information on the specification of the control string,
+			see <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3S</manvolnum></citerefentry>.
+			This function may be supplied by the application if different behavior
+			is desired.
+		</para>
+	</refsection>
+	<refsection xml:id="fb_file_devices">
+		<info>
+			<title>FB_FILE DEVICES</title>
+		</info>
+		<para>
+			The following devices are supported by the library; not all may
+			be available on any given system.  New device support can be
+			incorporated by the addition of a single module to the library.
+		</para>
+		<variablelist remap="TP">
+			<varlistentry>
+				<term>
+					<filename>/dev/debug</filename>
+					<emphasis remap="I">[num]</emphasis>
+				</term>
+				<listitem>
+					<para>The "/dev/debug" interface prints one line to logs each call
+						to the frame buffer library.
+						<!-- .br -->
+						<emphasis remap="I">num</emphasis>
+						is a bitvector indicating the levels of verbosity of the output.  See
+						<emphasis remap="B">fb.h</emphasis>
+						for the bit definitions.</para>
+				</listitem>
+			</varlistentry>
+			<varlistentry>
+				<term>
+					<emphasis remap="I">filename</emphasis>
+				</term>
+				<listitem>
+					<para>Disk file interface</para>
+				</listitem>
+			</varlistentry>
+			<varlistentry>
+				<term>
+					<emphasis remap="B">hostname:</emphasis>
+					<emphasis remap="I">[devicename]</emphasis>
+				</term>
+				<listitem>
+					<para>TCP-based network links to a remote framebuffer, where
+						<emphasis remap="I">devicename</emphasis>
+						is any from this list, for example,
+						fictitious.brlcad.org:/dev/ik0 or fictitious.brlcad.org:/dev/sgi.
+						A <emphasis remap="B">hostname</emphasis>
+						with a null<emphasis remap="I">devicename</emphasis>
+						will select the default display device on that host.
+						If explicitly specifying a remote device,
+						be careful not to omit the colon between the host and device name,
+						or you will be specifying a local disk file as the result.
+						Note that for security reasons, it is not permitted to access a
+						disk file via the remote interface.</para>
+				</listitem>
+			</varlistentry>
+		</variablelist>
+	</refsection>
+	<refsection xml:id="examples">
+		<info>
+			<title>EXAMPLES</title>
+		</info>
+		<para><emphasis remap="I">Libfb</emphasis>
+			can be loaded with any C program:
+		</para>
+		<synopsis>
+			$ &#x2009;<filename>/bin/cc &#x2009;program.c &#x2009;-lfb -l\&lt;system-library...\&gt;</filename>
+		</synopsis>
+		<para>
+			where <emphasis remap="I">&lt;system-library&gt;</emphasis>
+			denotes specific libraries necessary on a particular machine.  All machines
+			with networking will require the "-lpkg" option.  Machines which support the
+			X Windows(tm) system will require the "-lX11" option.
+		</para>
+	</refsection>
+	<refsection xml:id="return_values">
+		<info>
+			<title>RETURN VALUES</title>
+		</info>
+		<para><emphasis remap="I">fb_close</emphasis>,
+			<emphasis remap="I">fb_write</emphasis>,
+			<emphasis remap="I">fb_read</emphasis>,
+			<emphasis remap="I">fb_wmap</emphasis>,
+			<emphasis remap="I">fb_rmap</emphasis>,
+			<emphasis remap="I">fb_clear</emphasis>,
+			<emphasis remap="I">fb_cursor</emphasis>,
+			<emphasis remap="I">fb_scursor</emphasis>,
+			<emphasis remap="I">fb_setcursor</emphasis>,
+			<emphasis remap="I">fb_window</emphasis>,
+			<emphasis remap="I">fb_zoom</emphasis>,
+			<emphasis remap="I">fb_ioinit</emphasis>,
+			<emphasis remap="I">fb_seek</emphasis>,
+			<emphasis remap="I">fb_wpixel</emphasis>,
+			<emphasis remap="I">fb_rpixel</emphasis>
+			and
+			<emphasis remap="I">fb_flush</emphasis>
+			return -1 to indicate failure.
+			<emphasis remap="I">Fb_open</emphasis>
+			returns FBIO_NULL to indicate failure, and a non-null FBIO structure pointer
+			upon success.
+			<emphasis remap="I">fb_read</emphasis>,
+			and
+			<emphasis remap="I">fb_write</emphasis>
+			return the number of pixels actually read or written.
+			<emphasis remap="I">fb_gettype</emphasis>
+			returns a pointer to a NULL terminated description string.
+		</para>
+	</refsection>
+	<refsection xml:id="see_also">
+		<info>
+			<title>SEE ALSO</title>
+		</info>
+		<para><citerefentry><refentrytitle>fbhelp</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>brlcad</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+	</refsection>
+	<refsection xml:id="author">
+		<title>AUTHOR</title>
+		<para>BRL-CAD Team</para>
+	</refsection>
+	<refsection xml:id="bug_reports">
+		<info>
+			<title>BUG REPORTS</title>
+		</info>
+		<para>
+			Reports of bugs or problems should be submitted via electronic
+			mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.
+		</para>
+	</refsection>
 </refentry>
