ncurses 6.0 - patch 20170506
[ncurses.git] / doc / html / ncurses-intro.html
index 451e7ab4d32dba74f0b72854dd9f9c9fb495476b..0f4e89972c6f7e0755e4484e5f1d415e2a083112 100644 (file)
@@ -1,8 +1,7 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
 <!--
-  $Id: ncurses-intro.html,v 1.43 2007/03/03 19:31:50 tom Exp $
+  $Id: ncurses-intro.html,v 1.47 2017/05/05 12:03:28 tom Exp $
   ****************************************************************************
-  * Copyright (c) 1998-2006,2007 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2013,2017 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
   * authorization.                                                           *
   ****************************************************************************
 -->
-<HTML>
-<HEAD>
-<TITLE>Writing Programs with NCURSES</TITLE>
-<link rev="made" href="mailto:bugs-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-</HEAD>
-<BODY>
-
-<H1>Writing Programs with NCURSES</H1>
-
-<BLOCKQUOTE>
-by Eric S. Raymond and Zeyd M. Ben-Halim<BR>
-updates since release 1.9.9e by Thomas Dickey
-</BLOCKQUOTE>
-
-<H1>Contents</H1>
-<UL>
-<LI><A HREF="#introduction">Introduction</A>
-<UL>
-<LI><A HREF="#history">A Brief History of Curses</A>
-<LI><A HREF="#scope">Scope of This Document</A>
-<LI><A HREF="#terminology">Terminology</A>
-</UL>
-<LI><A HREF="#curses">The Curses Library</A>
-<UL>
-<LI><A HREF="#overview">An Overview of Curses</A>
-<UL>
-<LI><A HREF="#compiling">Compiling Programs using Curses</A>
-<LI><A HREF="#updating">Updating the Screen</A>
-<LI><A HREF="#stdscr">Standard Windows and Function Naming Conventions</A>
-<LI><A HREF="#variables">Variables</A>
-</UL>
-<LI><A HREF="#using">Using the Library</A>
-<UL>
-<LI><A HREF="#starting">Starting up</A>
-<LI><A HREF="#output">Output</A>
-<LI><A HREF="#input">Input</A>
-<LI><A HREF="#formschars">Using Forms Characters</A>
-<LI><A HREF="#attributes">Character Attributes and Color</A>
-<LI><A HREF="#mouse">Mouse Interfacing</A>
-<LI><A HREF="#finishing">Finishing Up</A>
-</UL>
-<LI><A HREF="#functions">Function Descriptions</A>
-<UL>
-<LI><A HREF="#init">Initialization and Wrapup</A>
-<LI><A HREF="#flush">Causing Output to the Terminal</A>
-<LI><A HREF="#lowlevel">Low-Level Capability Access</A>
-<LI><A HREF="#debugging">Debugging</A>
-</UL>
-<LI><A HREF="#hints">Hints, Tips, and Tricks</A>
-<UL>
-<LI><A HREF="#caution">Some Notes of Caution</A>
-<LI><A HREF="#leaving">Temporarily Leaving ncurses Mode</A>
-<LI><A HREF="#xterm">Using <CODE>ncurses</CODE> under <CODE>xterm</CODE></A>
-<LI><A HREF="#screens">Handling Multiple Terminal Screens</A>
-<LI><A HREF="#testing">Testing for Terminal Capabilities</A>
-<LI><A HREF="#tuning">Tuning for Speed</A>
-<LI><A HREF="#special">Special Features of <CODE>ncurses</CODE></A>
-</UL>
-<LI><A HREF="#compat">Compatibility with Older Versions</A>
-<UL>
-<LI><A HREF="#refbug">Refresh of Overlapping Windows</A>
-<LI><A HREF="#backbug">Background Erase</A>
-</UL>
-<LI><A HREF="#xsifuncs">XSI Curses Conformance</A>
-</UL>
-<LI><A HREF="#panels">The Panels Library</A>
-<UL>
-<LI><A HREF="#pcompile">Compiling With the Panels Library</A>
-<LI><A HREF="#poverview">Overview of Panels</A>
-<LI><A HREF="#pstdscr">Panels, Input, and the Standard Screen</A>
-<LI><A HREF="#hiding">Hiding Panels</A>
-<LI><A HREF="#pmisc">Miscellaneous Other Facilities</A>
-</UL>
-<LI><A HREF="#menu">The Menu Library</A>
-<UL>
-<LI><A HREF="#mcompile">Compiling with the menu Library</A>
-<LI><A HREF="#moverview">Overview of Menus</A>
-<LI><A HREF="#mselect">Selecting items</A>
-<LI><A HREF="#mdisplay">Menu Display</A>
-<LI><A HREF="#mwindows">Menu Windows</A>
-<LI><A HREF="#minput">Processing Menu Input</A>
-<LI><A HREF="#mmisc">Miscellaneous Other Features</A>
-</UL>
-<LI><A HREF="#form">The Forms Library</A>
-<UL>
-<LI><A HREF="#fcompile">Compiling with the forms Library</A>
-<LI><A HREF="#foverview">Overview of Forms</A>
-<LI><A HREF="#fcreate">Creating and Freeing Fields and Forms</A>
-<LI><A HREF="#fattributes">Fetching and Changing Field Attributes</A>
-<UL>
-<LI><A HREF="#fsizes">Fetching Size and Location Data</A>
-<LI><A HREF="#flocation">Changing the Field Location</A>
-<LI><A HREF="#fjust">The Justification Attribute</A>
-<LI><A HREF="#fdispatts">Field Display Attributes</A>
-<LI><A HREF="#foptions">Field Option Bits</A>
-<LI><A HREF="#fstatus">Field Status</A>
-<LI><A HREF="#fuser">Field User Pointer</A>
-</UL>
-<LI><A HREF="#fdynamic">Variable-Sized Fields</A>
-<LI><A HREF="#fvalidation">Field Validation</A>
-<UL>
-<LI><A HREF="#ftype_alpha">TYPE_ALPHA</A>
-<LI><A HREF="#ftype_alnum">TYPE_ALNUM</A>
-<LI><A HREF="#ftype_enum">TYPE_ENUM</A>
-<LI><A HREF="#ftype_integer">TYPE_INTEGER</A>
-<LI><A HREF="#ftype_numeric">TYPE_NUMERIC</A>
-<LI><A HREF="#ftype_regexp">TYPE_REGEXP</A>
-</UL>
-<LI><A HREF="#fbuffer">Direct Field Buffer Manipulation</A>
-<LI><A HREF="#formattrs">Attributes of Forms</A>
-<LI><A HREF="#fdisplay">Control of Form Display</A>
-<LI><A HREF="#fdriver">Input Processing in the Forms Driver</A>
-<UL>
-<LI><A HREF="#fpage">Page Navigation Requests</A>
-<LI><A HREF="#ffield">Inter-Field Navigation Requests</A>
-<LI><A HREF="#fifield">Intra-Field Navigation Requests</A>
-<LI><A HREF="#fscroll">Scrolling Requests</A>
-<LI><A HREF="#fedit">Field Editing Requests</A>
-<LI><A HREF="#forder">Order Requests</A>
-<LI><A HREF="#fappcmds">Application Commands</A>
-</UL>
-<LI><A HREF="#fhooks">Field Change Hooks</A>
-<LI><A HREF="#ffocus">Field Change Commands</A>
-<LI><A HREF="#frmoptions">Form Options</A>
-<LI><A HREF="#fcustom">Custom Validation Types</A>
-<UL>
-<LI><A HREF="#flinktypes">Union Types</A>
-<LI><A HREF="#fnewtypes">New Field Types</A>
-<LI><A HREF="#fcheckargs">Validation Function Arguments</A>
-<LI><A HREF="#fcustorder">Order Functions For Custom Types</A>
-<LI><A HREF="#fcustprobs">Avoiding Problems</A>
-</UL>
-</UL>
-</UL>
-
-<HR>
-<H1><A NAME="introduction">Introduction</A></H1>
-
-This document is an introduction to programming with <CODE>curses</CODE>. It is
-not an exhaustive reference for the curses Application Programming Interface
-(API); that role is filled by the <CODE>curses</CODE> manual pages.  Rather, it
-is intended to help C programmers ease into using the package. <P>
-
-This document is aimed at C applications programmers not yet specifically
-familiar with ncurses.  If you are already an experienced <CODE>curses</CODE>
-programmer, you should nevertheless read the sections on
-<A HREF="#mouse">Mouse Interfacing</A>, <A HREF="#debugging">Debugging</A>,
-<A HREF="#compat">Compatibility with Older Versions</A>,
-and <A HREF="#hints">Hints, Tips, and Tricks</A>.  These will bring you up
-to speed on the special features and quirks of the <CODE>ncurses</CODE>
-implementation.  If you are not so experienced, keep reading. <P>
-
-The <CODE>curses</CODE> package is a subroutine library for
-terminal-independent screen-painting and input-event handling which
-presents a high level screen model to the programmer, hiding differences
-between terminal types and doing automatic optimization of output to change
-one screen full of text into another.  <CODE>Curses</CODE> uses terminfo, which
-is a database format that can describe the capabilities of thousands of
-different terminals. <P>
-
-The <CODE>curses</CODE> API may seem something of an archaism on UNIX desktops
-increasingly dominated by X, Motif, and Tcl/Tk.  Nevertheless, UNIX still
-supports tty lines and X supports <EM>xterm(1)</EM>; the <CODE>curses</CODE>
-API has the advantage of (a) back-portability to character-cell terminals,
-and (b) simplicity.  For an application that does not require bit-mapped
-graphics and multiple fonts, an interface implementation using <CODE>curses</CODE>
-will typically be a great deal simpler and less expensive than one using an
-X toolkit.
-
-<H2><A NAME="history">A Brief History of Curses</A></H2>
-
-Historically, the first ancestor of <CODE>curses</CODE> was the routines written to
-provide screen-handling for the game <CODE>rogue</CODE>; these used the
-already-existing <CODE>termcap</CODE> database facility for describing terminal
-capabilities.  These routines were abstracted into a documented library and
-first released with the early BSD UNIX versions. <P>
-
-System III UNIX from Bell Labs featured a rewritten and much-improved
-<CODE>curses</CODE> library.  It introduced the terminfo format.  Terminfo is based
-on Berkeley's termcap database, but contains a number of improvements and
-extensions. Parameterized capabilities strings were introduced, making it
-possible to describe multiple video attributes, and colors and to handle far
-more unusual terminals than possible with termcap.  In the later AT&amp;T
-System V releases, <CODE>curses</CODE> evolved to use more facilities and offer
-more capabilities, going far beyond BSD curses in power and flexibility.
-
-<H2><A NAME="scope">Scope of This Document</A></H2>
-
-This document describes <CODE>ncurses</CODE>, a free implementation of
-the System V <CODE>curses</CODE> API with some clearly marked extensions.
-It includes the following System V curses features:
-<UL>
-<LI>Support for multiple screen highlights (BSD curses could only
-handle one `standout' highlight, usually reverse-video).
-<LI>Support for line- and box-drawing using forms characters.
-<LI>Recognition of function keys on input.
-<LI>Color support.
-<LI>Support for pads (windows of larger than screen size on which the
-screen or a subwindow defines a viewport).
-</UL>
-
-Also, this package makes use of the insert and delete line and character
-features of terminals so equipped, and determines how to optimally use these
-features with no help from the programmer.  It allows arbitrary combinations of
-video attributes to be displayed, even on terminals that leave ``magic
-cookies'' on the screen to mark changes in attributes. <P>
-
-The <CODE>ncurses</CODE> package can also capture and use event reports from a
-mouse in some environments (notably, xterm under the X window system).  This
-document includes tips for using the mouse. <P>
-
-The <CODE>ncurses</CODE> package was originated by Pavel Curtis.  The original
-maintainer of this package is
-<A HREF="mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</A>
-&lt;zmbenhal@netcom.com&gt;.
-<A HREF="mailto:esr@snark.thyrsus.com">Eric S. Raymond</A>
-&lt;esr@snark.thyrsus.com&gt;
-wrote many of the new features in versions after 1.8.1
-and wrote most of this introduction.
-J&uuml;rgen Pfeifer
-wrote all of the menu and forms code as well as the
-<A HREF="http://www.adahome.com">Ada95</A> binding.
-Ongoing work is being done by
-<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A> (maintainer).
-Contact the current maintainers at
-<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.
-<P>
-
-This document also describes the <A HREF="#panels">panels</A> extension library,
-similarly modeled on the SVr4 panels facility.  This library allows you to
-associate backing store with each of a stack or deck of overlapping windows,
-and provides operations for moving windows around in the stack that change
-their visibility in the natural way (handling window overlaps). <P>
-
-Finally, this document describes in detail the <A HREF="#menu">menus</A> and <A
-HREF="#form">forms</A> extension libraries, also cloned from System V,
-which support easy construction and sequences of menus and fill-in
-forms.
-
-
-<H2><A NAME="terminology">Terminology</A></H2>
-
-In this document, the following terminology is used with reasonable
-consistency:
-
-<DL>
-<DT> window
-<DD>
-A data structure describing a sub-rectangle of the screen (possibly the
-entire screen).  You can write to a window as though it were a miniature
-screen, scrolling independently of other windows on the physical screen.
-<DT> screens
-<DD>
-A subset of windows which are as large as the terminal screen, i.e., they start
-at the upper left hand corner and encompass the lower right hand corner.  One
-of these, <CODE>stdscr</CODE>, is automatically provided for the programmer.
-<DT> terminal screen
-<DD>
-The package's idea of what the terminal display currently looks like, i.e.,
-what the user sees now.  This is a special screen.
-</DL>
-
-<H1><A NAME="curses">The Curses Library</A></H1>
-
-<H2><A NAME="overview">An Overview of Curses</A></H2>
-
-<H3><A NAME="compiling">Compiling Programs using Curses</A></H3>
-
-In order to use the library, it is necessary to have certain types and
-variables defined.  Therefore, the programmer must have a line:
-
-<PRE>
-         #include &lt;curses.h&gt;
-</PRE>
-
-at the top of the program source.  The screen package uses the Standard I/O
-library, so <CODE>&lt;curses.h&gt;</CODE> includes
-<CODE>&lt;stdio.h&gt;</CODE>. <CODE>&lt;curses.h&gt;</CODE> also includes
-<CODE>&lt;termios.h&gt;</CODE>, <CODE>&lt;termio.h&gt;</CODE>, or
-<CODE>&lt;sgtty.h&gt;</CODE> depending on your system.  It is redundant (but
-harmless) for the programmer to do these includes, too. In linking with
-<CODE>curses</CODE> you need to have <CODE>-lncurses</CODE> in your LDFLAGS or on the
-command line.  There is no need for any other libraries.
-
-<H3><A NAME="updating">Updating the Screen</A></H3>
-
-In order to update the screen optimally, it is necessary for the routines to
-know what the screen currently looks like and what the programmer wants it to
-look like next. For this purpose, a data type (structure) named WINDOW is
-defined which describes a window image to the routines, including its starting
-position on the screen (the (y, x) coordinates of the upper left hand corner)
-and its size.  One of these (called <CODE>curscr</CODE>, for current screen) is a
-screen image of what the terminal currently looks like.  Another screen (called
-<CODE>stdscr</CODE>, for standard screen) is provided by default to make changes
-on. <P>
-
-A window is a purely internal representation. It is used to build and store a
-potential image of a portion of the terminal.  It doesn't bear any necessary
-relation to what is really on the terminal screen; it's more like a
-scratchpad or write buffer. <P>
-
-To make the section of physical screen corresponding to a window reflect the
-contents of the window structure, the routine <CODE>refresh()</CODE> (or
-<CODE>wrefresh()</CODE> if the window is not <CODE>stdscr</CODE>) is called. <P>
-
-A given physical screen section may be within the scope of any number of
-overlapping windows.  Also, changes can be made to windows in any order,
-without regard to motion efficiency.  Then, at will, the programmer can
-effectively say ``make it look like this,'' and let the package implementation
-determine the most efficient way to repaint the screen.
-
-<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3>
-
-As hinted above, the routines can use several windows, but two are
-automatically given: <CODE>curscr</CODE>, which knows what the terminal looks like,
-and <CODE>stdscr</CODE>, which is what the programmer wants the terminal to look
-like next.  The user should never actually access <CODE>curscr</CODE> directly.
-Changes should be made to through the API, and then the routine
-<CODE>refresh()</CODE> (or <CODE>wrefresh()</CODE>) called. <P>
-
-Many functions are defined to use <CODE>stdscr</CODE> as a default screen.  For
-example, to add a character to <CODE>stdscr</CODE>, one calls <CODE>addch()</CODE> with
-the desired character as argument.  To write to a different window. use the
-routine <CODE>waddch()</CODE> (for `w'indow-specific addch()) is provided.  This
-convention of prepending function names with a `w' when they are to be
-applied to specific windows is consistent.  The only routines which do not
-follow it are those for which a window must always be specified. <P>
-
-In order to move the current (y, x) coordinates from one point to another, the
-routines <CODE>move()</CODE> and <CODE>wmove()</CODE> are provided.  However, it is
-often desirable to first move and then perform some I/O operation.  In order to
-avoid clumsiness, most I/O routines can be preceded by the prefix 'mv' and
-the desired (y, x) coordinates prepended to the arguments to the function.  For
-example, the calls
-
-<PRE>
-         move(y, x);
-         addch(ch);
-</PRE>
-
-can be replaced by
-
-<PRE>
-         mvaddch(y, x, ch);
-</PRE>
-
-and
-
-<PRE>
-         wmove(win, y, x);
-         waddch(win, ch);
-</PRE>
-
-can be replaced by
-
-<PRE>
-         mvwaddch(win, y, x, ch);
-</PRE>
-
-Note that the window description pointer (win) comes before the added (y, x)
-coordinates.  If a function requires a window pointer, it is always the first
-parameter passed.
-
-<H3><A NAME="variables">Variables</A></H3>
-
-The <CODE>curses</CODE> library sets some variables describing the terminal
-capabilities.
-
-<PRE>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+
+<html>
+<head>
+  <meta name="generator" content=
+  "HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
+
+  <title>Writing Programs with NCURSES</title>
+  <link rev="made" href="mailto:bugs-ncurses@gnu.org">
+  <meta http-equiv="Content-Type" content=
+  "text/html; charset=us-ascii">
+</head>
+
+<body>
+  <h1>Writing Programs with NCURSES</h1>
+
+  <blockquote>
+    by Eric S. Raymond and Zeyd M. Ben-Halim<br>
+    updates since release 1.9.9e by Thomas Dickey
+  </blockquote>
+
+  <h1>Contents</h1>
+
+  <ul>
+    <li>
+      <a href="#introduction">Introduction</a>
+
+      <ul>
+        <li><a href="#history">A Brief History of Curses</a></li>
+
+        <li><a href="#scope">Scope of This Document</a></li>
+
+        <li><a href="#terminology">Terminology</a></li>
+      </ul>
+    </li>
+
+    <li>
+      <a href="#curses">The Curses Library</a>
+
+      <ul>
+        <li>
+          <a href="#overview">An Overview of Curses</a>
+
+          <ul>
+            <li><a href="#compiling">Compiling Programs using
+            Curses</a></li>
+
+            <li><a href="#updating">Updating the Screen</a></li>
+
+            <li><a href="#stdscr">Standard Windows and Function
+            Naming Conventions</a></li>
+
+            <li><a href="#variables">Variables</a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#using">Using the Library</a>
+
+          <ul>
+            <li><a href="#starting">Starting up</a></li>
+
+            <li><a href="#output">Output</a></li>
+
+            <li><a href="#input">Input</a></li>
+
+            <li><a href="#formschars">Using Forms
+            Characters</a></li>
+
+            <li><a href="#attributes">Character Attributes and
+            Color</a></li>
+
+            <li><a href="#mouse">Mouse Interfacing</a></li>
+
+            <li><a href="#finishing">Finishing Up</a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#functions">Function Descriptions</a>
+
+          <ul>
+            <li><a href="#init">Initialization and Wrapup</a></li>
+
+            <li><a href="#flush">Causing Output to the
+            Terminal</a></li>
+
+            <li><a href="#lowlevel">Low-Level Capability
+            Access</a></li>
+
+            <li><a href="#debugging">Debugging</a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#hints">Hints, Tips, and Tricks</a>
+
+          <ul>
+            <li><a href="#caution">Some Notes of Caution</a></li>
+
+            <li><a href="#leaving">Temporarily Leaving ncurses
+            Mode</a></li>
+
+            <li><a href="#xterm">Using <code>ncurses</code> under
+            <code>xterm</code></a></li>
+
+            <li><a href="#screens">Handling Multiple Terminal
+            Screens</a></li>
+
+            <li><a href="#testing">Testing for Terminal
+            Capabilities</a></li>
+
+            <li><a href="#tuning">Tuning for Speed</a></li>
+
+            <li><a href="#special">Special Features of
+            <code>ncurses</code></a></li>
+          </ul>
+        </li>
+
+        <li>
+          <a href="#compat">Compatibility with Older Versions</a>
+
+          <ul>
+            <li><a href="#refbug">Refresh of Overlapping
+            Windows</a></li>
+
+            <li><a href="#backbug">Background Erase</a></li>
+          </ul>
+        </li>
+
+        <li><a href="#xsifuncs">XSI Curses Conformance</a></li>
+      </ul>
+    </li>
+
+    <li>
+      <a href="#panels">The Panels Library</a>
+
+      <ul>
+        <li><a href="#pcompile">Compiling With the Panels
+        Library</a></li>
+
+        <li><a href="#poverview">Overview of Panels</a></li>
+
+        <li><a href="#pstdscr">Panels, Input, and the Standard
+        Screen</a></li>
+
+        <li><a href="#hiding">Hiding Panels</a></li>
+
+        <li><a href="#pmisc">Miscellaneous Other
+        Facilities</a></li>
+      </ul>
+    </li>
+
+    <li>
+      <a href="#menu">The Menu Library</a>
+
+      <ul>
+        <li><a href="#mcompile">Compiling with the menu
+        Library</a></li>
+
+        <li><a href="#moverview">Overview of Menus</a></li>
+
+        <li><a href="#mselect">Selecting items</a></li>
+
+        <li><a href="#mdisplay">Menu Display</a></li>
+
+        <li><a href="#mwindows">Menu Windows</a></li>
+
+        <li><a href="#minput">Processing Menu Input</a></li>
+
+        <li><a href="#mmisc">Miscellaneous Other Features</a></li>
+      </ul>
+    </li>
+
+    <li>
+      <a href="#form">The Forms Library</a>
+
+      <ul>
+        <li><a href="#fcompile">Compiling with the forms
+        Library</a></li>
+
+        <li><a href="#foverview">Overview of Forms</a></li>
+
+        <li><a href="#fcreate">Creating and Freeing Fields and
+        Forms</a></li>
+
+        <li>
+          <a href="#fattributes">Fetching and Changing Field
+          Attributes</a>
+
+          <ul>
+            <li><a href="#fsizes">Fetching Size and Location
+            Data</a></li>
+
+            <li><a href="#flocation">Changing the Field
+            Location</a></li>
+
+            <li><a href="#fjust">The Justification
+            Attribute</a></li>
+
+            <li><a href="#fdispatts">Field Display
+            Attributes</a></li>
+
+            <li><a href="#foptions">Field Option Bits</a></li>
+
+            <li><a href="#fstatus">Field Status</a></li>
+
+            <li><a href="#fuser">Field User Pointer</a></li>
+          </ul>
+        </li>
+
+        <li><a href="#fdynamic">Variable-Sized Fields</a></li>
+
+        <li>
+          <a href="#fvalidation">Field Validation</a>
+
+          <ul>
+            <li><a href="#ftype_alpha">TYPE_ALPHA</a></li>
+
+            <li><a href="#ftype_alnum">TYPE_ALNUM</a></li>
+
+            <li><a href="#ftype_enum">TYPE_ENUM</a></li>
+
+            <li><a href="#ftype_integer">TYPE_INTEGER</a></li>
+
+            <li><a href="#ftype_numeric">TYPE_NUMERIC</a></li>
+
+            <li><a href="#ftype_regexp">TYPE_REGEXP</a></li>
+          </ul>
+        </li>
+
+        <li><a href="#fbuffer">Direct Field Buffer
+        Manipulation</a></li>
+
+        <li><a href="#formattrs">Attributes of Forms</a></li>
+
+        <li><a href="#fdisplay">Control of Form Display</a></li>
+
+        <li>
+          <a href="#fdriver">Input Processing in the Forms
+          Driver</a>
+
+          <ul>
+            <li><a href="#fpage">Page Navigation Requests</a></li>
+
+            <li><a href="#ffield">Inter-Field Navigation
+            Requests</a></li>
+
+            <li><a href="#fifield">Intra-Field Navigation
+            Requests</a></li>
+
+            <li><a href="#fscroll">Scrolling Requests</a></li>
+
+            <li><a href="#fedit">Field Editing Requests</a></li>
+
+            <li><a href="#forder">Order Requests</a></li>
+
+            <li><a href="#fappcmds">Application Commands</a></li>
+          </ul>
+        </li>
+
+        <li><a href="#fhooks">Field Change Hooks</a></li>
+
+        <li><a href="#ffocus">Field Change Commands</a></li>
+
+        <li><a href="#frmoptions">Form Options</a></li>
+
+        <li>
+          <a href="#fcustom">Custom Validation Types</a>
+
+          <ul>
+            <li><a href="#flinktypes">Union Types</a></li>
+
+            <li><a href="#fnewtypes">New Field Types</a></li>
+
+            <li><a href="#fcheckargs">Validation Function
+            Arguments</a></li>
+
+            <li><a href="#fcustorder">Order Functions For Custom
+            Types</a></li>
+
+            <li><a href="#fcustprobs">Avoiding Problems</a></li>
+          </ul>
+        </li>
+      </ul>
+    </li>
+  </ul>
+  <hr>
+
+  <h1><a name="introduction" id=
+  "introduction">Introduction</a></h1>
+
+  <p>This document is an introduction to programming with
+  <code>curses</code>. It is not an exhaustive reference for the
+  curses Application Programming Interface (API); that role is
+  filled by the <code>curses</code> manual pages. Rather, it is
+  intended to help C programmers ease into using the package.</p>
+
+  <p>This document is aimed at C applications programmers not yet
+  specifically familiar with ncurses. If you are already an
+  experienced <code>curses</code> programmer, you should
+  nevertheless read the sections on <a href="#mouse">Mouse
+  Interfacing</a>, <a href="#debugging">Debugging</a>, <a href=
+  "#compat">Compatibility with Older Versions</a>, and <a href=
+  "#hints">Hints, Tips, and Tricks</a>. These will bring you up to
+  speed on the special features and quirks of the
+  <code>ncurses</code> implementation. If you are not so
+  experienced, keep reading.</p>
+
+  <p>The <code>curses</code> package is a subroutine library for
+  terminal-independent screen-painting and input-event handling
+  which presents a high level screen model to the programmer,
+  hiding differences between terminal types and doing automatic
+  optimization of output to change one screen full of text into
+  another. <code>Curses</code> uses terminfo, which is a database
+  format that can describe the capabilities of thousands of
+  different terminals.</p>
+
+  <p>The <code>curses</code> API may seem something of an archaism
+  on UNIX desktops increasingly dominated by X, Motif, and Tcl/Tk.
+  Nevertheless, UNIX still supports tty lines and X supports
+  <em>xterm(1)</em>; the <code>curses</code> API has the advantage
+  of (a) back-portability to character-cell terminals, and (b)
+  simplicity. For an application that does not require bit-mapped
+  graphics and multiple fonts, an interface implementation using
+  <code>curses</code> will typically be a great deal simpler and
+  less expensive than one using an X toolkit.</p>
+
+  <h2><a name="history" id="history">A Brief History of
+  Curses</a></h2>
+
+  <p>Historically, the first ancestor of <code>curses</code> was
+  the routines written to provide screen-handling for the game
+  <code>rogue</code>; these used the already-existing
+  <code>termcap</code> database facility for describing terminal
+  capabilities. These routines were abstracted into a documented
+  library and first released with the early BSD UNIX versions.</p>
+
+  <p>System III UNIX from Bell Labs featured a rewritten and
+  much-improved <code>curses</code> library. It introduced the
+  terminfo format. Terminfo is based on Berkeley's termcap
+  database, but contains a number of improvements and extensions.
+  Parameterized capabilities strings were introduced, making it
+  possible to describe multiple video attributes, and colors and to
+  handle far more unusual terminals than possible with termcap. In
+  the later AT&amp;T System V releases, <code>curses</code> evolved
+  to use more facilities and offer more capabilities, going far
+  beyond BSD curses in power and flexibility.</p>
+
+  <h2><a name="scope" id="scope">Scope of This Document</a></h2>
+
+  <p>This document describes <code>ncurses</code>, a free
+  implementation of the System V <code>curses</code> API with some
+  clearly marked extensions. It includes the following System V
+  curses features:</p>
+
+  <ul>
+    <li>Support for multiple screen highlights (BSD curses could
+    only handle one &ldquo;standout&rdquo; highlight, usually
+    reverse-video).</li>
+
+    <li>Support for line- and box-drawing using forms
+    characters.</li>
+
+    <li>Recognition of function keys on input.</li>
+
+    <li>Color support.</li>
+
+    <li>Support for pads (windows of larger than screen size on
+    which the screen or a subwindow defines a viewport).</li>
+  </ul>
+
+  <p>Also, this package makes use of the insert and delete line and
+  character features of terminals so equipped, and determines how
+  to optimally use these features with no help from the programmer.
+  It allows arbitrary combinations of video attributes to be
+  displayed, even on terminals that leave &ldquo;magic
+  cookies&rdquo; on the screen to mark changes in attributes.</p>
+
+  <p>The <code>ncurses</code> package can also capture and use
+  event reports from a mouse in some environments (notably, xterm
+  under the X window system). This document includes tips for using
+  the mouse.</p>
+
+  <p>The <code>ncurses</code> package was originated by Pavel
+  Curtis. The original maintainer of this package is <a href=
+  "mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</a>
+  &lt;zmbenhal@netcom.com&gt;. <a href=
+  "mailto:esr@snark.thyrsus.com">Eric S. Raymond</a>
+  &lt;esr@snark.thyrsus.com&gt; wrote many of the new features in
+  versions after 1.8.1 and wrote most of this introduction.
+  J&uuml;rgen Pfeifer wrote all of the menu and forms code as well
+  as the <a href="http://www.adahome.com">Ada95</a> binding.
+  Ongoing work is being done by <a href=
+  "mailto:dickey@invisible-island.net">Thomas Dickey</a>
+  (maintainer). Contact the current maintainers at <a href=
+  "mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</a>.</p>
+
+  <p>This document also describes the <a href="#panels">panels</a>
+  extension library, similarly modeled on the SVr4 panels facility.
+  This library allows you to associate backing store with each of a
+  stack or deck of overlapping windows, and provides operations for
+  moving windows around in the stack that change their visibility
+  in the natural way (handling window overlaps).</p>
+
+  <p>Finally, this document describes in detail the <a href=
+  "#menu">menus</a> and <a href="#form">forms</a> extension
+  libraries, also cloned from System V, which support easy
+  construction and sequences of menus and fill-in forms.</p>
+
+  <h2><a name="terminology" id="terminology">Terminology</a></h2>
+
+  <p>In this document, the following terminology is used with
+  reasonable consistency:</p>
+
+  <dl>
+    <dt>window</dt>
+
+    <dd>A data structure describing a sub-rectangle of the screen
+    (possibly the entire screen). You can write to a window as
+    though it were a miniature screen, scrolling independently of
+    other windows on the physical screen.</dd>
+
+    <dt>screens</dt>
+
+    <dd>A subset of windows which are as large as the terminal
+    screen, i.e., they start at the upper left hand corner and
+    encompass the lower right hand corner. One of these,
+    <code>stdscr</code>, is automatically provided for the
+    programmer.</dd>
+
+    <dt>terminal screen</dt>
+
+    <dd>The package's idea of what the terminal display currently
+    looks like, i.e., what the user sees now. This is a special
+    screen.</dd>
+  </dl>
+
+  <h1><a name="curses" id="curses">The Curses Library</a></h1>
+
+  <h2><a name="overview" id="overview">An Overview of
+  Curses</a></h2>
+
+  <h3><a name="compiling" id="compiling">Compiling Programs using
+  Curses</a></h3>
+
+  <p>In order to use the library, it is necessary to have certain
+  types and variables defined. Therefore, the programmer must have
+  a line:</p>
+  <pre>
+          #include &lt;curses.h&gt;
+</pre>
+
+  <p>at the top of the program source. The screen package uses the
+  Standard I/O library, so <code>&lt;curses.h&gt;</code> includes
+  <code>&lt;stdio.h&gt;</code>. <code>&lt;curses.h&gt;</code> also
+  includes <code>&lt;termios.h&gt;</code>,
+  <code>&lt;termio.h&gt;</code>, or <code>&lt;sgtty.h&gt;</code>
+  depending on your system. It is redundant (but harmless) for the
+  programmer to do these includes, too. In linking with
+  <code>curses</code> you need to have <code>-lncurses</code> in
+  your LDFLAGS or on the command line. There is no need for any
+  other libraries.</p>
+
+  <h3><a name="updating" id="updating">Updating the Screen</a></h3>
+
+  <p>In order to update the screen optimally, it is necessary for
+  the routines to know what the screen currently looks like and
+  what the programmer wants it to look like next. For this purpose,
+  a data type (structure) named WINDOW is defined which describes a
+  window image to the routines, including its starting position on
+  the screen (the (y, x) coordinates of the upper left hand corner)
+  and its size. One of these (called <code>curscr</code>, for
+  current screen) is a screen image of what the terminal currently
+  looks like. Another screen (called <code>stdscr</code>, for
+  standard screen) is provided by default to make changes on.</p>
+
+  <p>A window is a purely internal representation. It is used to
+  build and store a potential image of a portion of the terminal.
+  It does not bear any necessary relation to what is really on the
+  terminal screen; it is more like a scratchpad or write
+  buffer.</p>
+
+  <p>To make the section of physical screen corresponding to a
+  window reflect the contents of the window structure, the routine
+  <code>refresh()</code> (or <code>wrefresh()</code> if the window
+  is not <code>stdscr</code>) is called.</p>
+
+  <p>A given physical screen section may be within the scope of any
+  number of overlapping windows. Also, changes can be made to
+  windows in any order, without regard to motion efficiency. Then,
+  at will, the programmer can effectively say &ldquo;make it look
+  like this,&rdquo; and let the package implementation determine
+  the most efficient way to repaint the screen.</p>
+
+  <h3><a name="stdscr" id="stdscr">Standard Windows and Function
+  Naming Conventions</a></h3>
+
+  <p>As hinted above, the routines can use several windows, but two
+  are automatically given: <code>curscr</code>, which knows what
+  the terminal looks like, and <code>stdscr</code>, which is what
+  the programmer wants the terminal to look like next. The user
+  should never actually access <code>curscr</code> directly.
+  Changes should be made to through the API, and then the routine
+  <code>refresh()</code> (or <code>wrefresh()</code>) called.</p>
+
+  <p>Many functions are defined to use <code>stdscr</code> as a
+  default screen. For example, to add a character to
+  <code>stdscr</code>, one calls <code>addch()</code> with the
+  desired character as argument. To write to a different window.
+  use the routine <code>waddch()</code> (for
+  <strong>w</strong>indow-specific addch()) is provided. This
+  convention of prepending function names with a &ldquo;w&rdquo;
+  when they are to be applied to specific windows is consistent.
+  The only routines which do not follow it are those for which a
+  window must always be specified.</p>
+
+  <p>In order to move the current (y, x) coordinates from one point
+  to another, the routines <code>move()</code> and
+  <code>wmove()</code> are provided. However, it is often desirable
+  to first move and then perform some I/O operation. In order to
+  avoid clumsiness, most I/O routines can be preceded by the prefix
+  &ldquo;mv&rdquo; and the desired (y, x) coordinates prepended to
+  the arguments to the function. For example, the calls</p>
+  <pre>
+          move(y, x);
+          addch(ch);
+</pre>
+
+  <p>can be replaced by</p>
+  <pre>
+          mvaddch(y, x, ch);
+</pre>
+
+  <p>and</p>
+  <pre>
+          wmove(win, y, x);
+          waddch(win, ch);
+</pre>
+
+  <p>can be replaced by</p>
+  <pre>
+          mvwaddch(win, y, x, ch);
+</pre>
+
+  <p>Note that the window description pointer (win) comes before
+  the added (y, x) coordinates. If a function requires a window
+  pointer, it is always the first parameter passed.</p>
+
+  <h3><a name="variables" id="variables">Variables</a></h3>
+
+  <p>The <code>curses</code> library sets some variables describing
+  the terminal capabilities.</p>
+  <pre>
       type   name      description
       ------------------------------------------------------------------
       int    LINES     number of lines on the terminal
       int    COLS      number of columns on the terminal
-</PRE>
-
-The <CODE>curses.h</CODE> also introduces some <CODE>#define</CODE> constants and types
-of general usefulness:
-
-<DL>
-<DT> <CODE>bool</CODE>
-<DD> boolean type, actually a `char' (e.g., <CODE>bool doneit;</CODE>)
-<DT> <CODE>TRUE</CODE>
-<DD> boolean `true' flag (1).
-<DT> <CODE>FALSE</CODE>
-<DD> boolean `false' flag (0).
-<DT> <CODE>ERR</CODE>
-<DD> error flag returned by routines on a failure (-1).
-<DT> <CODE>OK</CODE>
-<DD> error flag returned by routines when things go right.
-</DL>
-
-<H2><A NAME="using">Using the Library</A></H2>
-
-Now we describe how to actually use the screen package.  In it, we assume all
-updating, reading, etc. is applied to <CODE>stdscr</CODE>.  These instructions will
-work on any window, providing you change the function names and parameters as
-mentioned above. <P>
-
-Here is a sample program to motivate the discussion:
-
-<PRE>
+</pre>
+
+  <p>The <code>curses.h</code> also introduces some
+  <code>#define</code> constants and types of general
+  usefulness:</p>
+
+  <dl>
+    <dt><code>bool</code></dt>
+
+    <dd>boolean type, actually a &ldquo;char&rdquo; (e.g.,
+    <code>bool doneit;</code>)</dd>
+
+    <dt><code>TRUE</code></dt>
+
+    <dd>boolean &ldquo;true&rdquo; flag (1).</dd>
+
+    <dt><code>FALSE</code></dt>
+
+    <dd>boolean &ldquo;false&rdquo; flag (0).</dd>
+
+    <dt><code>ERR</code></dt>
+
+    <dd>error flag returned by routines on a failure (-1).</dd>
+
+    <dt><code>OK</code></dt>
+
+    <dd>error flag returned by routines when things go right.</dd>
+  </dl>
+
+  <h2><a name="using" id="using">Using the Library</a></h2>
+
+  <p>Now we describe how to actually use the screen package. In it,
+  we assume all updating, reading, etc. is applied to
+  <code>stdscr</code>. These instructions will work on any window,
+  providing you change the function names and parameters as
+  mentioned above.</p>
+
+  <p>Here is a sample program to motivate the discussion:</p>
+  <pre>
+#include &lt;stdlib.h&gt;
 #include &lt;curses.h&gt;
 #include &lt;signal.h&gt;
 
@@ -457,9 +652,9 @@ main(int argc, char *argv[])
 
         /*
          * Simple color assignment, often all we need.  Color pair 0 cannot
-        * be redefined.  This example uses the same value for the color
-        * pair as for the foreground color, though of course that is not
-        * necessary:
+         * be redefined.  This example uses the same value for the color
+         * pair as for the foreground color, though of course that is not
+         * necessary:
          */
         init_pair(1, COLOR_RED,     COLOR_BLACK);
         init_pair(2, COLOR_GREEN,   COLOR_BLACK);
@@ -473,13 +668,13 @@ main(int argc, char *argv[])
     for (;;)
     {
         int c = getch();     /* refresh, accept single keystroke of input */
-       attrset(COLOR_PAIR(num % 8));
-       num++;
+        attrset(COLOR_PAIR(num % 8));
+        num++;
 
         /* process the command keystroke */
     }
 
-    finish(0);               /* we're done */
+    finish(0);               /* we are done */
 }
 
 static void finish(int sig)
@@ -490,1165 +685,1364 @@ static void finish(int sig)
 
     exit(0);
 }
-</PRE>
-
-<H3><A NAME="starting">Starting up</A></H3>
-
-In order to use the screen package, the routines must know about terminal
-characteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be
-allocated.  These function <CODE>initscr()</CODE> does both these things. Since it
-must allocate space for the windows, it can overflow memory when attempting to
-do so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate
-the program with an error message.  <CODE>initscr()</CODE> must always be called
-before any of the routines which affect windows are used.  If it is not, the
-program will core dump as soon as either <CODE>curscr</CODE> or <CODE>stdscr</CODE> are
-referenced.  However, it is usually best to wait to call it until after you are
-sure you will need it, like after checking for startup errors.  Terminal status
-changing routines like <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called
-after <CODE>initscr()</CODE>. <P>
-
-Once the screen windows have been allocated, you can set them up for
-your program.  If you want to, say, allow a screen to scroll, use
-<CODE>scrollok()</CODE>.  If you want the cursor to be left in place after
-the last change, use <CODE>leaveok()</CODE>.  If this isn't done,
-<CODE>refresh()</CODE> will move the cursor to the window's current (y, x)
-coordinates after updating it. <P>
-
-You can create new windows of your own using the functions <CODE>newwin()</CODE>,
-<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>.  The routine <CODE>delwin()</CODE> will
-allow you to get rid of old windows.  All the options described above can be
-applied to any window.
-
-<H3><A NAME="output">Output</A></H3>
-
-Now that we have set things up, we will want to actually update the terminal.
-The basic functions used to change what will go on a window are
-<CODE>addch()</CODE> and <CODE>move()</CODE>.  <CODE>addch()</CODE> adds a character at the
-current (y, x) coordinates.  <CODE>move()</CODE> changes the current (y, x)
-coordinates to whatever you want them to be.  It returns <CODE>ERR</CODE> if you
-try to move off the window.  As mentioned above, you can combine the two into
-<CODE>mvaddch()</CODE> to do both things at once. <P>
-
-The other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>,
-all call <CODE>addch()</CODE> to add characters to the window. <P>
-
-After you have put on the window what you want there, when you want the portion
-of the terminal covered by the window to be made to look like it, you must call
-<CODE>refresh()</CODE>.  In order to optimize finding changes, <CODE>refresh()</CODE>
-assumes that any part of the window not changed since the last
-<CODE>refresh()</CODE> of that window has not been changed on the terminal, i.e.,
-that you have not refreshed a portion of the terminal with an overlapping
-window.  If this is not the case, the routine <CODE>touchwin()</CODE> is provided
-to make it look like the entire window has been changed, thus making
-<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P>
-
-If you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will
-make the screen look like <CODE>curscr</CODE> thinks it looks like.  This is useful
-for implementing a command which would redraw the screen in case it get messed
-up.
-
-<H3><A NAME="input">Input</A></H3>
-
-The complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if
-echo is set, will call <CODE>addch()</CODE> to echo the character.  Since the
-screen package needs to know what is on the terminal at all times, if
-characters are to be echoed, the tty must be in raw or cbreak mode.  Since
-initially the terminal has echoing enabled and is in ordinary ``cooked'' mode,
-one or the other has to changed before calling <CODE>getch()</CODE>; otherwise,
-the program's output will be unpredictable. <P>
-
-When you need to accept line-oriented input in a window, the functions
-<CODE>wgetstr()</CODE> and friends are available.  There is even a <CODE>wscanw()</CODE>
-function that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window
-input.  These pseudo-line-oriented functions turn on echoing while they
-execute. <P>
-
-The example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable
-support for function-key mapping.  With this feature, the <CODE>getch()</CODE> code
-watches the input stream for character sequences that correspond to arrow and
-function keys.  These sequences are returned as pseudo-character values.  The
-<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The
-mapping from sequences to <CODE>#define</CODE> values is determined by
-<CODE>key_</CODE> capabilities in the terminal's terminfo entry.
-
-<H3><A NAME="formschars">Using Forms Characters</A></H3>
-
-The <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and
-<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially
-defined by <CODE>ncurses</CODE>.  These are <CODE>#define</CODE> values set up in
-the <CODE>curses.h</CODE> header; see there for a complete list (look for
-the prefix <CODE>ACS_</CODE>). <P>
-
-The most useful of the ACS defines are the forms-drawing characters.  You can
-use these to draw boxes and simple graphs on the screen.  If the terminal
-does not have such characters, <CODE>curses.h</CODE> will map them to a
-recognizable (though ugly) set of ASCII defaults.
-
-<H3><A NAME="attributes">Character Attributes and Color</A></H3>
-
-The <CODE>ncurses</CODE> package supports screen highlights including standout,
-reverse-video, underline, and blink.  It also supports color, which is treated
-as another kind of highlight. <P>
-
-Highlights are encoded, internally, as high bits of the pseudo-character type
-(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a
-screen cell.  See the <CODE>curses.h</CODE> header file for a complete list of
-highlight mask values (look for the prefix <CODE>A_</CODE>).<P>
-
-There are two ways to make highlights.  One is to logical-or the value of the
-highlights you want into the character argument of an <CODE>addch()</CODE> call,
-or any other output call that takes a <CODE>chtype</CODE> argument. <P>
-
-The other is to set the current-highlight value.  This is logical-or'ed with
-any highlight you specify the first way.  You do this with the functions
-<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual
-pages for details.
-
-Color is a special kind of highlight.  The package actually thinks in terms
-of color pairs, combinations of foreground and background colors.  The sample
-code above sets up eight color pairs, all of the guaranteed-available colors
-on black.  Note that each color pair is, in effect, given the name of its
-foreground color.  Any other range of eight non-conflicting values could
-have been used as the first arguments of the <CODE>init_pair()</CODE> values. <P>
-
-Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can
-use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular
-color combination.  Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N,
-is itself a compile-time constant and can be used in initializers.
-
-<H3><A NAME="mouse">Mouse Interfacing</A></H3>
-
-The <CODE>ncurses</CODE> library also provides a mouse interface.
-<!-- The 'note' tag is not portable enough -->
-<blockquote>
-<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, it is not part of either
-the XSI Curses standard, nor of System V Release 4, nor BSD curses.
-System V Release 4 curses contains code with similar interface definitions,
-however it is not documented.  Other than by disassembling the library, we
-have no way to determine exactly how that mouse code works.
-Thus, we recommend that you wrap mouse-related code in an #ifdef using the
-feature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked
-on non-ncurses systems.
-</blockquote>
-
-Presently, mouse event reporting works in the following environments:
-<ul>
-<li>xterm and similar programs such as rxvt.
-<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro
-Rubini's mouse server.
-<li>FreeBSD sysmouse (console)
-<li>OS/2 EMX
-</ul>
-<P>
-The mouse interface is very simple.  To activate it, you use the function
-<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies
-what kinds of events you want your program to be able to see.  It will
-return the bit-mask of events that actually become visible, which may differ
-from the argument if the mouse device is not capable of reporting some of
-the event types you specify. <P>
-
-Once the mouse is active, your application's command loop should watch
-for a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>.  When
-you see this, a mouse event report has been queued.  To pick it off
-the queue, use the function <CODE>getmouse()</CODE> (you must do this before
-the next <CODE>wgetch()</CODE>, otherwise another mouse event might come
-in and make the first one inaccessible). <P>
-
-Each call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll
-pass it) with mouse event data.  The event data includes zero-origin,
-screen-relative character-cell coordinates of the mouse pointer.  It also
-includes an event mask.  Bits in this mask will be set, corresponding
-to the event type being reported. <P>
-
-The mouse structure contains two additional fields which may be
-significant in the future as ncurses interfaces to new kinds of
-pointing device.  In addition to x and y coordinates, there is a slot
-for a z coordinate; this might be useful with touch-screens that can
-return a pressure or duration parameter.  There is also a device ID
-field, which could be used to distinguish between multiple pointing
-devices. <P>
-
-The class of visible events may be changed at any time via <CODE>mousemask()</CODE>.
-Events that can be reported include presses, releases, single-, double- and
-triple-clicks (you can set the maximum button-down time for clicks).  If
-you don't make clicks visible, they will be reported as press-release
-pairs.  In some environments, the event mask may include bits reporting
-the state of shift, alt, and ctrl keys on the keyboard during the event. <P>
-
-A function to check whether a mouse event fell within a given window is
-also supplied.  You can use this to see whether a given window should
-consider a mouse event relevant to it. <P>
-
-Because mouse event reporting will not be available in all
-environments, it would be unwise to build <CODE>ncurses</CODE>
-applications that <EM>require</EM> the use of a mouse.  Rather, you should
-use the mouse as a shortcut for point-and-shoot commands your application
-would normally accept from the keyboard.  Two of the test games in the
-<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain
-code that illustrates how this can be done. <P>
-
-See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the
-mouse-interface functions.
-
-<H3><A NAME="finishing">Finishing Up</A></H3>
-
-In order to clean up after the <CODE>ncurses</CODE> routines, the routine
-<CODE>endwin()</CODE> is provided.  It restores tty modes to what they were when
-<CODE>initscr()</CODE> was first called, and moves the cursor down to the
-lower-left corner.  Thus, anytime after the call to initscr, <CODE>endwin()</CODE>
-should be called before exiting.
-
-<H2><A NAME="functions">Function Descriptions</A></H2>
-
-We describe the detailed behavior of some important curses functions here, as a
-supplement to the manual page descriptions.
-
-<H3><A NAME="init">Initialization and Wrapup</A></H3>
-
-<DL>
-<DT> <CODE>initscr()</CODE>
-<DD> The first function called should almost always be <CODE>initscr()</CODE>.
-This will determine the terminal type and
-initialize curses data structures. <CODE>initscr()</CODE> also arranges that
-the first call to <CODE>refresh()</CODE> will clear the screen.  If an error
-occurs a message is written to standard error and the program
-exits. Otherwise it returns a pointer to stdscr.  A few functions may be
-called before initscr (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>,
-<CODE>ripoffline()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple
-terminals, <CODE>newterm()</CODE>.)
-<DT> <CODE>endwin()</CODE>
-<DD> Your program should always call <CODE>endwin()</CODE> before exiting or
-shelling out of the program. This function will restore tty modes,
-move the cursor to the lower left corner of the screen, reset the
-terminal into the proper non-visual mode.  Calling <CODE>refresh()</CODE>
-or <CODE>doupdate()</CODE> after a temporary escape from the program will
-restore the ncurses screen from before the escape.
-<DT> <CODE>newterm(type, ofp, ifp)</CODE>
-<DD> A program which outputs to more than one terminal should use
-<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>.  <CODE>newterm()</CODE> should
-be called once for each terminal.  It returns a variable of type
-<CODE>SCREEN *</CODE> which should be saved as a reference to that
-terminal.
-(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we
-are describing in this introduction, but a collection of 
-parameters used to assist in optimizing the display.)
-The arguments are the type of the terminal (a string) and
-<CODE>FILE</CODE> pointers for the output and input of the terminal.  If
-type is NULL then the environment variable <CODE>$TERM</CODE> is used.
-<CODE>endwin()</CODE> should called once at wrapup time for each terminal
-opened using this function.
-<DT> <CODE>set_term(new)</CODE>
-<DD> This function is used to switch to a different terminal previously
-opened by <CODE>newterm()</CODE>.  The screen reference for the new terminal
-is passed as the parameter.  The previous terminal is returned by the
-function.  All other calls affect only the current terminal.
-<DT> <CODE>delscreen(sp)</CODE>
-<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures
-associated with a given <CODE>SCREEN</CODE> reference.
-</DL>
-
-<H3><A NAME="flush">Causing Output to the Terminal</A></H3>
-
-<DL>
-<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE>
-<DD> These functions must be called to actually get any output on
-the  terminal,  as  other  routines  merely  manipulate data
-structures.  <CODE>wrefresh()</CODE> copies the named window  to the physical
-terminal screen,  taking  into account  what is already
-there in  order to  do optimizations.  <CODE>refresh()</CODE> does a
-refresh of <CODE>stdscr</CODE>.   Unless <CODE>leaveok()</CODE> has been
-enabled, the physical cursor of the terminal is left at  the
-location of the window's cursor.
-<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE>
-<DD> These two functions allow multiple updates with more efficiency
-than wrefresh.  To use them, it is important to understand how curses
-works.  In addition to all the window structures, curses keeps two
-data structures representing the terminal screen: a physical screen,
-describing what is actually on the screen, and a virtual screen,
-describing what the programmer wants to have on the screen.  wrefresh
-works by first copying the named window to the virtual screen
-(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the
-screen (<CODE>doupdate()</CODE>).  If the programmer wishes to output
-several windows at once, a series of calls to <CODE>wrefresh</CODE> will result
-in alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>,
-causing several bursts of output to the screen.  By calling
-<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call
-<CODE>doupdate()</CODE> once, resulting in only one burst of output, with
-fewer total characters transmitted (this also avoids a visually annoying
-flicker at each update).
-</DL>
-
-<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3>
-
-<DL>
-<DT> <CODE>setupterm(term, filenum, errret)</CODE>
-<DD> This routine is called to initialize a terminal's description, without setting
-up the curses screen structures or changing the tty-driver mode bits.
-<CODE>term</CODE> is the character string representing the name of the terminal
-being used.  <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to
-be used for output.  <CODE>errret</CODE> is a pointer to an integer, in which a
-success or failure indication is returned.  The values returned can be 1 (all
-is well), 0 (no such terminal), or -1 (some problem locating the terminfo
-database). <P>
-
-The value of <CODE>term</CODE> can be given as NULL, which will cause the value of
-<CODE>TERM</CODE> in the environment to be used.  The <CODE>errret</CODE> pointer can
-also be given as NULL, meaning no error code is wanted.  If <CODE>errret</CODE> is
-defaulted, and something goes wrong, <CODE>setupterm()</CODE> will print an
-appropriate error message and exit, rather than returning.  Thus, a simple
-program can call setupterm(0, 1, 0) and not worry about initialization
-errors. <P>
-
-After the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is
-set to point to the current structure of terminal capabilities. By calling
-<CODE>setupterm()</CODE> for each terminal, and saving and restoring
-<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at
-once.  <CODE>Setupterm()</CODE> also stores the names section of the terminal
-description in the global character array <CODE>ttytype[]</CODE>.  Subsequent calls
-to <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it
-yourself if need be.
-</DL>
-
-<H3><A NAME="debugging">Debugging</A></H3>
-
-<!-- The 'note' tag is not portable enough -->
-<blockquote>
-<strong>NOTE:</strong> These functions are not part of the standard curses API!
-</blockquote>
-
-<DL>
-<DT> <CODE>trace()</CODE>
-<DD>
-This function can be used to explicitly set a trace level.  If the
-trace level is nonzero, execution of your program will generate a file
-called `trace' in the current working directory containing a report on
-the library's actions.  Higher trace levels enable more detailed (and
-verbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines
-in the <CODE>curses.h</CODE> file for details.  (It is also possible to set
-a trace level by assigning a trace level value to the environment variable
-<CODE>NCURSES_TRACE</CODE>).
-<DT> <CODE>_tracef()</CODE>
-<DD>
-This function can be used to output your own debugging information.  It is only
-available only if you link with -lncurses_g.  It can be used the same way as
-<CODE>printf()</CODE>, only it outputs a newline after the end of arguments.
-The output goes to a file called <CODE>trace</CODE> in the current directory.
-</DL>
-
-Trace logs can be difficult to interpret due to the sheer volume of
-data dumped in them.  There is a script called <STRONG>tracemunch</STRONG>
-included with the <CODE>ncurses</CODE> distribution that can alleviate
-this problem somewhat; it compacts long sequences of similar operations into
-more succinct single-line pseudo-operations. These pseudo-ops can be
-distinguished by the fact that they are named in capital letters.
-
-<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2>
-
-The <CODE>ncurses</CODE> manual pages are a complete reference for this library.
-In the remainder of this document, we discuss various useful methods that
-may not be obvious from the manual page descriptions.
-
-<H3><A NAME="caution">Some Notes of Caution</A></H3>
-
-If you find yourself thinking you need to use <CODE>noraw()</CODE> or
-<CODE>nocbreak()</CODE>, think again and move carefully.  It's probably
-better design to use <CODE>getstr()</CODE> or one of its relatives to
-simulate cooked mode.  The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE>
-functions try to restore cooked mode, but they may end up clobbering
-some control bits set before you started your application.  Also, they
-have always been poorly documented, and are likely to hurt your
-application's usability with other curses libraries. <P>
-
-Bear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>.
-Don't try to mix use of <CODE>stdscr</CODE> with use of windows declared
-by <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the
-screen.  The right way to handle this is to use <CODE>subwin()</CODE>, or
-not touch <CODE>stdscr</CODE> at all and tile your screen with declared
-windows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program
-event loop, with a single <CODE>doupdate()</CODE> call to trigger actual
-repainting. <P>
-
-You are much less likely to run into problems if you design your screen
-layouts to use tiled rather than overlapping windows.  Historically,
-curses support for overlapping windows has been weak, fragile, and poorly
-documented.  The <CODE>ncurses</CODE> library is not yet an exception to this
-rule. <P>
-
-There is a panels library included in the <CODE>ncurses</CODE>
-distribution that does a pretty good job of strengthening the
-overlapping-windows facilities. <P>
-
-Try to avoid using the global variables LINES and COLS.  Use
-<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> context instead.  Reason:
-your code may be ported to run in an environment with window resizes,
-in which case several screens could be open with different sizes.
-
-<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3>
-
-Sometimes you will want to write a program that spends most of its time in
-screen mode, but occasionally returns to ordinary `cooked' mode.  A common
-reason for this is to support shell-out.  This behavior is simple to arrange
-in <CODE>ncurses</CODE>. <P>
-
-To leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you
-were intending to terminate the program.  This will take the screen back to
-cooked mode; you can do your shell-out.  When you want to return to
-<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>.
-This will repaint the screen. <P>
-
-There is a boolean function, <CODE>isendwin()</CODE>, which code can use to
-test whether <CODE>ncurses</CODE> screen mode is active.  It returns <CODE>TRUE</CODE>
-in the interval between an <CODE>endwin()</CODE> call and the following
-<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise.  <P>
-
-Here is some sample code for shellout:
-
-<PRE>
+</pre>
+
+  <h3><a name="starting" id="starting">Starting up</a></h3>
+
+  <p>In order to use the screen package, the routines must know
+  about terminal characteristics, and the space for
+  <code>curscr</code> and <code>stdscr</code> must be allocated.
+  These function <code>initscr()</code> does both these things.
+  Since it must allocate space for the windows, it can overflow
+  memory when attempting to do so. On the rare occasions this
+  happens, <code>initscr()</code> will terminate the program with
+  an error message. <code>initscr()</code> must always be called
+  before any of the routines which affect windows are used. If it
+  is not, the program will core dump as soon as either
+  <code>curscr</code> or <code>stdscr</code> are referenced.
+  However, it is usually best to wait to call it until after you
+  are sure you will need it, like after checking for startup
+  errors. Terminal status changing routines like <code>nl()</code>
+  and <code>cbreak()</code> should be called after
+  <code>initscr()</code>.</p>
+
+  <p>Once the screen windows have been allocated, you can set them
+  up for your program. If you want to, say, allow a screen to
+  scroll, use <code>scrollok()</code>. If you want the cursor to be
+  left in place after the last change, use <code>leaveok()</code>.
+  If this is not done, <code>refresh()</code> will move the cursor
+  to the window's current (y, x) coordinates after updating it.</p>
+
+  <p>You can create new windows of your own using the functions
+  <code>newwin()</code>, <code>derwin()</code>, and
+  <code>subwin()</code>. The routine <code>delwin()</code> will
+  allow you to get rid of old windows. All the options described
+  above can be applied to any window.</p>
+
+  <h3><a name="output" id="output">Output</a></h3>
+
+  <p>Now that we have set things up, we will want to actually
+  update the terminal. The basic functions used to change what will
+  go on a window are <code>addch()</code> and <code>move()</code>.
+  <code>addch()</code> adds a character at the current (y, x)
+  coordinates. <code>move()</code> changes the current (y, x)
+  coordinates to whatever you want them to be. It returns
+  <code>ERR</code> if you try to move off the window. As mentioned
+  above, you can combine the two into <code>mvaddch()</code> to do
+  both things at once.</p>
+
+  <p>The other output functions, such as <code>addstr()</code> and
+  <code>printw()</code>, all call <code>addch()</code> to add
+  characters to the window.</p>
+
+  <p>After you have put on the window what you want there, when you
+  want the portion of the terminal covered by the window to be made
+  to look like it, you must call <code>refresh()</code>. In order
+  to optimize finding changes, <code>refresh()</code> assumes that
+  any part of the window not changed since the last
+  <code>refresh()</code> of that window has not been changed on the
+  terminal, i.e., that you have not refreshed a portion of the
+  terminal with an overlapping window. If this is not the case, the
+  routine <code>touchwin()</code> is provided to make it look like
+  the entire window has been changed, thus making
+  <code>refresh()</code> check the whole subsection of the terminal
+  for changes.</p>
+
+  <p>If you call <code>wrefresh()</code> with <code>curscr</code>
+  as its argument, it will make the screen look like
+  <code>curscr</code> thinks it looks like. This is useful for
+  implementing a command which would redraw the screen in case it
+  get messed up.</p>
+
+  <h3><a name="input" id="input">Input</a></h3>
+
+  <p>The complementary function to <code>addch()</code> is
+  <code>getch()</code> which, if echo is set, will call
+  <code>addch()</code> to echo the character. Since the screen
+  package needs to know what is on the terminal at all times, if
+  characters are to be echoed, the tty must be in raw or cbreak
+  mode. Since initially the terminal has echoing enabled and is in
+  ordinary &ldquo;cooked&rdquo; mode, one or the other has to
+  changed before calling <code>getch()</code>; otherwise, the
+  program's output will be unpredictable.</p>
+
+  <p>When you need to accept line-oriented input in a window, the
+  functions <code>wgetstr()</code> and friends are available. There
+  is even a <code>wscanw()</code> function that can do
+  <code>scanf()</code>(3)-style multi-field parsing on window
+  input. These pseudo-line-oriented functions turn on echoing while
+  they execute.</p>
+
+  <p>The example code above uses the call <code>keypad(stdscr,
+  TRUE)</code> to enable support for function-key mapping. With
+  this feature, the <code>getch()</code> code watches the input
+  stream for character sequences that correspond to arrow and
+  function keys. These sequences are returned as pseudo-character
+  values. The <code>#define</code> values returned are listed in
+  the <code>curses.h</code> The mapping from sequences to
+  <code>#define</code> values is determined by <code>key_</code>
+  capabilities in the terminal's terminfo entry.</p>
+
+  <h3><a name="formschars" id="formschars">Using Forms
+  Characters</a></h3>
+
+  <p>The <code>addch()</code> function (and some others, including
+  <code>box()</code> and <code>border()</code>) can accept some
+  pseudo-character arguments which are specially defined by
+  <code>ncurses</code>. These are <code>#define</code> values set
+  up in the <code>curses.h</code> header; see there for a complete
+  list (look for the prefix <code>ACS_</code>).</p>
+
+  <p>The most useful of the ACS defines are the forms-drawing
+  characters. You can use these to draw boxes and simple graphs on
+  the screen. If the terminal does not have such characters,
+  <code>curses.h</code> will map them to a recognizable (though
+  ugly) set of ASCII defaults.</p>
+
+  <h3><a name="attributes" id="attributes">Character Attributes and
+  Color</a></h3>
+
+  <p>The <code>ncurses</code> package supports screen highlights
+  including standout, reverse-video, underline, and blink. It also
+  supports color, which is treated as another kind of
+  highlight.</p>
+
+  <p>Highlights are encoded, internally, as high bits of the
+  pseudo-character type (<code>chtype</code>) that
+  <code>curses.h</code> uses to represent the contents of a screen
+  cell. See the <code>curses.h</code> header file for a complete
+  list of highlight mask values (look for the prefix
+  <code>A_</code>).</p>
+
+  <p>There are two ways to make highlights. One is to logical-or
+  the value of the highlights you want into the character argument
+  of an <code>addch()</code> call, or any other output call that
+  takes a <code>chtype</code> argument.</p>
+
+  <p>The other is to set the current-highlight value. This is
+  <em>logical-OR</em>ed with any highlight you specify the first
+  way. You do this with the functions <code>attron()</code>,
+  <code>attroff()</code>, and <code>attrset()</code>; see the
+  manual pages for details. Color is a special kind of highlight.
+  The package actually thinks in terms of color pairs, combinations
+  of foreground and background colors. The sample code above sets
+  up eight color pairs, all of the guaranteed-available colors on
+  black. Note that each color pair is, in effect, given the name of
+  its foreground color. Any other range of eight non-conflicting
+  values could have been used as the first arguments of the
+  <code>init_pair()</code> values.</p>
+
+  <p>Once you have done an <code>init_pair()</code> that creates
+  color-pair N, you can use <code>COLOR_PAIR(N)</code> as a
+  highlight that invokes that particular color combination. Note
+  that <code>COLOR_PAIR(N)</code>, for constant N, is itself a
+  compile-time constant and can be used in initializers.</p>
+
+  <h3><a name="mouse" id="mouse">Mouse Interfacing</a></h3>
+
+  <p>The <code>ncurses</code> library also provides a mouse
+  interface.</p>
+
+  <blockquote>
+    <strong>NOTE:</strong> this facility is specific to
+    <code>ncurses</code>, it is not part of either the XSI Curses
+    standard, nor of System V Release 4, nor BSD curses. System V
+    Release 4 curses contains code with similar interface
+    definitions, however it is not documented. Other than by
+    disassembling the library, we have no way to determine exactly
+    how that mouse code works. Thus, we recommend that you wrap
+    mouse-related code in an #ifdef using the feature macro
+    NCURSES_MOUSE_VERSION so it will not be compiled and linked on
+    non-ncurses systems.
+  </blockquote>
+
+  <p>Presently, mouse event reporting works in the following
+  environments:</p>
+
+  <ul>
+    <li>xterm and similar programs such as rxvt.</li>
+
+    <li>Linux console, when configured with <code>gpm</code>(1),
+    Alessandro Rubini's mouse server.</li>
+
+    <li>FreeBSD sysmouse (console)</li>
+
+    <li>OS/2 EMX</li>
+  </ul>
+
+  <p>The mouse interface is very simple. To activate it, you use
+  the function <code>mousemask()</code>, passing it as first
+  argument a bit-mask that specifies what kinds of events you want
+  your program to be able to see. It will return the bit-mask of
+  events that actually become visible, which may differ from the
+  argument if the mouse device is not capable of reporting some of
+  the event types you specify.</p>
+
+  <p>Once the mouse is active, your application's command loop
+  should watch for a return value of <code>KEY_MOUSE</code> from
+  <code>wgetch()</code>. When you see this, a mouse event report
+  has been queued. To pick it off the queue, use the function
+  <code>getmouse()</code> (you must do this before the next
+  <code>wgetch()</code>, otherwise another mouse event might come
+  in and make the first one inaccessible).</p>
+
+  <p>Each call to <code>getmouse()</code> fills a structure (the
+  address of which you will pass it) with mouse event data. The
+  event data includes zero-origin, screen-relative character-cell
+  coordinates of the mouse pointer. It also includes an event mask.
+  Bits in this mask will be set, corresponding to the event type
+  being reported.</p>
+
+  <p>The mouse structure contains two additional fields which may
+  be significant in the future as ncurses interfaces to new kinds
+  of pointing device. In addition to x and y coordinates, there is
+  a slot for a z coordinate; this might be useful with
+  touch-screens that can return a pressure or duration parameter.
+  There is also a device ID field, which could be used to
+  distinguish between multiple pointing devices.</p>
+
+  <p>The class of visible events may be changed at any time via
+  <code>mousemask()</code>. Events that can be reported include
+  presses, releases, single-, double- and triple-clicks (you can
+  set the maximum button-down time for clicks). If you do not make
+  clicks visible, they will be reported as press-release pairs. In
+  some environments, the event mask may include bits reporting the
+  state of shift, alt, and ctrl keys on the keyboard during the
+  event.</p>
+
+  <p>A function to check whether a mouse event fell within a given
+  window is also supplied. You can use this to see whether a given
+  window should consider a mouse event relevant to it.</p>
+
+  <p>Because mouse event reporting will not be available in all
+  environments, it would be unwise to build <code>ncurses</code>
+  applications that <em>require</em> the use of a mouse. Rather,
+  you should use the mouse as a shortcut for point-and-shoot
+  commands your application would normally accept from the
+  keyboard. Two of the test games in the <code>ncurses</code>
+  distribution (<code>bs</code> and <code>knight</code>) contain
+  code that illustrates how this can be done.</p>
+
+  <p>See the manual page <code>curs_mouse(3X)</code> for full
+  details of the mouse-interface functions.</p>
+
+  <h3><a name="finishing" id="finishing">Finishing Up</a></h3>
+
+  <p>In order to clean up after the <code>ncurses</code> routines,
+  the routine <code>endwin()</code> is provided. It restores tty
+  modes to what they were when <code>initscr()</code> was first
+  called, and moves the cursor down to the lower-left corner. Thus,
+  anytime after the call to initscr, <code>endwin()</code> should
+  be called before exiting.</p>
+
+  <h2><a name="functions" id="functions">Function
+  Descriptions</a></h2>
+
+  <p>We describe the detailed behavior of some important curses
+  functions here, as a supplement to the manual page
+  descriptions.</p>
+
+  <h3><a name="init" id="init">Initialization and Wrapup</a></h3>
+
+  <dl>
+    <dt><code>initscr()</code></dt>
+
+    <dd>The first function called should almost always be
+    <code>initscr()</code>. This will determine the terminal type
+    and initialize curses data structures. <code>initscr()</code>
+    also arranges that the first call to <code>refresh()</code>
+    will clear the screen. If an error occurs a message is written
+    to standard error and the program exits. Otherwise it returns a
+    pointer to stdscr. A few functions may be called before initscr
+    (<code>slk_init()</code>, <code>filter()</code>,
+    <code>ripoffline()</code>, <code>use_env()</code>, and, if you
+    are using multiple terminals, <code>newterm()</code>.)</dd>
+
+    <dt><code>endwin()</code></dt>
+
+    <dd>Your program should always call <code>endwin()</code>
+    before exiting or shelling out of the program. This function
+    will restore tty modes, move the cursor to the lower left
+    corner of the screen, reset the terminal into the proper
+    non-visual mode. Calling <code>refresh()</code> or
+    <code>doupdate()</code> after a temporary escape from the
+    program will restore the ncurses screen from before the
+    escape.</dd>
+
+    <dt><code>newterm(type, ofp, ifp)</code></dt>
+
+    <dd>A program which outputs to more than one terminal should
+    use <code>newterm()</code> instead of <code>initscr()</code>.
+    <code>newterm()</code> should be called once for each terminal.
+    It returns a variable of type <code>SCREEN *</code> which
+    should be saved as a reference to that terminal. (NOTE: a
+    SCREEN variable is not a <em>screen</em> in the sense we are
+    describing in this introduction, but a collection of parameters
+    used to assist in optimizing the display.) The arguments are
+    the type of the terminal (a string) and <code>FILE</code>
+    pointers for the output and input of the terminal. If type is
+    NULL then the environment variable <code>$TERM</code> is used.
+    <code>endwin()</code> should called once at wrapup time for
+    each terminal opened using this function.</dd>
+
+    <dt><code>set_term(new)</code></dt>
+
+    <dd>This function is used to switch to a different terminal
+    previously opened by <code>newterm()</code>. The screen
+    reference for the new terminal is passed as the parameter. The
+    previous terminal is returned by the function. All other calls
+    affect only the current terminal.</dd>
+
+    <dt><code>delscreen(sp)</code></dt>
+
+    <dd>The inverse of <code>newterm()</code>; deallocates the data
+    structures associated with a given <code>SCREEN</code>
+    reference.</dd>
+  </dl>
+
+  <h3><a name="flush" id="flush">Causing Output to the
+  Terminal</a></h3>
+
+  <dl>
+    <dt><code>refresh()</code> and <code>wrefresh(win)</code></dt>
+
+    <dd>These functions must be called to actually get any output
+    on the terminal, as other routines merely manipulate data
+    structures. <code>wrefresh()</code> copies the named window to
+    the physical terminal screen, taking into account what is
+    already there in order to do optimizations.
+    <code>refresh()</code> does a refresh of <code>stdscr</code>.
+    Unless <code>leaveok()</code> has been enabled, the physical
+    cursor of the terminal is left at the location of the window's
+    cursor.</dd>
+
+    <dt><code>doupdate()</code> and
+    <code>wnoutrefresh(win)</code></dt>
+
+    <dd>These two functions allow multiple updates with more
+    efficiency than wrefresh. To use them, it is important to
+    understand how curses works. In addition to all the window
+    structures, curses keeps two data structures representing the
+    terminal screen: a physical screen, describing what is actually
+    on the screen, and a virtual screen, describing what the
+    programmer wants to have on the screen. wrefresh works by first
+    copying the named window to the virtual screen
+    (<code>wnoutrefresh()</code>), and then calling the routine to
+    update the screen (<code>doupdate()</code>). If the programmer
+    wishes to output several windows at once, a series of calls to
+    <code>wrefresh</code> will result in alternating calls to
+    <code>wnoutrefresh()</code> and <code>doupdate()</code>,
+    causing several bursts of output to the screen. By calling
+    <code>wnoutrefresh()</code> for each window, it is then
+    possible to call <code>doupdate()</code> once, resulting in
+    only one burst of output, with fewer total characters
+    transmitted (this also avoids a visually annoying flicker at
+    each update).</dd>
+  </dl>
+
+  <h3><a name="lowlevel" id="lowlevel">Low-Level Capability
+  Access</a></h3>
+
+  <dl>
+    <dt><code>setupterm(term, filenum, errret)</code></dt>
+
+    <dd>
+      This routine is called to initialize a terminal's
+      description, without setting up the curses screen structures
+      or changing the tty-driver mode bits. <code>term</code> is
+      the character string representing the name of the terminal
+      being used. <code>filenum</code> is the UNIX file descriptor
+      of the terminal to be used for output. <code>errret</code> is
+      a pointer to an integer, in which a success or failure
+      indication is returned. The values returned can be 1 (all is
+      well), 0 (no such terminal), or -1 (some problem locating the
+      terminfo database).
+
+      <p>The value of <code>term</code> can be given as NULL, which
+      will cause the value of <code>TERM</code> in the environment
+      to be used. The <code>errret</code> pointer can also be given
+      as NULL, meaning no error code is wanted. If
+      <code>errret</code> is defaulted, and something goes wrong,
+      <code>setupterm()</code> will print an appropriate error
+      message and exit, rather than returning. Thus, a simple
+      program can call setupterm(0, 1, 0) and not worry about
+      initialization errors.</p>
+
+      <p>After the call to <code>setupterm()</code>, the global
+      variable <code>cur_term</code> is set to point to the current
+      structure of terminal capabilities. By calling
+      <code>setupterm()</code> for each terminal, and saving and
+      restoring <code>cur_term</code>, it is possible for a program
+      to use two or more terminals at once.
+      <code>Setupterm()</code> also stores the names section of the
+      terminal description in the global character array
+      <code>ttytype[]</code>. Subsequent calls to
+      <code>setupterm()</code> will overwrite this array, so you
+      will have to save it yourself if need be.</p>
+    </dd>
+  </dl>
+
+  <h3><a name="debugging" id="debugging">Debugging</a></h3>
+
+  <blockquote>
+    <strong>NOTE:</strong> These functions are not part of the
+    standard curses API!
+  </blockquote>
+
+  <dl>
+    <dt><code>trace()</code></dt>
+
+    <dd>This function can be used to explicitly set a trace level.
+    If the trace level is nonzero, execution of your program will
+    generate a file called &ldquo;trace&rdquo; in the current
+    working directory containing a report on the library's actions.
+    Higher trace levels enable more detailed (and verbose)
+    reporting -- see comments attached to <code>TRACE_</code>
+    defines in the <code>curses.h</code> file for details. (It is
+    also possible to set a trace level by assigning a trace level
+    value to the environment variable
+    <code>NCURSES_TRACE</code>).</dd>
+
+    <dt><code>_tracef()</code></dt>
+
+    <dd>This function can be used to output your own debugging
+    information. It is only available only if you link with
+    -lncurses_g. It can be used the same way as
+    <code>printf()</code>, only it outputs a newline after the end
+    of arguments. The output goes to a file called
+    <code>trace</code> in the current directory.</dd>
+  </dl>
+
+  <p>Trace logs can be difficult to interpret due to the sheer
+  volume of data dumped in them. There is a script called
+  <strong>tracemunch</strong> included with the
+  <code>ncurses</code> distribution that can alleviate this problem
+  somewhat; it compacts long sequences of similar operations into
+  more succinct single-line pseudo-operations. These pseudo-ops can
+  be distinguished by the fact that they are named in capital
+  letters.</p>
+
+  <h2><a name="hints" id="hints">Hints, Tips, and Tricks</a></h2>
+
+  <p>The <code>ncurses</code> manual pages are a complete reference
+  for this library. In the remainder of this document, we discuss
+  various useful methods that may not be obvious from the manual
+  page descriptions.</p>
+
+  <h3><a name="caution" id="caution">Some Notes of Caution</a></h3>
+
+  <p>If you find yourself thinking you need to use
+  <code>noraw()</code> or <code>nocbreak()</code>, think again and
+  move carefully. It is probably better design to use
+  <code>getstr()</code> or one of its relatives to simulate cooked
+  mode. The <code>noraw()</code> and <code>nocbreak()</code>
+  functions try to restore cooked mode, but they may end up
+  clobbering some control bits set before you started your
+  application. Also, they have always been poorly documented, and
+  are likely to hurt your application's usability with other curses
+  libraries.</p>
+
+  <p>Bear in mind that <code>refresh()</code> is a synonym for
+  <code>wrefresh(stdscr)</code>. Do not try to mix use of
+  <code>stdscr</code> with use of windows declared by
+  <code>newwin()</code>; a <code>refresh()</code> call will blow
+  them off the screen. The right way to handle this is to use
+  <code>subwin()</code>, or not touch <code>stdscr</code> at all
+  and tile your screen with declared windows which you then
+  <code>wnoutrefresh()</code> somewhere in your program event loop,
+  with a single <code>doupdate()</code> call to trigger actual
+  repainting.</p>
+
+  <p>You are much less likely to run into problems if you design
+  your screen layouts to use tiled rather than overlapping windows.
+  Historically, curses support for overlapping windows has been
+  weak, fragile, and poorly documented. The <code>ncurses</code>
+  library is not yet an exception to this rule.</p>
+
+  <p>There is a panels library included in the <code>ncurses</code>
+  distribution that does a pretty good job of strengthening the
+  overlapping-windows facilities.</p>
+
+  <p>Try to avoid using the global variables LINES and COLS. Use
+  <code>getmaxyx()</code> on the <code>stdscr</code> context
+  instead. Reason: your code may be ported to run in an environment
+  with window resizes, in which case several screens could be open
+  with different sizes.</p>
+
+  <h3><a name="leaving" id="leaving">Temporarily Leaving NCURSES
+  Mode</a></h3>
+
+  <p>Sometimes you will want to write a program that spends most of
+  its time in screen mode, but occasionally returns to ordinary
+  &ldquo;cooked&rdquo; mode. A common reason for this is to support
+  shell-out. This behavior is simple to arrange in
+  <code>ncurses</code>.</p>
+
+  <p>To leave <code>ncurses</code> mode, call <code>endwin()</code>
+  as you would if you were intending to terminate the program. This
+  will take the screen back to cooked mode; you can do your
+  shell-out. When you want to return to <code>ncurses</code> mode,
+  simply call <code>refresh()</code> or <code>doupdate()</code>.
+  This will repaint the screen.</p>
+
+  <p>There is a boolean function, <code>isendwin()</code>, which
+  code can use to test whether <code>ncurses</code> screen mode is
+  active. It returns <code>TRUE</code> in the interval between an
+  <code>endwin()</code> call and the following
+  <code>refresh()</code>, <code>FALSE</code> otherwise.</p>
+
+  <p>Here is some sample code for shellout:</p>
+  <pre>
     addstr("Shelling out...");
     def_prog_mode();           /* save current tty modes */
     endwin();                  /* restore original tty modes */
     system("sh");              /* run shell */
     addstr("returned.\n");     /* prepare return message */
     refresh();                 /* restore save modes, repaint screen */
-</PRE>
-
-<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3>
-
-A resize operation in X sends <CODE>SIGWINCH</CODE> to the application running
-under xterm.
-
-The easiest way to handle <CODE>SIGWINCH</CODE>
-is to do an <CODE>endwin</CODE>,
-followed by an <CODE>refresh</CODE> and a screen repaint you code
-yourself.
-The <CODE>refresh</CODE> will pick up the new screen size from the
-xterm's environment. <P>
-
-That is the standard way, of course (it even works with some vendor's curses
-implementations).
-Its drawback is that it clears the screen to reinitialize the display, and does
-not resize subwindows which must be shrunk.
-<CODE>Ncurses</CODE> provides an extension which works better, the
-<CODE>resizeterm</CODE> function.  That function ensures that all windows
-are limited to the new screen dimensions, and pads <CODE>stdscr</CODE>
-with blanks if the screen is larger. <P>
-
-The <CODE>ncurses</CODE> library provides a SIGWINCH signal handler,
-which pushes a <CODE>KEY_RESIZE</CODE> via the wgetch() calls.
-When <CODE>ncurses</CODE> returns that code,
-it calls <code>resizeterm</CODE>
-to update the size of the standard screen's window, repainting that
-(filling with blanks or truncating as needed).
-It also resizes other windows,
-but its effect may be less satisfactory because it cannot
-know how you want the screen re-painted.
-You will usually have to write special-purpose code to handle
-<CODE>KEY_RESIZE</CODE> yourself.
-
-<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3>
-
-The <CODE>initscr()</CODE> function actually calls a function named
-<CODE>newterm()</CODE> to do most of its work.  If you are writing a program that
-opens multiple terminals, use <CODE>newterm()</CODE> directly. <P>
-
-For each call, you will have to specify a terminal type and a pair of file
-pointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be
-set to the last one allocated.  You will switch between screens with the
-<CODE>set_term</CODE> call.  Note that you will also have to call
-<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself.
-
-<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3>
-
-Sometimes you may want to write programs that test for the presence of various
-capabilities before deciding whether to go into <CODE>ncurses</CODE> mode.  An easy
-way to do this is to call <CODE>setupterm()</CODE>, then use the functions
-<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your
-testing. <P>
-
-A particularly useful case of this often comes up when you want to
-test whether a given terminal type should be treated as `smart'
-(cursor-addressable) or `stupid'.  The right way to test this is to see
-if the return value of <CODE>tigetstr("cup")</CODE> is non-NULL.  Alternatively,
-you can include the <CODE>term.h</CODE> file and test the value of the
-macro <CODE>cursor_address</CODE>.
-
-<H3><A NAME="tuning">Tuning for Speed</A></H3>
-
-Use the <CODE>addchstr()</CODE> family of functions for fast
-screen-painting of text when you know the text doesn't contain any
-control characters.  Try to make attribute changes infrequent on your
-screens.  Don't use the <CODE>immedok()</CODE> option!
-
-<H3><A NAME="special">Special Features of NCURSES</A></H3>
-
-The <CODE>wresize()</CODE> function allows you to resize a window in place.
-The associated <CODE>resizeterm()</CODE> function simplifies the construction
-of <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows.  <P>
-
-The <CODE>define_key()</CODE> function allows you
-to define at runtime function-key control sequences which are not in the
-terminal description.
-The <CODE>keyok()</CODE> function allows you to temporarily
-enable or disable interpretation of any function-key control sequence. <P>
-
-The <CODE>use_default_colors()</CODE> function allows you to construct
-applications which can use the terminal's default foreground and
-background colors as an additional "default" color.
-Several terminal emulators support this feature, which is based on ISO 6429. <P>
-
-Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8.
-While most terminals which provide color allow only 8 colors, about
-a quarter (including XFree86 xterm) support 16 colors.
-
-<H2><A NAME="compat">Compatibility with Older Versions</A></H2>
-
-Despite our best efforts, there are some differences between <CODE>ncurses</CODE>
-and the (undocumented!) behavior of older curses implementations.  These arise
-from ambiguities or omissions in the documentation of the API.
-
-<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3>
-
-If you define two windows A and B that overlap, and then alternately scribble
-on and refresh them, the changes made to the overlapping region under historic
-<CODE>curses</CODE> versions were often not documented precisely. <P>
-
-To understand why this is a problem, remember that screen updates are
-calculated between two representations of the <EM>entire</EM> display. The
-documentation says that when you refresh a window, it is first copied to the
-virtual screen, and then changes are calculated to update the physical screen
-(and applied to the terminal).  But "copied to" is not very specific, and
-subtle differences in how copying works can produce different behaviors in the
-case where two overlapping windows are each being refreshed at unpredictable
-intervals. <P>
-
-What happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE>
-does with its argument -- what portions of the argument window it copies to the
-virtual screen.  Some implementations do "change copy", copying down only
-locations in the window that have changed (or been marked changed with
-<CODE>wtouchln()</CODE> and friends).  Some implementations do  "entire copy",
-copying <EM>all</EM> window locations to the virtual screen whether or not
-they have changed. <P>
-
-The <CODE>ncurses</CODE> library itself has not always been consistent on this
-score.  Due to a bug, versions 1.8.7 to 1.9.8a did entire copy.  Versions
-1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P>
-
-For most commercial curses implementations, it is not documented and not known
-for sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do
-change copy or entire copy.  We know that System V release 3 curses has logic
-in it that looks like an attempt to do change copy, but the surrounding logic
-and data representations are sufficiently complex, and our knowledge
-sufficiently indirect, that it's hard to know whether this is reliable.
-
-It is not clear what the SVr4 documentation and XSI standard intend.  The XSI
-Curses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be
-describing entire-copy, but it is possible with some effort and straining to
-read them the other way. <P>
-
-It might therefore be unwise to rely on either behavior in programs that might
-have to be linked with other curses implementations.  Instead, you can do an
-explicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to
-guarantee an entire-contents copy anywhere. <P>
-
-The really clean way to handle this is to use the panels library.  If,
-when you want a screen update, you do <CODE>update_panels()</CODE>, it will
-do all the necessary <CODE>wnoutrefresh()</CODE> calls for whatever panel
-stacking order you have defined.  Then you can do one <CODE>doupdate()</CODE>
-and there will be a <EM>single</EM> burst of physical I/O that will do
-all your updates.
-
-<H3><A NAME="backbug">Background Erase</A></H3>
-
-If you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or
-older) you may be surprised by the behavior of the erase functions.  In older
-versions, erased areas of a window were filled with a blank modified by the
-window's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>,
-<STRONG>wattroff()</STRONG> and friends). <P>
-
-In newer versions, this is not so.  Instead, the attribute of erased blanks
-is normal unless and until it is modified by the functions <CODE>bkgdset()</CODE>
-or <CODE>wbkgdset()</CODE>. <P>
-
-This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and
-the XSI Curses standard.
-
-<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2>
-
-The <CODE>ncurses</CODE> library is intended to be base-level conformant with the
-XSI Curses standard from X/Open.  Many extended-level features (in fact, almost
-all features not directly concerned with wide characters and
-internationalization) are also supported. <P>
-
-One effect of XSI conformance is the change in behavior described under
-<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P>
-
-Also, <CODE>ncurses</CODE> meets the XSI requirement that every macro
-entry point have a corresponding function which may be linked (and
-will be prototype-checked) if the macro definition is disabled with
-<CODE>#undef</CODE>.
-
-<H1><A NAME="panels">The Panels Library</A></H1>
-
-The <CODE>ncurses</CODE> library by itself provides good support for screen
-displays in which the windows are tiled (non-overlapping).  In the more
-general case that windows may overlap, you have to use a series of
-<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be
-careful about the order you do the window refreshes in.  It has to be
-bottom-upwards, otherwise parts of windows that should be obscured will
-show through. <P>
-
-When your interface design is such that windows may dive deeper into the
-visibility stack or pop to the top at runtime, the resulting book-keeping
-can be tedious and difficult to get right.  Hence the panels library. <P>
-
-The <CODE>panel</CODE> library first appeared in AT&amp;T System V.  The
-version documented here is the <CODE>panel</CODE> code distributed
-with <CODE>ncurses</CODE>.
-
-<H2><A NAME="pcompile">Compiling With the Panels Library</A></H2>
-
-Your panels-using modules must import the panels library declarations with
-
-<PRE>
-         #include &lt;panel.h&gt;
-</PRE>
-
-and must be linked explicitly with the panels library using an
-<CODE>-lpanel</CODE> argument.  Note that they must also link the
-<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>.  Many linkers
-are two-pass and will accept either order, but it is still good practice
-to put <CODE>-lpanel</CODE> first and <CODE>-lncurses</CODE> second.
-
-<H2><A NAME="poverview">Overview of Panels</A></H2>
-
-A panel object is a window that is implicitly treated as part of a
-<DFN>deck</DFN> including all other panel objects.  The deck has an implicit
-bottom-to-top visibility order.  The panels library includes an update
-function (analogous to <CODE>refresh()</CODE>) that displays all panels in the
-deck in the proper order to resolve overlaps.  The standard window,
-<CODE>stdscr</CODE>, is considered below all panels. <P>
-
-Details on the panels functions are available in the man pages.  We'll just
-hit the highlights here. <P>
-
-You create a panel from a window by calling <CODE>new_panel()</CODE> on a
-window pointer.  It then becomes the top of the deck.  The panel's window
-is available as the value of <CODE>panel_window()</CODE> called with the
-panel pointer as argument.<P>
-
-You can delete a panel (removing it from the deck) with <CODE>del_panel</CODE>.
-This will not deallocate the associated window; you have to do that yourself.
+</pre>
+
+  <h3><a name="xterm" id="xterm">Using NCURSES under XTERM</a></h3>
+
+  <p>A resize operation in X sends <code>SIGWINCH</code> to the
+  application running under xterm. The easiest way to handle
+  <code>SIGWINCH</code> is to do an <code>endwin</code>, followed
+  by an <code>refresh</code> and a screen repaint you code
+  yourself. The <code>refresh</code> will pick up the new screen
+  size from the xterm's environment.</p>
+
+  <p>That is the standard way, of course (it even works with some
+  vendor's curses implementations). Its drawback is that it clears
+  the screen to reinitialize the display, and does not resize
+  subwindows which must be shrunk. <code>Ncurses</code> provides an
+  extension which works better, the <code>resizeterm</code>
+  function. That function ensures that all windows are limited to
+  the new screen dimensions, and pads <code>stdscr</code> with
+  blanks if the screen is larger.</p>
+
+  <p>The <code>ncurses</code> library provides a SIGWINCH signal
+  handler, which pushes a <code>KEY_RESIZE</code> via the wgetch()
+  calls. When <code>ncurses</code> returns that code, it calls
+  <code>resizeterm</code> to update the size of the standard
+  screen's window, repainting that (filling with blanks or
+  truncating as needed). It also resizes other windows, but its
+  effect may be less satisfactory because it cannot know how you
+  want the screen re-painted. You will usually have to write
+  special-purpose code to handle <code>KEY_RESIZE</code>
+  yourself.</p>
+
+  <h3><a name="screens" id="screens">Handling Multiple Terminal
+  Screens</a></h3>
+
+  <p>The <code>initscr()</code> function actually calls a function
+  named <code>newterm()</code> to do most of its work. If you are
+  writing a program that opens multiple terminals, use
+  <code>newterm()</code> directly.</p>
+
+  <p>For each call, you will have to specify a terminal type and a
+  pair of file pointers; each call will return a screen reference,
+  and <code>stdscr</code> will be set to the last one allocated.
+  You will switch between screens with the <code>set_term</code>
+  call. Note that you will also have to call
+  <code>def_shell_mode</code> and <code>def_prog_mode</code> on
+  each tty yourself.</p>
+
+  <h3><a name="testing" id="testing">Testing for Terminal
+  Capabilities</a></h3>
+
+  <p>Sometimes you may want to write programs that test for the
+  presence of various capabilities before deciding whether to go
+  into <code>ncurses</code> mode. An easy way to do this is to call
+  <code>setupterm()</code>, then use the functions
+  <code>tigetflag()</code>, <code>tigetnum()</code>, and
+  <code>tigetstr()</code> to do your testing.</p>
+
+  <p>A particularly useful case of this often comes up when you
+  want to test whether a given terminal type should be treated as
+  &ldquo;smart&rdquo; (cursor-addressable) or &ldquo;stupid&rdquo;.
+  The right way to test this is to see if the return value of
+  <code>tigetstr("cup")</code> is non-NULL. Alternatively, you can
+  include the <code>term.h</code> file and test the value of the
+  macro <code>cursor_address</code>.</p>
+
+  <h3><a name="tuning" id="tuning">Tuning for Speed</a></h3>
+
+  <p>Use the <code>addchstr()</code> family of functions for fast
+  screen-painting of text when you know the text does not contain
+  any control characters. Try to make attribute changes infrequent
+  on your screens. Do not use the <code>immedok()</code>
+  option!</p>
+
+  <h3><a name="special" id="special">Special Features of
+  NCURSES</a></h3>
+
+  <p>The <code>wresize()</code> function allows you to resize a
+  window in place. The associated <code>resizeterm()</code>
+  function simplifies the construction of <a href=
+  "#xterm">SIGWINCH</a> handlers, for resizing all windows.</p>
+
+  <p>The <code>define_key()</code> function allows you to define at
+  runtime function-key control sequences which are not in the
+  terminal description. The <code>keyok()</code> function allows
+  you to temporarily enable or disable interpretation of any
+  function-key control sequence.</p>
+
+  <p>The <code>use_default_colors()</code> function allows you to
+  construct applications which can use the terminal's default
+  foreground and background colors as an additional "default"
+  color. Several terminal emulators support this feature, which is
+  based on ISO 6429.</p>
+
+  <p>Ncurses supports up 16 colors, unlike SVr4 curses which
+  defines only 8. While most terminals which provide color allow
+  only 8 colors, about a quarter (including XFree86 xterm) support
+  16 colors.</p>
+
+  <h2><a name="compat" id="compat">Compatibility with Older
+  Versions</a></h2>
+
+  <p>Despite our best efforts, there are some differences between
+  <code>ncurses</code> and the (undocumented!) behavior of older
+  curses implementations. These arise from ambiguities or omissions
+  in the documentation of the API.</p>
+
+  <h3><a name="refbug" id="refbug">Refresh of Overlapping
+  Windows</a></h3>
+
+  <p>If you define two windows A and B that overlap, and then
+  alternately scribble on and refresh them, the changes made to the
+  overlapping region under historic <code>curses</code> versions
+  were often not documented precisely.</p>
+
+  <p>To understand why this is a problem, remember that screen
+  updates are calculated between two representations of the
+  <em>entire</em> display. The documentation says that when you
+  refresh a window, it is first copied to the virtual screen, and
+  then changes are calculated to update the physical screen (and
+  applied to the terminal). But "copied to" is not very specific,
+  and subtle differences in how copying works can produce different
+  behaviors in the case where two overlapping windows are each
+  being refreshed at unpredictable intervals.</p>
+
+  <p>What happens to the overlapping region depends on what
+  <code>wnoutrefresh()</code> does with its argument -- what
+  portions of the argument window it copies to the virtual screen.
+  Some implementations do "change copy", copying down only
+  locations in the window that have changed (or been marked changed
+  with <code>wtouchln()</code> and friends). Some implementations
+  do "entire copy", copying <em>all</em> window locations to the
+  virtual screen whether or not they have changed.</p>
+
+  <p>The <code>ncurses</code> library itself has not always been
+  consistent on this score. Due to a bug, versions 1.8.7 to 1.9.8a
+  did entire copy. Versions 1.8.6 and older, and versions 1.9.9 and
+  newer, do change copy.</p>
+
+  <p>For most commercial curses implementations, it is not
+  documented and not known for sure (at least not to the
+  <code>ncurses</code> maintainers) whether they do change copy or
+  entire copy. We know that System V release 3 curses has logic in
+  it that looks like an attempt to do change copy, but the
+  surrounding logic and data representations are sufficiently
+  complex, and our knowledge sufficiently indirect, that it is hard
+  to know whether this is reliable. It is not clear what the SVr4
+  documentation and XSI standard intend. The XSI Curses standard
+  barely mentions wnoutrefresh(); the SVr4 documents seem to be
+  describing entire-copy, but it is possible with some effort and
+  straining to read them the other way.</p>
+
+  <p>It might therefore be unwise to rely on either behavior in
+  programs that might have to be linked with other curses
+  implementations. Instead, you can do an explicit
+  <code>touchwin()</code> before the <code>wnoutrefresh()</code>
+  call to guarantee an entire-contents copy anywhere.</p>
+
+  <p>The really clean way to handle this is to use the panels
+  library. If, when you want a screen update, you do
+  <code>update_panels()</code>, it will do all the necessary
+  <code>wnoutrefresh()</code> calls for whatever panel stacking
+  order you have defined. Then you can do one
+  <code>doupdate()</code> and there will be a <em>single</em> burst
+  of physical I/O that will do all your updates.</p>
+
+  <h3><a name="backbug" id="backbug">Background Erase</a></h3>
+
+  <p>If you have been using a very old versions of
+  <code>ncurses</code> (1.8.7 or older) you may be surprised by the
+  behavior of the erase functions. In older versions, erased areas
+  of a window were filled with a blank modified by the window's
+  current attribute (as set by <strong>wattrset()</strong>,
+  <strong>wattron()</strong>, <strong>wattroff()</strong> and
+  friends).</p>
+
+  <p>In newer versions, this is not so. Instead, the attribute of
+  erased blanks is normal unless and until it is modified by the
+  functions <code>bkgdset()</code> or <code>wbkgdset()</code>.</p>
+
+  <p>This change in behavior conforms <code>ncurses</code> to
+  System V Release 4 and the XSI Curses standard.</p>
+
+  <h2><a name="xsifuncs" id="xsifuncs">XSI Curses
+  Conformance</a></h2>
+
+  <p>The <code>ncurses</code> library is intended to be base-level
+  conformant with the XSI Curses standard from X/Open. Many
+  extended-level features (in fact, almost all features not
+  directly concerned with wide characters and internationalization)
+  are also supported.</p>
+
+  <p>One effect of XSI conformance is the change in behavior
+  described under <a href="#backbug">"Background Erase --
+  Compatibility with Old Versions"</a>.</p>
+
+  <p>Also, <code>ncurses</code> meets the XSI requirement that
+  every macro entry point have a corresponding function which may
+  be linked (and will be prototype-checked) if the macro definition
+  is disabled with <code>#undef</code>.</p>
+
+  <h1><a name="panels" id="panels">The Panels Library</a></h1>
+
+  <p>The <code>ncurses</code> library by itself provides good
+  support for screen displays in which the windows are tiled
+  (non-overlapping). In the more general case that windows may
+  overlap, you have to use a series of <code>wnoutrefresh()</code>
+  calls followed by a <code>doupdate()</code>, and be careful about
+  the order you do the window refreshes in. It has to be
+  bottom-upwards, otherwise parts of windows that should be
+  obscured will show through.</p>
+
+  <p>When your interface design is such that windows may dive
+  deeper into the visibility stack or pop to the top at runtime,
+  the resulting book-keeping can be tedious and difficult to get
+  right. Hence the panels library.</p>
+
+  <p>The <code>panel</code> library first appeared in AT&amp;T
+  System V. The version documented here is the <code>panel</code>
+  code distributed with <code>ncurses</code>.</p>
+
+  <h2><a name="pcompile" id="pcompile">Compiling With the Panels
+  Library</a></h2>
+
+  <p>Your panels-using modules must import the panels library
+  declarations with</p>
+  <pre>
+          #include &lt;panel.h&gt;
+</pre>
+
+  <p>and must be linked explicitly with the panels library using an
+  <code>-lpanel</code> argument. Note that they must also link the
+  <code>ncurses</code> library with <code>-lncurses</code>. Many
+  linkers are two-pass and will accept either order, but it is
+  still good practice to put <code>-lpanel</code> first and
+  <code>-lncurses</code> second.</p>
+
+  <h2><a name="poverview" id="poverview">Overview of
+  Panels</a></h2>
+
+  <p>A panel object is a window that is implicitly treated as part
+  of a <dfn>deck</dfn> including all other panel objects. The deck
+  has an implicit bottom-to-top visibility order. The panels
+  library includes an update function (analogous to
+  <code>refresh()</code>) that displays all panels in the deck in
+  the proper order to resolve overlaps. The standard window,
+  <code>stdscr</code>, is considered below all panels.</p>
+
+  <p>Details on the panels functions are available in the man
+  pages. We will just hit the highlights here.</p>
+
+  <p>You create a panel from a window by calling
+  <code>new_panel()</code> on a window pointer. It then becomes the
+  top of the deck. The panel's window is available as the value of
+  <code>panel_window()</code> called with the panel pointer as
+  argument.</p>
+
+  <p>You can delete a panel (removing it from the deck) with
+  <code>del_panel</code>. This will not deallocate the associated
+  window; you have to do that yourself. You can replace a panel's
+  window with a different window by calling
+  <code>replace_window</code>. The new window may be of different
+  size; the panel code will re-compute all overlaps. This operation
+  does not change the panel's position in the deck.</p>
+
+  <p>To move a panel's window, use <code>move_panel()</code>. The
+  <code>mvwin()</code> function on the panel's window is not
+  sufficient because it does not update the panels library's
+  representation of where the windows are. This operation leaves
+  the panel's depth, contents, and size unchanged.</p>
+
+  <p>Two functions (<code>top_panel()</code>,
+  <code>bottom_panel()</code>) are provided for rearranging the
+  deck. The first pops its argument window to the top of the deck;
+  the second sends it to the bottom. Either operation leaves the
+  panel's screen location, contents, and size unchanged.</p>
+
+  <p>The function <code>update_panels()</code> does all the
+  <code>wnoutrefresh()</code> calls needed to prepare for
+  <code>doupdate()</code> (which you must call yourself,
+  afterwards).</p>
+
+  <p>Typically, you will want to call <code>update_panels()</code>
+  and <code>doupdate()</code> just before accepting command input,
+  once in each cycle of interaction with the user. If you call
+  <code>update_panels()</code> after each and every panel write,
+  you will generate a lot of unnecessary refresh activity and
+  screen flicker.</p>
+
+  <h2><a name="pstdscr" id="pstdscr">Panels, Input, and the
+  Standard Screen</a></h2>
+
+  <p>You should not mix <code>wnoutrefresh()</code> or
+  <code>wrefresh()</code> operations with panels code; this will
+  work only if the argument window is either in the top panel or
+  unobscured by any other panels.</p>
+
+  <p>The <code>stsdcr</code> window is a special case. It is
+  considered below all panels. Because changes to panels may
+  obscure parts of <code>stdscr</code>, though, you should call
+  <code>update_panels()</code> before <code>doupdate()</code> even
+  when you only change <code>stdscr</code>.</p>
+
+  <p>Note that <code>wgetch</code> automatically calls
+  <code>wrefresh</code>. Therefore, before requesting input from a
+  panel window, you need to be sure that the panel is totally
+  unobscured.</p>
+
+  <p>There is presently no way to display changes to one obscured
+  panel without repainting all panels.</p>
+
+  <h2><a name="hiding" id="hiding">Hiding Panels</a></h2>
+
+  <p>It is possible to remove a panel from the deck temporarily;
+  use <code>hide_panel</code> for this. Use
+  <code>show_panel()</code> to render it visible again. The
+  predicate function <code>panel_hidden</code> tests whether or not
+  a panel is hidden.</p>
+
+  <p>The <code>panel_update</code> code ignores hidden panels. You
+  cannot do <code>top_panel()</code> or <code>bottom_panel</code>
+  on a hidden panel(). Other panels operations are applicable.</p>
+
+  <h2><a name="pmisc" id="pmisc">Miscellaneous Other
+  Facilities</a></h2>
+
+  <p>It is possible to navigate the deck using the functions
+  <code>panel_above()</code> and <code>panel_below</code>. Handed a
+  panel pointer, they return the panel above or below that panel.
+  Handed <code>NULL</code>, they return the bottom-most or top-most
+  panel.</p>
+
+  <p>Every panel has an associated user pointer, not used by the
+  panel code, to which you can attach application data. See the man
+  page documentation of <code>set_panel_userptr()</code> and
+  <code>panel_userptr</code> for details.</p>
+
+  <h1><a name="menu" id="menu">The Menu Library</a></h1>
+
+  <p>A menu is a screen display that assists the user to choose
+  some subset of a given set of items. The <code>menu</code>
+  library is a curses extension that supports easy programming of
+  menu hierarchies with a uniform but flexible interface.</p>
 
-You can replace a panel's window with a different window by calling
-<CODE>replace_window</CODE>.  The new window may be of different size;
-the panel code will re-compute all overlaps.  This operation doesn't
-change the panel's position in the deck. <P>
+  <p>The <code>menu</code> library first appeared in AT&amp;T
+  System V. The version documented here is the <code>menu</code>
+  code distributed with <code>ncurses</code>.</p>
 
-To move a panel's window, use <CODE>move_panel()</CODE>.  The
-<CODE>mvwin()</CODE> function on the panel's window isn't sufficient because it
-doesn't update the panels library's representation of where the windows are.
-This operation leaves the panel's depth, contents, and size unchanged. <P>
+  <h2><a name="mcompile" id="mcompile">Compiling With the menu
+  Library</a></h2>
 
-Two functions (<CODE>top_panel()</CODE>, <CODE>bottom_panel()</CODE>) are
-provided for rearranging the deck.  The first pops its argument window to the
-top of the deck; the second sends it to the bottom.  Either operation leaves
-the panel's screen location, contents, and size unchanged. <P>
+  <p>Your menu-using modules must import the menu library
+  declarations with</p>
+  <pre>
+          #include &lt;menu.h&gt;
+</pre>
 
-The function <CODE>update_panels()</CODE> does all the
-<CODE>wnoutrefresh()</CODE> calls needed to prepare for
-<CODE>doupdate()</CODE> (which you must call yourself, afterwards). <P>
-
-Typically, you will want to call <CODE>update_panels()</CODE> and
-<CODE>doupdate()</CODE> just before accepting command input, once in each cycle
-of interaction with the user.  If you call <CODE>update_panels()</CODE> after
-each and every panel write, you'll generate a lot of unnecessary refresh
-activity and screen flicker.
-
-<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2>
-
-You shouldn't mix <CODE>wnoutrefresh()</CODE> or <CODE>wrefresh()</CODE>
-operations with panels code; this will work only if the argument window
-is either in the top panel or unobscured by any other panels. <P>
-
-The <CODE>stsdcr</CODE> window is a special case.  It is considered below all
-panels.  Because changes to panels may obscure parts of <CODE>stdscr</CODE>,
-though, you should call <CODE>update_panels()</CODE> before
-<CODE>doupdate()</CODE> even when you only change <CODE>stdscr</CODE>. <P>
-
-Note that <CODE>wgetch</CODE> automatically calls <CODE>wrefresh</CODE>.
-Therefore, before requesting input from a panel window, you need to be sure
-that the panel is totally unobscured. <P>
-
-There is presently no way to display changes to one obscured panel without
-repainting all panels.
-
-<H2><A NAME="hiding">Hiding Panels</A></H2>
-
-It's possible to remove a panel from the deck temporarily; use
-<CODE>hide_panel</CODE> for this.  Use <CODE>show_panel()</CODE> to render it
-visible again.  The predicate function <CODE>panel_hidden</CODE>
-tests whether or not a panel is hidden. <P>
-
-The <CODE>panel_update</CODE> code ignores hidden panels.  You cannot do
-<CODE>top_panel()</CODE> or <CODE>bottom_panel</CODE> on a hidden panel().
-Other panels operations are applicable.
-
-<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2>
-
-It's possible to navigate the deck using the functions
-<CODE>panel_above()</CODE> and <CODE>panel_below</CODE>.  Handed a panel
-pointer, they return the panel above or below that panel.  Handed
-<CODE>NULL</CODE>, they return the bottom-most or top-most panel. <P>
-
-Every panel has an associated user pointer, not used by the panel code, to
-which you can attach application data.  See the man page documentation
-of <CODE>set_panel_userptr()</CODE> and <CODE>panel_userptr</CODE> for
-details.
-
-<H1><A NAME="menu">The Menu Library</A></H1>
-
-A menu is a screen display that assists the user to choose some subset
-of a given set of items.  The <CODE>menu</CODE> library is a curses
-extension that supports easy programming of menu hierarchies with a
-uniform but flexible interface. <P>
-
-The <CODE>menu</CODE> library first appeared in AT&amp;T System V.  The
-version documented here is the <CODE>menu</CODE> code distributed
-with <CODE>ncurses</CODE>.
-
-<H2><A NAME="mcompile">Compiling With the menu Library</A></H2>
-
-Your menu-using modules must import the menu library declarations with
-
-<PRE>
-         #include &lt;menu.h&gt;
-</PRE>
-
-and must be linked explicitly with the menus library using an
-<CODE>-lmenu</CODE> argument.  Note that they must also link the
-<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>.  Many linkers
-are two-pass and will accept either order, but it is still good practice
-to put <CODE>-lmenu</CODE> first and <CODE>-lncurses</CODE> second.
-
-<H2><A NAME="moverview">Overview of Menus</A></H2>
-
-The menus created by this library consist of collections of
-<DFN>items</DFN> including a name string part and a description string
-part.  To make menus, you create groups of these items and connect
-them with menu frame objects. <P>
-
-The menu can then by <DFN>posted</DFN>, that is written to an
-associated window.  Actually, each menu has two associated windows; a
-containing window in which the programmer can scribble titles or
-borders, and a subwindow in which the menu items proper are displayed.
-If this subwindow is too small to display all the items, it will be a
-scrollable viewport on the collection of items. <P>
-
-A menu may also be <DFN>unposted</DFN> (that is, undisplayed), and finally
-freed to make the storage associated with it and its items available for
-re-use. <P>
-
-The general flow of control of a menu program looks like this:
-
-<OL>
-<LI>Initialize <CODE>curses</CODE>.
-<LI>Create the menu items, using <CODE>new_item()</CODE>.
-<LI>Create the menu using <CODE>new_menu()</CODE>.
-<LI>Post the menu using <CODE>post_menu()</CODE>.
-<LI>Refresh the screen.
-<LI>Process user requests via an input loop.
-<LI>Unpost the menu using <CODE>unpost_menu()</CODE>.
-<LI>Free the menu, using <CODE>free_menu()</CODE>.
-<LI>Free the items using <CODE>free_item()</CODE>.
-<LI>Terminate <CODE>curses</CODE>.
-</OL>
-
-<H2><A NAME="mselect">Selecting items</A></H2>
-
-Menus may be multi-valued or (the default) single-valued (see the manual
-page <CODE>menu_opts(3x)</CODE> to see how to change the default).
-Both types always have a <DFN>current item</DFN>. <P>
-
-From a single-valued menu you can read the selected value simply by looking
-at the current item.  From a multi-valued menu, you get the selected set
-by looping through the items applying the <CODE>item_value()</CODE>
-predicate function.  Your menu-processing code can use the function
-<CODE>set_item_value()</CODE> to flag the items in the select set. <P>
-
-Menu items can be made unselectable using <CODE>set_item_opts()</CODE>
-or <CODE>item_opts_off()</CODE> with the <CODE>O_SELECTABLE</CODE>
-argument.  This is the only option so far defined for menus, but it
-is good practice to code as though other option bits might be on.
-
-<H2><A NAME="mdisplay">Menu Display</A></H2>
-
-The menu library calculates a minimum display size for your window, based
-on the following variables:
-
-<UL>
-<LI>The number and maximum length of the menu items
-<LI>Whether the O_ROWMAJOR option is enabled
-<LI>Whether display of descriptions is enabled
-<LI>Whatever menu format may have been set by the programmer
-<LI>The length of the menu mark string used for highlighting selected items
-</UL>
-
-The function <CODE>set_menu_format()</CODE> allows you to set the
-maximum size of the viewport or <DFN>menu page</DFN> that will be used
-to display menu items.  You can retrieve any format associated with a
-menu with <CODE>menu_format()</CODE>. The default format is rows=16,
-columns=1. <P>
-
-The actual menu page may be smaller than the format size.  This depends
-on the item number and size and whether O_ROWMAJOR is on.  This option
-(on by default) causes menu items to be displayed in a `raster-scan'
-pattern, so that if more than one item will fit horizontally the first
-couple of items are side-by-side in the top row.  The alternative is
-column-major display, which tries to put the first several items in
-the first column. <P>
-
-As mentioned above, a menu format not large enough to allow all items to fit
-on-screen will result in a menu display that is vertically scrollable. <P>
-You can scroll it with requests to the menu driver, which will be described
-in the section on <A HREF="#minput">menu input handling</A>. <P>
-
-Each menu has a <DFN>mark string</DFN> used to visually tag selected items;
-see the <CODE>menu_mark(3x)</CODE> manual page for details.  The mark
-string length also influences the menu page size. <P>
-
-The function <CODE>scale_menu()</CODE> returns the minimum display size
-that the menu code computes from all these factors.
-
-There are other menu display attributes including a select attribute,
-an attribute for selectable items, an attribute for unselectable items,
-and a pad character used to separate item name text from description
-text.  These have reasonable defaults which the library allows you to
-change (see the <CODE>menu_attribs(3x)</CODE> manual page.
-
-<H2><A NAME="mwindows">Menu Windows</A></H2>
-
-Each menu has, as mentioned previously, a pair of associated windows.
-Both these windows are painted when the menu is posted and erased when
-the menu is unposted. <P>
-
-The outer or frame window is not otherwise touched by the menu
-routines.  It exists so the programmer can associate a title, a
-border, or perhaps help text with the menu and have it properly
-refreshed or erased at post/unpost time.  The inner window or
-<DFN>subwindow</DFN> is where the current menu page is displayed. <P>
-
-By default, both windows are <CODE>stdscr</CODE>.  You can set them with the
-functions in <CODE>menu_win(3x)</CODE>. <P>
-
-When you call <CODE>post_menu()</CODE>, you write the menu to its
-subwindow.  When you call <CODE>unpost_menu()</CODE>, you erase the
-subwindow, However, neither of these actually modifies the screen.  To
-do that, call <CODE>wrefresh()</CODE> or some equivalent.
-
-<H2><A NAME="minput">Processing Menu Input</A></H2>
-
-The main loop of your menu-processing code should call
-<CODE>menu_driver()</CODE> repeatedly. The first argument of this routine
-is a menu pointer; the second is a menu command code.  You should write an
-input-fetching routine that maps input characters to menu command codes, and
-pass its output to <CODE>menu_driver()</CODE>.  The menu command codes are
-fully documented in <CODE>menu_driver(3x)</CODE>. <P>
-
-The simplest group of command codes is <CODE>REQ_NEXT_ITEM</CODE>,
-<CODE>REQ_PREV_ITEM</CODE>, <CODE>REQ_FIRST_ITEM</CODE>,
-<CODE>REQ_LAST_ITEM</CODE>, <CODE>REQ_UP_ITEM</CODE>,
-<CODE>REQ_DOWN_ITEM</CODE>, <CODE>REQ_LEFT_ITEM</CODE>,
-<CODE>REQ_RIGHT_ITEM</CODE>.  These change the currently selected
-item.  These requests may cause scrolling of the menu page if it only
-partially displayed. <P>
-
-There are explicit requests for scrolling which also change the
-current item (because the select location does not change, but the
-item there does).  These are <CODE>REQ_SCR_DLINE</CODE>,
-<CODE>REQ_SCR_ULINE</CODE>, <CODE>REQ_SCR_DPAGE</CODE>, and
-<CODE>REQ_SCR_UPAGE</CODE>. <P>
-
-The <CODE>REQ_TOGGLE_ITEM</CODE> selects or deselects the current item.
-It is for use in multi-valued menus; if you use it with <CODE>O_ONEVALUE</CODE>
-on, you'll get an error return (<CODE>E_REQUEST_DENIED</CODE>). <P>
-
-Each menu has an associated pattern buffer.  The
-<CODE>menu_driver()</CODE> logic tries to accumulate printable ASCII
-characters passed in in that buffer; when it matches a prefix of an
-item name, that item (or the next matching item) is selected.  If
-appending a character yields no new match, that character is deleted
-from the pattern buffer, and <CODE>menu_driver()</CODE> returns
-<CODE>E_NO_MATCH</CODE>. <P>
-
-Some requests change the pattern buffer directly:
-<CODE>REQ_CLEAR_PATTERN</CODE>, <CODE>REQ_BACK_PATTERN</CODE>,
-<CODE>REQ_NEXT_MATCH</CODE>, <CODE>REQ_PREV_MATCH</CODE>.  The latter
-two are useful when pattern buffer input matches more than one item
-in a multi-valued menu. <P>
-
-Each successful scroll or item navigation request clears the pattern
-buffer.  It is also possible to set the pattern buffer explicitly
-with <CODE>set_menu_pattern()</CODE>. <P>
-
-Finally, menu driver requests above the constant <CODE>MAX_COMMAND</CODE>
-are considered application-specific commands.  The <CODE>menu_driver()</CODE>
-code ignores them and returns <CODE>E_UNKNOWN_COMMAND</CODE>.
-
-<H2><A NAME="mmisc">Miscellaneous Other Features</A></H2>
-
-Various menu options can affect the processing and visual appearance
-and input processing of menus.  See <CODE>menu_opts(3x) for
-details.</CODE> <P>
-
-It is possible to change the current item from application code; this
-is useful if you want to write your own navigation requests.  It is
-also possible to explicitly set the top row of the menu display.  See
-<CODE>mitem_current(3x)</CODE>.
-
-If your application needs to change the menu subwindow cursor for
-any reason, <CODE>pos_menu_cursor()</CODE> will restore it to the
-correct location for continuing menu driver processing. <P>
-
-It is possible to set hooks to be called at menu initialization and
-wrapup time, and whenever the selected item changes.  See
-<CODE>menu_hook(3x)</CODE>. <P>
-
-Each item, and each menu, has an associated user pointer on which you
-can hang application data.  See <CODE>mitem_userptr(3x)</CODE> and
-<CODE>menu_userptr(3x)</CODE>.
-
-<H1><A NAME="form">The Forms Library</A></H1>
-
-The <CODE>form</CODE> library is a curses extension that supports easy
-programming of on-screen forms for data entry and program control. <P>
-
-The <CODE>form</CODE> library first appeared in AT&amp;T System V.  The
-version documented here is the <CODE>form</CODE> code distributed
-with <CODE>ncurses</CODE>.
-
-<H2><A NAME="fcompile">Compiling With the form Library</A></H2>
-
-Your form-using modules must import the form library declarations with
-
-<PRE>
-         #include &lt;form.h&gt;
-</PRE>
-
-and must be linked explicitly with the forms library using an
-<CODE>-lform</CODE> argument.  Note that they must also link the
-<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>.  Many linkers
-are two-pass and will accept either order, but it is still good practice
-to put <CODE>-lform</CODE> first and <CODE>-lncurses</CODE> second.
-
-<H2><A NAME="foverview">Overview of Forms</A></H2>
-
-A form is a collection of fields; each field may be either a label
-(explanatory text) or a data-entry location.  Long forms may be
-segmented into pages; each entry to a new page clears the screen. <P>
-To make forms, you create groups of fields and connect them with form
-frame objects; the form library makes this relatively simple. <P>
-
-Once defined, a form can be <DFN>posted</DFN>, that is written to an
-associated window.  Actually, each form has two associated windows; a
-containing window in which the programmer can scribble titles or
-borders, and a subwindow in which the form fields proper are displayed. <P>
-
-As the form user fills out the posted form, navigation and editing
-keys support movement between fields, editing keys support modifying
-field, and plain text adds to or changes data in a current field.  The
-form library allows you (the forms designer) to bind each navigation
-and editing key to any keystroke accepted by <CODE>curses</CODE>
-
-Fields may have validation conditions on them, so that they check input
-data for type and value.  The form library supplies a rich set of
-pre-defined field types, and makes it relatively easy to define new ones. <P>
-
-Once its transaction is completed (or aborted), a form may be
-<DFN>unposted</DFN> (that is, undisplayed), and finally freed to make
-the storage associated with it and its items available for re-use. <P>
-
-The general flow of control of a form program looks like this:
-
-<OL>
-<LI>Initialize <CODE>curses</CODE>.
-<LI>Create the form fields, using <CODE>new_field()</CODE>.
-<LI>Create the form using <CODE>new_form()</CODE>.
-<LI>Post the form using <CODE>post_form()</CODE>.
-<LI>Refresh the screen.
-<LI>Process user requests via an input loop.
-<LI>Unpost the form using <CODE>unpost_form()</CODE>.
-<LI>Free the form, using <CODE>free_form()</CODE>.
-<LI>Free the fields using <CODE>free_field()</CODE>.
-<LI>Terminate <CODE>curses</CODE>.
-</OL>
+  <p>and must be linked explicitly with the menus library using an
+  <code>-lmenu</code> argument. Note that they must also link the
+  <code>ncurses</code> library with <code>-lncurses</code>. Many
+  linkers are two-pass and will accept either order, but it is
+  still good practice to put <code>-lmenu</code> first and
+  <code>-lncurses</code> second.</p>
 
-Note that this looks much like a menu program; the form library handles
-tasks which are in many ways similar, and its interface was obviously
-designed to resemble that of the <A HREF="#menu">menu library</A>
-wherever possible. <P>
+  <h2><a name="moverview" id="moverview">Overview of Menus</a></h2>
+
+  <p>The menus created by this library consist of collections of
+  <dfn>items</dfn> including a name string part and a description
+  string part. To make menus, you create groups of these items and
+  connect them with menu frame objects.</p>
 
-In forms programs, however, the `process user requests' is somewhat more
-complicated than for menus.  Besides menu-like navigation operations,
-the menu driver loop has to support field editing and data validation.
+  <p>The menu can then by <dfn>posted</dfn>, that is written to an
+  associated window. Actually, each menu has two associated
+  windows; a containing window in which the programmer can scribble
+  titles or borders, and a subwindow in which the menu items proper
+  are displayed. If this subwindow is too small to display all the
+  items, it will be a scrollable viewport on the collection of
+  items.</p>
 
-<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2>
+  <p>A menu may also be <dfn>unposted</dfn> (that is, undisplayed),
+  and finally freed to make the storage associated with it and its
+  items available for re-use.</p>
+
+  <p>The general flow of control of a menu program looks like
+  this:</p>
 
-The basic function for creating fields is <CODE>new_field()</CODE>:
+  <ol>
+    <li>Initialize <code>curses</code>.</li>
 
-<PRE>
-FIELD *new_field(int height, int width,   /* new field size */
-                 int top, int left,       /* upper left corner */
-                 int offscreen,           /* number of offscreen rows */
-                 int nbuf);               /* number of working buffers */
-</PRE>
-
-Menu items always occupy a single row, but forms fields may have
-multiple rows.  So <CODE>new_field()</CODE> requires you to specify a
-width and height (the first two arguments, which mist both be greater
-than zero). <P>
-
-You must also specify the location of the field's upper left corner on
-the screen (the third and fourth arguments, which must be zero or
-greater). Note that these coordinates are relative to the form
-subwindow, which will coincide with <CODE>stdscr</CODE> by default but
-need not be <CODE>stdscr</CODE> if you've done an explicit
-<CODE>set_form_win()</CODE> call. <P>
-
-The fifth argument allows you to specify a number of off-screen rows.  If
-this is zero, the entire field will always be displayed.  If it is
-nonzero, the form will be scrollable, with only one screen-full (initially
-the top part) displayed at any given time.  If you make a field dynamic
-and grow it so it will no longer fit on the screen, the form will become
-scrollable even if the <CODE>offscreen</CODE> argument was initially zero. <P>
-
-The forms library allocates one working buffer per field; the size of
-each buffer is <CODE>((height + offscreen)*width + 1</CODE>, one character
-for each position in the field plus a NUL terminator.  The sixth
-argument is the number of additional data buffers to allocate for the
-field; your application can use them for its own purposes.
-
-<PRE>
-FIELD *dup_field(FIELD *field,            /* field to copy */
-                 int top, int left);      /* location of new copy */
-</PRE>
+    <li>Create the menu items, using <code>new_item()</code>.</li>
 
-The function <CODE>dup_field()</CODE> duplicates an existing field at a
-new location.  Size and buffering information are copied; some
-attribute flags and status bits are not (see the
-<CODE>form_field_new(3X)</CODE> for details).
+    <li>Create the menu using <code>new_menu()</code>.</li>
 
-<PRE>
-FIELD *link_field(FIELD *field,           /* field to copy */
-                  int top, int left);     /* location of new copy */
-</PRE>
+    <li>Post the menu using <code>post_menu()</code>.</li>
 
-The function <CODE>link_field()</CODE> also duplicates an existing field
-at a new location.  The difference from <CODE>dup_field()</CODE> is that
-it arranges for the new field's buffer to be shared with the old one. <P>
+    <li>Refresh the screen.</li>
 
-Besides the obvious use in making a field editable from two different
-form pages, linked fields give you a way to hack in dynamic labels.  If
-you declare several fields linked to an original, and then make them
-inactive, changes from the original will still be propagated to the
-linked fields. <P>
+    <li>Process user requests via an input loop.</li>
 
-As with duplicated fields, linked fields have attribute bits separate
-from the original. <P>
+    <li>Unpost the menu using <code>unpost_menu()</code>.</li>
 
-As you might guess, all these field-allocations return <CODE>NULL</CODE> if
-the field allocation is not possible due to an out-of-memory error or
-out-of-bounds arguments. <P>
+    <li>Free the menu, using <code>free_menu()</code>.</li>
 
-To connect fields to a form, use
+    <li>Free the items using <code>free_item()</code>.</li>
 
-<PRE>
-FORM *new_form(FIELD **fields);
-</PRE>
+    <li>Terminate <code>curses</code>.</li>
+  </ol>
+
+  <h2><a name="mselect" id="mselect">Selecting items</a></h2>
+
+  <p>Menus may be multi-valued or (the default) single-valued (see
+  the manual page <code>menu_opts(3x)</code> to see how to change
+  the default). Both types always have a <dfn>current
+  item</dfn>.</p>
+
+  <p>From a single-valued menu you can read the selected value
+  simply by looking at the current item. From a multi-valued menu,
+  you get the selected set by looping through the items applying
+  the <code>item_value()</code> predicate function. Your
+  menu-processing code can use the function
+  <code>set_item_value()</code> to flag the items in the select
+  set.</p>
+
+  <p>Menu items can be made unselectable using
+  <code>set_item_opts()</code> or <code>item_opts_off()</code> with
+  the <code>O_SELECTABLE</code> argument. This is the only option
+  so far defined for menus, but it is good practice to code as
+  though other option bits might be on.</p>
+
+  <h2><a name="mdisplay" id="mdisplay">Menu Display</a></h2>
+
+  <p>The menu library calculates a minimum display size for your
+  window, based on the following variables:</p>
+
+  <ul>
+    <li>The number and maximum length of the menu items</li>
+
+    <li>Whether the O_ROWMAJOR option is enabled</li>
+
+    <li>Whether display of descriptions is enabled</li>
+
+    <li>Whatever menu format may have been set by the
+    programmer</li>
+
+    <li>The length of the menu mark string used for highlighting
+    selected items</li>
+  </ul>
+
+  <p>The function <code>set_menu_format()</code> allows you to set
+  the maximum size of the viewport or <dfn>menu page</dfn> that
+  will be used to display menu items. You can retrieve any format
+  associated with a menu with <code>menu_format()</code>. The
+  default format is rows=16, columns=1.</p>
+
+  <p>The actual menu page may be smaller than the format size. This
+  depends on the item number and size and whether O_ROWMAJOR is on.
+  This option (on by default) causes menu items to be displayed in
+  a &ldquo;raster-scan&rdquo; pattern, so that if more than one
+  item will fit horizontally the first couple of items are
+  side-by-side in the top row. The alternative is column-major
+  display, which tries to put the first several items in the first
+  column.</p>
+
+  <p>As mentioned above, a menu format not large enough to allow
+  all items to fit on-screen will result in a menu display that is
+  vertically scrollable.</p>
+
+  <p>You can scroll it with requests to the menu driver, which will
+  be described in the section on <a href="#minput">menu input
+  handling</a>.</p>
+
+  <p>Each menu has a <dfn>mark string</dfn> used to visually tag
+  selected items; see the <code>menu_mark(3x)</code> manual page
+  for details. The mark string length also influences the menu page
+  size.</p>
+
+  <p>The function <code>scale_menu()</code> returns the minimum
+  display size that the menu code computes from all these factors.
+  There are other menu display attributes including a select
+  attribute, an attribute for selectable items, an attribute for
+  unselectable items, and a pad character used to separate item
+  name text from description text. These have reasonable defaults
+  which the library allows you to change (see the
+  <code>menu_attribs(3x)</code> manual page.</p>
+
+  <h2><a name="mwindows" id="mwindows">Menu Windows</a></h2>
+
+  <p>Each menu has, as mentioned previously, a pair of associated
+  windows. Both these windows are painted when the menu is posted
+  and erased when the menu is unposted.</p>
+
+  <p>The outer or frame window is not otherwise touched by the menu
+  routines. It exists so the programmer can associate a title, a
+  border, or perhaps help text with the menu and have it properly
+  refreshed or erased at post/unpost time. The inner window or
+  <dfn>subwindow</dfn> is where the current menu page is
+  displayed.</p>
+
+  <p>By default, both windows are <code>stdscr</code>. You can set
+  them with the functions in <code>menu_win(3x)</code>.</p>
+
+  <p>When you call <code>post_menu()</code>, you write the menu to
+  its subwindow. When you call <code>unpost_menu()</code>, you
+  erase the subwindow, However, neither of these actually modifies
+  the screen. To do that, call <code>wrefresh()</code> or some
+  equivalent.</p>
+
+  <h2><a name="minput" id="minput">Processing Menu Input</a></h2>
+
+  <p>The main loop of your menu-processing code should call
+  <code>menu_driver()</code> repeatedly. The first argument of this
+  routine is a menu pointer; the second is a menu command code. You
+  should write an input-fetching routine that maps input characters
+  to menu command codes, and pass its output to
+  <code>menu_driver()</code>. The menu command codes are fully
+  documented in <code>menu_driver(3x)</code>.</p>
+
+  <p>The simplest group of command codes is
+  <code>REQ_NEXT_ITEM</code>, <code>REQ_PREV_ITEM</code>,
+  <code>REQ_FIRST_ITEM</code>, <code>REQ_LAST_ITEM</code>,
+  <code>REQ_UP_ITEM</code>, <code>REQ_DOWN_ITEM</code>,
+  <code>REQ_LEFT_ITEM</code>, <code>REQ_RIGHT_ITEM</code>. These
+  change the currently selected item. These requests may cause
+  scrolling of the menu page if it only partially displayed.</p>
+
+  <p>There are explicit requests for scrolling which also change
+  the current item (because the select location does not change,
+  but the item there does). These are <code>REQ_SCR_DLINE</code>,
+  <code>REQ_SCR_ULINE</code>, <code>REQ_SCR_DPAGE</code>, and
+  <code>REQ_SCR_UPAGE</code>.</p>
+
+  <p>The <code>REQ_TOGGLE_ITEM</code> selects or deselects the
+  current item. It is for use in multi-valued menus; if you use it
+  with <code>O_ONEVALUE</code> on, you will get an error return
+  (<code>E_REQUEST_DENIED</code>).</p>
+
+  <p>Each menu has an associated pattern buffer. The
+  <code>menu_driver()</code> logic tries to accumulate printable
+  ASCII characters passed in in that buffer; when it matches a
+  prefix of an item name, that item (or the next matching item) is
+  selected. If appending a character yields no new match, that
+  character is deleted from the pattern buffer, and
+  <code>menu_driver()</code> returns <code>E_NO_MATCH</code>.</p>
+
+  <p>Some requests change the pattern buffer directly:
+  <code>REQ_CLEAR_PATTERN</code>, <code>REQ_BACK_PATTERN</code>,
+  <code>REQ_NEXT_MATCH</code>, <code>REQ_PREV_MATCH</code>. The
+  latter two are useful when pattern buffer input matches more than
+  one item in a multi-valued menu.</p>
+
+  <p>Each successful scroll or item navigation request clears the
+  pattern buffer. It is also possible to set the pattern buffer
+  explicitly with <code>set_menu_pattern()</code>.</p>
+
+  <p>Finally, menu driver requests above the constant
+  <code>MAX_COMMAND</code> are considered application-specific
+  commands. The <code>menu_driver()</code> code ignores them and
+  returns <code>E_UNKNOWN_COMMAND</code>.</p>
+
+  <h2><a name="mmisc" id="mmisc">Miscellaneous Other
+  Features</a></h2>
+
+  <p>Various menu options can affect the processing and visual
+  appearance and input processing of menus. See <code>menu_opts(3x)
+  for details.</code></p>
+
+  <p>It is possible to change the current item from application
+  code; this is useful if you want to write your own navigation
+  requests. It is also possible to explicitly set the top row of
+  the menu display. See <code>mitem_current(3x)</code>. If your
+  application needs to change the menu subwindow cursor for any
+  reason, <code>pos_menu_cursor()</code> will restore it to the
+  correct location for continuing menu driver processing.</p>
+
+  <p>It is possible to set hooks to be called at menu
+  initialization and wrapup time, and whenever the selected item
+  changes. See <code>menu_hook(3x)</code>.</p>
+
+  <p>Each item, and each menu, has an associated user pointer on
+  which you can hang application data. See
+  <code>mitem_userptr(3x)</code> and
+  <code>menu_userptr(3x)</code>.</p>
+
+  <h1><a name="form" id="form">The Forms Library</a></h1>
+
+  <p>The <code>form</code> library is a curses extension that
+  supports easy programming of on-screen forms for data entry and
+  program control.</p>
+
+  <p>The <code>form</code> library first appeared in AT&amp;T
+  System V. The version documented here is the <code>form</code>
+  code distributed with <code>ncurses</code>.</p>
+
+  <h2><a name="fcompile" id="fcompile">Compiling With the form
+  Library</a></h2>
+
+  <p>Your form-using modules must import the form library
+  declarations with</p>
+  <pre>
+          #include &lt;form.h&gt;
+</pre>
+
+  <p>and must be linked explicitly with the forms library using an
+  <code>-lform</code> argument. Note that they must also link the
+  <code>ncurses</code> library with <code>-lncurses</code>. Many
+  linkers are two-pass and will accept either order, but it is
+  still good practice to put <code>-lform</code> first and
+  <code>-lncurses</code> second.</p>
+
+  <h2><a name="foverview" id="foverview">Overview of Forms</a></h2>
+
+  <p>A form is a collection of fields; each field may be either a
+  label (explanatory text) or a data-entry location. Long forms may
+  be segmented into pages; each entry to a new page clears the
+  screen.</p>
+
+  <p>To make forms, you create groups of fields and connect them
+  with form frame objects; the form library makes this relatively
+  simple.</p>
+
+  <p>Once defined, a form can be <dfn>posted</dfn>, that is written
+  to an associated window. Actually, each form has two associated
+  windows; a containing window in which the programmer can scribble
+  titles or borders, and a subwindow in which the form fields
+  proper are displayed.</p>
+
+  <p>As the form user fills out the posted form, navigation and
+  editing keys support movement between fields, editing keys
+  support modifying field, and plain text adds to or changes data
+  in a current field. The form library allows you (the forms
+  designer) to bind each navigation and editing key to any
+  keystroke accepted by <code>curses</code> Fields may have
+  validation conditions on them, so that they check input data for
+  type and value. The form library supplies a rich set of
+  pre-defined field types, and makes it relatively easy to define
+  new ones.</p>
+
+  <p>Once its transaction is completed (or aborted), a form may be
+  <dfn>unposted</dfn> (that is, undisplayed), and finally freed to
+  make the storage associated with it and its items available for
+  re-use.</p>
+
+  <p>The general flow of control of a form program looks like
+  this:</p>
+
+  <ol>
+    <li>Initialize <code>curses</code>.</li>
+
+    <li>Create the form fields, using
+    <code>new_field()</code>.</li>
+
+    <li>Create the form using <code>new_form()</code>.</li>
+
+    <li>Post the form using <code>post_form()</code>.</li>
+
+    <li>Refresh the screen.</li>
+
+    <li>Process user requests via an input loop.</li>
+
+    <li>Unpost the form using <code>unpost_form()</code>.</li>
+
+    <li>Free the form, using <code>free_form()</code>.</li>
 
-This function expects to see a NULL-terminated array of field pointers.
-Said fields are connected to a newly-allocated form object; its address
-is returned (or else NULL if the allocation fails).   <P>
+    <li>Free the fields using <code>free_field()</code>.</li>
 
-Note that <CODE>new_field()</CODE> does <EM>not</EM> copy the pointer array
-into private storage; if you modify the contents of the pointer array
-during forms processing, all manner of bizarre things might happen.  Also
-note that any given field may only be connected to one form. <P>
+    <li>Terminate <code>curses</code>.</li>
+  </ol>
 
-The functions <CODE>free_field()</CODE> and <CODE>free_form</CODE> are available
-to free field and form objects.  It is an error to attempt to free a field
-connected to a form, but not vice-versa; thus, you will generally free
-your form objects first.
+  <p>Note that this looks much like a menu program; the form
+  library handles tasks which are in many ways similar, and its
+  interface was obviously designed to resemble that of the <a href=
+  "#menu">menu library</a> wherever possible.</p>
 
-<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2>
+  <p>In forms programs, however, the &ldquo;process user
+  requests&rdquo; is somewhat more complicated than for menus.
+  Besides menu-like navigation operations, the menu driver loop has
+  to support field editing and data validation.</p>
+
+  <h2><a name="fcreate" id="fcreate">Creating and Freeing Fields
+  and Forms</a></h2>
+
+  <p>The basic function for creating fields is
+  <code>new_field()</code>:</p>
+  <pre>
+FIELD *new_field(int height, int width,   /* new field size */
+                 int top, int left,       /* upper left corner */
+                 int offscreen,           /* number of offscreen rows */
+                 int nbuf);               /* number of working buffers */
+</pre>
+
+  <p>Menu items always occupy a single row, but forms fields may
+  have multiple rows. So <code>new_field()</code> requires you to
+  specify a width and height (the first two arguments, which mist
+  both be greater than zero).</p>
+
+  <p>You must also specify the location of the field's upper left
+  corner on the screen (the third and fourth arguments, which must
+  be zero or greater). Note that these coordinates are relative to
+  the form subwindow, which will coincide with <code>stdscr</code>
+  by default but need not be <code>stdscr</code> if you have done
+  an explicit <code>set_form_win()</code> call.</p>
+
+  <p>The fifth argument allows you to specify a number of
+  off-screen rows. If this is zero, the entire field will always be
+  displayed. If it is nonzero, the form will be scrollable, with
+  only one screen-full (initially the top part) displayed at any
+  given time. If you make a field dynamic and grow it so it will no
+  longer fit on the screen, the form will become scrollable even if
+  the <code>offscreen</code> argument was initially zero.</p>
+
+  <p>The forms library allocates one working buffer per field; the
+  size of each buffer is <code>((height + offscreen)*width +
+  1</code>, one character for each position in the field plus a NUL
+  terminator. The sixth argument is the number of additional data
+  buffers to allocate for the field; your application can use them
+  for its own purposes.</p>
+  <pre>
+FIELD *dup_field(FIELD *field,            /* field to copy */
+                 int top, int left);      /* location of new copy */
+</pre>
+
+  <p>The function <code>dup_field()</code> duplicates an existing
+  field at a new location. Size and buffering information are
+  copied; some attribute flags and status bits are not (see the
+  <code>form_field_new(3X)</code> for details).</p>
+  <pre>
+FIELD *link_field(FIELD *field,           /* field to copy */
+                  int top, int left);     /* location of new copy */
+</pre>
 
-Each form field has a number of location and size attributes
-associated with it. There are other field attributes used to control
-display and editing of the field.  Some (for example, the <CODE>O_STATIC</CODE> bit)
-involve sufficient complications to be covered in sections of their own
-later on.  We cover the functions used to get and set several basic
-attributes here. <P>
+  <p>The function <code>link_field()</code> also duplicates an
+  existing field at a new location. The difference from
+  <code>dup_field()</code> is that it arranges for the new field's
+  buffer to be shared with the old one.</p>
 
-When a field is created, the attributes not specified by the
-<CODE>new_field</CODE> function are copied from an invisible system
-default field.  In attribute-setting and -fetching functions, the
-argument NULL is taken to mean this field.  Changes to it persist
-as defaults until your forms application terminates.
+  <p>Besides the obvious use in making a field editable from two
+  different form pages, linked fields give you a way to hack in
+  dynamic labels. If you declare several fields linked to an
+  original, and then make them inactive, changes from the original
+  will still be propagated to the linked fields.</p>
 
-<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3>
+  <p>As with duplicated fields, linked fields have attribute bits
+  separate from the original.</p>
 
-You can retrieve field sizes and locations through:
+  <p>As you might guess, all these field-allocations return
+  <code>NULL</code> if the field allocation is not possible due to
+  an out-of-memory error or out-of-bounds arguments.</p>
 
-<PRE>
+  <p>To connect fields to a form, use</p>
+  <pre>
+FORM *new_form(FIELD **fields);
+</pre>
+
+  <p>This function expects to see a NULL-terminated array of field
+  pointers. Said fields are connected to a newly-allocated form
+  object; its address is returned (or else NULL if the allocation
+  fails).</p>
+
+  <p>Note that <code>new_field()</code> does <em>not</em> copy the
+  pointer array into private storage; if you modify the contents of
+  the pointer array during forms processing, all manner of bizarre
+  things might happen. Also note that any given field may only be
+  connected to one form.</p>
+
+  <p>The functions <code>free_field()</code> and
+  <code>free_form</code> are available to free field and form
+  objects. It is an error to attempt to free a field connected to a
+  form, but not vice-versa; thus, you will generally free your form
+  objects first.</p>
+
+  <h2><a name="fattributes" id="fattributes">Fetching and Changing
+  Field Attributes</a></h2>
+
+  <p>Each form field has a number of location and size attributes
+  associated with it. There are other field attributes used to
+  control display and editing of the field. Some (for example, the
+  <code>O_STATIC</code> bit) involve sufficient complications to be
+  covered in sections of their own later on. We cover the functions
+  used to get and set several basic attributes here.</p>
+
+  <p>When a field is created, the attributes not specified by the
+  <code>new_field</code> function are copied from an invisible
+  system default field. In attribute-setting and -fetching
+  functions, the argument NULL is taken to mean this field. Changes
+  to it persist as defaults until your forms application
+  terminates.</p>
+
+  <h3><a name="fsizes" id="fsizes">Fetching Size and Location
+  Data</a></h3>
+
+  <p>You can retrieve field sizes and locations through:</p>
+  <pre>
 int field_info(FIELD *field,              /* field from which to fetch */
                int *height, *int width,   /* field size */
                int *top, int *left,       /* upper left corner */
                int *offscreen,            /* number of offscreen rows */
                int *nbuf);                /* number of working buffers */
-</PRE>
-
-This function is a sort of inverse of <CODE>new_field()</CODE>; instead of
-setting size and location attributes of a new field, it fetches them
-from an existing one.
+</pre>
 
-<H3><A NAME="flocation">Changing the Field Location</A></H3>
+  <p>This function is a sort of inverse of
+  <code>new_field()</code>; instead of setting size and location
+  attributes of a new field, it fetches them from an existing
+  one.</p>
 
-It is possible to move a field's location on the screen:
+  <h3><a name="flocation" id="flocation">Changing the Field
+  Location</a></h3>
 
-<PRE>
+  <p>It is possible to move a field's location on the screen:</p>
+  <pre>
 int move_field(FIELD *field,              /* field to alter */
                int top, int left);        /* new upper-left corner */
-</PRE>
-
-You can, of course. query the current location through <CODE>field_info()</CODE>.
+</pre>
 
-<H3><A NAME="fjust">The Justification Attribute</A></H3>
+  <p>You can, of course. query the current location through
+  <code>field_info()</code>.</p>
 
-One-line fields may be unjustified, justified right, justified left,
-or centered.  Here is how you manipulate this attribute:
+  <h3><a name="fjust" id="fjust">The Justification
+  Attribute</a></h3>
 
-<PRE>
+  <p>One-line fields may be unjustified, justified right, justified
+  left, or centered. Here is how you manipulate this attribute:</p>
+  <pre>
 int set_field_just(FIELD *field,          /* field to alter */
                    int justmode);         /* mode to set */
 
 int field_just(FIELD *field);             /* fetch mode of field */
-</PRE>
+</pre>
 
-The mode values accepted and returned by this functions are
-preprocessor macros <CODE>NO_JUSTIFICATION</CODE>, <CODE>JUSTIFY_RIGHT</CODE>,
-<CODE>JUSTIFY_LEFT</CODE>, or <CODE>JUSTIFY_CENTER</CODE>.
+  <p>The mode values accepted and returned by this functions are
+  preprocessor macros <code>NO_JUSTIFICATION</code>,
+  <code>JUSTIFY_RIGHT</code>, <code>JUSTIFY_LEFT</code>, or
+  <code>JUSTIFY_CENTER</code>.</p>
 
-<H3><A NAME="fdispatts">Field Display Attributes</A></H3>
+  <h3><a name="fdispatts" id="fdispatts">Field Display
+  Attributes</a></h3>
 
-For each field, you can set a foreground attribute for entered
-characters, a background attribute for the entire field, and a pad
-character for the unfilled portion of the field.  You can also
-control pagination of the form. <P>
+  <p>For each field, you can set a foreground attribute for entered
+  characters, a background attribute for the entire field, and a
+  pad character for the unfilled portion of the field. You can also
+  control pagination of the form.</p>
 
-This group of four field attributes controls the visual appearance
-of the field on the screen, without affecting in any way the data
-in the field buffer.
-
-<PRE>
+  <p>This group of four field attributes controls the visual
+  appearance of the field on the screen, without affecting in any
+  way the data in the field buffer.</p>
+  <pre>
 int set_field_fore(FIELD *field,          /* field to alter */
                    chtype attr);          /* attribute to set */
 
@@ -1668,22 +2062,20 @@ int set_new_page(FIELD *field,            /* field to alter */
                  int flag);               /* TRUE to force new page */
 
 chtype new_page(FIELD *field);            /* field to query */
-</PRE>
-
-The attributes set and returned by the first four functions are normal
-<CODE>curses(3x)</CODE> display attribute values (<CODE>A_STANDOUT</CODE>,
-<CODE>A_BOLD</CODE>, <CODE>A_REVERSE</CODE> etc).
-
-The page bit of a field controls whether it is displayed at the start of
-a new form screen.
+</pre>
 
-<H3><A NAME="foptions">Field Option Bits</A></H3>
+  <p>The attributes set and returned by the first four functions
+  are normal <code>curses(3x)</code> display attribute values
+  (<code>A_STANDOUT</code>, <code>A_BOLD</code>,
+  <code>A_REVERSE</code> etc). The page bit of a field controls
+  whether it is displayed at the start of a new form screen.</p>
 
-There is also a large collection of field option bits you can set to control
-various aspects of forms processing.  You can manipulate them with these
-functions:
+  <h3><a name="foptions" id="foptions">Field Option Bits</a></h3>
 
-<PRE>
+  <p>There is also a large collection of field option bits you can
+  set to control various aspects of forms processing. You can
+  manipulate them with these functions:</p>
+  <pre>
 int set_field_opts(FIELD *field,          /* field to alter */
                    int attr);             /* attribute to set */
 
@@ -1694,423 +2086,476 @@ int field_opts_off(FIELD *field,          /* field to alter */
                    int attr);             /* attributes to turn off */
 
 int field_opts(FIELD *field);             /* field to query */
-</PRE>
-
-By default, all options are on.  Here are the available option bits:
-<DL>
-<DT> O_VISIBLE
-<DD> Controls whether the field is visible on the screen.  Can be used
-during form processing to hide or pop up fields depending on the value
-of parent fields.
-<DT> O_ACTIVE
-<DD> Controls whether the field is active during forms processing (i.e.
-visited by form navigation keys).  Can be used to make labels or derived
-fields with buffer values alterable by the forms application, not the user.
-<DT> O_PUBLIC
-<DD> Controls whether data is displayed during field entry.  If this option is
-turned off on a field, the library will accept and edit data in that field,
-but it will not be displayed and the visible field cursor will not move.
-You can turn off the O_PUBLIC bit to define password fields.
-<DT> O_EDIT
-<DD> Controls whether the field's data can be modified.  When this option is
-off, all editing requests except <CODE>REQ_PREV_CHOICE</CODE> and
-<CODE>REQ_NEXT_CHOICE</CODE> will fail.  Such read-only fields may be useful for
-help messages.
-<DT> O_WRAP
-<DD> Controls word-wrapping in multi-line fields.  Normally, when any
-character of a (blank-separated) word reaches the end of the current line, the
-entire word is wrapped to the next line (assuming there is one).  When this
-option is off, the word will be split across the line break.
-<DT> O_BLANK
-<DD> Controls field blanking.  When this option is on, entering a character at
-the first field position erases the entire field (except for the just-entered
-character).
-<DT> O_AUTOSKIP
-<DD> Controls automatic skip to next field when this one fills.  Normally,
-when the forms user tries to type more data into a field than will fit,
-the editing location jumps to next field.  When this option is off, the
-user's cursor will hang at the end of the field.  This option is ignored
-in dynamic fields that have not reached their size limit.
-<DT> O_NULLOK
-<DD> Controls whether <A HREF="#fvalidation">validation</A> is applied to
-blank fields.  Normally, it is not; the user can leave a field blank
-without invoking the usual validation check on exit.  If this option is
-off on a field, exit from it will invoke a validation check.
-<DT> O_PASSOK
-<DD> Controls whether validation occurs on every exit, or only after
-the field is modified.  Normally the latter is true.  Setting O_PASSOK
-may be useful if your field's validation function may change during
-forms processing.
-<DT> O_STATIC
-<DD> Controls whether the field is fixed to its initial dimensions.  If you
-turn this off, the field becomes <A HREF="#fdynamic">dynamic</A> and will
-stretch to fit entered data.
-</DL>
-
-A field's options cannot be changed while the field is currently selected.
-However, options may be changed on posted fields that are not current. <P>
-
-The option values are bit-masks and can be composed with logical-or in
-the obvious way.
-
-<H2><A NAME="fstatus">Field Status</A></H2>
-
-Every field has a status flag, which is set to FALSE when the field is
-created and TRUE when the value in field buffer 0 changes.  This flag can
-be queried and set directly:
-
-<PRE>
-int set_field_status(FIELD *field,      /* field to alter */
-                   int status);         /* mode to set */
+</pre>
 
-int field_status(FIELD *field);         /* fetch mode of field */
-</PRE>
+  <p>By default, all options are on. Here are the available option
+  bits:</p>
 
-Setting this flag under program control can be useful if you use the same
-form repeatedly, looking for modified fields each time. <P>
+  <dl>
+    <dt>O_VISIBLE</dt>
 
-Calling <CODE>field_status()</CODE> on a field not currently selected
-for input will return a correct value.  Calling <CODE>field_status()</CODE> on a
-field that is currently selected for input may not necessarily give a
-correct field status value, because entered data isn't necessarily copied to
-buffer zero before the exit validation check.
+    <dd>Controls whether the field is visible on the screen. Can be
+    used during form processing to hide or pop up fields depending
+    on the value of parent fields.</dd>
 
-To guarantee that the returned status value reflects reality, call
-<CODE>field_status()</CODE> either (1) in the field's exit validation check
-routine, (2) from the field's or form's initialization or termination
-hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been
-processed by the forms driver.
+    <dt>O_ACTIVE</dt>
 
-<H2><A NAME="fuser">Field User Pointer</A></H2>
+    <dd>Controls whether the field is active during forms
+    processing (i.e. visited by form navigation keys). Can be used
+    to make labels or derived fields with buffer values alterable
+    by the forms application, not the user.</dd>
 
-Each field structure contains one character pointer slot that is not used
-by the forms library.  It is intended to be used by applications to store
-private per-field data.  You can manipulate it with:
+    <dt>O_PUBLIC</dt>
 
-<PRE>
-int set_field_userptr(FIELD *field,       /* field to alter */
-                   char *userptr);        /* mode to set */
+    <dd>Controls whether data is displayed during field entry. If
+    this option is turned off on a field, the library will accept
+    and edit data in that field, but it will not be displayed and
+    the visible field cursor will not move. You can turn off the
+    O_PUBLIC bit to define password fields.</dd>
 
-char *field_userptr(FIELD *field);        /* fetch mode of field */
-</PRE>
+    <dt>O_EDIT</dt>
 
-(Properly, this user pointer field ought to have <CODE>(void *)</CODE> type.
-The <CODE>(char *)</CODE> type is retained for System V compatibility.) <P>
+    <dd>Controls whether the field's data can be modified. When
+    this option is off, all editing requests except
+    <code>REQ_PREV_CHOICE</code> and <code>REQ_NEXT_CHOICE</code>
+    will fail. Such read-only fields may be useful for help
+    messages.</dd>
 
-It is valid to set the user pointer of the default field (with a
-<CODE>set_field_userptr()</CODE> call passed a NULL field pointer.)
-When a new field is created, the default-field user pointer is copied
-to initialize the new field's user pointer.
+    <dt>O_WRAP</dt>
 
-<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2>
+    <dd>Controls word-wrapping in multi-line fields. Normally, when
+    any character of a (blank-separated) word reaches the end of
+    the current line, the entire word is wrapped to the next line
+    (assuming there is one). When this option is off, the word will
+    be split across the line break.</dd>
 
-Normally, a field is fixed at the size specified for it at creation
-time.  If, however, you turn off its O_STATIC bit, it becomes
-<DFN>dynamic</DFN> and will automatically resize itself to accommodate
-data as it is entered.  If the field has extra buffers associated with it,
-they will grow right along with the main input buffer.  <P>
+    <dt>O_BLANK</dt>
 
-A one-line dynamic field will have a fixed height (1) but variable
-width, scrolling horizontally to display data within the field area as
-originally dimensioned and located.  A multi-line dynamic field will
-have a fixed width, but variable height (number of rows), scrolling
-vertically to display data within the field area as originally
-dimensioned and located. <P>
+    <dd>Controls field blanking. When this option is on, entering a
+    character at the first field position erases the entire field
+    (except for the just-entered character).</dd>
 
-Normally, a dynamic field is allowed to grow without limit.  But it is
-possible to set an upper limit on the size of a dynamic field.  You do
-it with this function:
+    <dt>O_AUTOSKIP</dt>
 
-<PRE>
+    <dd>Controls automatic skip to next field when this one fills.
+    Normally, when the forms user tries to type more data into a
+    field than will fit, the editing location jumps to next field.
+    When this option is off, the user's cursor will hang at the end
+    of the field. This option is ignored in dynamic fields that
+    have not reached their size limit.</dd>
+
+    <dt>O_NULLOK</dt>
+
+    <dd>Controls whether <a href="#fvalidation">validation</a> is
+    applied to blank fields. Normally, it is not; the user can
+    leave a field blank without invoking the usual validation check
+    on exit. If this option is off on a field, exit from it will
+    invoke a validation check.</dd>
+
+    <dt>O_PASSOK</dt>
+
+    <dd>Controls whether validation occurs on every exit, or only
+    after the field is modified. Normally the latter is true.
+    Setting O_PASSOK may be useful if your field's validation
+    function may change during forms processing.</dd>
+
+    <dt>O_STATIC</dt>
+
+    <dd>Controls whether the field is fixed to its initial
+    dimensions. If you turn this off, the field becomes <a href=
+    "#fdynamic">dynamic</a> and will stretch to fit entered
+    data.</dd>
+  </dl>
+
+  <p>A field's options cannot be changed while the field is
+  currently selected. However, options may be changed on posted
+  fields that are not current.</p>
+
+  <p>The option values are bit-masks and can be composed with
+  logical-or in the obvious way.</p>
+
+  <h2><a name="fstatus" id="fstatus">Field Status</a></h2>
+
+  <p>Every field has a status flag, which is set to FALSE when the
+  field is created and TRUE when the value in field buffer 0
+  changes. This flag can be queried and set directly:</p>
+  <pre>
+int set_field_status(FIELD *field,      /* field to alter */
+                   int status);         /* mode to set */
+
+int field_status(FIELD *field);         /* fetch mode of field */
+</pre>
+
+  <p>Setting this flag under program control can be useful if you
+  use the same form repeatedly, looking for modified fields each
+  time.</p>
+
+  <p>Calling <code>field_status()</code> on a field not currently
+  selected for input will return a correct value. Calling
+  <code>field_status()</code> on a field that is currently selected
+  for input may not necessarily give a correct field status value,
+  because entered data is not necessarily copied to buffer zero
+  before the exit validation check. To guarantee that the returned
+  status value reflects reality, call <code>field_status()</code>
+  either (1) in the field's exit validation check routine, (2) from
+  the field's or form's initialization or termination hooks, or (3)
+  just after a <code>REQ_VALIDATION</code> request has been
+  processed by the forms driver.</p>
+
+  <h2><a name="fuser" id="fuser">Field User Pointer</a></h2>
+
+  <p>Each field structure contains one character pointer slot that
+  is not used by the forms library. It is intended to be used by
+  applications to store private per-field data. You can manipulate
+  it with:</p>
+  <pre>
+int set_field_userptr(FIELD *field,       /* field to alter */
+                   char *userptr);        /* mode to set */
+
+char *field_userptr(FIELD *field);        /* fetch mode of field */
+</pre>(Properly, this user pointer field ought to have <code>(void
+*)</code> type. The <code>(char *)</code> type is retained for
+System V compatibility.)
+
+  <p>It is valid to set the user pointer of the default field (with
+  a <code>set_field_userptr()</code> call passed a NULL field
+  pointer.) When a new field is created, the default-field user
+  pointer is copied to initialize the new field's user pointer.</p>
+
+  <h2><a name="fdynamic" id="fdynamic">Variable-Sized
+  Fields</a></h2>
+
+  <p>Normally, a field is fixed at the size specified for it at
+  creation time. If, however, you turn off its O_STATIC bit, it
+  becomes <dfn>dynamic</dfn> and will automatically resize itself
+  to accommodate data as it is entered. If the field has extra
+  buffers associated with it, they will grow right along with the
+  main input buffer.</p>
+
+  <p>A one-line dynamic field will have a fixed height (1) but
+  variable width, scrolling horizontally to display data within the
+  field area as originally dimensioned and located. A multi-line
+  dynamic field will have a fixed width, but variable height
+  (number of rows), scrolling vertically to display data within the
+  field area as originally dimensioned and located.</p>
+
+  <p>Normally, a dynamic field is allowed to grow without limit.
+  But it is possible to set an upper limit on the size of a dynamic
+  field. You do it with this function:</p>
+  <pre>
 int set_max_field(FIELD *field,     /* field to alter (may not be NULL) */
                    int max_size);   /* upper limit on field size */
-</PRE>
-
-If the field is one-line, <CODE>max_size</CODE> is taken to be a column size
-limit; if it is multi-line, it is taken to be a line size limit.  To disable
-any limit, use an argument of zero.  The growth limit can be changed whether
-or not the O_STATIC bit is on, but has no effect until it is. <P>
-
-The following properties of a field change when it becomes dynamic:
-
-<UL>
-<LI>If there is no growth limit, there is no final position of the field;
-therefore <CODE>O_AUTOSKIP</CODE> and <CODE>O_NL_OVERLOAD</CODE> are ignored.
-<LI>Field justification will be ignored (though whatever justification is
-set up will be retained internally and can be queried).
-<LI>The <CODE>dup_field()</CODE> and <CODE>link_field()</CODE> calls copy
-dynamic-buffer sizes.  If the <CODE>O_STATIC</CODE> option is set on one of a
-collection of links, buffer resizing will occur only when the field is
-edited through that link.
-<LI>The call <CODE>field_info()</CODE> will retrieve the original static size of
-the field; use <CODE>dynamic_field_info()</CODE> to get the actual dynamic size.
-</UL>
-
-<H2><A NAME="fvalidation">Field Validation</A></H2>
-
-By default, a field will accept any data that will fit in its input buffer.
-However, it is possible to attach a validation type to a field.  If you do
-this, any attempt to leave the field while it contains data that doesn't
-match the validation type will fail.  Some validation types also have a
-character-validity check for each time a character is entered in the field. <P>
-
-A field's validation check (if any) is not called when
-<CODE>set_field_buffer()</CODE> modifies the input buffer, nor when that buffer
-is changed through a linked field. <P>
-
-The <CODE>form</CODE> library provides a rich set of pre-defined validation
-types, and gives you the capability to define custom ones of your own.  You
-can examine and change field validation attributes with the following
-functions:
-
-<PRE>
+</pre>
+
+  <p>If the field is one-line, <code>max_size</code> is taken to be
+  a column size limit; if it is multi-line, it is taken to be a
+  line size limit. To disable any limit, use an argument of zero.
+  The growth limit can be changed whether or not the O_STATIC bit
+  is on, but has no effect until it is.</p>
+
+  <p>The following properties of a field change when it becomes
+  dynamic:</p>
+
+  <ul>
+    <li>If there is no growth limit, there is no final position of
+    the field; therefore <code>O_AUTOSKIP</code> and
+    <code>O_NL_OVERLOAD</code> are ignored.</li>
+
+    <li>Field justification will be ignored (though whatever
+    justification is set up will be retained internally and can be
+    queried).</li>
+
+    <li>The <code>dup_field()</code> and <code>link_field()</code>
+    calls copy dynamic-buffer sizes. If the <code>O_STATIC</code>
+    option is set on one of a collection of links, buffer resizing
+    will occur only when the field is edited through that
+    link.</li>
+
+    <li>The call <code>field_info()</code> will retrieve the
+    original static size of the field; use
+    <code>dynamic_field_info()</code> to get the actual dynamic
+    size.</li>
+  </ul>
+
+  <h2><a name="fvalidation" id="fvalidation">Field
+  Validation</a></h2>
+
+  <p>By default, a field will accept any data that will fit in its
+  input buffer. However, it is possible to attach a validation type
+  to a field. If you do this, any attempt to leave the field while
+  it contains data that does not match the validation type will
+  fail. Some validation types also have a character-validity check
+  for each time a character is entered in the field.</p>
+
+  <p>A field's validation check (if any) is not called when
+  <code>set_field_buffer()</code> modifies the input buffer, nor
+  when that buffer is changed through a linked field.</p>
+
+  <p>The <code>form</code> library provides a rich set of
+  pre-defined validation types, and gives you the capability to
+  define custom ones of your own. You can examine and change field
+  validation attributes with the following functions:</p>
+  <pre>
 int set_field_type(FIELD *field,          /* field to alter */
                    FIELDTYPE *ftype,      /* type to associate */
                    ...);                  /* additional arguments*/
 
 FIELDTYPE *field_type(FIELD *field);      /* field to query */
-</PRE>
+</pre>
 
-The validation type of a field is considered an attribute of the field.  As
-with other field attributes, Also, doing <CODE>set_field_type()</CODE> with a
-<CODE>NULL</CODE> field default will change the system default for validation of
-newly-created fields. <P>
+  <p>The validation type of a field is considered an attribute of
+  the field. As with other field attributes, Also, doing
+  <code>set_field_type()</code> with a <code>NULL</code> field
+  default will change the system default for validation of
+  newly-created fields.</p>
 
-Here are the pre-defined validation types:
+  <p>Here are the pre-defined validation types:</p>
 
-<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3>
+  <h3><a name="ftype_alpha" id="ftype_alpha">TYPE_ALPHA</a></h3>
 
-This field type accepts alphabetic data; no blanks, no digits, no special
-characters (this is checked at character-entry time).  It is set up with:
-
-<PRE>
+  <p>This field type accepts alphabetic data; no blanks, no digits,
+  no special characters (this is checked at character-entry time).
+  It is set up with:</p>
+  <pre>
 int set_field_type(FIELD *field,          /* field to alter */
                    TYPE_ALPHA,            /* type to associate */
                    int width);            /* maximum width of field */
-</PRE>
-
-The <CODE>width</CODE> argument sets a minimum width of data.  Typically
-you'll want to set this to the field width; if it's greater than the
-field width, the validation check will always fail.  A minimum width
-of zero makes field completion optional.
+</pre>
 
-<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3>
+  <p>The <code>width</code> argument sets a minimum width of data.
+  Typically you will want to set this to the field width; if it is
+  greater than the field width, the validation check will always
+  fail. A minimum width of zero makes field completion
+  optional.</p>
 
-This field type accepts alphabetic data and digits; no blanks, no special
-characters (this is checked at character-entry time).  It is set up with:
+  <h3><a name="ftype_alnum" id="ftype_alnum">TYPE_ALNUM</a></h3>
 
-<PRE>
+  <p>This field type accepts alphabetic data and digits; no blanks,
+  no special characters (this is checked at character-entry time).
+  It is set up with:</p>
+  <pre>
 int set_field_type(FIELD *field,          /* field to alter */
                    TYPE_ALNUM,            /* type to associate */
                    int width);            /* maximum width of field */
-</PRE>
-
-The <CODE>width</CODE> argument sets a minimum width of data.  As with
-TYPE_ALPHA, typically you'll want to set this to the field width; if it's
-greater than the field width, the validation check will always fail.  A
-minimum width of zero makes field completion optional.
+</pre>
 
-<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3>
+  <p>The <code>width</code> argument sets a minimum width of data.
+  As with TYPE_ALPHA, typically you will want to set this to the
+  field width; if it is greater than the field width, the
+  validation check will always fail. A minimum width of zero makes
+  field completion optional.</p>
 
-This type allows you to restrict a field's values to be among a specified
-set of string values (for example, the two-letter postal codes for U.S.
-states).  It is set up with:
+  <h3><a name="ftype_enum" id="ftype_enum">TYPE_ENUM</a></h3>
 
-<PRE>
+  <p>This type allows you to restrict a field's values to be among
+  a specified set of string values (for example, the two-letter
+  postal codes for U.S. states). It is set up with:</p>
+  <pre>
 int set_field_type(FIELD *field,          /* field to alter */
                    TYPE_ENUM,             /* type to associate */
                    char **valuelist;      /* list of possible values */
                    int checkcase;         /* case-sensitive? */
                    int checkunique);      /* must specify uniquely? */
-</PRE>
-
-The <CODE>valuelist</CODE> parameter must point at a NULL-terminated list of
-valid strings.  The <CODE>checkcase</CODE> argument, if true, makes comparison
-with the string case-sensitive. <P>
-
-When the user exits a TYPE_ENUM field, the validation procedure tries to
-complete the data in the buffer to a valid entry.  If a complete choice string
-has been entered, it is of course valid.  But it is also possible to enter a
-prefix of a valid string and have it completed for you. <P>
-
-By default, if you enter such a prefix and it matches more than one value
-in the string list, the prefix will be completed to the first matching
-value.  But the <CODE>checkunique</CODE> argument, if true, requires prefix
-matches to be unique in order to be valid. <P>
-
-The <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests
-can be particularly useful with these fields.
-
-<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3>
-
-This field type accepts an integer.  It is set up as follows:
-
-<PRE>
+</pre>
+
+  <p>The <code>valuelist</code> parameter must point at a
+  NULL-terminated list of valid strings. The <code>checkcase</code>
+  argument, if true, makes comparison with the string
+  case-sensitive.</p>
+
+  <p>When the user exits a TYPE_ENUM field, the validation
+  procedure tries to complete the data in the buffer to a valid
+  entry. If a complete choice string has been entered, it is of
+  course valid. But it is also possible to enter a prefix of a
+  valid string and have it completed for you.</p>
+
+  <p>By default, if you enter such a prefix and it matches more
+  than one value in the string list, the prefix will be completed
+  to the first matching value. But the <code>checkunique</code>
+  argument, if true, requires prefix matches to be unique in order
+  to be valid.</p>
+
+  <p>The <code>REQ_NEXT_CHOICE</code> and
+  <code>REQ_PREV_CHOICE</code> input requests can be particularly
+  useful with these fields.</p>
+
+  <h3><a name="ftype_integer" id=
+  "ftype_integer">TYPE_INTEGER</a></h3>
+
+  <p>This field type accepts an integer. It is set up as
+  follows:</p>
+  <pre>
 int set_field_type(FIELD *field,          /* field to alter */
                    TYPE_INTEGER,          /* type to associate */
                    int padding,           /* # places to zero-pad to */
                    int vmin, int vmax);   /* valid range */
-</PRE>
-
-Valid characters consist of an optional leading minus and digits.
-The range check is performed on exit.  If the range maximum is less
-than or equal to the minimum, the range is ignored. <P>
+</pre>
 
-If the value passes its range check, it is padded with as many leading
-zero digits as necessary to meet the padding argument. <P>
+  <p>Valid characters consist of an optional leading minus and
+  digits. The range check is performed on exit. If the range
+  maximum is less than or equal to the minimum, the range is
+  ignored.</p>
 
-A <CODE>TYPE_INTEGER</CODE> value buffer can conveniently be interpreted
-with the C library function <CODE>atoi(3)</CODE>.
+  <p>If the value passes its range check, it is padded with as many
+  leading zero digits as necessary to meet the padding
+  argument.</p>
 
-<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3>
+  <p>A <code>TYPE_INTEGER</code> value buffer can conveniently be
+  interpreted with the C library function <code>atoi(3)</code>.</p>
 
-This field type accepts a decimal number.  It is set up as follows:
+  <h3><a name="ftype_numeric" id=
+  "ftype_numeric">TYPE_NUMERIC</a></h3>
 
-<PRE>
+  <p>This field type accepts a decimal number. It is set up as
+  follows:</p>
+  <pre>
 int set_field_type(FIELD *field,              /* field to alter */
                    TYPE_NUMERIC,              /* type to associate */
                    int padding,               /* # places of precision */
                    double vmin, double vmax); /* valid range */
-</PRE>
-
-Valid characters consist of an optional leading minus and digits. possibly
-including a decimal point. If your system supports locale's, the decimal point
-character used must be the one defined by your locale. The range check is
-performed on exit. If the range maximum is less than or equal to the minimum,
-the range is ignored. <P>
+</pre>
 
-If the value passes its range check, it is padded with as many trailing
-zero digits as necessary to meet the padding argument. <P>
+  <p>Valid characters consist of an optional leading minus and
+  digits. possibly including a decimal point. If your system
+  supports locale's, the decimal point character used must be the
+  one defined by your locale. The range check is performed on exit.
+  If the range maximum is less than or equal to the minimum, the
+  range is ignored.</p>
 
-A <CODE>TYPE_NUMERIC</CODE> value buffer can conveniently be interpreted
-with the C library function <CODE>atof(3)</CODE>.
+  <p>If the value passes its range check, it is padded with as many
+  trailing zero digits as necessary to meet the padding
+  argument.</p>
 
-<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3>
+  <p>A <code>TYPE_NUMERIC</code> value buffer can conveniently be
+  interpreted with the C library function <code>atof(3)</code>.</p>
 
-This field type accepts data matching a regular expression.  It is set up
-as follows:
+  <h3><a name="ftype_regexp" id="ftype_regexp">TYPE_REGEXP</a></h3>
 
-<PRE>
+  <p>This field type accepts data matching a regular expression. It
+  is set up as follows:</p>
+  <pre>
 int set_field_type(FIELD *field,          /* field to alter */
                    TYPE_REGEXP,           /* type to associate */
                    char *regexp);         /* expression to match */
-</PRE>
+</pre>
 
-The syntax for regular expressions is that of <CODE>regcomp(3)</CODE>.
-The check for regular-expression match is performed on exit.
+  <p>The syntax for regular expressions is that of
+  <code>regcomp(3)</code>. The check for regular-expression match
+  is performed on exit.</p>
 
-<H2><A NAME="fbuffer">Direct Field Buffer Manipulation</A></H2>
+  <h2><a name="fbuffer" id="fbuffer">Direct Field Buffer
+  Manipulation</a></h2>
 
-The chief attribute of a field is its buffer contents.  When a form has
-been completed, your application usually needs to know the state of each
-field buffer.  You can find this out with:
-
-<PRE>
+  <p>The chief attribute of a field is its buffer contents. When a
+  form has been completed, your application usually needs to know
+  the state of each field buffer. You can find this out with:</p>
+  <pre>
 char *field_buffer(FIELD *field,          /* field to query */
                    int bufindex);         /* number of buffer to query */
-</PRE>
-
-Normally, the state of the zero-numbered buffer for each field is set by
-the user's editing actions on that field.  It's sometimes useful to be able
-to set the value of the zero-numbered (or some other) buffer from your
-application:
+</pre>
 
-<PRE>
+  <p>Normally, the state of the zero-numbered buffer for each field
+  is set by the user's editing actions on that field. It is
+  sometimes useful to be able to set the value of the zero-numbered
+  (or some other) buffer from your application:</p>
+  <pre>
 int set_field_buffer(FIELD *field,        /* field to alter */
                    int bufindex,          /* number of buffer to alter */
                    char *value);          /* string value to set */
-</PRE>
-
-If the field is not large enough and cannot be resized to a sufficiently
-large size to contain the specified value, the value will be truncated
-to fit. <P>
-
-Calling <CODE>field_buffer()</CODE> with a null field pointer will raise an
-error.  Calling <CODE>field_buffer()</CODE> on a field not currently selected
-for input will return a correct value.  Calling <CODE>field_buffer()</CODE> on a
-field that is currently selected for input may not necessarily give a
-correct field buffer value, because entered data isn't necessarily copied to
-buffer zero before the exit validation check.
-
-To guarantee that the returned buffer value reflects on-screen reality,
-call <CODE>field_buffer()</CODE> either (1) in the field's exit validation
-check routine, (2) from the field's or form's initialization or termination
-hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been processed
-by the forms driver.
-
-<H2><A NAME="formattrs">Attributes of Forms</A></H2>
-
-As with field attributes, form attributes inherit a default from a
-system default form structure.  These defaults can be queried or set by
-of these functions using a form-pointer argument of <CODE>NULL</CODE>. <P>
-
-The principal attribute of a form is its field list.  You can query
-and change this list with:
-
-<PRE>
+</pre>
+
+  <p>If the field is not large enough and cannot be resized to a
+  sufficiently large size to contain the specified value, the value
+  will be truncated to fit.</p>
+
+  <p>Calling <code>field_buffer()</code> with a null field pointer
+  will raise an error. Calling <code>field_buffer()</code> on a
+  field not currently selected for input will return a correct
+  value. Calling <code>field_buffer()</code> on a field that is
+  currently selected for input may not necessarily give a correct
+  field buffer value, because entered data is not necessarily
+  copied to buffer zero before the exit validation check. To
+  guarantee that the returned buffer value reflects on-screen
+  reality, call <code>field_buffer()</code> either (1) in the
+  field's exit validation check routine, (2) from the field's or
+  form's initialization or termination hooks, or (3) just after a
+  <code>REQ_VALIDATION</code> request has been processed by the
+  forms driver.</p>
+
+  <h2><a name="formattrs" id="formattrs">Attributes of
+  Forms</a></h2>
+
+  <p>As with field attributes, form attributes inherit a default
+  from a system default form structure. These defaults can be
+  queried or set by of these functions using a form-pointer
+  argument of <code>NULL</code>.</p>
+
+  <p>The principal attribute of a form is its field list. You can
+  query and change this list with:</p>
+  <pre>
 int set_form_fields(FORM *form,           /* form to alter */
                     FIELD **fields);      /* fields to connect */
 
 char *form_fields(FORM *form);            /* fetch fields of form */
 
 int field_count(FORM *form);              /* count connect fields */
-</PRE>
-
-The second argument of <CODE>set_form_fields()</CODE> may be a
-NULL-terminated field pointer array like the one required by
-<CODE>new_form()</CODE>. In that case, the old fields of the form are
-disconnected but not freed (and eligible to be connected to other
-forms), then the new fields are connected. <P>
-
-It may also be null, in which case the old fields are disconnected
-(and not freed) but no new ones are connected. <P>
-
-The <CODE>field_count()</CODE> function simply counts the number of fields
-connected to a given from.  It returns -1 if the form-pointer argument
-is NULL.
-
-<H2><A NAME="fdisplay">Control of Form Display</A></H2>
-
-In the overview section, you saw that to display a form you normally
-start by defining its size (and fields), posting it, and refreshing
-the screen.  There is an hidden step before posting, which is the
-association of the form with a frame window (actually, a pair of
-windows) within which it will be displayed.  By default, the forms
-library associates every form with the full-screen window
-<CODE>stdscr</CODE>. <P>
-
-By making this step explicit, you can associate a form with a declared
-frame window on your screen display.  This can be useful if you want to
-adapt the form display to different screen sizes, dynamically tile
-forms on the screen, or use a form as part of an interface layout
-managed by <A HREF="#panels">panels</A>. <P>
-
-The two windows associated with each form have the same functions as
-their analogues in the <A HREF="#menu">menu library</A>.  Both these
-windows are painted when the form is posted and erased when the form
-is unposted. <P>
-
-The outer or frame window is not otherwise touched by the form
-routines.  It exists so the programmer can associate a title, a
-border, or perhaps help text with the form and have it properly
-refreshed or erased at post/unpost time. The inner window or subwindow
-is where the current form page is actually displayed. <P>
-
-In order to declare your own frame window for a form, you'll need to
-know the size of the form's bounding rectangle.  You can get this
-information with:
-
-<PRE>
+</pre>
+
+  <p>The second argument of <code>set_form_fields()</code> may be a
+  NULL-terminated field pointer array like the one required by
+  <code>new_form()</code>. In that case, the old fields of the form
+  are disconnected but not freed (and eligible to be connected to
+  other forms), then the new fields are connected.</p>
+
+  <p>It may also be null, in which case the old fields are
+  disconnected (and not freed) but no new ones are connected.</p>
+
+  <p>The <code>field_count()</code> function simply counts the
+  number of fields connected to a given from. It returns -1 if the
+  form-pointer argument is NULL.</p>
+
+  <h2><a name="fdisplay" id="fdisplay">Control of Form
+  Display</a></h2>
+
+  <p>In the overview section, you saw that to display a form you
+  normally start by defining its size (and fields), posting it, and
+  refreshing the screen. There is an hidden step before posting,
+  which is the association of the form with a frame window
+  (actually, a pair of windows) within which it will be displayed.
+  By default, the forms library associates every form with the
+  full-screen window <code>stdscr</code>.</p>
+
+  <p>By making this step explicit, you can associate a form with a
+  declared frame window on your screen display. This can be useful
+  if you want to adapt the form display to different screen sizes,
+  dynamically tile forms on the screen, or use a form as part of an
+  interface layout managed by <a href="#panels">panels</a>.</p>
+
+  <p>The two windows associated with each form have the same
+  functions as their analogues in the <a href="#menu">menu
+  library</a>. Both these windows are painted when the form is
+  posted and erased when the form is unposted.</p>
+
+  <p>The outer or frame window is not otherwise touched by the form
+  routines. It exists so the programmer can associate a title, a
+  border, or perhaps help text with the form and have it properly
+  refreshed or erased at post/unpost time. The inner window or
+  subwindow is where the current form page is actually
+  displayed.</p>
+
+  <p>In order to declare your own frame window for a form, you will
+  need to know the size of the form's bounding rectangle. You can
+  get this information with:</p>
+  <pre>
 int scale_form(FORM *form,                /* form to query */
                int *rows,                 /* form rows */
                int *cols);                /* form cols */
-</PRE>
-
-The form dimensions are passed back in the locations pointed to by
-the arguments.  Once you have this information, you can use it to
-declare of windows, then use one of these functions:
+</pre>
 
-<PRE>
+  <p>The form dimensions are passed back in the locations pointed
+  to by the arguments. Once you have this information, you can use
+  it to declare of windows, then use one of these functions:</p>
+  <pre>
 int set_form_win(FORM *form,              /* form to alter */
                  WINDOW *win);            /* frame window to connect */
 
@@ -2120,319 +2565,448 @@ int set_form_sub(FORM *form,              /* form to alter */
                  WINDOW *win);            /* form subwindow to connect */
 
 WINDOW *form_sub(FORM *form);             /* fetch form subwindow of form */
-</PRE>
-
-Note that curses operations, including <CODE>refresh()</CODE>, on the form,
-should be done on the frame window, not the form subwindow. <P>
+</pre>
 
-It is possible to check from your application whether all of a
-scrollable field is actually displayed within the menu subwindow.  Use
-these functions:
+  <p>Note that curses operations, including <code>refresh()</code>,
+  on the form, should be done on the frame window, not the form
+  subwindow.</p>
 
-<PRE>
+  <p>It is possible to check from your application whether all of a
+  scrollable field is actually displayed within the menu subwindow.
+  Use these functions:</p>
+  <pre>
 int data_ahead(FORM *form);               /* form to be queried */
 
 int data_behind(FORM *form);              /* form to be queried */
-</PRE>
+</pre>
 
-The function <CODE>data_ahead()</CODE> returns TRUE if (a) the current
-field is one-line and has undisplayed data off to the right, (b) the current
-field is multi-line and there is data off-screen below it. <P>
+  <p>The function <code>data_ahead()</code> returns TRUE if (a) the
+  current field is one-line and has undisplayed data off to the
+  right, (b) the current field is multi-line and there is data
+  off-screen below it.</p>
 
-The function <CODE>data_behind()</CODE> returns TRUE if the first (upper
-left hand) character position is off-screen (not being displayed). <P>
+  <p>The function <code>data_behind()</code> returns TRUE if the
+  first (upper left hand) character position is off-screen (not
+  being displayed).</p>
 
-Finally, there is a function to restore the form window's cursor to the
-value expected by the forms driver:
-
-<PRE>
+  <p>Finally, there is a function to restore the form window's
+  cursor to the value expected by the forms driver:</p>
+  <pre>
 int pos_form_cursor(FORM *)               /* form to be queried */
-</PRE>
-
-If your application changes the form window cursor, call this function before
-handing control back to the forms driver in order to re-synchronize it.
+</pre>
 
-<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2>
+  <p>If your application changes the form window cursor, call this
+  function before handing control back to the forms driver in order
+  to re-synchronize it.</p>
 
-The function <CODE>form_driver()</CODE> handles virtualized input requests
-for form navigation, editing, and validation requests, just as
-<CODE>menu_driver</CODE> does for menus (see the section on <A
-HREF="#minput">menu input handling</A>).
+  <h2><a name="fdriver" id="fdriver">Input Processing in the Forms
+  Driver</a></h2>
 
-<PRE>
+  <p>The function <code>form_driver()</code> handles virtualized
+  input requests for form navigation, editing, and validation
+  requests, just as <code>menu_driver</code> does for menus (see
+  the section on <a href="#minput">menu input handling</a>).</p>
+  <pre>
 int form_driver(FORM *form,               /* form to pass input to */
                 int request);             /* form request code */
-</PRE>
-
-Your input virtualization function needs to take input and then convert it
-to either an alphanumeric character (which is treated as data to be
-entered in the currently-selected field), or a forms processing request. <P>
-
-The forms driver provides hooks (through input-validation and
-field-termination functions) with which your application code can check
-that the input taken by the driver matched what was expected.
-
-<H3><A NAME="fpage">Page Navigation Requests</A></H3>
-
-These requests cause page-level moves through the form,
-triggering display of a new form screen.
-
-<DL>
-<DT> <CODE>REQ_NEXT_PAGE</CODE>
-<DD> Move to the next form page.
-<DT> <CODE>REQ_PREV_PAGE</CODE>
-<DD> Move to the previous form page.
-<DT> <CODE>REQ_FIRST_PAGE</CODE>
-<DD> Move to the first form page.
-<DT> <CODE>REQ_LAST_PAGE</CODE>
-<DD> Move to the last form page.
-</DL>
-
-These requests treat the list as cyclic; that is, <CODE>REQ_NEXT_PAGE</CODE>
-from the last page goes to the first, and <CODE>REQ_PREV_PAGE</CODE> from
-the first page goes to the last.
-
-<H3><A NAME="ffield">Inter-Field Navigation Requests</A></H3>
-
-These requests handle navigation between fields on the same page.
-
-<DL>
-<DT> <CODE>REQ_NEXT_FIELD</CODE>
-<DD> Move to next field.
-<DT> <CODE>REQ_PREV_FIELD</CODE>
-<DD> Move to previous field.
-<DT> <CODE>REQ_FIRST_FIELD</CODE>
-<DD> Move to the first field.
-<DT> <CODE>REQ_LAST_FIELD</CODE>
-<DD> Move to the last field.
-<DT> <CODE>REQ_SNEXT_FIELD</CODE>
-<DD> Move to sorted next field.
-<DT> <CODE>REQ_SPREV_FIELD</CODE>
-<DD> Move to sorted previous field.
-<DT> <CODE>REQ_SFIRST_FIELD</CODE>
-<DD> Move to the sorted first field.
-<DT> <CODE>REQ_SLAST_FIELD</CODE>
-<DD> Move to the sorted last field.
-<DT> <CODE>REQ_LEFT_FIELD</CODE>
-<DD> Move left to field.
-<DT> <CODE>REQ_RIGHT_FIELD</CODE>
-<DD> Move right to field.
-<DT> <CODE>REQ_UP_FIELD</CODE>
-<DD> Move up to field.
-<DT> <CODE>REQ_DOWN_FIELD</CODE>
-<DD> Move down to field.
-</DL>
-
-These requests treat the list of fields on a page as cyclic; that is,
-<CODE>REQ_NEXT_FIELD</CODE> from the last field goes to the first, and
-<CODE>REQ_PREV_FIELD</CODE> from the first field goes to the last. The
-order of the fields for these (and the <CODE>REQ_FIRST_FIELD</CODE> and
-<CODE>REQ_LAST_FIELD</CODE> requests) is simply the order of the field
-pointers in the form array (as set up by <CODE>new_form()</CODE> or
-<CODE>set_form_fields()</CODE> <P>
-
-It is also possible to traverse the fields as if they had been sorted in
-screen-position order, so the sequence goes left-to-right and top-to-bottom.
-To do this, use the second group of four sorted-movement requests.  <P>
-
-Finally, it is possible to move between fields using visual directions up,
-down, right, and left.  To accomplish this, use the third group of four
-requests.  Note, however, that the position of a form for purposes of these
-requests is its upper-left corner. <P>
-
-For example, suppose you have a multi-line field B, and two
-single-line fields A and C on the same line with B, with A to the left
-of B and C to the right of B.  A <CODE>REQ_MOVE_RIGHT</CODE> from A will
-go to B only if A, B, and C <EM>all</EM> share the same first line;
-otherwise it will skip over B to C.
-
-<H3><A NAME="fifield">Intra-Field Navigation Requests</A></H3>
-
-These requests drive movement of the edit cursor within the currently
-selected field.
-
-<DL>
-<DT> <CODE>REQ_NEXT_CHAR</CODE>
-<DD> Move to next character.
-<DT> <CODE>REQ_PREV_CHAR</CODE>
-<DD> Move to previous character.
-<DT> <CODE>REQ_NEXT_LINE</CODE>
-<DD> Move to next line.
-<DT> <CODE>REQ_PREV_LINE</CODE>
-<DD> Move to previous line.
-<DT> <CODE>REQ_NEXT_WORD</CODE>
-<DD> Move to next word.
-<DT> <CODE>REQ_PREV_WORD</CODE>
-<DD> Move to previous word.
-<DT> <CODE>REQ_BEG_FIELD</CODE>
-<DD> Move to beginning of field.
-<DT> <CODE>REQ_END_FIELD</CODE>
-<DD> Move to end of field.
-<DT> <CODE>REQ_BEG_LINE</CODE>
-<DD> Move to beginning of line.
-<DT> <CODE>REQ_END_LINE</CODE>
-<DD> Move to end of line.
-<DT> <CODE>REQ_LEFT_CHAR</CODE>
-<DD> Move left in field.
-<DT> <CODE>REQ_RIGHT_CHAR</CODE>
-<DD> Move right in field.
-<DT> <CODE>REQ_UP_CHAR</CODE>
-<DD> Move up in field.
-<DT> <CODE>REQ_DOWN_CHAR</CODE>
-<DD> Move down in field.
-</DL>
-
-Each <EM>word</EM> is separated from the previous and next characters
-by whitespace.  The commands to move to beginning and end of line or field
-look for the first or last non-pad character in their ranges.
-
-<H3><A NAME="fscroll">Scrolling Requests</A></H3>
-
-Fields that are dynamic and have grown and fields explicitly created
-with offscreen rows are scrollable.  One-line fields scroll horizontally;
-multi-line fields scroll vertically.  Most scrolling is triggered by
-editing and intra-field movement (the library scrolls the field to keep the
-cursor visible).  It is possible to explicitly request scrolling with the
-following requests:
-
-<DL>
-<DT> <CODE>REQ_SCR_FLINE</CODE>
-<DD> Scroll vertically forward a line.
-<DT> <CODE>REQ_SCR_BLINE</CODE>
-<DD> Scroll vertically backward a line.
-<DT> <CODE>REQ_SCR_FPAGE</CODE>
-<DD> Scroll vertically forward a page.
-<DT> <CODE>REQ_SCR_BPAGE</CODE>
-<DD> Scroll vertically backward a page.
-<DT> <CODE>REQ_SCR_FHPAGE</CODE>
-<DD> Scroll vertically forward half a page.
-<DT> <CODE>REQ_SCR_BHPAGE</CODE>
-<DD> Scroll vertically backward half a page.
-<DT> <CODE>REQ_SCR_FCHAR</CODE>
-<DD> Scroll horizontally forward a character.
-<DT> <CODE>REQ_SCR_BCHAR</CODE>
-<DD> Scroll horizontally backward a character.
-<DT> <CODE>REQ_SCR_HFLINE</CODE>
-<DD> Scroll horizontally one field width forward.
-<DT> <CODE>REQ_SCR_HBLINE</CODE>
-<DD> Scroll horizontally one field width backward.
-<DT> <CODE>REQ_SCR_HFHALF</CODE>
-<DD> Scroll horizontally one half field width forward.
-<DT> <CODE>REQ_SCR_HBHALF</CODE>
-<DD> Scroll horizontally one half field width backward.
-</DL>
-
-For scrolling purposes, a <EM>page</EM> of a field is the height
-of its visible part.
-
-<H3><A NAME="fedit">Editing Requests</A></H3>
-
-When you pass the forms driver an ASCII character, it is treated as a
-request to add the character to the field's data buffer.  Whether this
-is an insertion or a replacement depends on the field's edit mode
-(insertion is the default. <P>
-
-The following requests support editing the field and changing the edit
-mode:
-
-<DL>
-<DT> <CODE>REQ_INS_MODE</CODE>
-<DD> Set insertion mode.
-<DT> <CODE>REQ_OVL_MODE</CODE>
-<DD> Set overlay mode.
-<DT> <CODE>REQ_NEW_LINE</CODE>
-<DD> New line request (see below for explanation).
-<DT> <CODE>REQ_INS_CHAR</CODE>
-<DD> Insert space at character location.
-<DT> <CODE>REQ_INS_LINE</CODE>
-<DD> Insert blank line at character location.
-<DT> <CODE>REQ_DEL_CHAR</CODE>
-<DD> Delete character at cursor.
-<DT> <CODE>REQ_DEL_PREV</CODE>
-<DD> Delete previous word at cursor.
-<DT> <CODE>REQ_DEL_LINE</CODE>
-<DD> Delete line at cursor.
-<DT> <CODE>REQ_DEL_WORD</CODE>
-<DD> Delete word at cursor.
-<DT> <CODE>REQ_CLR_EOL</CODE>
-<DD> Clear to end of line.
-<DT> <CODE>REQ_CLR_EOF</CODE>
-<DD> Clear to end of field.
-<DT> <CODE>REQ_CLEAR_FIELD</CODE>
-<DD> Clear entire field.
-</DL>
-
-The behavior of the <CODE>REQ_NEW_LINE</CODE> and <CODE>REQ_DEL_PREV</CODE> requests
-is complicated and partly controlled by a pair of forms options.
-The special cases are triggered when the cursor is at the beginning of
-a field, or on the last line of the field. <P>
-
-First, we consider <CODE>REQ_NEW_LINE</CODE>: <P>
-
-The normal behavior of <CODE>REQ_NEW_LINE</CODE> in insert mode is to break the
-current line at the position of the edit cursor, inserting the portion of
-the current line after the cursor as a new line following the current
-and moving the cursor to the beginning of that new line (you may think
-of this as inserting a newline in the field buffer). <P>
-
-The normal behavior of <CODE>REQ_NEW_LINE</CODE> in overlay mode is to clear the
-current line from the position of the edit cursor to end of line.
-The cursor is then moved to the beginning of the next line. <P>
-
-However, <CODE>REQ_NEW_LINE</CODE> at the beginning of a field, or on the
-last line of a field, instead does a <CODE>REQ_NEXT_FIELD</CODE>.
-<CODE>O_NL_OVERLOAD</CODE> option is off, this special action is
-disabled. <P>
-
-Now, let us consider <CODE>REQ_DEL_PREV</CODE>: <P>
-
-The normal behavior of <CODE>REQ_DEL_PREV</CODE> is to delete the previous
-character.  If insert mode is on, and the cursor is at the start of a
-line, and the text on that line will fit on the previous one, it
-instead appends the contents of the current line to the previous one
-and deletes the current line (you may think of this as deleting a
-newline from the field buffer). <P>
-
-However, <CODE>REQ_DEL_PREV</CODE> at the beginning of a field is instead
-treated as a <CODE>REQ_PREV_FIELD</CODE>. <P> If the
-<CODE>O_BS_OVERLOAD</CODE> option is off, this special action is
-disabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P>
-
-See <A HREF="#frmoptions">Form Options</A> for discussion of how to set
-and clear the overload options.
-
-<H3><A NAME="forder">Order Requests</A></H3>
-
-If the type of your field is ordered, and has associated functions
-for getting the next and previous values of the type from a given value,
-there are requests that can fetch that value into the field buffer:
-
-<DL>
-<DT> <CODE>REQ_NEXT_CHOICE</CODE>
-<DD> Place the successor value of the current value in the buffer.
-<DT> <CODE>REQ_PREV_CHOICE</CODE>
-<DD> Place the predecessor value of the current value in the buffer.
-</DL>
-
-Of the built-in field types, only <CODE>TYPE_ENUM</CODE> has built-in successor
-and predecessor functions.  When you define a field type of your own
-(see <A HREF="#fcustom">Custom Validation Types</A>), you can associate
-our own ordering functions.
-
-<H3><A NAME="fappcmds">Application Commands</A></H3>
-
-Form requests are represented as integers above the <CODE>curses</CODE> value
-greater than <CODE>KEY_MAX</CODE> and less than or equal to the constant
-<CODE>MAX_COMMAND</CODE>.  If your input-virtualization routine returns a
-value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it.
-
-<H2><A NAME="fhooks">Field Change Hooks</A></H2>
-
-It is possible to set function hooks to be executed whenever the
-current field or form changes.  Here are the functions that support this:
-
-<PRE>
-typedef void   (*HOOK)();       /* pointer to function returning void */
+</pre>
+
+  <p>Your input virtualization function needs to take input and
+  then convert it to either an alphanumeric character (which is
+  treated as data to be entered in the currently-selected field),
+  or a forms processing request.</p>
+
+  <p>The forms driver provides hooks (through input-validation and
+  field-termination functions) with which your application code can
+  check that the input taken by the driver matched what was
+  expected.</p>
+
+  <h3><a name="fpage" id="fpage">Page Navigation Requests</a></h3>
+
+  <p>These requests cause page-level moves through the form,
+  triggering display of a new form screen.</p>
+
+  <dl>
+    <dt><code>REQ_NEXT_PAGE</code></dt>
+
+    <dd>Move to the next form page.</dd>
+
+    <dt><code>REQ_PREV_PAGE</code></dt>
+
+    <dd>Move to the previous form page.</dd>
+
+    <dt><code>REQ_FIRST_PAGE</code></dt>
+
+    <dd>Move to the first form page.</dd>
+
+    <dt><code>REQ_LAST_PAGE</code></dt>
+
+    <dd>Move to the last form page.</dd>
+  </dl>
+
+  <p>These requests treat the list as cyclic; that is,
+  <code>REQ_NEXT_PAGE</code> from the last page goes to the first,
+  and <code>REQ_PREV_PAGE</code> from the first page goes to the
+  last.</p>
+
+  <h3><a name="ffield" id="ffield">Inter-Field Navigation
+  Requests</a></h3>
+
+  <p>These requests handle navigation between fields on the same
+  page.</p>
+
+  <dl>
+    <dt><code>REQ_NEXT_FIELD</code></dt>
+
+    <dd>Move to next field.</dd>
+
+    <dt><code>REQ_PREV_FIELD</code></dt>
+
+    <dd>Move to previous field.</dd>
+
+    <dt><code>REQ_FIRST_FIELD</code></dt>
+
+    <dd>Move to the first field.</dd>
+
+    <dt><code>REQ_LAST_FIELD</code></dt>
+
+    <dd>Move to the last field.</dd>
+
+    <dt><code>REQ_SNEXT_FIELD</code></dt>
+
+    <dd>Move to sorted next field.</dd>
+
+    <dt><code>REQ_SPREV_FIELD</code></dt>
+
+    <dd>Move to sorted previous field.</dd>
+
+    <dt><code>REQ_SFIRST_FIELD</code></dt>
+
+    <dd>Move to the sorted first field.</dd>
+
+    <dt><code>REQ_SLAST_FIELD</code></dt>
+
+    <dd>Move to the sorted last field.</dd>
+
+    <dt><code>REQ_LEFT_FIELD</code></dt>
+
+    <dd>Move left to field.</dd>
+
+    <dt><code>REQ_RIGHT_FIELD</code></dt>
+
+    <dd>Move right to field.</dd>
+
+    <dt><code>REQ_UP_FIELD</code></dt>
+
+    <dd>Move up to field.</dd>
+
+    <dt><code>REQ_DOWN_FIELD</code></dt>
+
+    <dd>Move down to field.</dd>
+  </dl>
+
+  <p>These requests treat the list of fields on a page as cyclic;
+  that is, <code>REQ_NEXT_FIELD</code> from the last field goes to
+  the first, and <code>REQ_PREV_FIELD</code> from the first field
+  goes to the last. The order of the fields for these (and the
+  <code>REQ_FIRST_FIELD</code> and <code>REQ_LAST_FIELD</code>
+  requests) is simply the order of the field pointers in the form
+  array (as set up by <code>new_form()</code> or
+  <code>set_form_fields()</code></p>
+
+  <p>It is also possible to traverse the fields as if they had been
+  sorted in screen-position order, so the sequence goes
+  left-to-right and top-to-bottom. To do this, use the second group
+  of four sorted-movement requests.</p>
+
+  <p>Finally, it is possible to move between fields using visual
+  directions up, down, right, and left. To accomplish this, use the
+  third group of four requests. Note, however, that the position of
+  a form for purposes of these requests is its upper-left
+  corner.</p>
+
+  <p>For example, suppose you have a multi-line field B, and two
+  single-line fields A and C on the same line with B, with A to the
+  left of B and C to the right of B. A <code>REQ_MOVE_RIGHT</code>
+  from A will go to B only if A, B, and C <em>all</em> share the
+  same first line; otherwise it will skip over B to C.</p>
+
+  <h3><a name="fifield" id="fifield">Intra-Field Navigation
+  Requests</a></h3>
+
+  <p>These requests drive movement of the edit cursor within the
+  currently selected field.</p>
+
+  <dl>
+    <dt><code>REQ_NEXT_CHAR</code></dt>
+
+    <dd>Move to next character.</dd>
+
+    <dt><code>REQ_PREV_CHAR</code></dt>
+
+    <dd>Move to previous character.</dd>
+
+    <dt><code>REQ_NEXT_LINE</code></dt>
+
+    <dd>Move to next line.</dd>
+
+    <dt><code>REQ_PREV_LINE</code></dt>
+
+    <dd>Move to previous line.</dd>
+
+    <dt><code>REQ_NEXT_WORD</code></dt>
+
+    <dd>Move to next word.</dd>
+
+    <dt><code>REQ_PREV_WORD</code></dt>
+
+    <dd>Move to previous word.</dd>
+
+    <dt><code>REQ_BEG_FIELD</code></dt>
+
+    <dd>Move to beginning of field.</dd>
+
+    <dt><code>REQ_END_FIELD</code></dt>
+
+    <dd>Move to end of field.</dd>
+
+    <dt><code>REQ_BEG_LINE</code></dt>
+
+    <dd>Move to beginning of line.</dd>
+
+    <dt><code>REQ_END_LINE</code></dt>
+
+    <dd>Move to end of line.</dd>
+
+    <dt><code>REQ_LEFT_CHAR</code></dt>
+
+    <dd>Move left in field.</dd>
+
+    <dt><code>REQ_RIGHT_CHAR</code></dt>
+
+    <dd>Move right in field.</dd>
+
+    <dt><code>REQ_UP_CHAR</code></dt>
+
+    <dd>Move up in field.</dd>
+
+    <dt><code>REQ_DOWN_CHAR</code></dt>
+
+    <dd>Move down in field.</dd>
+  </dl>
+
+  <p>Each <em>word</em> is separated from the previous and next
+  characters by whitespace. The commands to move to beginning and
+  end of line or field look for the first or last non-pad character
+  in their ranges.</p>
+
+  <h3><a name="fscroll" id="fscroll">Scrolling Requests</a></h3>
+
+  <p>Fields that are dynamic and have grown and fields explicitly
+  created with offscreen rows are scrollable. One-line fields
+  scroll horizontally; multi-line fields scroll vertically. Most
+  scrolling is triggered by editing and intra-field movement (the
+  library scrolls the field to keep the cursor visible). It is
+  possible to explicitly request scrolling with the following
+  requests:</p>
+
+  <dl>
+    <dt><code>REQ_SCR_FLINE</code></dt>
+
+    <dd>Scroll vertically forward a line.</dd>
+
+    <dt><code>REQ_SCR_BLINE</code></dt>
+
+    <dd>Scroll vertically backward a line.</dd>
+
+    <dt><code>REQ_SCR_FPAGE</code></dt>
+
+    <dd>Scroll vertically forward a page.</dd>
+
+    <dt><code>REQ_SCR_BPAGE</code></dt>
+
+    <dd>Scroll vertically backward a page.</dd>
+
+    <dt><code>REQ_SCR_FHPAGE</code></dt>
+
+    <dd>Scroll vertically forward half a page.</dd>
+
+    <dt><code>REQ_SCR_BHPAGE</code></dt>
+
+    <dd>Scroll vertically backward half a page.</dd>
+
+    <dt><code>REQ_SCR_FCHAR</code></dt>
+
+    <dd>Scroll horizontally forward a character.</dd>
+
+    <dt><code>REQ_SCR_BCHAR</code></dt>
+
+    <dd>Scroll horizontally backward a character.</dd>
+
+    <dt><code>REQ_SCR_HFLINE</code></dt>
+
+    <dd>Scroll horizontally one field width forward.</dd>
+
+    <dt><code>REQ_SCR_HBLINE</code></dt>
+
+    <dd>Scroll horizontally one field width backward.</dd>
+
+    <dt><code>REQ_SCR_HFHALF</code></dt>
+
+    <dd>Scroll horizontally one half field width forward.</dd>
+
+    <dt><code>REQ_SCR_HBHALF</code></dt>
+
+    <dd>Scroll horizontally one half field width backward.</dd>
+  </dl>
+
+  <p>For scrolling purposes, a <em>page</em> of a field is the
+  height of its visible part.</p>
+
+  <h3><a name="fedit" id="fedit">Editing Requests</a></h3>
+
+  <p>When you pass the forms driver an ASCII character, it is
+  treated as a request to add the character to the field's data
+  buffer. Whether this is an insertion or a replacement depends on
+  the field's edit mode (insertion is the default.</p>
+
+  <p>The following requests support editing the field and changing
+  the edit mode:</p>
+
+  <dl>
+    <dt><code>REQ_INS_MODE</code></dt>
+
+    <dd>Set insertion mode.</dd>
+
+    <dt><code>REQ_OVL_MODE</code></dt>
+
+    <dd>Set overlay mode.</dd>
+
+    <dt><code>REQ_NEW_LINE</code></dt>
+
+    <dd>New line request (see below for explanation).</dd>
+
+    <dt><code>REQ_INS_CHAR</code></dt>
+
+    <dd>Insert space at character location.</dd>
+
+    <dt><code>REQ_INS_LINE</code></dt>
+
+    <dd>Insert blank line at character location.</dd>
+
+    <dt><code>REQ_DEL_CHAR</code></dt>
+
+    <dd>Delete character at cursor.</dd>
+
+    <dt><code>REQ_DEL_PREV</code></dt>
+
+    <dd>Delete previous word at cursor.</dd>
+
+    <dt><code>REQ_DEL_LINE</code></dt>
+
+    <dd>Delete line at cursor.</dd>
+
+    <dt><code>REQ_DEL_WORD</code></dt>
+
+    <dd>Delete word at cursor.</dd>
+
+    <dt><code>REQ_CLR_EOL</code></dt>
+
+    <dd>Clear to end of line.</dd>
+
+    <dt><code>REQ_CLR_EOF</code></dt>
+
+    <dd>Clear to end of field.</dd>
+
+    <dt><code>REQ_CLEAR_FIELD</code></dt>
+
+    <dd>Clear entire field.</dd>
+  </dl>
+
+  <p>The behavior of the <code>REQ_NEW_LINE</code> and
+  <code>REQ_DEL_PREV</code> requests is complicated and partly
+  controlled by a pair of forms options. The special cases are
+  triggered when the cursor is at the beginning of a field, or on
+  the last line of the field.</p>
+
+  <p>First, we consider <code>REQ_NEW_LINE</code>:</p>
+
+  <p>The normal behavior of <code>REQ_NEW_LINE</code> in insert
+  mode is to break the current line at the position of the edit
+  cursor, inserting the portion of the current line after the
+  cursor as a new line following the current and moving the cursor
+  to the beginning of that new line (you may think of this as
+  inserting a newline in the field buffer).</p>
+
+  <p>The normal behavior of <code>REQ_NEW_LINE</code> in overlay
+  mode is to clear the current line from the position of the edit
+  cursor to end of line. The cursor is then moved to the beginning
+  of the next line.</p>
+
+  <p>However, <code>REQ_NEW_LINE</code> at the beginning of a
+  field, or on the last line of a field, instead does a
+  <code>REQ_NEXT_FIELD</code>. <code>O_NL_OVERLOAD</code> option is
+  off, this special action is disabled.</p>
+
+  <p>Now, let us consider <code>REQ_DEL_PREV</code>:</p>
+
+  <p>The normal behavior of <code>REQ_DEL_PREV</code> is to delete
+  the previous character. If insert mode is on, and the cursor is
+  at the start of a line, and the text on that line will fit on the
+  previous one, it instead appends the contents of the current line
+  to the previous one and deletes the current line (you may think
+  of this as deleting a newline from the field buffer).</p>
+
+  <p>However, <code>REQ_DEL_PREV</code> at the beginning of a field
+  is instead treated as a <code>REQ_PREV_FIELD</code>.</p>
+
+  <p>If the <code>O_BS_OVERLOAD</code> option is off, this special
+  action is disabled and the forms driver just returns
+  <code>E_REQUEST_DENIED</code>.</p>
+
+  <p>See <a href="#frmoptions">Form Options</a> for discussion of
+  how to set and clear the overload options.</p>
+
+  <h3><a name="forder" id="forder">Order Requests</a></h3>
+
+  <p>If the type of your field is ordered, and has associated
+  functions for getting the next and previous values of the type
+  from a given value, there are requests that can fetch that value
+  into the field buffer:</p>
+
+  <dl>
+    <dt><code>REQ_NEXT_CHOICE</code></dt>
+
+    <dd>Place the successor value of the current value in the
+    buffer.</dd>
+
+    <dt><code>REQ_PREV_CHOICE</code></dt>
+
+    <dd>Place the predecessor value of the current value in the
+    buffer.</dd>
+  </dl>
+
+  <p>Of the built-in field types, only <code>TYPE_ENUM</code> has
+  built-in successor and predecessor functions. When you define a
+  field type of your own (see <a href="#fcustom">Custom Validation
+  Types</a>), you can associate our own ordering functions.</p>
+
+  <h3><a name="fappcmds" id="fappcmds">Application
+  Commands</a></h3>
+
+  <p>Form requests are represented as integers above the
+  <code>curses</code> value greater than <code>KEY_MAX</code> and
+  less than or equal to the constant <code>MAX_COMMAND</code>. If
+  your input-virtualization routine returns a value above
+  <code>MAX_COMMAND</code>, the forms driver will ignore it.</p>
+
+  <h2><a name="fhooks" id="fhooks">Field Change Hooks</a></h2>
+
+  <p>It is possible to set function hooks to be executed whenever
+  the current field or form changes. Here are the functions that
+  support this:</p>
+  <pre>
+typedef void    (*HOOK)();       /* pointer to function returning void */
 
 int set_form_init(FORM *form,    /* form to alter */
                   HOOK hook);    /* initialization hook */
@@ -2453,53 +3027,66 @@ int set_field_term(FORM *form,   /* form to alter */
                   HOOK hook);    /* termination hook */
 
 HOOK field_term(FORM *form);     /* form to query */
-</PRE>
-
-These functions allow you to either set or query four different hooks.
-In each of the set functions, the second argument should be the
-address of a hook function.  These functions differ only in the timing
-of the hook call.
-
-<DL>
-<DT> form_init
-<DD> This hook is called when the form is posted; also, just after
-each page change operation.
-<DT> field_init
-<DD> This hook is called when the form is posted; also, just after
-each field change
-<DT> field_term
-<DD> This hook is called just after field validation; that is, just before
-the field is altered.  It is also called when the form is unposted.
-<DT> form_term
-<DD> This hook is called when the form is unposted; also, just before
-each page change operation.
-</DL>
-
-Calls to these hooks may be triggered
-<OL>
-<LI>When user editing requests are processed by the forms driver
-<LI>When the current page is changed by <CODE>set_current_field()</CODE> call
-<LI>When the current field is changed by a <CODE>set_form_page()</CODE> call
-</OL>
-
-See <A NAME="ffocus">Field Change Commands</A> for discussion of the latter
-two cases. <P>
-
-You can set a default hook for all fields by passing one of the set functions
-a NULL first argument. <P>
-
-You can disable any of these hooks by (re)setting them to NULL, the default
-value.
-
-<H2><A HREF="#ffocus">Field Change Commands</A></H2>
-
-Normally, navigation through the form will be driven by the user's
-input requests.  But sometimes it is useful to be able to move the
-focus for editing and viewing under control of your application, or
-ask which field it currently is in.  The following functions help you
-accomplish this:
-
-<PRE>
+</pre>
+
+  <p>These functions allow you to either set or query four
+  different hooks. In each of the set functions, the second
+  argument should be the address of a hook function. These
+  functions differ only in the timing of the hook call.</p>
+
+  <dl>
+    <dt>form_init</dt>
+
+    <dd>This hook is called when the form is posted; also, just
+    after each page change operation.</dd>
+
+    <dt>field_init</dt>
+
+    <dd>This hook is called when the form is posted; also, just
+    after each field change</dd>
+
+    <dt>field_term</dt>
+
+    <dd>This hook is called just after field validation; that is,
+    just before the field is altered. It is also called when the
+    form is unposted.</dd>
+
+    <dt>form_term</dt>
+
+    <dd>This hook is called when the form is unposted; also, just
+    before each page change operation.</dd>
+  </dl>
+
+  <p>Calls to these hooks may be triggered</p>
+
+  <ol>
+    <li>When user editing requests are processed by the forms
+    driver</li>
+
+    <li>When the current page is changed by
+    <code>set_current_field()</code> call</li>
+
+    <li>When the current field is changed by a
+    <code>set_form_page()</code> call</li>
+  </ol>
+
+  <p>See <a name="ffocus" id="ffocus">Field Change Commands</a> for
+  discussion of the latter two cases.</p>
+
+  <p>You can set a default hook for all fields by passing one of
+  the set functions a NULL first argument.</p>
+
+  <p>You can disable any of these hooks by (re)setting them to
+  NULL, the default value.</p>
+
+  <h2><a href="#ffocus">Field Change Commands</a></h2>
+
+  <p>Normally, navigation through the form will be driven by the
+  user's input requests. But sometimes it is useful to be able to
+  move the focus for editing and viewing under control of your
+  application, or ask which field it currently is in. The following
+  functions help you accomplish this:</p>
+  <pre>
 int set_current_field(FORM *form,         /* form to alter */
                       FIELD *field);      /* field to shift to */
 
@@ -2507,33 +3094,33 @@ FIELD *current_field(FORM *form);         /* form to query */
 
 int field_index(FORM *form,               /* form to query */
                 FIELD *field);            /* field to get index of */
-</PRE>
-
-The function <CODE>field_index()</CODE> returns the index of the given field
-in the given form's field array (the array passed to <CODE>new_form()</CODE> or
-<CODE>set_form_fields()</CODE>). <P>
+</pre>
 
-The initial current field of a form is the first active field on the
-first page. The function <CODE>set_form_fields()</CODE> resets this.<P>
+  <p>The function <code>field_index()</code> returns the index of
+  the given field in the given form's field array (the array passed
+  to <code>new_form()</code> or
+  <code>set_form_fields()</code>).</p>
 
-It is also possible to move around by pages.
+  <p>The initial current field of a form is the first active field
+  on the first page. The function <code>set_form_fields()</code>
+  resets this.</p>
 
-<PRE>
+  <p>It is also possible to move around by pages.</p>
+  <pre>
 int set_form_page(FORM *form,             /* form to alter */
                   int page);              /* page to go to (0-origin) */
 
 int form_page(FORM *form);                /* return form's current page */
-</PRE>
-
-The initial page of a newly-created form is 0.  The function
-<CODE>set_form_fields()</CODE> resets this.
+</pre>
 
-<H2><A NAME="frmoptions">Form Options</A></H2>
+  <p>The initial page of a newly-created form is 0. The function
+  <code>set_form_fields()</code> resets this.</p>
 
-Like fields, forms may have control option bits.  They can be changed
-or queried with these functions:
+  <h2><a name="frmoptions" id="frmoptions">Form Options</a></h2>
 
-<PRE>
+  <p>Like fields, forms may have control option bits. They can be
+  changed or queried with these functions:</p>
+  <pre>
 int set_form_opts(FORM *form,             /* form to alter */
                   int attr);              /* attribute to set */
 
@@ -2544,179 +3131,206 @@ int form_opts_off(FORM *form,             /* form to alter */
                   int attr);              /* attributes to turn off */
 
 int form_opts(FORM *form);                /* form to query */
-</PRE>
+</pre>
 
-By default, all options are on.  Here are the available option bits:
+  <p>By default, all options are on. Here are the available option
+  bits:</p>
 
-<DL>
-<DT> O_NL_OVERLOAD
-<DD> Enable overloading of <CODE>REQ_NEW_LINE</CODE> as described in <A
-href="#fedit">Editing Requests</A>.  The value of this option is
-ignored on dynamic fields that have not reached their size limit;
-these have no last line, so the circumstances for triggering a
-<CODE>REQ_NEXT_FIELD</CODE> never arise.
-<DT> O_BS_OVERLOAD
-<DD> Enable overloading of <CODE>REQ_DEL_PREV</CODE> as described in
-<A href="#fedit">Editing Requests</A>.
-</DL>
+  <dl>
+    <dt>O_NL_OVERLOAD</dt>
 
-The option values are bit-masks and can be composed with logical-or in
-the obvious way.
+    <dd>Enable overloading of <code>REQ_NEW_LINE</code> as
+    described in <a href="#fedit">Editing Requests</a>. The value
+    of this option is ignored on dynamic fields that have not
+    reached their size limit; these have no last line, so the
+    circumstances for triggering a <code>REQ_NEXT_FIELD</code>
+    never arise.</dd>
 
-<H2><A NAME="fcustom">Custom Validation Types</A></H2>
+    <dt>O_BS_OVERLOAD</dt>
 
-The <CODE>form</CODE> library gives you the capability to define custom
-validation types of your own.  Further, the optional additional arguments
-of <CODE>set_field_type</CODE> effectively allow you to parameterize validation
-types.  Most of the complications in the validation-type interface have to
-do with the handling of the additional arguments within custom validation
-functions.
+    <dd>Enable overloading of <code>REQ_DEL_PREV</code> as
+    described in <a href="#fedit">Editing Requests</a>.</dd>
+  </dl>
 
-<H3><A NAME="flinktypes">Union Types</A></H3>
+  <p>The option values are bit-masks and can be composed with
+  logical-or in the obvious way.</p>
 
-The simplest way to create a custom data type is to compose it from two
-preexisting ones:
+  <h2><a name="fcustom" id="fcustom">Custom Validation
+  Types</a></h2>
 
-<PRE>
+  <p>The <code>form</code> library gives you the capability to
+  define custom validation types of your own. Further, the optional
+  additional arguments of <code>set_field_type</code> effectively
+  allow you to parameterize validation types. Most of the
+  complications in the validation-type interface have to do with
+  the handling of the additional arguments within custom validation
+  functions.</p>
+
+  <h3><a name="flinktypes" id="flinktypes">Union Types</a></h3>
+
+  <p>The simplest way to create a custom data type is to compose it
+  from two preexisting ones:</p>
+  <pre>
 FIELD *link_fieldtype(FIELDTYPE *type1,
                       FIELDTYPE *type2);
-</PRE>
+</pre>
 
-This function creates a field type that will accept any of the values
-legal for either of its argument field types (which may be either
-predefined or programmer-defined).
+  <p>This function creates a field type that will accept any of the
+  values legal for either of its argument field types (which may be
+  either predefined or programmer-defined). If a
+  <code>set_field_type()</code> call later requires arguments, the
+  new composite type expects all arguments for the first type, than
+  all arguments for the second. Order functions (see <a href=
+  "#forder">Order Requests</a>) associated with the component types
+  will work on the composite; what it does is check the validation
+  function for the first type, then for the second, to figure what
+  type the buffer contents should be treated as.</p>
 
-If a <CODE>set_field_type()</CODE> call later requires arguments, the new
-composite type expects all arguments for the first type, than all arguments
-for the second.  Order functions (see <A HREF="#forder">Order Requests</A>)
-associated with the component types will work on the composite; what it does
-is check the validation function for the first type, then for the second, to
-figure what type the buffer contents should be treated as.
+  <h3><a name="fnewtypes" id="fnewtypes">New Field Types</a></h3>
 
-<H3><A NAME="fnewtypes">New Field Types</A></H3>
+  <p>To create a field type from scratch, you need to specify one
+  or both of the following things:</p>
 
-To create a field type from scratch, you need to specify one or both of the
-following things:
+  <ul>
+    <li>A character-validation function, to check each character as
+    it is entered.</li>
 
-<UL>
-<LI>A character-validation function, to check each character as it is entered.
-<LI>A field-validation function to be applied on exit from the field.
-</UL>
+    <li>A field-validation function to be applied on exit from the
+    field.</li>
+  </ul>
 
-Here's how you do that:
-<PRE>
-typedef int    (*HOOK)();       /* pointer to function returning int */
+  <p>Here is how you do that:</p>
+  <pre>
+typedef int     (*HOOK)();       /* pointer to function returning int */
 
 FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
                          HOOK c_validate) /* character validator */
 
 
 int free_fieldtype(FIELDTYPE *ftype);     /* type to free */
-</PRE>
+</pre>
+
+  <p>At least one of the arguments of <code>new_fieldtype()</code>
+  must be non-NULL. The forms driver will automatically call the
+  new type's validation functions at appropriate points in
+  processing a field of the new type.</p>
+
+  <p>The function <code>free_fieldtype()</code> deallocates the
+  argument fieldtype, freeing all storage associated with it.</p>
+
+  <p>Normally, a field validator is called when the user attempts
+  to leave the field. Its first argument is a field pointer, from
+  which it can get to field buffer 0 and test it. If the function
+  returns TRUE, the operation succeeds; if it returns FALSE, the
+  edit cursor stays in the field.</p>
+
+  <p>A character validator gets the character passed in as a first
+  argument. It too should return TRUE if the character is valid,
+  FALSE otherwise.</p>
+
+  <h3><a name="fcheckargs" id="fcheckargs">Validation Function
+  Arguments</a></h3>
+
+  <p>Your field- and character- validation functions will be passed
+  a second argument as well. This second argument is the address of
+  a structure (which we will call a <em>pile</em>) built from any
+  of the field-type-specific arguments passed to
+  <code>set_field_type()</code>. If no such arguments are defined
+  for the field type, this pile pointer argument will be NULL.</p>
+
+  <p>In order to arrange for such arguments to be passed to your
+  validation functions, you must associate a small set of
+  storage-management functions with the type. The forms driver will
+  use these to synthesize a pile from the trailing arguments of
+  each <code>set_field_type()</code> argument, and a pointer to the
+  pile will be passed to the validation functions.</p>
+
+  <p>Here is how you make the association:</p>
+  <pre>
+typedef char    *(*PTRHOOK)();    /* pointer to function returning (char *) */
+typedef void    (*VOIDHOOK)();    /* pointer to function returning void */
 
-At least one of the arguments of <CODE>new_fieldtype()</CODE> must be
-non-NULL.  The forms driver will automatically call the new type's
-validation functions at appropriate points in processing a field of
-the new type. <P>
+int set_fieldtype_arg(FIELDTYPE *type,    /* type to alter */
+                      PTRHOOK make_str,   /* make structure from args */
+                      PTRHOOK copy_str,   /* make copy of structure */
+                      VOIDHOOK free_str); /* free structure storage */
+</pre>
 
-The function <CODE>free_fieldtype()</CODE> deallocates the argument
-fieldtype, freeing all storage associated with it. <P>
+  <p>Here is how the storage-management hooks are used:</p>
 
-Normally, a field validator is called when the user attempts to
-leave the field.  Its first argument is a field pointer, from which it
-can get to field buffer 0 and test it.  If the function returns TRUE,
-the operation succeeds; if it returns FALSE, the edit cursor stays in
-the field. <P>
+  <dl>
+    <dt><code>make_str</code></dt>
 
-A character validator gets the character passed in as a first argument.
-It too should return TRUE if the character is valid, FALSE otherwise.
+    <dd>This function is called by <code>set_field_type()</code>.
+    It gets one argument, a <code>va_list</code> of the
+    type-specific arguments passed to
+    <code>set_field_type()</code>. It is expected to return a pile
+    pointer to a data structure that encapsulates those
+    arguments.</dd>
 
-<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3>
+    <dt><code>copy_str</code></dt>
 
-Your field- and character- validation functions will be passed a
-second argument as well.  This second argument is the address of a
-structure (which we'll call a <EM>pile</EM>) built from any of the
-field-type-specific arguments passed to <CODE>set_field_type()</CODE>.  If
-no such arguments are defined for the field type, this pile pointer
-argument will be NULL. <P>
+    <dd>This function is called by form library functions that
+    allocate new field instances. It is expected to take a pile
+    pointer, copy the pile to allocated storage, and return the
+    address of the pile copy.</dd>
 
-In order to arrange for such arguments to be passed to your validation
-functions, you must associate a small set of storage-management functions
-with the type.  The forms driver will use these to synthesize a pile
-from the trailing arguments of each <CODE>set_field_type()</CODE> argument, and
-a pointer to the pile will be passed to the validation functions. <P>
+    <dt><code>free_str</code></dt>
 
-Here is how you make the association:
+    <dd>This function is called by field- and type-deallocation
+    routines in the library. It takes a pile pointer argument, and
+    is expected to free the storage of that pile.</dd>
+  </dl>
 
-<PRE>
-typedef char   *(*PTRHOOK)();    /* pointer to function returning (char *) */
-typedef void   (*VOIDHOOK)();    /* pointer to function returning void */
+  <p>The <code>make_str</code> and <code>copy_str</code> functions
+  may return NULL to signal allocation failure. The library
+  routines will that call them will return error indication when
+  this happens. Thus, your validation functions should never see a
+  NULL file pointer and need not check specially for it.</p>
 
-int set_fieldtype_arg(FIELDTYPE *type,    /* type to alter */
-                      PTRHOOK make_str,   /* make structure from args */
-                      PTRHOOK copy_str,   /* make copy of structure */
-                      VOIDHOOK free_str); /* free structure storage */
-</PRE>
-
-Here is how the storage-management hooks are used:
-
-<DL>
-<DT> <CODE>make_str</CODE>
-<DD> This function is called by <CODE>set_field_type()</CODE>.  It gets one
-argument, a <CODE>va_list</CODE> of the type-specific arguments passed to
-<CODE>set_field_type()</CODE>.  It is expected to return a pile pointer to a data
-structure that encapsulates those arguments.
-<DT> <CODE>copy_str</CODE>
-<DD> This function is called by form library functions that allocate new
-field instances.  It is expected to take a pile pointer, copy the pile
-to allocated storage, and return the address of the pile copy.
-<DT> <CODE>free_str</CODE>
-<DD> This function is called by field- and type-deallocation routines in the
-library.  It takes a pile pointer argument, and is expected to free the
-storage of that pile.
-</DL>
-
-The <CODE>make_str</CODE> and <CODE>copy_str</CODE> functions may return NULL to
-signal allocation failure.  The library routines will that call them will
-return error indication when this happens.  Thus, your validation functions
-should never see a NULL file pointer and need not check specially for it.
-
-<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3>
-
-Some custom field types are simply ordered in the same well-defined way
-that <CODE>TYPE_ENUM</CODE> is.  For such types, it is possible to define
-successor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE>
-and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how:
-
-<PRE>
-typedef int    (*INTHOOK)();     /* pointer to function returning int */
+  <h3><a name="fcustorder" id="fcustorder">Order Functions For
+  Custom Types</a></h3>
+
+  <p>Some custom field types are simply ordered in the same
+  well-defined way that <code>TYPE_ENUM</code> is. For such types,
+  it is possible to define successor and predecessor functions to
+  support the <code>REQ_NEXT_CHOICE</code> and
+  <code>REQ_PREV_CHOICE</code> requests. Here is how:</p>
+  <pre>
+typedef int     (*INTHOOK)();     /* pointer to function returning int */
 
 int set_fieldtype_arg(FIELDTYPE *type,    /* type to alter */
                       INTHOOK succ,       /* get successor value */
                       INTHOOK pred);      /* get predecessor value */
-</PRE>
-
-The successor and predecessor arguments will each be passed two arguments;
-a field pointer, and a pile pointer (as for the validation functions).  They
-are expected to use the function <CODE>field_buffer()</CODE> to read the
-current value, and <CODE>set_field_buffer()</CODE> on buffer 0 to set the next
-or previous value.  Either hook may return TRUE to indicate success (a
-legal next or previous value was set) or FALSE to indicate failure.
-
-<H3><A NAME="fcustprobs">Avoiding Problems</A></H3>
-
-The interface for defining custom types is complicated and tricky.
-Rather than attempting to create a custom type entirely from scratch,
-you should start by studying the library source code for whichever of
-the pre-defined types seems to be closest to what you want. <P>
-
-Use that code as a model, and evolve it towards what you really want.
-You will avoid many problems and annoyances that way.  The code
-in the <CODE>ncurses</CODE> library has been specifically exempted from
-the package copyright to support this. <P>
-
-If your custom type defines order functions, have do something intuitive
-with a blank field.  A useful convention is to make the successor of a
-blank field the types minimum value, and its predecessor the maximum.
-</BODY>
-</HTML>
+</pre>
+
+  <p>The successor and predecessor arguments will each be passed
+  two arguments; a field pointer, and a pile pointer (as for the
+  validation functions). They are expected to use the function
+  <code>field_buffer()</code> to read the current value, and
+  <code>set_field_buffer()</code> on buffer 0 to set the next or
+  previous value. Either hook may return TRUE to indicate success
+  (a legal next or previous value was set) or FALSE to indicate
+  failure.</p>
+
+  <h3><a name="fcustprobs" id="fcustprobs">Avoiding
+  Problems</a></h3>
+
+  <p>The interface for defining custom types is complicated and
+  tricky. Rather than attempting to create a custom type entirely
+  from scratch, you should start by studying the library source
+  code for whichever of the pre-defined types seems to be closest
+  to what you want.</p>
+
+  <p>Use that code as a model, and evolve it towards what you
+  really want. You will avoid many problems and annoyances that
+  way. The code in the <code>ncurses</code> library has been
+  specifically exempted from the package copyright to support
+  this.</p>
+
+  <p>If your custom type defines order functions, have do something
+  intuitive with a blank field. A useful convention is to make the
+  successor of a blank field the types minimum value, and its
+  predecessor the maximum.</p>
+</body>
+</html>