Virgin import of FSF groff v1.15

4 files changed, 5785 insertions, 12 deletions

diff --git a/contrib/groff/doc/Makefile b/contrib/groff/doc/Makefile
index 4c56aa3..cccc52c 100644
--- a/contrib/groff/doc/Makefile
+++ b/contrib/groff/doc/Makefile
@@ -20,15 +20,15 @@
 FFLAG=-F..
 TROFF=../troff/troff -M../tmac $(FFLAG)
 GROPS=../grops/grops $(FFLAG)
-DOCS=meref.PS meintro.PS pic.PS
+DOCS=meref.ps meintro.ps pic.ps
 MEMACROS=../macros/tmac.e
 SOELIM=../soelim/soelim
 
 all: $(DOCS)
 
-.SUFFIXES: .tr .me .ms .PS .dit
+.SUFFIXES: .tr .me .ms .ps .dit
 
-.dit.PS:
+.dit.ps:
 	$(GROPS) $< >$@
 
 .me.dit:
@@ -39,18 +39,24 @@ all: $(DOCS)
 .tr.dit:
 	$(TROFF) -Tps $< >$@
 
-meref.PS: meref.dit
-meintro.PS: meintro.dit
+meref.ps: meref.dit
+meintro.ps: meintro.dit
 
 # This production must use -p -e -t so pic/eqn processing is done
-pic.PS: pic.ms
-	sed $< -e "s;@VERSION@;`cat ../VERSION`;" \
+pic.ps: pic.ms
+	sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
 	| ../groff/groff -p -e -t -Tps $(FFLAG) -ms  >$@
 
+pic.html: pic.ms
+	sed -e "s;@VERSION@;`cat ../VERSION`;" $< \
+	| ../groff/groff -p -e -t -Thtml $(FFLAG) -ms -mhtml >$@
+
 install:
 
 clean:
-	-rm -f *.PS *.dit core
+	-rm -f *.ps *.html *.png *.gif *.dit core
+	-rm -f *.aux *.cp *.cps *.cv *.cn *.dvi *.fn *.fns *.ky *.kys \
+               *.log *.op *.pg *.pgs *.ps *.toc *.tp *.tps *.tr *.vr *.vrs
 
 distclean: clean
 
diff --git a/contrib/groff/doc/groff.texinfo b/contrib/groff/doc/groff.texinfo
new file mode 100644
index 0000000..85d92c6
--- /dev/null
+++ b/contrib/groff/doc/groff.texinfo
@@ -0,0 +1,5762 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header (This is for running Texinfo on a region.)
+@setfilename  groff
+@settitle The GNU Troff Manual
+@setchapternewpage odd
+@footnotestyle separate
+@c %**end of header (This is for running Texinfo on a region.)
+
+
+@dircategory Miscellaneous
+@direntry
+* Groff: (groff).   The GNU troff document formatting system.
+@end direntry
+
+
+@smallbook
+
+
+@iftex
+@finalout
+@end iftex
+
+
+@ifinfo
+This Info file documents GNU troff version 1.12.
+
+Published by the Free Software Foundation
+59 Temple Place, Suite 330
+Boston, MA  02111-1307  USA
+
+Copyright (C) 1994, 1999 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Foundation.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this
+one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the Free Software Foundation
+instead of in the original English.
+@end ifinfo
+
+
+@titlepage
+@title groff
+@subtitle The GNU implementation of @code{groff}
+@subtitle Edition 1.12
+@subtitle October 1999
+@author by Trent A.@w{ }Fisher
+@author and the maintainer of groff
+
+@c Include the Distribution inside the titlepage environment so
+@c that headings are turned off.  Headings on and off do not work.
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1994, 1999 Free Software Foundation, Inc.
+
+@sp 2
+Version 1.13 of @code{groff}, @*
+October 1999
+@sp 2
+Published by the Free Software Foundation @*
+59 Temple Place, Suite 330 @*
+Boston, MA  02111-1307  USA
+
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' may be
+included in a translation approved by the Free Software Foundation
+instead of in the original English.
+
+Cover art by Etienne Suvasa.
+@end titlepage
+@page
+
+
+
+@node Top, Copying, (dir), (dir)
+
+@ifinfo
+This Info file documents groff version 1.13, the GNU implementation of
+the troff typesetting system.
+
+This is an in-progress document; contributions, comments, or
+contributions are welcome.  Send them to bug-groff@@gnu.org.
+@end ifinfo
+
+@menu
+* Copying::                     
+* Introduction::                
+* Invoking groff::              
+* Tutorial for Macro Users::    
+* -man::                        
+* -ms::                         
+* -me::                         
+* -mm::                         
+* Programming Tutorial::        
+* geqn::                        
+* gtbl::                        
+* gpic::                        
+* grap::                        
+* grefer::                      
+* gsoelim::                     
+* Devices::                     
+* File formats::                
+* Installation::                
+* Request Index::               
+* Register Index::              
+* String Index::                
+* Macro Index::                 
+* Program Index::               
+* Concept Index::               
+@end menu
+
+
+
+@node Copying, Introduction, Top, Top
+@cindex copying
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111, USA
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+@end display
+
+@unnumberedsec Preamble
+
+The licenses for most software are designed to take away your freedom to
+share and change it.  By contrast, the GNU General Public License is
+intended to guarantee your freedom to share and change free software --
+to make sure the software is free for all its users.  This General
+Public License applies to most of the Free Software Foundation's
+software and to any other program whose authors commit to using it.
+(Some other Free Software Foundation software is covered by the GNU
+Library General Public License instead.)  You can apply it to your
+programs, too.
+
+When we speak of free software, we are referring to freedom, not price.
+Our General Public Licenses are designed to make sure that you have the
+freedom to distribute copies of free software (and charge for this
+service if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs; and that you know you can do these things.
+
+To protect your rights, we need to make restrictions that forbid anyone
+to deny you these rights or to ask you to surrender the rights.  These
+restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+For example, if you distribute copies of such a program, whether gratis
+or for a fee, you must give the recipients all the rights that you have.
+You must make sure that they, too, receive or can get the source code.
+And you must show them these terms so they know their rights.
+
+We protect your rights with two steps: (1)@w{ }copyright the software,
+and (2)@w{ }offer you this license which gives you legal permission to
+copy, distribute and/or modify the software.
+
+Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+Finally, any free program is threatened constantly by software patents.
+We wish to avoid the danger that redistributors of a free program will
+individually obtain patent licenses, in effect making the program
+proprietary.  To prevent this, we have made it clear that any patent
+must be licensed for everyone's free use or not licensed at all.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate 0
+@item
+This License applies to any program or other work which contains a
+notice placed by the copyright holder saying it may be distributed under
+the terms of this General Public License.  The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it, either
+verbatim or with modifications and/or translated into another language.
+(Hereinafter, translation is included without limitation in the term
+``modification''.)  Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of running
+the Program is not restricted, and the output from the Program is
+covered only if its contents constitute a work based on the Program
+(independent of having been made by running the Program).  Whether that
+is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's source code
+as you receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice and
+disclaimer of warranty; keep intact all the notices that refer to this
+License and to the absence of any warranty; and give any other
+recipients of the Program a copy of this License along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion of it,
+thus forming a work based on the Program, and copy and distribute such
+modifications or work under the terms of Section@w{ }1 above, provided
+that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices stating
+that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in whole or
+in part contains or is derived from the Program or any part thereof, to
+be licensed as a whole at no charge to all third parties under the terms
+of this License.
+
+@item
+If the modified program normally reads commands interactively when run,
+you must cause it, when started running for such interactive use in the
+most ordinary way, to print or display an announcement including an
+appropriate copyright notice and a notice that there is no warranty (or
+else, saying that you provide a warranty) and that users may
+redistribute the program under these conditions, and telling the user
+how to view a copy of this License.  (Exception: if the Program itself
+is interactive but does not normally print such an announcement, your
+work based on the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program, and
+can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based on
+the Program, the distribution of the whole must be on the terms of this
+License, whose permissions for other licensees extend to the entire
+whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of a
+storage or distribution medium does not bring the other work under the
+scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it, under
+Section@w{ }2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable source
+code, which must be distributed under the terms of Sections 1 and 2
+above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three years, to
+give any third party, for a charge no more than your cost of physically
+performing source distribution, a complete machine-readable copy of the
+corresponding source code, to be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer to
+distribute corresponding source code.  (This alternative is allowed only
+for noncommercial distribution and only if you received the program in
+object code or executable form with such an offer, in accord with
+Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to control
+compilation and installation of the executable.  However, as a special
+exception, the source code distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies the
+executable.
+
+If distribution of executable or object code is made by offering access
+to copy from a designated place, then offering equivalent access to copy
+the source code from the same place counts as distribution of the source
+code, even though third parties are not compelled to copy the source
+along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program except
+as expressly provided under this License.  Any attempt otherwise to
+copy, modify, sublicense or distribute the Program is void, and will
+automatically terminate your rights under this License.  However,
+parties who have received copies, or rights, from you under this License
+will not have their licenses terminated so long as such parties remain
+in full compliance.
+
+@item
+You are not required to accept this License, since you have not signed
+it.  However, nothing else grants you permission to modify or distribute
+the Program or its derivative works.  These actions are prohibited by
+law if you do not accept this License.  Therefore, by modifying or
+distributing the Program (or any work based on the Program), you
+indicate your acceptance of this License to do so, and all its terms and
+conditions for copying, distributing or modifying the Program or works
+based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further restrictions
+on the recipients' exercise of the rights granted herein.  You are not
+responsible for enforcing compliance by third parties to this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent license
+would not permit royalty-free redistribution of the Program by all those
+who receive copies directly or indirectly through you, then the only way
+you could satisfy both it and this License would be to refrain entirely
+from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is implemented
+by public license practices.  Many people have made generous
+contributions to the wide range of software distributed through that
+system in reliance on consistent application of that system; it is up to
+the author/donor to decide if he or she is willing to distribute
+software through any other system and a licensee cannot impose that
+choice.
+
+This section is intended to make thoroughly clear what is believed to be
+a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in certain
+countries either by patents or by copyrighted interfaces, the original
+copyright holder who places the Program under this License may add an
+explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions of
+the General Public License from time to time.  Such new versions will be
+similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Program does not specify a version
+number of this License, you may choose any version ever published by the
+Free Software Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free programs
+whose distribution conditions are different, write to the author to ask
+for permission.  For software which is copyrighted by the Free Software
+Foundation, write to the Free Software Foundation; we sometimes make
+exceptions for this.  Our decision will be guided by the two goals of
+preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
+THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
+EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
+THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+YOU@.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
+DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
+(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
+OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program.  It is safest to
+attach them to the start of each source file to most effectively convey
+the exclusion of warranty; and each file should have at least the
+``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy} @var{name of author}
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2 of the License, or (at your
+option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place, Suite 330, Boston, MA 02111, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
+`show w'.  This is free software, and you are welcome to redistribute it
+under certain conditions; type `show c' for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary.  Here is a sample; alter the names:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written 
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+This General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications
+with the library.  If this is what you want to do, use the GNU Library
+General Public License instead of this License.
+
+
+
+@node Introduction, Invoking groff, Copying, Top
+@chapter Introduction
+@cindex introduction
+
+GNU @code{troff} (or @code{groff}) is a system for typesetting
+documents.  @code{troff} is very flexible and has been in existence (and
+use) for about 3@w{ }decades.  It is quite widespread and firmly
+entrenched in the @sc{Unix} community.
+
+
+
+@menu
+* What Is groff?::              
+* History::                     
+* groff Capabilities::          
+* Macro Packages::              
+* Preprocessors::               
+* Postprocessors::              
+* Credits::                     
+@end menu
+
+@node What Is groff?, History, Introduction, Introduction
+@section What Is @code{groff}?
+@cindex what is @code{groff}?
+@cindex @code{groff} -- what is it?
+
+
+@code{groff} is of an older generation of document preparation systems,
+which operate more like compilers than the more recent interactive
+WYSIWYG @footnote{What You See Is What You Get} systems.  @code{groff}
+and its contemporary counterpart, @TeX{}, both work using a @dfn{batch}
+paradigm: The input (or @dfn{source}) files are normal text files with
+embedded formatting commands.  These files can then be processed by
+@code{groff} to produce a typeset document on a variety of devices.
+
+Likewise, @code{groff} should not be confused with a @dfn{word
+processor}, since that term connotes an integrated system which includes
+an editor and a text formatter.  Also, many word processors follow the
+WYSIWYG paradigm which was discussed earlier.
+
+Although WYSIWYG systems may be easier to use, they have a number of
+disadvantages compared to @code{troff}:
+
+@itemize @bullet{}
+@item
+They must be used on a bitmapped display to do any operations on your
+document.
+@item
+Most of the WYSIWYG systems are either non-free or are not very
+portable.
+@item
+@code{troff} is firmly entrenched in all @sc{Unix} systems.
+@item
+It is difficult to have a wide range of capabilities available within
+the confines of a GUI/window system.
+@item
+It is more difficult to make global changes to a document.
+@end itemize
+
+@quotation
+``GUIs normally make it simple to accomplish simple actions and
+impossible to accomplish complex actions.''  --Doug Gwyn (22/Jun/91 in
+@code{comp.unix.wizards})
+@end quotation
+
+
+
+@node History, groff Capabilities, What Is groff?, Introduction
+@section History
+@cindex history
+
+@code{troff} can trace its origins back to a formatting program called
+@code{runoff} which ran on MIT's CTSS system.  This name came from the
+common phrase of the time ``I'll run off a document.''
+
+The first version of @sc{Unix} was developed on a PDP-7 which was
+sitting around Bell Labs.  In 1971 the developers wanted to get a PDP-11
+for further work on the operating system.  In order to justify the cost
+for this system, they proposed that they would implement a document
+formatting system for the AT&T patents division.  This first formatting
+program was a reimplementation of @code{runoff}.  In accordance with
+@sc{Unix}'s penchant for abreviations, it was named @code{roff} (an
+abreviation of @code{runoff}).
+
+When they needed a more flexible language, a new version of @code{roff}
+called @code{nroff} (Newer @code{roff}) was written.  It had a much more
+complicated syntax, but provided the basis for all future versions.
+When they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{
+}Ossanna wrote a version of @code{nroff} which would drive it.  It was
+dubbed @code{troff} for typesetter @code{roff}, although many people
+have speculated that it actually means Times @code{roff} because of
+@code{troff}'s use of the Times font family by default.  As such, the
+name @code{troff} is pronounced t-roff rather than trough.
+
+With @code{troff} came @code{nroff} (they were actually the same program
+except for some @samp{#ifdefs}), which was for producing output for line
+printers and ascii terminals.  It understood everything @code{troff}
+did, and ignored the commands which were not aplicable (i.e.@: font
+changes).
+
+Since there are several things which cannot be done easily in
+@code{troff}, work on several preprocessors began.  These programs would
+transform certain parts of a document into @code{troff}, which made a
+very natural use of pipes in @sc{Unix}.
+
+The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
+specified in a much simpler and more intuitive manner.  @code{tbl} is a
+preprocessor for formatting tables.  The @code{refer} preprocessor (and
+the similar program, @code{bib}) processes citations in a document
+according to a bibliographic database.
+
+Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
+language and produced output specifically for the CAT phototypesetter.
+He rewrote it in C, although it was now 7000@w{ }lines of uncommented
+code and still dependent on the CAT.  As the CAT became less common, and
+was no longer supported by the manufacturer, the need to make it support
+other devices became a priority.  However, before this could be done, he
+was killed in an auto accident.
+
+@pindex ditroff
+So, Brian Kernighan took on the task of rewriting @code{troff}.  The
+newly rewritten version produced a device independent code which was
+very easy for postprocessors to read and translate to the appropriate
+printer codes.  Also, this new version of @code{troff} (called
+@code{ditroff}) had several extentions, which included drawing
+functions.
+
+Due to the additional abilities of the new version of @code{troff},
+several new preprocessors appeared.  The @code{pic} preprocessor
+provides a wide range of drawing functions.  Likewise the @code{ideal}
+preprocessor did the same, although via a much different paradigm.  The
+@code{grap} preprocessor took specifications for graphs, but, unlike
+other preprocessors, produced @code{pic} code.
+
+James Clark began work on a GNU implementation of @code{ditroff} in
+early@w{ }1989.  The first version, @code{groff}@w{ }0.3.1, was released
+June@w{ }1990.  @code{groff} included
+
+@itemize @bullet{}
+@item
+A replacement for @code{ditroff} with many extentions.
+@item
+The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
+@item
+Postprocessors for ascii devices, PostScript, @TeX{} DVI, and X@w{
+}windows.  GNU @code{troff} also eliminated the need for a separate
+@code{nroff} program with a postprocessor which would produce ascii
+output.
+@item
+A version of the @code{-me} macros and an implementation of the
+@code{-man} macros.
+@end itemize
+
+Also, a front-end was included which could construct the, sometimes
+painfully long, pipelines required for all the post- and preprocessors.
+
+Development of GNU @code{troff} progressed rapidly, and saw the
+additions of a replacement for @code{refer}, an implementation of the
+@code{-ms} and @code{-mm} macros, and a program to deduce how to format
+a document (@code{grog}).
+
+It was declared a stable (i.e.@: non beta) package with the release of
+version@w{ }1.04 around November@w{ }1991.
+
+
+
+@node groff Capabilities, Macro Packages, History, Introduction
+@section @code{groff} Capabilities
+@cindex @code{groff} capabilities
+@cindex capabilities of @code{groff}
+
+So what exactly is @code{groff} capable of doing?  @code{groff} provides
+a wide range of low-level text formatting operations.  Using these, you
+can perform a wide range of formatting tasks, such as footnotes, table
+of contents, multiple columns, etc.
+
+@itemize @bullet{}
+@item
+Text filling, adjusting, and centering
+@item
+Hyphenation
+@item
+Page control
+@item
+Font and character size control
+@item
+Vertical spacing (i.e.@: double spacing)
+@item
+Line length and indenting
+@item
+Macros, strings, diversions, and traps
+@item
+Number registers
+@item
+Tabs, leaders, and fields
+@item
+Input and output conventions and character translation
+@item
+Overstrike, bracket, line drawing, and zero-width functions
+@item
+Local horizontal and vertical motions and the width function
+@item
+Three-part titles
+@item
+Output line numbering
+@item
+Conditional acceptance of input
+@item
+Environment switching
+@item
+Insertions from the standard input
+@item
+Input/output file switching
+@item
+Output and error messages
+@end itemize
+
+
+@node Macro Packages, Preprocessors, groff Capabilities, Introduction
+@section Macro Packages
+@cindex macro packages
+
+Since @code{groff} provides such low level facilities, it can be quite
+difficult to use by itself.  However, @code{groff} provides a
+@dfn{macro} facility which allows you to specify how certain routine
+operations (e.g.@w{ }starting paragraphs, printing headers and footers,
+etc.)@: should be done.  These macros can be collected together into a
+@dfn{macro package}.  There are a number of macro packages available;
+the most common (and the ones described in this manual) are @code{-man},
+@code{-me}, @code{-ms}, and @code{-mm}.
+
+
+@node Preprocessors, Postprocessors, Macro Packages, Introduction
+@section Preprocessors
+@cindex preprocessors
+
+Although @code{groff} provides most functions needed to format a
+document, some operations would be unwieldy (i.e.@: drawing pictures).
+Therefore, programs called preprocessors were written which understand
+their own language and produce the necessary groff operations.  These
+preprocessors are able to differentiate their own input from the rest of
+the document via markers.
+
+To use a preprocessor, @sc{Unix} pipes are used to feed the output from
+the preprocessor into @code{groff}.  Any number of preprocessors may be
+used on a given document; in this case, the preprocessors are linked
+together into one pipeline.  However, in @code{groff}, the user does not
+need to construct the pipe, but only tell @code{groff} what
+preprocessors to use.
+
+@code{groff} currently has preprocessors for producing tables
+(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
+(@code{pic}), and for processing bibliographies (@code{refer}).  An
+associated program which is useful when dealing with preprocessors is
+@code{soelim}.
+
+There are other preprocessors in existence, but there are,
+unfortunately, no free implementations available.  They are for drawing
+pictures (@code{ideal} and @code{gremlin}), for drawing graphs
+(@code{grap}), and chemical structures (@code{chem}).
+
+
+@node Postprocessors, Credits, Preprocessors, Introduction
+@section Postprocessors
+@cindex postprocessors
+
+@code{groff} actually produces device independent code which may be fed
+into a postprocessor which will produce output for a particular device.
+Currently, @code{groff} has postprocessors for PostScript, ascii
+terminals, X@w{ }windows (for previewing), @TeX{} DVI format, and HTML.
+
+
+@node Credits,  , Postprocessors, Introduction
+@section Credits
+@cindex credits
+
+
+Large portions of this manual were taken from existing documents, most
+notably, the manual pages for the @code{groff} package by James Clark,
+and Eric Allman's papers on the @code{-me} macro package.
+
+
+
+@node Invoking groff, Tutorial for Macro Users, Introduction, Top
+@chapter Invoking @code{groff}
+@cindex invoking @code{groff}
+@cindex @code{groff} invocation
+
+
+@pindex groff
+@pindex gtroff
+This section focuses on how to invoke the @code{groff} front end.  This
+front end takes care of the details of constructing the pipeline among
+the preprocessors, @code{gtroff} and the postprocessor.
+
+It has become a tradition that GNU programs get the prefix @dfn{g} to
+distinguish it from its original counterparts provided by the host
+(@pxref{Environment}, for more details).  Thus, for example, @code{geqn}
+is GNU @code{eqn}.  On operating systems like Linux or the Hurd, which
+don't contain proprietary software, this prefix is omitted since GNU
+@code{troff} is the only used incarnation of @code{troff}.  Exception:
+@code{groff} is never replaced by `roff'.
+
+
+@menu
+* Options::                     
+* Environment::                 
+* Invocation Examples::         
+@end menu
+
+@node Options, Environment, Invoking groff, Invoking groff
+@section Options
+@cindex options
+
+
+@pindex groff
+@pindex gtroff
+@pindex gpic
+@pindex geqn
+@pindex gtbl
+@pindex grefer
+@pindex gsoelim
+@code{groff} is a front-end to the groff document formatting system.
+Normally it runs the @code{gtroff} program and a postprocessor
+appropriate for the selected device.  The default device is @samp{ps}.
+It can optionally preprocess with any of @code{gpic}, @code{geqn},
+@code{gtbl}, @code{grefer}, or @code{gsoelim}.
+
+This section only documents options to the @code{groff} front end.  Many
+of the arguments to @code{groff} are passed on to @code{gtroff},
+therefore those are also included.  Arguments to pre- or postprocessors
+can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
+gtbl}, @ref{Invoking grefer}, @ref{Invoking gsoelim}, @ref{Invoking
+grotty}, @ref{Invoking grops}, @ref{Invoking grohtml}, @ref{Invoking
+grodvi}, and @ref{Invoking gxditview}
+
+The command line format for @code{groff} is:
+
+@example
+groff [ -abehilpstvzCENRSVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
+      [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
+      [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
+      [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ]
+      [ @var{files}@dots{} ]
+@end example
+
+The command line format for @code{gtroff} is as follows.  As you can
+see, many of the options to @code{groff} are actually passed on to
+@code{gtroff}.
+
+@example
+gtroff [ -abivzCER ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
+       [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
+       [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
+       [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
+@end example
+
+Options without an argument can be grouped behind a single @samp{-}.  A
+filename of @samp{-} denotes the standard input.
+
+@pindex grog
+The @code{grog} command can be used to guess the correct @code{groff}
+command to use to format a file.
+
+@table @samp
+@item -h
+Print a help message.
+@item -e
+Preprocess with @code{geqn}.
+@item -t
+Preprocess with @code{gtbl}.
+@item -p
+Preprocess with @code{gpic}.
+@item -s
+Preprocess with @code{gsoelim}.
+@item -R
+Preprocess with @code{grefer}.  No mechanism is provided for passing
+arguments to @code{grefer} because most @code{grefer} options have
+equivalent commands which can be included in the file.  @xref{grefer},
+for more details.
+
+@pindex troffrc
+Note that @code{gtroff} also accepts a @samp{-R} option, which is not
+accessible via @code{groff}.  This option prevents the loading of the
+@file{troffrc} file.
+@item -v
+Make programs run by @code{groff} print out their version number.
+@item -V
+Print the pipeline on stdout instead of executing it.
+@item -z
+Suppress output from @code{gtroff}.  Only error messages will be printed.
+@item -Z
+Do not postprocess the output of @code{gtroff}.  Normally @code{groff}
+will automatically run the appropriate postprocessor.
+@item -P@var{arg}
+Pass @var{arg} to the postprocessor.  Each argument should be passed
+with a separate @samp{-P} option. Note that groff does not prepend
+@samp{-} to @var{arg} before passing it to the postprocessor.
+@item -l
+Send the output to a printer.  The command used for this is specified by
+the print command in the device description file.
+@item -L@var{arg}
+Pass @var{arg} to the spooler.  Each argument should be passed with a
+separate @samp{-L} option.  Note that @code{groff} does not prepend a
+@samp{-} to @var{arg} before passing it to the postprocessor.
+@item -T@var{dev}
+Prepare output for device @var{dev}.  The default device is @samp{ps}.
+The following are the output devices currently available:
+@table @samp
+@item ps
+For PostScript printers and previewers.
+@item dvi
+For TeX dvi format.
+@item X75
+For a 75 dpi X11 previewer.
+@item X100
+For a 100dpi X11 previewer.
+@item ascii
+For typewriter-like devices.
+@item latin1
+For typewriter-like devices using the ISO Latin-1 character set.
+@item lj4
+For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
+@item html
+To produce HTML output.
+@end table
+
+The postprocessor to be used for a device is specified by the
+@code{postpro} command in the device description file.  (@xref{Font
+Files}, for more info.)  This can be overridden with the @samp{-X}
+option.
+@item -X
+Preview with @code{gxditview} instead of using the usual postprocessor.
+This is unlikely to produce good results except with @samp{-Tps}.
+@item -N
+Don't allow newlines with @code{eqn} delimiters.  This is the same as
+the @samp{-N} option in @code{geqn}.
+@item -S
+Safer mode.  Pass the @samp{-S} option to @code{gpic} and use the
+@samp{-msafer} macros with @code{gtroff}.
+@item -a
+Generate an ASCII approximation of the typeset output.
+@item -b
+Print a backtrace with each warning or error message.  This backtrace
+should help track down the cause of the error.  The line numbers given
+in the backtrace may not always be correct: @code{troff}'s idea of line
+numbers gets confused by @code{as} or @code{am} requests.
+@item -i
+Read the standard input after all the named input files have been
+processed.
+@item -w@var{name}
+Enable warning @var{name}.  Available warnings are described in
+@ref{Debugging}.  Multiple @samp{-w} options are allowed.
+@item -W@var{name}
+Inhibit warning @var{name}.  Multiple @samp{-W} options are allowed.
+@item -E
+Inhibit all error messages.
+@item -C
+Enable compatibility mode.
+@item -d@var{cs}
+@itemx -d@var{name}=s
+Define @var{c} or @var{name} to be a string @var{s}; @var{c} must be a
+one-letter @var{name}.
+@item -f@var{fam}
+Use @var{fam} as the default font family.
+@item -m@var{name}
+Read in the file @file{tmac.@var{name}}.  Normally this will be searched
+for in @code{groff}'s lib directory.
+@item -n@var{num}
+Number the first page @var{num}.
+@item -o@var{list}
+Output only pages in @var{list}, which is a comma-separated list of page
+ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
+print every page between @var{m} and @var{n}, @samp{-@var{n}} means
+print every page up to @var{n}, @samp{@var{n}-} means print every page
+from @var{n}.  @code{troff} will exit after printing the last page in
+the list.
+@item -r@var{cn}
+@itemx -r@var{name}=@var{n}
+Set number register @var{c} or @var{name} to @var{n}; @var{c} must be a
+one-letter @var{name}; @var{n} can be any troff numeric expression.
+@item -F@var{dir}
+Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
+name of the device) for the @file{DESC} file and font files before the
+normal directory.
+@item -M@var{dir}
+Search directory @var{dir} for macro files before the normal directory.
+@end table
+
+
+
+@node Environment, Invocation Examples, Options, Invoking groff
+@section Environment
+@cindex environment
+
+
+There are also several environment variables which can modify groff's
+behavior.
+
+@table @code
+@item GROFF_COMMAND_PREFIX
+If this is set to @var{X}, then @code{groff} will run
+@var{X}@code{troff} instead of @code{gtroff}.  This also applies to
+@code{tbl}, @code{pic}, @code{eqn}, @code{refer}, and @code{soelim}.  It
+does not apply to @code{grops}, @code{grodvi}, @code{grotty},
+@code{grohtml}, @code{grolj4}, and @code{gxditview}.
+@item GROFF_TMAC_PATH
+A colon separated list of directories in which to search for macro
+files.
+@item GROFF_TYPESETTER
+Default device.
+@item GROFF_FONT_PATH
+A colon separated list of directories in which to search for the
+@code{dev}@var{name} directory.
+@item PATH
+The search path for commands executed by groff.
+@item GROFF_TMPDIR
+The directory in which temporary files will be created.  If this is not
+set and @code{TMPDIR} is set, temporary files will be created in that
+directory.  Otherwise temporary files will be created in @code{/tmp}.
+The @code{grops} and @code{grefer} commands can create temporary files.
+@end table
+
+
+@node Invocation Examples,  , Environment, Invoking groff
+@section Invocation Examples
+@cindex invocation examples
+@cindex examples of invocation
+
+
+This section will list several common uses of @code{groff} and the
+command line which will accomplish it.
+
+@example
+groff file
+groff -X -me file
+groff -mm -rD1 -z file
+groff -tps -me file | lpr -Plw2
+... any more?? ...
+@end example
+
+@subsection @code{grog}
+
+@code{grog} reads files and guesses which of the @code{groff}
+preprocessors and/or macro packages are are required for formatting
+them, and prints the @code{groff} command including those options on the
+standard output.  The options generated are one of @samp{-e},
+@samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-s},
+and @samp{-t}.
+
+A filename of @samp{-} is taken to refer to the standard input.  If no
+files are specified the standard input will be read.  Any specified
+options will be included in the printed command.  No space is allowed
+between options and their arguments.  For example,
+
+@example
+grog -Tdvi paper.ms
+@end example
+
+will guess the approriate command to print @file{paper.ms} and then run
+it after adding the @samp{-Tdvi} option.
+
+
+@node Tutorial for Macro Users, -man, Invoking groff, Top
+@chapter Tutorial for Macro Users
+@cindex tutorial for macro users
+@cindex macro tutorial for users
+@cindex user's tutorial for macros
+@cindex user's macro tutorial
+
+Most users tend to use a macro package to format their papers.  This
+means that the whole breadth of @code{groff} is not neccessary for most
+people.  This chapter covers the material needed to efficiently use a
+macro package.
+
+
+@menu
+* Basics::                      
+* Common Features::             
+@end menu
+
+@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
+@section Basics
+@cindex basics
+
+
+This section covers some of the basic concepts you will need to
+understand to use a macro package.@footnote{This section is derived from
+@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman}
+References are made throughout to more detailed information, if desired.
+
+@code{groff} reads an input file prepared by the user and outputs a
+formatted paper suitable for publication or framing.  The input consists
+of text, or words to be printed, and embedded commands (@dfn{requests}
+and @dfn{escapes}), which tell @code{groff} how to format the printed
+copy.  For more detail on this @pxref{Embedded Commands}.
+
+The word @dfn{argument} is used in this manual to mean a word or number
+which appears on the same line as a request which modifies the meaning
+of that request.  For example, the request
+
+@example
+.sp
+@end example
+
+@noindent
+spaces one line, but
+
+@example
+.sp 4
+@end example
+
+@noindent
+spaces four lines.  The number@w{ }4 is an argument to the @code{sp}
+request which says to space four lines instead of one.  Arguments are
+separated from the request and from each other by spaces.  More details
+on this can be found in @ref{Request Arguments}.
+
+The primary function of @code{groff} is to collect words from input
+lines, fill output lines with those words, justify the right hand margin
+by inserting extra spaces in the line, and output the result.  For
+example, the input:
+
+@example
+Now is the time
+for all good men
+to come to the aid
+of their party.
+Four score and seven
+years ago,...
+@end example
+
+@noindent
+will be read, packed onto output lines, and justified to produce:
+
+@quotation
+Now is the time for all good men to come to the aid of their party.
+Four score and seven years ago,...
+@end quotation
+
+@cindex break
+@cindex line break
+Sometimes you may want to start a new output line even though the line
+you are on is not yet full; for example, at the end of a paragraph.  To
+do this you can cause a @dfn{break}, which starts a new output line.
+Some requests cause a break automatically, as do blank input lines and
+input lines beginning with a space.
+
+Not all input lines are text to be formatted.  Some of the input lines
+are requests which describe how to format the text.  Requests always
+have a period or an apostrophe (@samp{'}) as the first character of the
+input line.
+
+The text formatter also does more complex things, such as automatically
+numbering pages, skipping over page boundaries putting footnotes in the
+correct place, and so forth.
+
+Here a few hints for preparing text for input to @code{groff}.  First,
+keep the input lines short.  Short input lines are easier to edit, and
+@code{groff} will pack words onto longer lines for you anyhow.  In
+keeping with this, it is helpful to begin a new line after every period,
+comma, or phrase, since common corrections are to add or delete
+sentences or phrases.  Secondly, do not hyphenate words at the end of
+lines -- @code{groff} is smart enough to hyphenate words for you as
+needed, but is not smart enough to take hyphens out and join a word back
+together.  Also, words such as ``mother-in-law'' should not be broken
+over a line, since then you will get a space where not wanted, such as
+``mother- in-law''.
+
+@findex ls
+@cindex double spacing
+@cindex spacing
+Groff will double space output text automatically if you use the request
+@samp{.ls 2}.  You can revert to single spaced mode by typing @samp{.ls
+1}.
+
+A number of requests allow you to change the way the printed copy looks,
+sometimes called the @dfn{layout} of the output page.  Most of these
+requests adjust the placing of @dfn{white space} (blank lines or
+spaces).
+
+@findex bp
+@cindex new page
+The @samp{.bp} request starts a new page.
+
+@findex sp
+@cindex blank lines
+@cindex empty lines
+The request @samp{.sp @var{N}} leaves @var{N} lines of blank space.
+@var{N} can be omitted (meaning skip a single line) or can be of the
+form @var{N}i (for @var{N} inches) or @var{N}c (for @var{N}
+centimeters).  For example, the input:
+
+@example
+.sp 1.5i
+My thoughts on the subject
+.sp
+@end example
+
+@noindent
+leaves one and a half inches of space, followed by the line ``My
+thoughts on the subject'', followed by a single blank line.
+
+@findex ce
+@cindex centering lines
+Text lines can be centered by using the @samp{.ce} request.  The line
+after @samp{.ce} is centered (horizontally) on the page.  To center more
+than one line, use @samp{.ce @var{N}} (where @var{N} is the number of
+lines to center), followed by the @var{N} lines.  If you want to center
+many lines but don't want to count them, type:
+
+@example
+.ce 1000
+lines to center
+.ce 0
+@end example
+
+@noindent
+The @samp{.ce 0} request tells @code{groff} to center zero more lines,
+in other words, stop centering.
+
+@findex br
+@cindex line break
+@cindex break
+All of these requests cause a break; that is, they always start a new
+line.  If you want to start a new line without performing any other
+action, use @samp{.br}.
+
+
+@node Common Features,  , Basics, Tutorial for Macro Users
+@section Common Features
+@cindex common features
+@cindex features, common
+
+
+Groff provides very low level operations for formatting a document.
+There are many common routine operations which are done in all documents.
+These common operations are written into @dfn{macros} and collected into a
+@dfn{macro package}.
+
+All macro packages provide certain common capabilities which fall
+into the following categories.
+
+@subsection Paragraphs
+@cindex paragraphs
+
+One of the most common and most used capability is starting a
+paragraph.  There are a number of different types of paragraphs,
+any of which can be initiated with macros supplied by the macro
+package.  Normally paragraphs start with a blank line and the first
+line indented, like the text in this manual.  There are also block
+style paragraphs, which omit the indentation:
+
+@example
+Some   men  look   at  constitutions   with  sanctimonious
+reverence, and deem them like the ark of the covenant, too
+sacred to be touched.
+@end example
+
+And there are also indented paragraphs which begin with a tag or label
+at the margin and the remaining text indented.
+
+@example
+one   This is  the first paragraph.  Notice  how the first
+      line of  the resulting  paragraph lines up  with the
+      other lines in the paragraph.
+longlabel
+      This  paragraph   had  a  long   label.   The  first
+      character of text on the first line will not line up
+      with  the  text  on  second  and  subsequent  lines,
+      although they will line up with each other.
+@end example
+
+A variation of this is a bulleted list....
+
+@subsection Sections and Chapters
+
+Most macro packages supply some form of section headers.
+The simplest kind is simply the heading on a line by itself in bold
+type.  Others supply automatically numbered section heading or
+different heading styles at different levels.
+Some, more sophisticated, macro packages supply macros for starting
+chapters and appendicies.
+
+@subsection Headers and Footers
+
+Every macro packages gives you some way to manipulate the headers and
+footers (or @dfn{titles} on each page.  Some packages will allow you
+to have different ones on the even and odd pages (for material
+printed in a book form).
+The titles are called three-part titles, that is, there is a
+left-justified part, a centered part, and a right-justified part.
+An automatically generated page number may be put in any of these
+fields with the @samp{%} character.
+
+@subsection Page Layout
+
+Most macro packages let you specify top and bottom margins and other
+details about the appearance of the printed pages.
+
+@subsection Displays
+@cindex displays
+
+Displays are sections of text to be set off from the body
+of the paper.  Major quotes, tables, and figures are types of
+displays, as are all the examples used in this document.
+
+@cindex quotes, major
+@cindex major quotes
+Major quotes are quotes which are several lines long,
+and hence are set in from the rest of the text without
+quote marks around them.
+
+@cindex list
+A list is an indented, single spaced, unfilled display.  Lists should
+be used when the material to be printed
+should not be filled and justified like normal text, such
+as columns of figures or the examples used in this paper.
+
+@cindex keep
+A keep is a display of lines which are kept on a single page if
+possible.  An example of where you would use a
+keep might be a diagram.  Keeps differ from lists in that
+lists may be broken over a page boundary whereas keeps will
+not.
+
+@cindex keep, floating
+@cindex floating keep
+Floating keeps move relative to the text.  Hence, they
+are good for things which will be referred to by name, such
+as ``See figure 3''.  A floating keep will appear at the bottom of the
+current page if it will fit; otherwise, it will
+appear at the top of the next page.  Meanwhile, the surrounding text
+will `flow' around the keep, thus leaving now blank areas.
+
+@subsection Footnotes and annotations
+@cindex footnotes
+@cindex annotations
+
+There are a number of requests to save text for later
+printing.  Footnotes are printed at the bottom of the current
+page.  Delayed text is intended to be a variant form of foot-
+note; the text is printed only when explicitly called for,
+such as at the end of each chapter.
+
+Delayed text is very similar to a footnote except that
+it is printed when called for explicitly.  This allows a
+list of references to appear (for example) at the end of
+each chapter, as is the convention in some disciplines.
+
+Most macro packages which supply this functionality also supply a
+means of automatically numbering either type of annotation.
+
+@subsection Table of Contents
+
+Tables of contents are a type of
+delayed text having a tag (usually the page number) attached
+to each entry after a row of dots.  The table accumulates
+throughought the paper until printed, usually after the paper has
+ended.  Many macro packages will provide the abilitly to have several
+tables of contents (i.e. one standard one, one for tables, &c.)
+
+@subsection Indexes
+
+While some macro packages will use the term @dfn{index}, none
+actually provide that functionality.  The facilities they call
+indexes are actually more appropriate for tables of contents.
+
+@subsection Paper formats
+
+Some macro packages provide stock formats for various kinds of
+documents.  Many of them provide a common format for the title and
+opening pages of a technical paper.  The -mm macros in particular
+provide formats for letters and memorandums.
+
+@subsection Multiple Columns
+
+Some macro packages (except -man) provide the ability to have two or
+more columns on a page.
+
+@subsection Font and Size changes
+
+The builtin font and size functions are not always intuitive, so all
+macro packages provide macros to make these operations simpler.
+
+@subsection Predefined Strings
+
+Most macro packages provide various predefined strings for a variety
+of uses, examples are sub- and super-scripts, printable dates, quotes
+and various special characters.
+
+@subsection Preprocessor Support
+
+All macro packages provide support for the various preprocessors.
+
+@subsection Configuration and Customization
+
+Some macro packages provide means of customizing many of details of
+how the package behaves.  This ranges from setting the default type
+size to changing the appearance of section headers.
+
+
+@node -man, -ms, Tutorial for Macro Users, Top
+@chapter -man
+@cindex @code{-man}
+
+
+
+@node -ms, -me, -man, Top
+@chapter -ms
+@cindex @code{-ms}
+
+
+
+@node -me, -mm, -ms, Top
+@chapter -me
+@cindex @code{-me}
+
+
+
+@node -mm, Programming Tutorial, -me, Top
+@chapter -mm
+@cindex @code{-mm}
+
+
+
+@node Programming Tutorial, geqn, -mm, Top
+@chapter Programming Tutorial
+@cindex programming tutorial
+@cindex tutorial for programming
+
+This chapter covers @strong{all} of the facilities of groff.
+If you are intending to use a macro package, you probably do not want
+to read this chapter.
+
+
+@menu
+* Text::                        
+* Input Conventions::           
+* Measurements::                
+* Expressions::                 
+* Identifiers::                 
+* Embedded Commands::           
+* Registers::                   
+* Manipulating Filling and Adjusting::  
+* Manipulating Hyphenation::    
+* Manipulating Spacing::        
+* Tabs and Fields::             
+* Character Translations::      
+* Line Layout::                 
+* Page Layout::                 
+* Page Control::                
+* Fonts::                       
+* Sizes::                       
+* Strings::                     
+* Conditionals and Loops::      
+* Writing Macros::              
+* Page Motions::                
+* Drawing Functions::           
+* Traps::                       
+* Diversions::                  
+* Environments::                
+* I/O::                         
+* Postprocessor Access::        
+* Miscellany::                  
+* Debugging::                   
+* Implementation Differences::  
+* Summary::                     
+@end menu
+
+@node Text, Input Conventions, Programming Tutorial, Programming Tutorial
+@section Text
+@cindex text
+
+@code{groff} input files contain text with control commands
+interspersed throughout.  But, even without control codes,
+@code{groff} will still do several things with your text:
+filling and adjusting,
+adding additional space after sentences,
+hyphenating
+and
+inserting implicit line breaks.
+
+
+@menu
+* Filling and Adjusting::       
+* Hyphenation::                 
+* Sentences::                   
+* Tab Stops::                   
+* Implicit Line Breaks::        
+@end menu
+
+@node Filling and Adjusting, Hyphenation, Text, Text
+@subsection Filling and Adjusting
+@cindex filling and adjusting
+@cindex adjusting and filling
+
+
+When troff reads in text it collects words from input and fits as many
+of them together on one output line as it can.  This is known as
+@dfn{filling}.
+
+Once troff has a @dfn{filled} line it will try to @dfn{adjust} it.
+which means it will widen the spacing between words until
+the text reaches the right margin (in the default adjustment mode).
+Extra spaces between words are preserved, but
+spaces at the end of lines are ignored.
+Spaces at the front of a line will cause a @dfn{break}
+(breaks will be explained in @ref{Implicit Line Breaks})
+
+@c distribute these through the text
+@xref{Manipulating Filling and Adjusting}
+
+@node Hyphenation, Sentences, Filling and Adjusting, Text
+@subsection Hyphenation
+@cindex hyphenation
+
+
+Since the odds of finding a set of words, for every output line,
+which will fit nicely on a
+line without inserting excessive amounts of space between words
+is not great,
+troff will hyphenate words so that lines can be justified
+without there being too much space between words.
+It uses an internal hyphenation algorithm, to indicate which words can
+be hyphenated and how to do so.
+When a word is hyphenated the first part of the word will be added
+to the current filled line being output (with an attached hyphen),
+and the other portion will be added to the next line to be filled.
+
+@c distribute these through the text
+@xref{Manipulating Hyphenation}
+
+@node Sentences, Tab Stops, Hyphenation, Text
+@subsection Sentences
+@cindex sentences
+
+
+Although it is often debated,
+some typesetting rules say there should be different amounts of space
+after various puctuation marks.
+For example, a period at the end of a sentence
+should have twice as much space following it
+as would a comma or a period as part of an abbreviation.
+
+@cindex sentence spaces
+@cindex spaces between sentences
+Troff does this by flagging certain characters (normally
+@samp{!},  @samp{?} and @samp{.})
+as @dfn{end of sentence} characters.
+When troff encounters one of these characters at the end of a line it
+will append two @dfn{sentence spaces} in the formatted output.
+(thus, one of the conventions mentioned in @ref{Input Conventions}).
+
+@c also describe how characters like ) are treated here -jjc
+@c gotta do some research on this -trent
+
+
+
+@node Tab Stops, Implicit Line Breaks, Sentences, Text
+@subsection Tab Stops
+@cindex tab stops
+@cindex stops, tabulator
+
+
+Groff translates tabs in the input into movements to the next tab
+stop.  These tab stops are initially located every half inch across
+the page.
+Using this you can make simple tables.  However, this can often be
+deceptive as the appearance (and width) of your text on a terminal and
+the results from groff can vary greatly.
+
+Also, a possible sticking point is that lines beginning with tab
+characters will still be filled, again producing unexpected results.
+For example, the following input
+
+@example
+	1	2	3
+		4	5
+@end example
+
+@noindent
+will produce
+
+@example
+	1	2	3		4	5
+@end example
+
+@c Tab stops are with respect to the input line.  -jjc
+@c did that last section address that?? -trent
+
+
+
+@c distribute these through the text
+@xref{Tabs and Fields}
+
+@node Implicit Line Breaks,  , Tab Stops, Text
+@subsection Implicit Line Breaks
+@cindex implicit line breaks
+@cindex implicit breaks of lines
+@cindex line, implicit breaks
+@cindex break
+@cindex break, implicit
+@cindex line break
+
+An important concept in troff is the @dfn{break}.  When a @dfn{break}
+occurs, troff will output the partially filled line (unadjusted),
+and resume collecting and filling text on the next output line.
+
+@cindex blank line
+@cindex empty line
+@cindex line, blank
+There are several ways to cause a break in troff.
+A blank line will not only cause a break, but it will also cause a
+one line vertical space (effectively a blank line) to be output.
+
+A line which begins with a space will cause a break and the space
+will be output at the beginning of the next line.
+Note that this space isn't adjusted, even in fill mode.
+
+The end of file will also cause a break (otherwise the last line of
+your document may vanish!)
+
+Certain @dfn{requests} also cause breaks, implicitly or explicity.
+This will be discussed later.
+
+@c distribute these through the text
+@xref{Manipulating Filling and Adjusting}
+
+@node Input Conventions, Measurements, Text, Programming Tutorial
+@section Input Conventions
+@cindex input conventions
+@cindex conventions for input
+
+
+Since groff does filling automatically, it is traditional in groff not
+to try and type things in as nicely formatted paragraphs.  These are
+some conventions commonly used when typing groff text:
+
+@itemize @bullet{}
+@item
+Break lines after punctuation, particularily at the ends of
+sentences, and in other logical places.  Keep separate phrases on
+lines by themselves, as entire phrases are often added or deleted
+when editing.
+@item
+Try to keep lines less than 40-60 characters,
+to allow space for inserting more text.
+@item
+Do not try to do any formatting in a WYSIWYG manner (i.e. don't
+try and use spaces to get proper indentation).
+@end itemize
+
+
+@node Measurements, Expressions, Input Conventions, Programming Tutorial
+@section Measurements
+@cindex measurements
+
+
+@cindex units of measurement
+@cindex basic units
+@cindex machine units
+Troff (like any other programs) requires numeric parameters to
+specify various measurements.  Most numeric parameters
+@footnote{those that specify vertical or horizontal motion or a type
+size} may have a measurement unit attached.
+These units are specified as a single
+character which immediately follows the number or expression.
+Each of these units are understood, by troff, to be a multiple of its
+@dfn{basic unit}.  So, whenever a different measurement unit is
+specified troff converts this into its basic units.
+This basic unit, represented by a @samp{u} is a
+device dependent measurement which is quite small, ranging from
+1/75th to 1/72000th of an inch.
+
+Some of the measurement units are compleatly independent of any of
+the current settings (e.g. type size) of groff.
+
+@table @samp
+@item i
+@cindex inch
+Inches.  An antiquated measurement unit still in use in certain
+backwards countries.
+@item c
+@cindex centimeter
+Centimeters.
+@item p
+@cindex points
+Points.  This is a typesetter's measurement used for measure type size.
+It is 72 points to an inch.
+@item P
+@cindex pica
+Pica.  Another typesetting measurement.  6 Picas to an inch.
+@item s
+@item z
+@end table
+
+The other measurements understood by troff are dependent on settings
+currently in effect in troff.  These are very useful for specifying
+measurements which should look proper with any size of text.
+
+@table @samp
+@item m
+@cindex em
+Ems.  This unit is equal to the current font size in points.
+So called because it is @emph{approximately} the width of the letter
+@samp{m} in the current font.
+@item n
+@cindex en
+Ens.  This is half of an em.
+@item v
+@cindex vertical space
+@cindex space, vertical
+Vertical space.  This is equivalent to the current line spacing.
+@xref{Sizes}, for more information about this.
+@item M
+100ths of an em.
+@end table
+
+@c distribute these through the text
+@xref{Fractional Type Sizes}
+
+@menu
+* Default Units::               
+@end menu
+
+@node Default Units,  , Measurements, Measurements
+@subsection Default Units
+@cindex default units
+@cindex units, default
+
+
+Many requests take a default unit.  While this can be helpful at
+times, it can cause strange errors in some expressions.
+For example, the line  length  request  expects  em's.
+Here are several attempts to get 3.5 inches and the results:
+
+@example
+3.5i      @result{}   3.5i
+7/2       @result{}   0i
+7/2i      @result{}   0i
+7i/2      @result{}   .1i
+7i/2u     @result{}   3.5i
+@end example
+
+As you can see, the safest way to specify measurements is to always
+attach a scaling indicator.
+
+@node Expressions, Identifiers, Measurements, Programming Tutorial
+@section Expressions
+@cindex expressions
+
+
+Troff has most of operators common to other languages:
+
+@itemize @bullet
+@item
+Arithmetic: +, -, /, *, %
+@item
+Comparison: <, >, >=, <=, =, ==  (the last two are the same)
+@item
+Logical: &, :
+@item
+Unary operators: -, +, ! (if/while only??)
+@item
+Maximum and minimum: >?, <?
+@item
+Scaling: (@var{c};@var{e})
+Evaluate @var{e} using @var{c} as the default scaling indicator.
+If @var{c} is missing, ignore scaling indicators in the
+evaluation of @var{e}.
+@end itemize
+
+Parenthesis may be used as in any other language.
+However, in groff they are necessary to ensure order of evaluation.
+Groff has no operator precedence,
+expressions are evaluated left to right.
+This means that @samp{3+5*4} is evaluated as if it were parenthesized
+like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may expect.
+
+For many requests which cause a motion on the page, the unary
+operators work differently.
+The @samp{+} and @samp{-} operators indicate a motion relative to the
+current position (down or up, respectively).  The @samp{|} operator
+indicates an absolute position on the page or input line. (????)
+@code{+} and @code{-} are also treated differently by @code{nr} (?)
+
+Due to the way arguments are parsed, spaces are not allowed in
+expressions, unless the entire expression is surrounded by parenthesis.
+
+@c distribute these through the text
+@xref{Request Arguments}
+@c distribute these through the text
+@xref{Conditionals and Loops}
+
+@node Identifiers, Embedded Commands, Expressions, Programming Tutorial
+@section Identifiers
+@cindex identifiers
+
+Like any other language troff, has rules for properly formed
+identifiers.
+In troff an identifier can be made up of most any printable
+character.
+The only exception is characters which are interpreted by troff
+(backslash, square bracket and ?).  So, for example, any of the following
+are valid.
+
+@example
+br
+PP
+(l
+end-list
+@@_
+@end example
+
+You can test whether an identifier is valid in groff with the
+@code{\A} escape.  It expands to 1 or 0 according whether its argument
+(given in quotes) is or is not acceptable as the name of a string,
+macro, diversion, number register, environment or font. It will return
+0 if no argument is given. This is useful if you want to lookup user
+input in some sort of associative table.
+
+Identifiers in groff can be any length, but, in some contexts,
+groff needs to told
+where identifiers end and text begins (and in different ways
+depending on their length)
+
+@itemize @bullet{}
+@item
+Single character
+@item
+Two characters
+Must be prefixed with @samp{(} in some situations.
+@item
+Arbitrary length (groff only)
+Must be bracketed with @samp{[}, @samp{]} in some situations.
+Any length identifier can be put in brackets.
+@end itemize
+
+Unlike many other programming languages, undefined identifiers are
+silently ignored or expanded to nothing.
+
+
+@c distribute these through the text
+@xref{Interpolating Registers}
+@c distribute these through the text
+@xref{Strings}
+
+@node Embedded Commands, Registers, Identifiers, Programming Tutorial
+@section Embedded Commands
+@cindex embedded commands
+@cindex commands, embedded
+
+
+With most documents you need more funtionality beyond filling,
+adjusting and implicit line breaking.
+In order to gain further functionality, groff allows commands to be
+embeded into your text, in two ways.
+
+The first is a @dfn{request} which takes up an entire line, and does
+some large scale operation (e.g. break lines, start new pages).
+
+The other is an @dfn{escape} which can be embedded anywhere
+in your text, or even as an argument to a request. (Not always?)
+Escapes generally do more minor operations like sub- and super-
+scripts, print a symbol, &c.
+
+
+
+@menu
+* Requests::                    
+* Macros::                      
+* Escapes::                     
+@end menu
+
+@node Requests, Macros, Embedded Commands, Embedded Commands
+@subsection Requests
+@cindex requests
+
+
+@cindex control character
+@cindex character, control
+A request line begins with a control character,
+which is either a single quote (@samp{'}) or a period (@samp{.}).
+These can be changed @pxref{Character Translations}, for details.
+After this there may be optional tabs or spaces followed by an
+identifier which is the name of the request.
+This may be followed by any number of space separated arguments.
+
+@findex \&
+If you want to begin a line with a control character without it being
+interpreted, precede it with a @code{\&}.  This represents a zero
+width space, which means it will not affect you output.
+
+In most cases you will use the period as a control character.
+Several requests will cause a break, using the single quote control
+character will prevent this.
+
+
+@menu
+* Request Arguments::           
+@end menu
+
+@node Request Arguments,  , Requests, Requests
+@subsubsection Request Arguments
+@cindex request arguments
+@cindex arguments to requests
+
+
+Argument to requests (and macros) are processed much like the shell:
+The line is split into arguments according to spaces.
+An argument which is intended to contain spaces can either be enclosed
+in quotes (single or double), or have the spaces @dfn{escaped} with
+backslashes.
+
+So, for example:
+
+@example
+.uh The Mouse Problem
+.uh "The Mouse Problem"
+.uh The\ Mouse\ Problem
+@end example
+
+The first line is the @code{.uh} macro being called with 3 arguments,
+@samp{The}, @samp{Mouse}, and @samp{Problem}.
+The latter two have the same effect or calling the @code{.uh} macro
+with one argument @samp{The Mouse Problem}.
+
+Note, however, that the @code{.ds} request works differently.
+
+@c distribute these through the text
+@xref{Strings}
+
+@node Macros, Escapes, Requests, Embedded Commands
+@subsection Macros
+@cindex macros
+
+
+Troff has a @dfn{macro} facility for defining a series of lines which
+can be invoked by name.
+They are called in the same manner as requests
+and arguments may be passed in the same manner.
+
+
+@c distribute these through the text
+@xref{Writing Macros}
+@c distribute these through the text
+@xref{Request Arguments}
+
+@node Escapes,  , Macros, Embedded Commands
+@subsection Escapes
+@cindex escapes
+
+
+@findex \e
+@findex \\
+Escapes may occur anywhere in the input to groff.
+They begin with a backslash and are followed by a single character
+which indicates the function to be performed.
+If you want to have a backslash appear in your document, you should
+use the escape sequence @code{\e}.  Merely escaping the backslash
+with another backslash will work in @emph{some} curcumstances.
+
+Many escapes have no parameters, those that do, do so in one of two
+ways.  For escapes which require an identifier there must be a way for
+groff to tell where the identifier ends and the text begins.
+It assumes that the next single character is the identifier, but if
+that character is an open parenthesis, it takes the next two
+characters as the identifier; and if the next character is an open
+bracket, all characters until a close bracket are taken as the
+identifier.  Note that in the second case there is no closing
+parenthesis.  For example:
+
+@example
+\fB
+\n(XX
+\*[TeX]
+@end example
+
+Other escapes may require several arguments and/or some special
+format.  In these cases the @dfn{argument} is enclosed in single
+quotes (not required??) and the enclosing text is decoded according
+to what that escape expects.
+
+@example
+\l'1.5i\(bu'
+@end example
+
+@findex \\
+@findex \e
+@findex \E
+If you want to have a backslash appear in your output, you can use several
+escapes: @code{\\}, @code{\e} or @code{\E}.
+These are very similar, and only differ with respect to being used in
+macros or diversions (@xref{Copy-in Mode}, and @ref{Diversions}, for
+more information)
+
+
+
+@c distribute these through the text
+@xref{Identifiers}
+
+@menu
+* Comments::                    
+@end menu
+
+@node Comments,  , Escapes, Escapes
+@subsubsection Comments
+@cindex comments
+
+
+@findex \"
+Probably one of the most@footnote{Unfortunately, this is a lie.  But
+hopefully future troff hackers will believe it :-)}
+common forms of escapes is the comment.
+They begin with the @code{\"} escape and end at the end of the input
+line.
+
+This may sound simple, but it can be tricky to keep the comments from
+interfering with the apperarance of your final outupt.
+
+If the escape is to the right of some text or a request, that portion
+of the line will be ignored, but the space leading up to it will be
+noticed by groff.  This only affects the @code{.ds} request (any
+others?).
+
+One possibly irritating idiosyncracy is that you mustn't use tabs to
+line up your comments.
+Tabs are not treated as white space between request and macro
+arguments.
+
+If you have a comment on a line by itself, it will be treated as a
+blank line, because after eliminating the comment, that is all that
+remains.  So, it is common to start the line with @code{.\"} which
+will cause the line to be treated as an undefined request.
+
+Another commenting scheme seen sometimes is three consecutive single
+quotes (@code{'''}) at the begining of a line.  This works, but groff
+will give a warning about an undefined macro, which is harmless, but
+irritating.
+
+@findex \#
+Now to avoid all this groff has a new comment mechanism using the
+@code{\#} escape.  This escape works the same as @code{\"} except
+that the newline is also ignored.
+
+@findex ig
+For large blocks of text, the @code{ig} request may be useful.
+@c distribute these through the text
+@xref{Strings}
+
+@node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
+@section Registers
+@cindex registers
+
+
+Registers are groff's numeric variables.  groff has a number of
+builtin registers, supplying anything from the date to details of
+formatting parameters.
+
+@c distribute these through the text
+@xref{Identifiers}
+
+@menu
+* Setting Registers::           
+* Interpolating Registers::     
+* Auto-increment::              
+* Assigning Formats::           
+* Builtin Registers::           
+@end menu
+
+@node Setting Registers, Interpolating Registers, Registers, Registers
+@subsection Setting Registers
+@cindex setting registers
+@cindex registers, setting
+
+
+@findex nr
+@findex \R
+Registers are defined/set via the @code{nr}
+request or the @code{\R} escape, for example, the following two lines
+are equivalent:
+
+@example
+.nr a 1
+\R'a 1'
+@end example
+
+@findex rr
+The @code{rr} request will
+remove the register specified by the argument.
+
+@findex rnn
+The @code{rnn} request will rename a number register.
+The format is @samp{.rnn @var{x} @var{y}}, which will
+rename number register  @var{x} to @var{y}.
+
+@findex aln
+Aliases can be created for a number register.  The format is
+@samp{.aln @var{xx} @var{yy}}, which will create an alias @var{xx} for
+number register object named @var{yy}.  The new name and the old name
+will be exactly equivalent.  If @var{yy} is undefined, a warning of
+type @samp{reg} will be generated, and the request will be ignored.
+@xref{Debugging}, for information about warnings.
+
+
+@node Interpolating Registers, Auto-increment, Setting Registers, Registers
+@subsection Interpolating Registers
+@cindex interpolating registers
+@cindex registers, interpolating
+
+
+@findex \n
+Numeric registers are @dfn{interpolated} via the @code{\n} escape.
+@c the following is wrong.  Should I say any more than the above??
+@c This means that the value of the number register in expanded in-place
+@c on the input line before any other actions, i.e. before requests and
+@c escapes are interpreted.
+
+@example
+.nr as \na+\na
+\n(as
+@end example
+
+
+@node Auto-increment, Assigning Formats, Interpolating Registers, Registers
+@subsection Auto-increment
+@cindex auto-increment
+@cindex increment, automatic
+
+Number registers can also be auto incremented/decremented.  You can
+specify the increment/decrement factor with third argument to the
+@code{nr} request.  The default value is 0.  For example:
+
+@example
+.nr a 0 1
+.nr xx 0 5
+\n+a, \n+a, \n+a, \n+a, \n+a
+.br
+\n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx
+@end example
+
+Produces:
+
+@example
+1, 2, 3, 4, 5
+5, 10, 15, 20, 25
+@end example
+
+If you want to change the increment factor without changing the value
+of a register, the following can be used.
+
+@example
+.nr a \na 10
+@end example
+
+
+@node Assigning Formats, Builtin Registers, Auto-increment, Registers
+@subsection Assigning Formats
+@cindex assigning formats
+@cindex formats, assigning
+
+
+@findex af
+When a register is used in the text of an input file
+(as opposed to part of an expression)
+it is textually replaced (or interpolated) with a representation of
+that number.
+This output format can be changed to a variety of formats
+(numbers, roman numerals, etc)
+This is done using the @code{af} request.
+The first argument to @code{af} is the name of the number register to
+be changed,
+and the second argument is the output format.
+The following output formats are available:
+
+@table @samp
+@item 1
+This is the default format, decimal numbers:
+1, 2, 3, @dots{}
+@item 001
+Decimal numbers with as many leading zeros as specified.
+So, @samp{001} would result in 001, 002, 003, @dots{}
+@item I
+@cindex roman numerals
+@cindex numerals, roman
+Upper-case roman numerals:
+0, I, II, III, IV, @dots{}
+@item i
+Lower-case roman numerals:
+0, i, ii, iii, iv, @dots{}
+@item A
+Upper-case letters:
+A, B, C, @dots{}, Z, AA, AB, @dots{}
+@item a
+Lower-case letters:
+a, b, c, @dots{}, z, aa, ab, @dots{}
+@end table
+
+The following example will produce @samp{10, X, j, 010}.
+
+@example
+.nr a 10
+.af a 1           \" the default format
+\na,
+.af a I
+\na,
+.af a a
+\na,
+.af a 001
+\na
+@end example
+
+@findex \g
+The @code{\g} escape returns the current format of the specified
+register.  For example, @samp{\ga} after the following example would
+produce @samp{001}.
+
+
+
+@node Builtin Registers,  , Assigning Formats, Registers
+@subsection Builtin Registers
+@cindex builtin registers
+@cindex registers, builtin
+
+
+The following are some builtin registers, which are not listed
+elsewhere in this manual.  Any registers which begin with a @samp{.}
+are read-only.  A compleat listing of all builtin registers can be
+found in @ref{Register Index}.
+
+@table @code
+@item .H
+@vindex .H
+Horizontal resolution in basic units.
+@item .V
+@vindex .V
+Vertical resolution in basic units.
+@item dw
+@vindex dw
+Day of the week (1-7).
+@item dy
+@vindex dy
+Day of the year (1-31).
+@item mo
+@vindex mo
+Current month (1-12).
+@item yr
+@vindex yr
+Last two digits of the current year (see you in 7 years :-)
+@item .c
+@vindex .c
+@itemx c.
+@vindex c.
+The current @emph{input} line number.
+@item ln
+@vindex ln
+The current @emph{output} line number.
+@item .x
+@vindex .x
+The  major  version  number.  For example, if the version number is 1.03
+then @code{.x} will contain 1.
+@item .y
+@vindex .y
+The minor version number.  For example, if the version number is 1.03
+then @code{.y} will contain 03.
+@item .g
+@vindex .g
+Always 1.
+Macros should use this to determine whether they are running
+under GNU troff.
+@item .A
+@vindex .A
+If the current output device is ascii, this is set to 1,
+zero otherwise.
+@item .P
+@vindex .P
+This register indicates whether the current page is actualy being
+printed, i.e. if the @samp{-o} option is being used to only print
+selected pages.
+@xref{Options}, for more information.
+@end table
+
+@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
+@section Manipulating Filling and Adjusting
+@cindex manipulating filling and adjusting
+@cindex filling and adjusting, manipulating
+@cindex adjusting and filling, manipulating
+
+
+@findex br
+@cindex break
+@cindex line break
+Several ways of causing @dfn{breaks} were given in
+@ref{Implicit Line Breaks}.
+The @code{br} request will likewise cause a break.
+Several other requests will also cause breaks, implicitly.
+They are
+@code{bp},
+@code{ce},
+@code{fi},
+@code{fl},
+@code{in},
+@code{nf},
+@code{sp} and
+@code{ti}.
+
+@findex nf
+@findex fi
+@vindex .u
+Initially, groff will fill and ajust text to both margins.
+Filling can be disabled via the @code{nf} request
+and re-enabled with the @code{fi} request.
+These implicitly disable and re-enable adjusting.
+Both of these will cause break in text currently being filled.
+The number register @code{.u} is equal to 1 in fill mode and 0 in
+no-fill mode.
+
+@findex ad
+@findex na
+@vindex .j
+Adjusting can be disabled with the @code{ad} request and re-enabled
+with the @code{na} request.
+The @code{ad} request takes a single argument to indicate how to
+adjust text.
+The current adjustment mode is available in the number register
+@code{.j}.
+
+@table @samp
+@item l
+@cindex ragged-right
+Adjust text to the left margin.  This produces what is traditionally
+called ragged-right text.
+@item r
+Adjust text to the right margin.
+@item c
+Center filled text.
+@item b
+@itemx n
+Justify to both margins.  This is groff's default.
+@end table
+
+With no argument to @code{ad}, troff will adjust lines the same way
+it was the last time it was filling.  For example:
+
+@example
+text
+.ad r
+text
+.ad c
+text
+.na
+text
+.ad  \" back to centering
+text
+@end example
+
+@findex \p
+The escape @code{\p} will cause a break and cause the remaining text
+to be adjusted.
+
+@findex ss
+The @code{ss} request allows you to change the minimum size of a
+space between filled words.
+This request takes it's units as one twelfth of the
+spacewidth parameter for the current font.  Initially both the word
+space size and the sentence space size are 12.
+
+When two arguments are given to the @code{ss} request, the second argument
+gives the sentence space size. If the second argument is not given, the
+sentence space size will be the same as the word space size.
+The sentence space size
+is used in two circumstances: if the end of a sentence occurs at the end
+of a line in fill mode, then both an inter-word space and a sentence
+space will be added; if two spaces follow the end of a sentence in the
+middle of a line, then the second space will be a sentence space. Note
+that the behaviour of @sc{Unix} troff will be exactly that exhibited by GNU
+troff if a second argument is never given to the @code{ss} request. In GNU
+troff, as in @sc{Unix} troff, you should always follow a sentence with either
+a newline or two spaces.
+
+@vindex .ss
+@vindex .sss
+The number registers @code{.ss} and @code{.sss} are
+the values of the parameters set by the first and second
+arguments of the @code{ss} request.
+
+@findex ce
+The @code{ce} request will center text.
+While the @samp{ad c} request will also center text, it has the side
+effect of filling the text.  The @code{.ce} request will not fill the
+text it affects.
+This request causes a break.
+
+With no arguments, @code{ce} will fill the next line of text.
+The single argument @code{ce} takes is a number indicating the
+number of lines to be centered.  With no argument centering is
+disabled.
+
+A common idiom is to turn on centering for a large number of lines,
+and then turn off centering when you are done with the centered text.
+This is useful for any request which takes a number of lines as an
+argument.
+
+@example
+.ce 1000
+replace this
+with
+something
+more interesting
+@dots{}
+.ce 0
+@end example
+
+@vindex .ce
+The @code{.ce} number register contains the number of lines remaining
+to be centered, as set by the @code{ce} request.
+
+
+@findex rj
+@vindex .rj
+A similar request is @code{rj} request which will justify unfilled
+text to the right margin.  Its arguments are identical to the
+@code{ce} request.
+The @code{.rj} number register is
+the number of lines to be right-justified as set by the @code{rj}
+request.
+
+
+
+@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
+@section Manipulating Hyphenation
+@cindex manipulating hyphenation
+@cindex hyphenation, manipulating
+
+
+As discussed in @ref{Hyphenation}, groff will hyphenate words.
+There are a number of ways to modify the how hyphenation is done.
+
+@findex nh
+@findex hy
+@vindex .hy
+This hyphenation can be turned off with the @code{nh} request, and
+turned back on with the @code{hy} request.  However, troff's
+hyphenation facilities are far more flexible than this.  The @code{hy}
+request can be used to tell troff to restrict hypenation to certain
+cases.  The request takes a single numeric argument.
+The current hyphenation restrictions can be found in the number
+register @code{.hy}
+
+@table @samp
+@item 1
+The default argument, which
+indicates to hyphenate without restrictions.
+@item 2
+Do not hyphenate the last word on a page or column.
+@item 4
+Do not hyphenate the last two characters of a word.
+@item 8
+Do not hyphenate the first two characters of a word.
+@end table
+
+@findex hlm
+@vindex .hlc
+@vindex .hlm
+The @code{hlm} request will
+set the maximum number of consecutive hyphenated lines to the value
+given as the first argument.
+If this number is
+negative, there is no maximum.  The default value is -1.
+This value is
+associated with the current environment.  Only lines output from an
+environment count towards the maximum associated with that environment.
+Hyphens resulting from @code{\%} are counted; explicit hyphens are not.
+The current setting of this is available in the @code{.hlm} request.
+Also the number of immediately preceding consecutive hyphenated lines
+are available in the number register @code{.hlc}.
+
+@findex hw
+The @code{hw} request allows you to specify how a specific word is
+to be hyphenated.  It takes only one argument which is the word with
+hyphens at the hyphenation points.  For example:
+@samp{.hw in-sa-lub-rious}.
+@c In old versions of troff there was a
+@c limited amount of space to store such information, fortunately,
+@c with groff, this is no longer a restriction.
+
+@findex \%
+@cindex hyphenation character
+@cindex character, hyphenation
+You can also tell troff how to hyphenate words on the fly with the
+use of the @code{\%} escape, also known as the @dfn{hyphenation
+character}.  Preceding a word with this character will prevent it
+from being hyphenated, putting it in a word will indicate to troff
+that the word may be hyphenated at that point.  Note that this
+mechanism will only affect one word, if you want to change the
+hyphenation of a word for the entire document, use the @code{hw}
+request.
+
+@findex hc
+The @code{hc} request allows you to change the hyphenation character.
+The character specified as an argument will then work the same as the
+@code{\%} escape, and, thus, no longer appear in the output.  Without
+an argument it will return the hyphenation character to @code{\%}.
+
+@findex hpf
+To further customize hyphenation the @code{hpf} request will read in
+a file of hyphenation patterns.
+This file will be searched for in the
+same way that @file{tmac.@var{name}} is searched for when the
+@samp{-m@var{name}} option is specified.
+
+It should have the same format as the argument to the
+\patterns primitive in @TeX{}; the letters appearing in this file are
+interpreted as hyphenation codes.
+A @samp{%} character in the patterns file
+introduces a comment that continues to the end of the line.
+
+@findex hla
+@findex hpf
+@pindex troffrc
+The set of
+hyphenation patterns is associated with the current language set by the
+@code{hla} request.  The @code{hpf} request is usually invoked by the
+@file{troffrc} file.
+
+@findex hcode
+@code{.hcode @var{c1 code1 c2 code2...}}
+Set the hyphenation code of character @var{c1} to code1 and that of
+@var{c2} to @var{code2}.
+A hyphenation code must be a single input character (not a
+special character) other than a digit or a space.  Initially each
+lower-case letter has a hyphenation code, which is itself, and each
+upper-case letter has a hyphenation code which is the lower case
+version of itself.
+
+@findex hym
+@vindex .hym
+The @code{hym} request will set the hyphenation margin to the value
+given as the first argument: when the current adjustment mode is not
+@samp{b}, the line will not be hyphenated if the line is no more than
+that amount short.
+The default hyphenation margin is 0.  The default scaling
+indicator for this request is m.  The hyphenation margin is associated
+with the current environment.  The current hyphenation margin is
+available in the @code{.hym} register.
+
+@findex hys
+@vindex .hys
+The @code{hys} request set the hyphenation space to the value given as
+the first argument: when the current adjustment mode is b, don't
+hyphenate the line if the line can be justified by adding no more than
+that amount of extra space to each word space.  The default
+hyphenation space is 0.  The default scaling indicator for this
+request is m.  The hyphenation space is associated with the current
+environment.  The current hyphenation space is available in the
+@code{.hys} register.
+
+@findex shc
+The @code{shc} request will set the soft hyphen character to the
+argument given as an argument.  If the argument is omitted, the soft
+hyphen character will be set to the default @code{\(hy}. The soft
+hyphen character is the character which will be inserted when a word
+is hyphenated at a line break.  If the soft hyphen character does not
+exist in the font of the character immediately preceding a potential
+break point, then the line will not be broken at that point.  Neither
+definitions (specified with the @code{char} request) nor translations
+(specified with the @code{tr} request) are considered when finding the soft
+hyphen character.
+
+@findex hla
+@vindex .hla
+@pindex troffrc
+The @code{hla} request will set the current hyphenation language to
+that given by the first argument.  Hyphenation exceptions specified
+with the @code{hw} request and hyphenation patterns specified with the
+@code{hpf} request are both associated with the current hyphenation
+language.  The @code{hla} request is usually invoked by the
+@file{troffrc} file.  The current hyphenation language is available
+in the number register @code{.hla}.
+
+
+
+@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
+@section Manipulating Spacing
+@cindex manipulating spacing
+@cindex spacing, manipulating
+
+
+@findex sp
+The @code{sp} request will cause troff to space downwards the
+distance specified as the first argument.  With no argument it will
+advance 1 line.
+A negative argument will cause troff to move up the page the
+specified distance.
+If the argument is preceded by a @samp{|} troff will move that
+distance from the top of the page.
+
+@findex ls
+@vindex .L
+Often you may want your output to be double or triple spaced.
+The @code{ls} request will cause troff to output @var{n}-1 blank
+lines after each line of text, where @var{n} is the argument given to
+the @code{ls} request.  With no argument troff will go back to single
+spacing.  The number register @code{.L} contains the current line
+spacing setting.
+
+@findex \x
+@vindex .a
+Sometimes, extra vertical spacing is only needed occasionaly,
+i.e. to allow space for a tall construct (like an equation).
+The @code{\x} escape will do this.
+The escape is given a numerical argument (like @samp{\x'3p'}).
+If this number is positive extra vertical space will be inserted
+below the current line.  A negative number will add space above.
+If this escape is used multiple times on the same line, the maximum
+values are used.
+The @code{.a} number register contains the most recent
+extra vertical @strong{emph} line space.
+
+@example
+... example of inline equation ...
+@end example
+
+@findex ns
+@findex rs
+@cindex no-space mode
+@cindex mode, no-space
+Spacing (via either @code{sp} or via blank lines) can be disabled
+with the @code{ns} request.  This will enable @dfn{no-space mode}.
+This mode will end when actual text is output or the @code{rs}
+request is encountered.  No-space mode will also prevent requests to
+advance to the next page unless they are accompanied by a page number
+(@pxref{Page Control}, for more information.)
+
+
+@node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
+@section Tabs and Fields
+@cindex tabs and fields
+@cindex fields and tabs
+
+
+@findex \t
+Tab stops are much like those on a typewriter: a tab character (or the
+@code{\t} escape) on input will cause horizontal motion to the next
+tab stop.
+
+@findex ta
+Tab stops can be changed with the @code{ta} request.
+This request takes a series of numbers as arguments which indicate
+where each tab stop is to be (overriding any previous settings).
+These can be specified absolutely,
+i.e. as the distance from the left margin.
+For example, the following wil set tab stops every one inch.
+
+@example
+.ta 1i 2i 3i 4i 5i 6i
+@end example
+
+Tab stops can also be specified relatively (using a leading @samp{+})
+which means that the specified tab stop will be set that distance
+from the previous tab stop.  For example the following is equivalent
+to the previous example.
+
+@example
+.ta 1i +1i +1i +1i +1i +1i
+@end example
+
+After the specified tab stops repeat values may be set for tabs beyond
+the last one specified.  This is most commonly used to specify tabs
+set at equal intervals.  The compleat syntax for setting tabs is
+@code{ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2}
+@dots{} @var{rn}} This will set tabs at positions @var{n1}, @var{n2},
+@dots{}, @var{nn} and then set tabs at @var{nn}+@var{r1},
+@var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} and then at
+@var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, @dots{},
+@var{nn}+@var{rn}+@var{rn}, and so on.  For example the following is,
+yet again, the same as the previous examples.
+
+@example
+.ta T 1i
+@end example
+
+The material in each tab column may be justified to the right or left
+or centered in the column.  This is specified by appending an
+@samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop.
+The default justification is @samp{L}.
+
+@example
+.ta 1i 2iC 2iR
+@end example
+
+@vindex .tabs
+The number register @code{.tabs} contains
+a string representation of the current tab settings suitable for use as
+an argument to the @code{ta} request.
+
+@findex tc
+Normally troff will fill the space to the next tab stop with spaces.
+In some cases you may wish to change this.  The @code{tc} request
+will do this.  With no argument troff will revert to using spaces.
+
+@subsection Leaders
+@cindex leaders
+
+@findex lc
+Sometimes you may wish to use the @code{tc} request to fill a tab
+stop with a given character, but also, you want to use normal tab
+stops on the rest of the line.  For this groff provides an alternate
+tab mechanism, called @dfn{leaders} which will do just that.
+They are used exclusively to produce a repeated run of characters to
+the next tab stop.
+
+You can declare what character will be repeated with the @code{lc}
+request.  If you do not give it an argument, the leaders will act the
+same as tabs.
+
+@findex \a
+The difference is that a leader is invoked by using the @code{\a}
+escape.
+
+@cindex table of contents
+@cindex contents, table of
+So for a table of contents you may want to have tab stops defined so
+that the section number is one tab stop, the title is the second with
+the remaining space being filled with a line of dots and then the
+page number slightly separated from the dots.
+
+@example
+.lc .
+.ta .5iR 5i +.25i
+1.1\tFoo\a\t12
+@end example
+
+@subsection Fields
+@cindex fields
+
+@findex fc
+Fields are a more general way of laying out tabular data.
+@code{fc}
+
+@node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial
+@section Character Translations
+@cindex character translations
+@cindex translations of characters
+
+
+@findex cc
+@findex c2
+The control character (@samp{.}) and the no-break control character
+(@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
+respectively.
+The single argument is the new character to be used, with no argument
+the normal control character is restored.
+
+@findex ec
+@findex eo
+The @code{eo} request will compleatly disable the escape mechanism.
+The @code{ec} request can be used to change the escape character from
+the default @samp{\} to what is specified as an argument.
+
+@findex tr
+The @code{tr} request will translate characters.
+
+@findex trnt
+@findex \!
+@code{trnt}
+This is the same as the @code{tr} request except that the
+translations do not
+apply to text that is transparently throughput into a diversion with
+@code{\!}.  @xref{Diversions}, for more information.
+For example,
+
+@example
+.tr ab
+.di x
+\!.tm a
+.di
+.x
+@end example
+
+will print @samp{b}; if @code{trnt} is used instead of @code{tr} it
+will print @samp{a}.
+
+
+@node Line Layout, Page Layout, Character Translations, Programming Tutorial
+@section Line Layout
+@cindex line layout
+@cindex layout, line
+
+
+@cindex dimensions, line
+@cindex line dimensions
+The following drawing shows the dimensions which troff uses for
+placing a line of output onto the page.  They are labeled with the
+request which manipulates that dimension.
+
+@example
+@group
+              | -->| in |<--                   |
+           -->| po |<-----------ll------------>|
+              +----+----+----------------------+----+
+              |    :    :                      :    |
+              +----+----+----------------------+----+
+@end group
+@end example
+
+These dimensions are:
+
+@ftable @code
+@item po
+@vindex .o
+@dfn{Page offset}--This is the leftmost postition of text on the final
+output.  This can be adjusted with the @code{po} request, and the
+current setting can be found in the builtin number register @code{.o}
+Note, that this request does not cause a break, so changing the page
+offset in the middle of text being filled may not do what you expect.
+@item in
+@vindex .i
+@dfn{Indentation}--This is the distance from the left margin where text
+will be printed.  This can be adjusted with the @code{in} request, and
+the current setting can be found in the builtin number register.
+@code{.i}
+This request causes a break.
+
+@findex ti
+@findex .in
+There is also the request @code{ti} which will cause one output line
+to be indented, after which the indentation returns to 0.
+This request causes a break.
+The number register @code{.in} is the indent that applies to the
+current output line.
+@item ll
+@findex .l
+@findex .ll
+@dfn{Line length}--This is the distance from the left margin to right
+margin.  This can be adjusted with the @code{.ll} request, and the
+current setting can be found in the builtin number register @code{.l}
+Note, as the figure implies, line length is not affected by the current
+indentation.
+The number register @code{.ll} is
+the line length that applies to the current output line.
+@end ftable
+
+@example
+.in +.5i
+.ll -.5i
+A bunch of really boring text which should
+be indented from both margins.
+replace me with a better (and more) example!
+.in -.5i
+.ll +.5i
+@end example
+
+
+@node Page Layout, Page Control, Line Layout, Programming Tutorial
+@section Page Layout
+@cindex page layout
+@cindex layout, page
+
+
+Troff provides some very primitive operations for controlling page
+layout.
+
+@findex pl
+@vindex .p
+Troff lets you specify the @dfn{page length} via the @code{pl} request.
+This is the length of the physical output page.
+The current setting can
+be found in the builtin number register @code{.p}.  Note that this only
+specifies the size of the page, not the not the top and bottom margins.
+Those are not done by groff directly, @xref{Traps}, for further
+information on how to do this.
+
+@cindex headers
+@cindex footers
+@cindex titles
+Troff provides several operations which help in setting up top and
+bottom titles (or headers and footers)
+
+@findex tl
+The @code{tl} request will print a @dfn{title line}, which consists
+of three parts: a left justified portion, a centered portion and a
+right justified portion.  The argument to @code{tl} is specified as
+@code{'@var{left}'@var{center}'@var{right}'}
+The @samp{%} character is replaced with the current page number.
+
+@findex lt
+@vindex .lt
+The title line is printed using its own line length, which is
+specified with the @code{lt} request.  The current setting of this is
+available in the @code{.lt} number register.
+
+@findex pn
+The @code{pn} request will change the page number of the @emph{next}
+page.  The only argument is the page number.
+
+@vindex %
+@vindex .pn
+The current page number is stored in the number register @code{%}.
+The number register @code{.pn} contains the
+number of the next page:
+either the value set by a @code{pn} request, or
+the number of the current page plus 1.
+
+@findex pc
+The @code{pc} request will change the page number character (used by
+the @code{tl} request) to a different character.  With no argument,
+this mechanism is disabled.
+
+
+@c distribute these through the text
+@xref{Traps}
+
+@node Page Control, Fonts, Page Layout, Programming Tutorial
+@section Page Control
+@cindex page control
+@cindex control, page
+
+
+@findex bp
+To stop processing the current page, and move to the next page, you
+can invoke the @code{bp} request.  This request will also cause a
+break.  This request can also take an argument of what the next page
+should be numbered.
+The only difference
+between @code{bp} and @code{pn} is that @code{pn} does not cause a
+break or actually eject a page.
+
+@example
+.de newpage
+'bp
+'sp .5i
+.tl 'left top'center top'right top'
+'sp .3i
+..
+@end example
+
+@cindex orphan
+@findex ne
+Often you may want to make sure that you have a certain amount of
+space before a new page occurs.  This is most useful to make sure
+that there is not a single @dfn{orphan} line left at the bottom of a
+page.  The @code{ne} request will ensure that there is a certain
+distance, specified by the first argument, before the next page is
+triggered (@pxref{Traps}, for further information).
+The default unit for @code{ne} is v's and the default argument
+is 1v.
+
+For example, to make sure that no fewer than 2 lines get orphaned,
+you can do the following before each paragraph.
+
+@example
+.ne 2
+.ti +5n
+text
+@end example
+
+@findex sv
+@findex os
+The @code{sv} is similar to the @code{ne} request, it reserves the
+specified amount of vertical space.  If the desired amount of space
+exists before the next trap (bottom page boundary), the space will be
+output immediately.  If there is not enough space, it is stored for
+later output via the @code{os} request.
+The default argument is 1v and the default units are v's.
+
+
+@node Fonts, Sizes, Page Control, Programming Tutorial
+@section Fonts
+@cindex fonts
+
+
+@findex ft
+@findex \f
+Groff gives you the ability to switch fonts at any point in your
+text.  There are two ways to do this, via the @code{ft} request and
+the @code{\f} escape.
+
+Fonts are generaly specified as uppercase strings, which are usually
+1 to 4 characters representing an abreviation of acronym of the font
+name.
+
+The basic set of fonts are R, I, B, and BI.  These are Times Roman,
+Italic, Bold, and Bold Italic.  There is also at least one symbol
+font which contains various special symbols (greek, mathematics).
+These latter fonts cannot be used directly, but should be used via an
+escape.
+
+
+@menu
+* Changing Fonts::              
+* Font Families::               
+* Font Positions::              
+* Using Symbols::               
+* Artificial Fonts::            
+* Ligatures and Kerning::       
+@end menu
+
+@node Changing Fonts, Font Families, Fonts, Fonts
+@subsection Changing Fonts
+@cindex changing fonts
+@cindex fonts, changing
+
+
+@findex ft
+You can change fonts with both the @code{ft} request.
+With no arguments it
+will switch to the previous font (also known as P).
+
+@example
+eggs, bacon,
+.ft B
+spam
+.ft
+and sausage.
+@end example
+
+@findex \f
+The @code{\f} escape is useful for changing fonts in the middle of words
+
+@example
+eggs, bacon, \fBspam\fP and sausage.
+@end example
+
+Both of the above examples will produce the same output.
+
+Sometimes when putting letters of different fonts, you need more or
+less space at such boundaries.  There are two escapes to help with
+this.
+
+@findex \/
+The @code{\/} escape
+increases the width of the preceding character so that the spacing
+between that character and the following character will be correct if
+the following character is a roman character.  For example, if an italic
+f is immediately followed by a roman right parenthesis,  then in many
+fonts the top right portion of the f will overlap the top left of the
+right parenthesis.
+It is a good idea to use this escape sequence
+whenever an italic character is immediately followed by a roman
+character without any intervening space.
+
+@c producing @i{f}), which is ugly.  Inserting \/ produces f) and avoids this problem.
+
+@findex \,
+The @code{\,} escape
+modifies the spacing of the following character so that the spacing
+between that character and the preceding character will correct if the
+preceding character is a roman character.
+It is a good idea
+to use this escape sequence whenever a roman character is immediately
+followed by an italic character without any intervening space.
+
+@c For example, inserting \, between the parenthesis and the f changes (f to (f.
+
+@findex ftr
+The @code{ftr} request will translate fonts, it is called as
+@samp{.ftr @var{F G}}, which
+Translate font @var{F} to @var{G}.
+Whenever a font named @var{F} is referred to in @code{\f}
+escape sequence,
+or in the @code{ft}, @var{ul}, @var{bd}, @var{cs}, @var{tkf},
+@var{special}, @var{fspecial}, @var{fp},
+or @var{sty} requests, font @var{G} will be used.  If @var{G} is
+missing, or equal to @var{F} then font @var{F} will not be translated.
+
+
+@node Font Families, Font Positions, Changing Fonts, Fonts
+@subsection Font Families
+@cindex font families
+@cindex families, font
+
+
+Due to the variety of fonts available, groff has added the concept of
+font families.  Each of these families has four styles (R, I, B and BI),
+
+The fonts are specified as the concatenation of the font family and
+style.  Specifying a font without the family part will cause groff to
+use that style of the current family.
+By default, groff uses the Times family.
+
+This way, you can just use the basic four fonts and select a
+different font family on the command line.
+
+@findex fam
+@vindex .fam
+You can also switch font families with the @code{fam} request
+The current font family is available in the number register
+@code{.fam}.
+This is a string-valued register.
+
+@example
+spam,
+.fam H
+spam,
+.ft B
+spam,
+.fam T
+spam,
+.ft AR
+baked beans,
+.ft R
+and spam.
+@end example
+
+
+
+@node Font Positions, Using Symbols, Font Families, Fonts
+@subsection Font Positions
+@cindex font positions
+@cindex positions, font
+
+
+For the sake of old phototypesetters and compatability with old
+versions of troff, groff has the concept of font
+@dfn{positions}, on which various fonts are mounted.
+The last one or two are reserved for the symbol font(s).
+
+@findex fp
+New fonts can be mounted with the @code{fp} request.
+These numeric positions can then be referred to with font changing commands.
+When groff starts it is using font number one.
+
+@example
+.fp 1 H
+.fp 2 HI
+.fp 3 HB
+wink, wink,
+.ft 2
+nudge, nudge,
+.ft
+.ft 3
+say no more!
+.ft
+@end example
+
+(note that after these font changes have taken place the original
+font is restored.)
+
+@vindex .f
+The current font in use, as a font position.
+This can be useful to remember the current font, for later recall.
+
+@example
+.nr save-font \n(.f
+... lots 'o text ...
+.ft \n[save-font]
+@end example
+
+@vindex .fp
+The number of the next free font position is available in the number
+register @code{.fp}.  This is useful when mounting a new font, like so:
+
+@example
+.fp \n[.fp] NEATOFONT
+@end example
+
+@pindex DESC
+Fonts not listed in the @file{DESC} file are automatically mounted on
+the next available font position when they are referenced.
+If a font is to be
+mountfed explicitly with the @code{fp} request on an unused font position, it
+should be mounted on the first unused font position, which can be found
+in the @code{.fp} register; although troff does not enforce this strictly,
+it will not allow a font to be mounted at a position whose number is
+much greater than that of any currently used position.
+
+The @code{fp} request has an optional third argument.
+This argument gives the
+external name of the font, which is used for finding the font
+description file.  The second argument gives the internal name of the
+font which is used to refer to the font in troff after it has been
+mounted.  If there is no third argument then the internal name will be
+used as the external name.  This feature allows you to use fonts with
+long names in compatibility mode.
+
+
+
+@node Using Symbols, Artificial Fonts, Font Positions, Fonts
+@subsection Using Symbols
+@cindex using symbols
+@cindex symbols, using
+
+
+@findex \(
+@findex \[
+Symbols can be inserted by using a special escape sequence.
+This escape is simply the escape character (a backslash) followed by
+an identifier.  The symbol identifiers have to be two or more
+characters, since single characters conflict with all the other
+escapes.  The identifier can be either preceded by a parenthesis if
+it is two character, or surrounded by square brackets.
+So, the symbol for pi can be produced either by @code{\(*p} or
+@code{\[*p]}.
+
+@example
+area = \(*p\fIr\fP\u2\d
+@end example
+
+@findex \C
+The escape @code{\C'@var{xxx}'} will typeset character named
+@var{xxx}.  Normally it is more convenient to use @code{\[@var{xxx}]}.
+But @code{\C} has the advantage that it is compatible with recent
+versions of ditroff and is available in compatibility mode.
+
+@findex \N
+The escape @code{\N'@var{n}'} will typeset the character with code
+@var{n} in the current font.  @var{n} can be any integer.  Most devices only
+have characters with codes between 0 and 255.  If the current font
+does not contain a character with that code, special fonts will not be
+searched.  The @code{\N} escape sequence can be conveniently used on
+conjunction with the @code{char} request:
+
+@example
+.char \[phone] \f(ZD\N'37'
+@end example
+
+The code of each character is given in the fourth column in the font
+description file after the charset command.  It is possible to include
+unnamed characters in the font description file by using a name of
+@samp{---}; the @code{\N} escape sequence is the only way to use these.
+
+@findex cflags
+Each character has certain properties associated with it.
+These properties can be modified with the @code{cflags} request.
+The first argument is the the sum of the desired flags and the
+remaining arguments are the characters to have those properties.
+@table @code
+@item 1
+the character ends sentences (initially characters @samp{.?!} have this
+property);
+@item 2
+lines can be broken before the character (initially no characters have
+this property);
+@item 4
+lines can be broken after the character (initially characters
+@samp{-\(hy\(em} have this property);
+@item 8
+the character overlaps horizontally (initially characters
+@samp{\(ul\(rn\(ru} have this property);
+@item 16
+the character overlaps vertically (initially character @samp{\(br} has
+this property);
+@item 32
+an end of sentence character followed by any number of characters with
+this property will be treated as the end of a sentence if followed by a
+newline or two spaces; in other words the character is transparent for
+the purposes of end of sentence recognition; this is the same as having
+a zero space factor in @TeX{} (initially characters
+@samp{"')]*\(dg\(rq} have this property).
+@end table
+
+@findex char
+You can create new characters with the @code{char} request.  It is
+called as @samp{.char @var{c} @var{string}} Define character @var{c}
+to be @var{string}. Every time character @var{c} needs to be printed,
+@var{string} will be processed in a temporary environment and the
+result will be wrapped up into a single object.  Compatibility mode
+will be turned off and the escape character will be set to \ while
+@var{string} is being processed.  Any emboldening, constant spacing or
+track kerning will be applied to this object rather than to individual
+characters in @var{string}.  A character defined by this request can
+be used just like a normal character provided by the output device.
+In particular other characters can be translated to it with the
+@code{tr} request; it can be made the leader character by the
+@code{lc} request; repeated patterns can be drawn with the character
+using the @code{\l} and @code{\L} escape sequences;  words containing
+the character can be hyphenated correctly, if the @code{hcode} request
+is used to give the character a hyphenation code. There is a special
+anti-recursion feature: use of character within the character's
+definition will be handled like normal characters not defined with
+@code{char}.
+
+@findex rchar
+A character definition can be removed with the @code{rchar} request.  Its
+arguments are the characters to be removed.  This undoes the effect of
+a @code{char} request.
+
+@c distribute these through the text
+@xref{Special Characters}
+
+@node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
+@subsection Artificial Fonts
+@cindex artificial fonts
+@cindex fonts, artificial
+
+
+There are a number of requests for artificially creating fonts.
+These are largely vestigal remains from the days when output devices
+did not have a wide variety of fonts, and when nroff and troff were
+separate programs.
+These are no longer necessary in GNU Troff.
+
+@findex ul
+The @code{ul} request will print subsequent lines in italics on a
+device capable of it, or underline the text on an ascii output device.
+The single argument is the number of lines to be ``underlined,''
+with no argument, the next line will be underlined.
+
+@findex cu
+The @code{cu} request is similar to @code{ul} ...
+
+@findex uf
+The @code{uf} request will set the underline font used by @code{ul}
+and @code{cu}.
+
+@findex bd
+The @code{bd} request artificially creates a bold font by printing
+each character twice, slightly offset.
+The first argument specifies the font to embolden, and the second is
+the number of basic units, minus one, by which the two characters
+will be offset.  If the second argument is missing, emboldening will
+be turned off.
+
+
+@node Ligatures and Kerning,  , Artificial Fonts, Fonts
+@subsection Ligatures and Kerning
+@cindex ligatures and kerning
+@cindex kerning and ligatures
+
+
+@findex lg
+@vindex .lg
+@code{lg}
+@code{.lg}
+The current ligature mode.
+
+What is kerning??
+
+If the font description file contains pairwise kerning information,
+characters from that font will be kerned.  Kerning between two
+characters can be inhibited by placing a @code{\&} between them.
+
+@findex kern
+@vindex .kern
+@code{kern}
+If n is non-zero or missing, enable pairwise kerning, otherwise disable
+it.
+@code{.kern}
+1 if pairwise kerning is enabled, 0 otherwise.
+
+@findex tkf
+.tkf f s1 n1 s2 n2
+Enable track kerning for font f.  When the current font is f the width
+of every character will be increased by an amount between n1 and n2;
+when the current point size is less than or equal to s1 the width will
+be increased by n1; when it is greater than or equal to s2 the width
+will be increased by n2; when the point size is greater than or equal to
+s1 and less than or equal to s2 the increase in width is a linear
+function of the point size.
+
+
+@node Sizes, Strings, Fonts, Programming Tutorial
+@section Sizes
+@cindex sizes
+
+
+@cindex baseline
+Groff uses two dimensions with each line of text, type size and
+vertical spacing.  The type size is the height from the text
+@dfn{baseline} to the top of the tallest character (decenders may drop
+below this baseline).  Vertical spacing is the amount of space groff
+allows for a line of text, normally, this is about 20% larger than the
+current type size.  Ratios smaller than this can result in
+hard-to-read text, larger that this, it will spread your text out more
+vertically (useful for term papers).  By default, troff uses 10 point
+type on 12 point spacing.
+
+@cindex leading
+The difference between type size and vertical spacing is known, by
+typesetters, as @dfn{leading}.
+
+
+@menu
+* Changing Type Sizes::         
+* Fractional Type Sizes::       
+@end menu
+
+@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
+@subsection Changing Type Sizes
+@cindex changing type sizes
+@cindex type sizes, changing
+
+
+@findex ps
+@findex vs
+@findex \s
+@vindex .s
+@vindex .v
+Using the @code{ps} request and the @code{\s} escape you can change
+the type size.  The @code{vs} request will change the vertical
+spacing. The default unit for the @code{ps} and @code{vs} requests are
+points.
+The number registers @code{.s} and @code{.v} contain the current
+type size and vertical spacing.
+
+These requests take parameters in units of points.  You can specify
+sizes as an absolute size, or as a relative change from the current
+size.  The size 0 means go back to the previous size.  With no
+argument it will revert to the previous size.
+
+@example
+snap, snap,
+.ps +2
+grin, grin,
+.ps +2
+wink, wink, \s+2nudge, nudge,\s+8 say no more!
+.ps 10
+@end example
+
+The @code{\s} escape may be called in a variety of ways.
+Much like other escapes there must be a way to determine where the
+argument ends and the text begins.
+Any of the following forms are valid:
+@code{\s@var{n}},
+@code{\s+@var{n}},
+@code{\s-@var{n}},
+@code{\s(@var{nn}},
+@code{\s+(@var{nn}},
+@code{\s-(@var{nn}},
+@code{\s[+@var{nnn}]},
+@code{\s[-@var{nnn}]},
+@code{\s+[@var{nnn}]},
+@code{\s-[@var{nnn}]}.
+
+Some devices may only have certain permissible sizes, in which case
+groff will round to the nearest permissible size.
+
+@example
+... .sz macro example?? ...
+@end example
+
+@node Fractional Type Sizes,  , Changing Type Sizes, Sizes
+@subsection Fractional Type Sizes
+@cindex fractional type sizes
+@cindex type sizes, fractional
+
+
+A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
+@var{sizescale} is specified in the @file{DESC} file (1 by default.)
+There is a new scale indicator @samp{z} which has the effect of
+multiplying by @var{sizescale}.  Requests and escape sequences in
+troff interpret arguments that represent a pointsize as being in units
+of scaled points, but they evaluate each such argument using a default
+scale indicator of @samp{z}.  Arguments treated in this way are the
+argument to the @code{ps} request, the third argument to the @code{cs}
+request, the second and fourth arguments to the @code{tkf} request,
+the argument to the @code{\H} escape sequence, and those variants of
+the @code{\s} escape sequence that take a numeric expression as their
+argument.
+
+For example, suppose @var{sizescale} is 1000; then a scaled point will be
+equivalent to a millipoint; the request @samp{.ps 10.25} is equivalent to
+@samp{.ps 10.25z} and so sets the pointsize to 10250 scaled points, which is
+equal to 10.25 points.
+
+The number register @code{\n(.s} returns the pointsize in points as
+decimal fraction.  There is also a new number register @code{\n[.ps]}
+that returns the pointsize in scaled points.
+
+It would make no sense to use the @samp{z} scale indicator in a
+numeric expression whose default scale indicator was neither @samp{u}
+nor @samp{z}, and so troff disallows this.  Similarily it would make
+no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
+numeric expression whose default scale indicator was @samp{z}, and so
+troff disallows this as well.
+
+There is also new scale indicator @samp{s} which multiplies by the
+number of units in a scaled point.  So, for example, @samp{\n[.ps]s}
+is equal to 1m.  Be sure not to confuse the @samp{s} and @samp{z}
+scale indicators.
+
+@code{\s'+@var{n}'}
+@code{\s'-@var{n}'}
+@code{\s+'@var{n}'}
+@code{\s-'@var{n}'}
+Set the point size to @var{n} scaled points; @var{n} is a numeric
+expression with a default scale indicator of @samp{z}.
+
+@code{\n[.ps]}
+The current pointsize in scaled points.
+
+@code{\n[.psr]}
+The last-requested pointsize in scaled points.
+
+@code{\n[.sr]}
+The last requested pointsize in points as a decimal fraction.  This is a
+string-valued register.
+
+
+@c distribute these through the text
+@xref{Font Files}
+
+@node Strings, Conditionals and Loops, Sizes, Programming Tutorial
+@section Strings
+@cindex strings
+
+
+@findex ds
+Groff has string variables, which are entirely for user convenience
+(i.e. there are no builtin strings) They are defined via the
+@code{ds} request.
+
+@example
+.ds UX \s-1UNIX\s0\u\s-3tm\s0\d
+@end example
+
+@findex \*
+The are interpolated, or expanded in-place, via the @code{\*} escape:
+
+@example
+The \*(UX Operating System
+@end example
+
+Will produce:
+
+@example
+The UNIXtm Operating System
+@end example
+
+If the string named by the @code{\*} does not exist, the escape will
+be replaced by nothing.
+
+@cindex comments, with @code{ds}
+NOTE:  Unlike other requests the third argument takes up the entire
+line including trailing spaces.  This means that comments on a line
+with such a request can introduce unwanted space into a string.
+
+@example
+.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" trademark of you-know-who
+@end example
+
+Instead you should either put the comment on another line or
+have the comment escape adjacent with the end of the string.
+
+@example
+.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\"  trademark of you-know-who
+@end example
+
+If you need leading space you can start the string with a double
+quote.  No trailing quote is needed, in fact any trailing quote is
+included in your string.
+
+@cindex canibalism
+@example
+.ds sign "           Yours in a white wine sauce,
+@end example
+
+@findex as
+@cindex appending to strings
+@cindex strings, appending
+You can also append onto a string with the @code{as} request.
+It works the same as the @code{ds} request except that it appends the
+second argument onto the string named by the first argument.
+
+@example
+.as sign " with shallots, onions and garlic,
+@end example
+
+@findex \@key{ret}
+Strings are not limited to a sigle line of text.  A string can span
+several lines by escaping the newlines with a backslash.  The
+resulting string will be stored @emph{without} the newlines.
+
+@example
+.ds foo lots and lots \
+of text are on these \
+next several lines
+@end example
+
+@findex rn
+@code{rn}
+
+@findex rm
+@code{rm}
+
+@findex als
+@code{als}
+
+@findex chop
+@code{chop}
+
+@c distribute these through the text
+@xref{Identifiers}
+@c distribute these through the text
+@xref{Comments}
+
+@node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
+@section Conditionals and Loops
+@cindex conditionals and loops
+@cindex loops and conditionals
+
+
+@findex if
+@findex while
+In @code{if} and @code{while} requests, there are several more operators
+available:
+
+@table @code
+@item e
+@itemx o
+True if the current page is even or odd numbered (respectively)
+@item n
+@itemx t
+True if the document is being processed by
+nroff (or an ascii device) or troff.
+@item '@var{xxx}'@var{yyy}'
+True if the string @var{xxx} is equal to the string @var{yyy}.
+Other characters can be used in place of the single quotes.
+(Which?)
+The strings are `formatted' before being compared. (?)
+@item r@var{xxx}
+True if there is a number register named @var{xxx}.
+@item d@var{xxx}
+True if there is a string, macro, diversion, or request named @var{xxx}.
+@item c@var{ch}
+True if there is a character @var{ch} available;  @var{ch} is
+either an ASCII character or a special character @code{\(@var{ch}} or
+@code{\[@var{ch}]}; the condition will also be true if @var{ch} has been
+defined by the @code{char} request.
+@end table
+
+
+@menu
+* if-else::                     
+* while::                       
+@end menu
+
+@node if-else, while, Conditionals and Loops, Conditionals and Loops
+@subsection if-else
+@cindex if-else
+
+
+Troff has if-then-else constructs like other languages, although
+the formatting can be painful.
+
+@findex if
+The @code{if} request is troff's if statement, it is called as
+@samp{.if @var{expr} @var{anything}}, where @var{expr} is the
+expression to be evaluated,
+and @var{anything} (the remainder of the line)
+which will be executed if
+the @var{expr} evaluates to non-zero (true).
+@var{anything} will be interpreted as though it was on a line by
+itself.
+@xref{Expressions}, for more info.
+
+Here are some examples:
+
+@example
+.if t .ls 2				\" double spacing in troff
+.if 0 .ab how'd this happen??
+@end example
+
+@findex ie
+@findex el
+An if-then-else is written using two requests @code{ie} and @code{el}
+the first request is the if part and the latter is the else part.
+
+@example
+.ie
+.el
+@end example
+
+@findex \@{
+@findex \@}
+In many cases you will want more than one request to be executed as a
+result of any of these requests, this can be done using the \@{ and
+\@} escapes.
+The following example shows the possible ways to use these escapes.
+
+@example
+.ie t \@{\
+.    ds lq ``
+.    ds rq ''
+.\@}
+.el \
+.\@{\
+.    ds lq "
+.    ds rq "\@}
+.ds qq "
+@end example
+
+
+@c distribute these through the text
+@xref{Expressions}
+
+@node while,  , if-else, Conditionals and Loops
+@subsection while
+@cindex while
+
+
+@findex while
+Groff provides a looping construct using the @code{while} request,
+which is used much like the @code{if} (and related) requests.
+The first argument is an expression which will be evaluated.
+The @code{while} request will interpret the remainder of the line
+until the expression evaluates to 0 or false.
+
+@example
+.nr a 0 1
+.while (\na<9) \&\n+a,
+\&\n+a
+@end example
+
+The preceding example produces:
+
+@example
+1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+@end example
+
+@findex break
+@findex continue
+The @code{break} request will
+@dfn{break} out of a while loop.
+Be sure not to confuse this with the @code{.br} request.
+The @code{continue} request will
+finish the current iteration of a while loop.
+
+@c distribute these through the text
+@xref{Expressions}
+
+@node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
+@section Writing Macros
+@cindex writing macros
+@cindex macros, writing
+
+
+@findex de
+A macro is a collection of text and embedded commands which can be
+invoked multiple times.  Macros are used for defining common operations.
+Macros are defined using the @code{de} request.  This request takes
+a name for the macro as the first argument.  Subsequent lines are
+copied into an internal buffer until the line @code{..} is
+encountered.  The optional second argument to @code{de} can change
+this ending token.
+
+For example, suppose at the beginning of each paragraph, you want
+cause a break, move down a partial line and indent the first line.
+Such a macro could be defined as follows:
+
+@example
+.de P
+.br
+.sp .8v
+..
+@end example
+
+@findex am
+The @code{am} request works similarily to @code{de} except it appends
+onto the macro named by the first argument.  So, if we decide we want
+our previously @code{P} macro to actually do indented instead of
+block paragraphs we can add the necessary code to our existing macro.
+
+@example
+.am P
+.ti +5n
+..
+@end example
+
+@findex als
+@cindex aliases, macro
+@cindex macro aliases
+Macros can be aliased with the @code{als} request.
+
+@findex rn
+@code{rn}
+
+@findex rm
+@code{rm}
+
+@findex chop
+@code{chop}
+
+
+@menu
+* Copy-in Mode::                
+* Parameters::                  
+@end menu
+
+@node Copy-in Mode, Parameters, Writing Macros, Writing Macros
+@subsection Copy-in Mode
+@cindex copy-in mode
+@cindex mode, copy-in
+
+
+@findex \n
+@findex \$
+@findex \*
+@findex \\
+@findex \@key{RET}
+When troff reads in the test for a macro or diversion it copies the
+text (including request lines) into an internal buffer, except for
+escapes.  Escapes will be converted into an internal form, except for
+@code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which
+are evaluated and inserted into the text where the escape was located.
+This is known as @dfn{copy-in} mode.
+
+What this means is that you can specify when these escapes are to be
+evaluated (copy-in time or time of use) by insulating the escapes
+with an extra backslash.
+
+For example, the following will result in the numbers 20 and 10 being
+printed.
+
+@example
+.nr x 20
+.de y
+.nr x 10
+\&\nx
+\&\\nx
+..
+.y
+@end example
+
+
+
+@node Parameters,  , Copy-in Mode, Writing Macros
+@subsection Parameters
+@cindex parameters
+
+
+@findex \$
+@vindex .$
+The arguments to a macro can be examined using a variety of escapes.
+The number of arguments is available in the @code{.$} number register.
+Any individual argument can be retrieved with one of the following
+escapes:
+
+The escapes @code{\$@var{n}}, @code{\$(@var{nn}}
+and @code{\$[@var{nnn}]}
+will result in the @var{n}th, @var{nn}th or @var{nnn}th
+argument.  Macros can have a unlimited number of arguments.
+Note that due to copy-in mode, you will want to have two backslashes
+on these in actual use, since you do not want them interpolated until
+the macro is actually invoked.
+
+@findex shift
+The request @code{shift} will shift the arguments 1 position, or as
+many positions as specified by the first argument.
+After executing this request, argument
+@var{i} will become argument @var{i}-@var{n}; arguments 1 to @var{n}
+will no longer be available.
+Shifting by negative amounts is currently undefined.
+
+@findex \$*
+@findex \$@@
+In some cases you will want to just use all of the arguments at once.
+For example if you pass the arguments along to another macro.
+The @code{\$*} escape is
+the concatenation of all the arguments separated by spaces.
+A similar escape is @code{\$@@},
+which is
+the concatenation of all the arguments with each surrounded
+by double quotes, and separated by spaces.
+
+@findex \$0
+@findex als
+The @code{\$0} escape is 
+the name by which the current macro was invoked.  The @code{als}
+request can make a macro have more than one name.
+
+@example
+.de vl
+.ie \\n(.$=1 .ds Vl Pre-Release Version
+.el          .ds Vl Version \\$3, \\$4.
+..
+@end example
+
+This would be called as
+
+@example
+.vl $Id: groff.texinfo,v 1.5 1999/12/09 09:42:29 wlemb Exp $
+@end example
+
+
+@c distribute these through the text
+@xref{Request Arguments}
+
+@node Page Motions, Drawing Functions, Writing Macros, Programming Tutorial
+@section Page Motions
+@cindex page motions
+@cindex motions, page
+
+
+@findex sp
+Motions up and down the page can be done with the @code{sp} request.
+However, this causes a break so that the actual effect is to move to
+the left margin and then to the specified location.
+
+@findex mk
+@findex rt
+The request @code{mk} can be used to mark a location on a page, for
+movement to later.  This request takes a register name as an
+argument in which to store the current page location, with no
+argument it will store the location in an internal register.
+The results of this can be used later by the @code{rt} or the
+@code{sp} request.  The @code{rt} request will return
+@strong{upwards} to the location given in the register name given as
+an argument, with no argument it will return to the location marked
+with the @code{mk} request
+
+@example
+... dual column example ...
+@end example
+
+There are escapes which will give you much finer control of movements
+about the page.
+
+@findex \v
+The @code{\v'@var{e}'} will let you do arbitrary vertical motion from
+the current location on the page.  The argument @var{e} specifies the
+distance to move, positive is downwards and negative upwards.  The
+default unit for this escape is vertical spaces, @code{v}'s.  Beware,
+however, that troff will leave text processing to continue wherever
+the motion ends, so if you don't want to interfere with text
+processing, make sure your motions are balanced.
+
+There are some special case escapes for vertical motion.
+
+@ftable @code
+@item \r
+move upwards 1v.
+@item \u
+move upwards .5v.
+@item \d
+move down .5v.
+@end ftable
+
+@findex \h
+Horizontal motions can be done via the @code{\h'@var{e}'} escape.
+The expression @var{e} indicates how far to move: positive is
+rightwards and negative leftwards.
+
+There are a number of special case escapes for horizontal motion:
+
+@ftable @code
+@item \@key{SP}
+An unbreakable and unpadable (i.e. not expanded during filling) space.
+(Note: it is a backslash followed by a space.)
+@item \~
+This produces an unbreakable space that stretches like a normal
+interword space when a line is adjusted.
+@item \|
+a 1/6th em space.
+@item \^
+a 1/12th em space.
+@item \0
+a space the size of a digit.
+@item \&
+A zero width space.
+@item \)
+Like @code{\&} except that it behaves like a character declared with
+the @code{cflags} request to be transparent for the purposes of end
+of sentence recognition.
+@end ftable
+
+@example
+... tex logo example ...
+@end example
+
+@findex \w
+@cindex width escape
+@cindex escape, width
+Often you will want to do horizontal movement based on the width of
+some arbitrary text (e.g. given as an argument to a macro).
+For that, there is the escape @code{\w'@var{text}'} which will
+interpolate to the width of the given @var{text} in basic units.
+
+@example
+... strlen example ...
+@end example
+
+Font changes may occur in @var{text} and not affect current settings.
+
+Also after use, @code{\w} sets several registers:
+
+@table @code
+@item st
+@vindex st
+@itemx sb
+@vindex sb
+The highest and lowest point, respectively, in @var{text}.
+@item rst
+@vindex rst
+@itemx rsb
+@vindex rsb
+Like the @code{st} and @code{sb} registers, but takes account of the
+heights and depths of characters.
+@item ct
+@vindex ct
+is set according to what kinds of characters occur in @var{text}.
+@table @asis
+@item 0
+all short characters, no decenders or tall characters.
+@item 1
+decender
+@item 2
+tall character
+@item 3
+both a decender and a tall character
+@end table
+@item ssc
+@vindex ssc
+The amount of horizontal space (possibly negative) that should be
+added to the last character before a subscript.
+@item skw
+@vindex skw
+How far to right of the center of the last character in the @code{\w}
+argument, the center of an accent from a roman font should  be
+placed over that character.
+@end table
+
+@findex \k
+@vindex .k
+@code{\k}
+@code{.k}
+
+@node Drawing Functions, Traps, Page Motions, Programming Tutorial
+@section Drawing Functions
+@cindex drawing functions
+@cindex functions for drawing
+
+
+Groff provides a number of ways to draw lines, and other figures on
+the page.  Used in combination with the page motion commands
+(@pxref{Page Motions}, for more info) you can draw a wide variety of
+figures.  However, for complex drawings these operations can be quite
+cumbersome, and it may be wise to use the pic preprocessor.
+@xref{gpic}, for more information.
+
+All drawing is done via escapes.
+
+@findex \l
+The @code{\l} will draw a line rightwards from the current location.
+The full syntax for this escape is @samp{\l'@var{l}@var{c}'}, where
+@var{l} is the length of the line to be drawn, starting at the
+current location, positive numbers will draw to the right, and
+negative will draw towards the left.  This can also be specified
+absolutely (i.e. with a leading |) which will draw back to the
+begining of the line.
+
+The optional second parameter @var{c} is a character to draw the line
+with.  If this second argument is not specified, troff will use the
+underscore character.
+
+If you need to separate the two arguments (to prevent troff from
+interpreting a drawing character as a scaling indicator), you can
+separate them with @code{\&}.
+
+And now, for a useful example:
+
+@example
+.de box
+\(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
+..
+@end example
+
+Note that this works by outputing a box rule (a vertical line), then
+the text given as an argument and then another box rule.
+Then the line drawing escapes both draw from the current location to
+the beginning of the @emph{input} line.
+
+@findex \L
+Vertical lines are drawn using the @code{\L} escape.  It's parameters
+are specified the same as the @code{\l} escape.  If the length is
+positive, the movement will be downwards, and upwards for negative.
+The default character is the box rule character.
+As with the vertical motion escapes, text processing will blindly
+continue where the line ends.
+
+@example
+...box macro...
+@end example
+
+@findex \D
+More flexible drawing functions are available via the @code{\D}
+escape.  While the previous escapes will work on an ascii device,
+these escapes will not.
+
+@table @code
+@item \D'l @var{x} @var{y}'
+Draw a line from the current location to the relative point specified
+by @var{x}, @var{y}.
+
+@example
+...revised box macro...
+@end example
+
+@item \D'c @var{d}'
+Draw a circle with a diameter of @var{d} with the leftmost point at
+the current position.
+@item \D'C @var{d}'
+Draw a solid circle with the same parameters as an outlined circle.
+@item \D'e @var{dx} @var{dy}'
+Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
+diameter of @var{dy} with the leftmost point at the current position.
+@item \D'E @var{dx} @var{dy}'
+Draw a solid elipse with the same parameters as an outlined elipse.
+@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
+Draw an arc clockwise from the current location through the two
+specified locations.
+@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
+Draw a spline from the current location to
+@var{dx1}, @var{dy1} and then to @var{dx2}, @var{dy2}, and so on.
+@item \D'f @var{n}'
+Set the shade of gray to be used for filling solid objects to @var{n};
+@var{n} must be an integer between 0 and 1000, where 0 corresponds
+solid white and 1000 to solid black, and values in between correspond
+to intermediate shades of gray.  This applies only to solid circles,
+solid ellipses and solid polygons.  By default, a level of 1000 will
+be used.
+@item  \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
+Draw a polygon from the current location to @var{dx1}, @var{dy1}
+and then to @var{dx2}, @var{dy2} and so on.  When the specified data
+points are exhausted, a line is drawn back to the starting point.
+
+@example
+... box example (yes, again)...
+@end example
+
+@itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
+Draw a solid polygon with the same parameters as an outlined polygon.
+
+@example
+... shaded box example ...
+@end example
+
+@item \D't @var{n}'
+Set the current line thickness to @var{n} machine units.
+A value of zero selects the smallest available line thickness.
+
+@end table
+
+Current position
+
+@findex \b
+@cindex pile, character
+@cindex character pile
+The @code{\b} escape will @dfn{pile} a sequence of characters
+vertically, and center it vertically on the current line.
+This can be used to build large brackets and braces.
+
+@example
+\b'\(lt\(bv\(lk\(bv\(lb'
+@end example
+
+
+
+
+@node Traps, Diversions, Drawing Functions, Programming Tutorial
+@section Traps
+@cindex traps
+
+
+Traps are locations, which, when reached, will call a specified macro.
+These traps can occur at a given location on the page, at a given
+location in the current diversion, after a certain number of input
+lines or at the end of input.
+
+@findex ch
+Any of these traps can be changed after they have been set with the
+@code{ch} request.  The first arguemnt is the name of the trap or
+macro, and the second is the new value for that trap.
+
+
+@menu
+* Page Location Traps::         
+* Diversion Traps::             
+* Input Line Traps::            
+* End-of-input Traps::          
+@end menu
+
+@node Page Location Traps, Diversion Traps, Traps, Traps
+@subsection Page Location Traps
+@cindex page location traps
+@cindex traps, page location
+
+
+Page location traps are frequently used for page headers and
+footers.  The following is a simple example of this.
+
+@example
+.de hd                          \" Page header
+'sp .5i
+.tl 'Title''date'
+'sp .3i
+..
+.de fo                          \" Page footer
+'sp 1v
+.tl ''%''
+'bp
+..
+.wh 0   hd                      \" top of the page
+.wh -1i fo                      \" one inch from bottom
+@end example
+
+@vindex .t
+The number register @code{.t} is the distance to the next trap.
+
+@findex ch
+The location of a trap can be changed later on with the @code{ch}
+request.
+The first argument is the name of the macro to be invoked at the trap
+and the second argument is the new location for the trap.
+This is useful when you are building up footnotes in a diversion, and
+you need to allow more space at the bottom of the page for them.
+
+@example
+... (simplified) footnote example ...
+@end example
+
+@findex vpt
+@findex wh
+@findex dt
+@vindex .vpt
+The @code{vpt} request will enable vertical position traps if the argment is
+non-zero, disable them otherwise.  Vertical position traps are traps
+set by the @code{wh} or @code{dt} requests.  Traps set by the
+@code{it} request are not vertical position traps.  The parameter that
+controls whether vertical position traps are enabled is global.
+Initially vertical position traps are enabled.  The current setting of
+this is available in the number register @code{.vpt}.
+
+@vindex .trunc
+@findex ne
+The number register @code{.trunc} contains
+the amount of vertical space truncated by the most recently
+sprung vertical position trap, or, if the trap was sprung by a
+@code{ne} request, minus the amount of vertical motion produced by
+the @code{ne} request.  In other words, at the point a trap is
+sprung, it represents the difference of what the vertical position
+would have been but for the trap, and what the vertical position
+actually is.
+
+@vindex .ne
+The number register @code{.ne} contains
+the amount of space that was needed in the last @code{ne} request that caused
+a trap to be sprung.  Useful in conjunction with the @code{.trunc}
+register.  @xref{Page Control}, for more information.
+
+
+
+@node Diversion Traps, Input Line Traps, Page Location Traps, Traps
+@subsection Diversion Traps
+@cindex diversion traps
+@cindex traps, diversion
+
+
+@findex dt
+@vindex .t
+Traps can also be set @emph{within} a diversion using the @code{dt}
+request.  Like @code{wh} the first argument is the location of the
+trap and the second argument is the name of the macro to be invoked.
+The number register @code{.t} will still work within diversions.
+@xref{Diversions}, for more information.
+
+@node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
+@subsection Input Line Traps
+@cindex input line traps
+@cindex traps, input line
+
+
+@findex it
+The @code{it} request will set an input line trap.  The format for
+calling this is @samp{.it @var{n} @var{name}}, where @var{n} is the
+number of lines of input which may be read before @dfn{springing} the
+trap, @var{name} is the macro to be invoked.  Request lines are not
+counted as input lines.
+
+For example, one possible use is to have a macro which will print the
+next @var{n} lines in a bold font.
+
+@example
+.de B
+.it B-end \\$1
+.ft B
+..
+.de B-end
+.ft R
+..
+@end example
+
+@node End-of-input Traps,  , Input Line Traps, Traps
+@subsection End-of-input Traps
+@cindex end-of-input traps
+@cindex traps, end-of-input
+
+
+@findex em
+The @code{em} request will set a trap at the end of input.
+The macro specified as an arguement will be executed after the last
+line of the input file has been processed.
+
+For example, if your document had to have a section at the bottom of
+the last page for someone to approve you document, you could set it
+up with @code{em}.
+
+@example
+.de approval
+.ne 5v
+.sp |(\\n(.t-6v)
+.in +4i
+.lc _
+.br
+Approved:\t\a
+.sp
+Date:\t\t\a
+..
+.em approval
+@end example
+
+
+@node Diversions, Environments, Traps, Programming Tutorial
+@section Diversions
+@cindex diversions
+
+
+In Troff you can divert text into a named storage area, due to the
+similarity to defining macros it is sometimes said to be stored in a
+macro.  This is used for saving text for output at a later time,
+which is useful for keeping blocks of text on the same page,
+footnotes, tables of contents and indexes.
+
+@findex di
+@findex da
+Diversion is initiated by the @code{di} request, like the @code{de}
+request it takes an argument of a macro name to divert subsequent
+text to into.  The @code{da} macro will append to an existing diversion.
+
+@example
+... end-note example ...
+@end example
+
+@vindex .z
+@vindex .d
+@vindex nl
+@vindex .h
+Diversions may be nested.
+The number register @code{.z} contains the name of the current diversion.
+The number register @code{.d} contains the current vertical place in
+the diversion.  If not in a diversion it is the same as the register
+@code{nl}.
+@code{.h}
+
+@vindex dn
+@vindex dl
+After compleating a diversion, the builtin number registers @code{dn}
+and @code{dl} contain the vertical and horizontal size of the diversion.
+
+@example
+.\" Center text both horizontally & vertically
+.de (c
+.br
+.nf
+.di @@c
+..
+.de )c
+.br
+.di
+.nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
+.sp \\n(@@su
+.ce 1000
+.nf
+.@c
+.br
+.ce 0
+.sp \\n(@@su
+.br
+.fi
+.rr @@s
+..
+@end example
+
+@findex \!
+Requests, macros and escapes are interpreted when read into a
+diversion.
+There are two ways to prevent this, either way will take the given
+text and @dfn{transparently} embed it into the diversion.
+The first method is to prefix the line with @code{\!}.  This will
+cause the entire line to be transparently inserted into the diversion.
+This is useful for macros you do not want invoked until the diverted
+text is actually output.
+
+@c anything  is  read  in  copy  mode. (what about \! ??)
+
+@findex \?
+The other way is to surround the text by the @code{\?} escape, i.e.
+@samp{\?@var{anything}\?}.
+@var{anything} may not  contain
+newlines; use @code{\!} if you want to embed newlines in a diversion.  The
+escape sequence @code{\?} is also recognised in copy mode and turned into a
+single internal code; it is this code that terminates anything.  Thus
+the followin example will print 4.
+
+@example
+.nr x 1
+.nf
+.di d
+\?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
+.di
+.nr x 2
+.di e
+.d
+.di
+.nr x 3
+.di f
+.e
+.di
+.nr x 4
+.f
+@end example
+
+@findex rn
+@code{rn}
+
+@findex rm
+@code{rm}
+
+@findex als
+@code{als}
+
+@findex chop
+@code{chop}
+
+@findex asciify
+@code{asciify}
+This request only exists in order to make it possible to make certain
+gross hacks work with GNU troff.  It @dfn{unformats} the diversion
+specified as an argument in
+such a way that ASCII characters that were formatted and diverted
+will be treated like ordinary input characters when the diversion is
+reread.  For example, the following will set register @code{n} to 1.
+
+@example
+.tr  @@.
+.di  x
+@@nr\  n\  1
+.br
+.di
+.tr  @@@@
+.asciify  x
+.x
+@end example
+
+
+@c distribute these through the text
+@xref{Copy-in Mode}
+
+@node Environments, I/O, Diversions, Programming Tutorial
+@section Environments
+@cindex environments
+
+
+Often you will need to print some text in a certain format regardless
+of what may be in effect at the time, for example, in a trap invoked
+macro to print headers and footers.
+To solve this groff has @dfn{environments} in which text is processed.
+An environment contains most of the parameters that control
+text processing.  You can switch amongst these environments, by
+default groff processes text in environment 0.
+The following is the information kept in an environment.
+
+@itemize @bullet{}
+@item
+Type size
+@item
+Font (family and style)
+@item
+Page parameters
+@item
+Fill/adjust mode
+@item
+Tab stops
+@item
+Partially collected lines
+@end itemize
+
+These environments may be given arbitrary names
+(@pxref{Identifiers}, for more info.)
+Old versions of troff only had environments named 0, 1 and 2.
+
+@findex ev
+@vindex .ev
+The @code{ev} request will switch among these environments.
+The single argument is the name of the environment to switch to, with
+no argument groff will switch back to the previous enviroment.
+There is no limit on the number of named environments;
+they will be created the first time that they are referenced.
+The @code{.ev} number register contains
+the name or number of the current environment.  This is a string-valued
+register.
+
+@example
+... page break macro, revised ...
+@end example
+
+@example
+.ev footnote-env
+.fam N
+.ps 6
+.vs 8
+.ll -.5i
+.ev
+...
+.ev footnote-env
+\(dg Note the large, friendly letters.
+.ev
+@end example
+
+
+
+
+@node I/O, Postprocessor Access, Environments, Programming Tutorial
+@section I/O
+@cindex i/o
+
+
+@findex so
+The @code{so} request will read in the file given as an argument and
+include it in place of the @code{so} request.  This is quite useful
+for large documents, i.e. keeping each chapter in a separate file.
+@xref{gsoelim}, for more information.
+
+@findex mso
+The @code{mso} request is
+the same as the @code{so} request except that file is searched for in
+the same way that @file{tmac.@var{name}} is searched for when the
+@samp{-m@var{name}} option is specified.
+
+@findex cf
+@findex trf
+The @code{cf} and @code{trf} requests are to include a file.
+It will transparently output the contents of file filename.  Each
+line is output
+as it would be were it preceded by @code{\!}; however, the lines are not
+subject to copy-mode interpretation.  If the file does not end with a
+newline, then a newline will be added.  For example, you can define a
+macro @code{x} containing the contents of file @file{f}, using
+
+@example
+.di x
+.trf f
+.di
+@end example
+
+.cf filename
+When  used  in  a  diversion, this will embed in the diversion an object
+which,  when  reread,  will  cause  the  contents  of  filename  to   be
+transparently copied through to the output.  In @sc{Unix} troff, the contents
+of filename is immediately copied through to the  output  regardless  of
+whether  there  is  a  current diversion; this behaviour is so anomalous
+that it must be considered a bug.
+
+
+With @code{trf}, unlike @code{cf}, the file cannot contain characters
+such as NUL that are not legal troff input characters.
+
+@findex nx
+The @code{nx} request will force groff to continue processing of the
+file specified as an argument.
+
+@findex rd
+The @code{rd} request will read from standard input, and include what
+is read as though it were part of the input file.  Text is read until
+a blank line is encountered.
+
+@cindex form letters
+@cindex letters, form
+Using these two requests you can set up form letters.
+The form letter template is constructed like this:
+
+@example
+.ce
+\*(td
+.sp 2
+.nf
+.rd
+.sp
+.rd
+.fi
+Body of letter.
+.bp
+.nx repeat.let
+@end example
+
+@findex ex
+When this is run, the following file should be redirected in.
+Note that requests included in this file are executed as though they
+were part of the form letter.  The last block of input is the
+@code{ex} requests which tells groff to stop processing.  If this was
+not there, groff would not know when to stop.
+
+@cindex Beagle Brothers
+@example
+Trent A. Fisher
+708 NW 19th Av., #202
+Portland, OR  97209
+
+Dear Trent,
+
+Len Adollar
+4315 Sierra Vista
+San Diego, CA  92103
+
+Dear Mr. Adollar,
+
+.ex
+@end example
+
+@findex pi
+@code{pi}
+
+@findex sy
+The @code{sy} request will allow arbitrary system commands to be
+executed from within a groff document.  The output is not saved
+anyplace, so it is up to you to do so.
+
+For example, the following example will introduce the current time
+into your document:
+
+@cindex time
+@pindex perl
+@example
+.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
+	     (localtime(time))[2,1,0]' > /tmp/x\n[$$]
+.so /tmp/x\n[$$]
+.sy rm /tmp/x\n[$$]
+\nH:\nM:\nS
+@end example
+
+Note that this works by having the perl script (run by @code{sy})
+print out the @code{nr} requests which will set the number registers
+@samp{H}, @samp{M} and @samp{S}, and then reads those commands in
+with the @code{so} request.
+
+@vindex systat
+The @code{systat} number register contains
+The return value of the @code{system()} function executed by the last
+@code{sy} request.
+
+@findex open
+The @code{open} request will open
+a file (specified as the second argument) for writing and associate
+the stream (specified as the first argument) with it.
+
+@findex opena
+The @code{opena} is
+like open, but if filename exists, append to it instead of truncating
+it.
+
+@findex write
+@findex ds
+@cindex copy-in mode
+@cindex mode, copy-in
+The @code{write} request will write to the file associated with the
+stream specified by the first argument.  The stream must previously
+have been the subject of an open request.  The remainder of the line
+in interpreted as the @code{ds} request reads its second argument: a
+leading @code{"} will be stripped, and it will be read in copy-in mode.
+
+@findex close
+The @code{close} request will
+close the stream specified by the first argument; stream will no
+longer be an acceptable argument to the @code{write} request.
+
+@example
+... example of open write &c...
+@end example
+
+@findex \v
+The @code{\V} escape will
+interpolate the contents of the specified environment variable, as returned
+by getenv(3).
+The argument to @code{\V} is specified as an identifier, i.e.
+@samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}.
+@code{\V} is interpreted in copy-in mode.
+
+
+@node Postprocessor Access, Miscellany, I/O, Programming Tutorial
+@section Postprocessor Access
+@cindex postprocessor access
+@cindex access of postprocessor
+
+
+There are two escapes which will allow you to give information
+directly to the postprocessor.  This is particularly useful for
+embedding PostScript into your final document.
+
+@findex \X
+The @code{\X} escape will embed its argument into the gtroff output
+preceded with @samp{x X}.
+
+@findex \Y
+The @code{\Y} escape is called with an identifier (i.e.
+@code{\Y@var{x}},
+@code{\Y(@var{xx}} or
+@code{\Y[@var{xxx}]}).
+This is approximately equivalent to @samp{\X'\*[@var{xxx}]'}.
+However the contents
+of the string or macro @var{xxx} are not interpreted; also it is
+permitted for
+@var{xxx} to have been defined as a macro and thus contain newlines
+(it is not permitted for the argument to @code{\X} to contain newlines).
+The inclusion of
+newlines requires an extetension to the @sc{Unix} troff output format, and will
+confuse drivers that do not know about this extension.
+
+
+@c distribute these through the text
+@xref{Devices}
+
+@node Miscellany, Debugging, Postprocessor Access, Programming Tutorial
+@section Miscellany
+@cindex miscellany
+
+
+This section contains parts of troff which cannot (yet) be
+categorized elsewhere in this manual.
+
+@findex nm
+Line numbers can be printed in the left margin
+using the @code{nm} request.
+The first argument is the line number of the @emph{next} output line,
+this defaults to 1.
+The second argument indicates on which lines numbers will be printed,
+i.e. 5 means put line numbers on every 5 lines, this defaults to 1.
+The third argument is the space to be left between the number and
+your text, this defaults to 1.
+The fourth argument is the indentation of the line numbers.
+Without arguments, line numbers are turned off.
+
+@findex nn
+The @code{nn} request will temporarily turn off line numbering.
+The first argument is the number of lines not to be numbered,
+this defaults to 1. (does this disable incrementing or display?)
+
+@example
+... line numbering example ...
+@end example
+
+@findex mc
+margin characters can be automatically printed to the right of your
+text with the @code{mc} request.
+The first argument is the character to be printed and the second
+argument is the distance away from your text.
+With no arguments the margin characters are turned off.
+If this occurs before a break, no margin character will be printed.
+
+This is quite useful for indicating text that has changed, and, in
+fact, there are programs available for doing this (they are called
+@code{nrchbar} and @code{changebar} and can be found in any
+@samp{comp.sources.unix} archive.
+
+@example
+... margin char example ...
+@end example
+
+@findex lf
+@pindex soelim
+The @code{lf} primary reason for existence is to make debugging
+documents which are split into many files, which are then put
+together with @code{soelim} and other preprocessors.
+The first argument is the name of the file and the second argument is
+the input line number in that file.
+This way troff can produce error messages which are intelligible to
+the user.
+
+@example
+... example of soelim'ed doc ...
+@end example
+
+@node Debugging, Implementation Differences, Miscellany, Programming Tutorial
+@section Debugging
+@cindex debugging
+
+
+Troff is not easy to debug, but there are some useful features and
+strategies for debugging.
+
+@itemize @bullet{}
+@item
+@findex tm
+The @code{tm} request will send output to stderr, this is very useful for
+printing debugging output.
+@item
+When doing something involved it is useful to leave the debugging
+statements in the code and have them turned on by a command line
+flag.
+
+@example
+.if \n(DB .tm debugging output
+@end example
+
+Then you can activate these statements with:
+
+@example
+groff -rDB=1 file
+@end example
+
+@item
+@findex ab
+The @code{ab} request is similar to the @code{tm} request,
+except that it will cause groff to stop processing.
+With no argument it will print @samp{User Abort}.
+@item
+@findex ex
+The @code{ex} request will also cause groff to stop processing.
+@item
+If you know you are going to get many errors and no useful output,
+you can tell groff to suppress formatted output with the @samp{-z}
+flag.
+@item
+@findex pm
+The @code{pm} request will dump out the entire symbol table.
+@item
+@findex pnr
+The @code{pnr} request will print the names and contents of all
+currently defined number registers on stderr.
+@item
+@findex ptr
+The @code{ptr} request will
+print the names and positions of all traps (not including input line
+traps and diversion traps) on stderr.  Empty slots in the page trap list
+are printed as well, because they can affect the priority of
+subsequently planted traps.
+@item
+@findex fl
+The @code{fl} request instructs groff to flush its output immediately.
+The intention is that this be used when using troff interactively.
+There is little other use for it.
+@item
+@findex backtrace
+The @code{backtrace} request will
+print a backtrace of the input stack on stderr.
+@item
+Groff has command line options for printing out more warnings
+(@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or
+an error occurs.  The most verbose level of warnings is @samp{-ww}.
+@item
+@findex warn
+@vindex .warn
+The @code{warn} request controls the level of warnings checked for.
+The one argument is the sum of the numbers associated with each
+warning that is to be enabled; all other warnings will be disabled.
+The number associated with each warning is listed below.
+For example, @code{.warn 0} will disable all warnings, and
+@code{.warn 1} will disable
+all warnings except that about missing characters.  If an argument
+is not given, all warnings will be enabled.
+The number register @code{.warn} contains the current warning level.
+@end itemize
+
+@subsection Warnings
+@cindex warnings
+
+The warnings that can be given by troff are divided into the
+following categories.  The name associated with each warning is used
+by the @samp{-w} and @samp{-W} options; the number is used by the
+@code{warn} request, and by the @code{.warn} register.
+
+@table @samp
+@item  char
+@itemx 1
+Non-existent characters.  This is enabled by default.
+@item  number
+@itemx 2
+Invalid numeric expressions.  This is enabled by default.
+@item  break
+@itemx 4
+In fill mode, lines which could not be broken so that
+their length was less than the line length.  This is
+enabled by default.
+@item  delim
+@itemx 8
+Missing or mismatched closing delimiters.
+@item  el
+@itemx 16
+Use of the @code{el} request with no matching @code{ie} request.
+@xref{if-else}, for more information.
+@item  scale
+@itemx 32
+Meaningless scaling indicators.
+@item  range
+@itemx 64
+Out of range arguments.
+@item  syntax
+@itemx 128
+Dubious syntax in numeric expressions.
+@item  di
+@itemx 256
+@findex di
+@findex da
+Use of @code{di} or @code{da} without an argument when there is no
+current diversion.
+@item  mac
+@itemx 512
+Use of undefined strings, macros and diversions.
+When an undefined string, macro or diversion is used,
+that string is automatically defined as empty.  So,
+in most cases, at most one warning will be given for
+each name.
+@item  reg
+@itemx 1024
+Use of undefined number registers.  When an undefined
+number register is used, that register is
+automatically defined to have a value of 0.  a
+definition is automatically made with a value of 0.
+So, in most cases, at most one warning will be given
+for use of a particular name.
+@item  tab
+@itemx 2048
+Use of a tab character where a number was expected.
+@item  right-brace
+@itemx 4096
+@findex \@}
+Use of @code{\@}} where a number was expected.
+@item  missing
+@itemx 8192
+Requests that are missing non-optional arguments.
+@item  input
+@itemx 16384
+Illegal input characters.
+@item  escape
+@itemx 32768
+Unrecognized escape sequences.  When an unrecognized
+escape sequence is encountered, the escape character
+is ignored.
+@item  space
+@itemx 65536
+Missing space between a request or macro and its
+argument.  This warning will be given when  an
+undefined name longer than two characters is
+encountered, and the first two characters of the name
+make a defined name.  The request or macro will not
+be invoked. When this warning is given, no macro is
+automatically defined.  This is enabled by default.
+This warning will never occur in compatibility mode.
+@item  font
+@itemx 131072
+Non-existent fonts. This is enabled by default.
+@item all
+All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
+intended that this covers
+all warnings that are useful with traditional macro packages.
+@item w
+All warnings.
+@end table
+
+
+@node Implementation Differences, Summary, Debugging, Programming Tutorial
+@section Implementation Differences
+@cindex implementation differences
+@cindex differences in implementation
+
+
+GNU troff has a number of features which cause incompatibilites with
+documents written with old versions of troff.
+
+Long names cause some incompatibilities.  @sc{Unix} troff will interpret
+
+@example
+.dsabcd
+@end example
+
+@findex \*
+@findex \n
+@findex cp
+@vindex .C
+as defining a string @samp{ab} with contents @samp{cd}.
+Normally, GNU troff will interpret this as a call of a macro named
+@code{dsabcd}.  Also @sc{Unix} troff will interpret @code{\*[} or
+@code{\n[} as references to a string or number register called
+@samp{[}.  In GNU troff, however, this will normally be interpreted as the
+start of a long name.  In compatibility mode GNU troff will interpret
+these things in the traditional way.  In compatibility mode, however,
+long names are not recognised.  Compatibility mode can be turned on with
+the @samp{-C} command line option, and turned on or off with the
+@code{cp} request.
+The number register @code{.C} is 1 if compatibility mode is on, 0 otherwise.
+
+@findex \A
+GNU troff does not allow the use of the escape sequences
+@samp{\| \^ \& \@} \@{ \@key{SP} \' \` \- \_ \! \% \c} in names of
+strings, macros,
+diversions, number registers, fonts or environments; @sc{Unix} troff does.
+The @code{\A} escape sequence may be helpful in avoiding use of these escape
+sequences in names.
+
+@cindex fractional point sizes
+@cindex point sizes, fractional
+@findex ps
+Fractional pointsizes cause one noteworthy incompatibility.  In @sc{Unix}
+troff the @code{ps} request ignores scale indicators and so
+
+@example
+.ps 10u
+@end example
+
+will set the pointsize to 10 points, whereas in GNU troff it will set
+the pointsize to 10 scaled points.
+@xref{Fractional Type Sizes}, for more information.
+
+@findex bd
+@findex cs
+@findex tkf
+@findex tr
+@findex fp
+In GNU troff there is a fundamental difference between unformatted,
+input characters, and formatted, output characters.  Everything that
+affects how an output character will be output is stored with the
+character; once an output character has been constructed it  is
+unaffected by any subsequent requests that are executed, including
+@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp}
+requests.  Normally output characters are constructed
+from input characters at the moment immediately before the character is
+added to the current output line.  Macros, diversions and strings are
+all, in fact, the same type of object; they contain lists of input
+characters and output characters in any combination.  An  output
+character does not behave like an input character for the purposes of
+macro processing; it does not inherit any of the special properties that
+the input character from which it was constructed might have had. For
+example,
+
+@example
+.di x
+\\\\
+.br
+.di
+.x
+@end example
+
+@findex \e
+@findex \!
+@findex \?
+will print @samp{\\} in GNU troff; each pair of input backslashes is
+turned into one
+output backslash and the resulting output backslashes are not
+interpreted as escape
+characters when they are reread. @sc{Unix} troff would interpret them as
+escape characters when they were reread and would end up printing one
+@samp{\}.
+The correct way to obtain a printable backslash is to use the
+@code{\e} escape
+sequence: this will always print a single instance of the current escape
+character, regardless of whether or not it is used in a diversion; it
+will also work in both GNU troff and @sc{Unix} troff. If you wish for some
+reason to store in a diversion an escape sequence that will be
+interpreted when the diversion is reread, you can either use the
+traditional @code{\!} transparent output facility, or, if this is unsuitable,
+the new @code{\?} escape sequence.  @xref{Diversions}, for more information.
+
+
+@node Summary,  , Implementation Differences, Programming Tutorial
+@section Summary
+@cindex summary
+
+
+@node geqn, gtbl, Programming Tutorial, Top
+@chapter @code{geqn}
+@cindex @code{eqn}
+@cindex @code{geqn}
+
+
+@menu
+* Invoking geqn::               
+@end menu
+
+@node Invoking geqn,  , geqn, geqn
+@section Invoking @code{geqn}
+@cindex invoking @code{geqn}
+@cindex @code{geqn}, invoking
+
+
+
+@node gtbl, gpic, geqn, Top
+@chapter @code{gtbl}
+@cindex @code{tbl}
+@cindex @code{gtbl}
+
+
+@menu
+* Invoking gtbl::               
+@end menu
+
+@node Invoking gtbl,  , gtbl, gtbl
+@section Invoking @code{gtbl}
+@cindex invoking @code{gtbl}
+@cindex @code{gtbl}, invoking
+
+
+@node gpic, grap, gtbl, Top
+@chapter @code{gpic}
+@cindex @code{pic}
+@cindex @code{gpic}
+
+
+@menu
+* Invoking gpic::               
+@end menu
+
+@node Invoking gpic,  , gpic, gpic
+@section Invoking @code{gpic}
+@cindex invoking @code{gpic}
+@cindex @code{gpic}, invoking
+
+
+
+@node grap, grefer, gpic, Top
+@chapter @code{grap}
+@cindex @code{grap}
+
+
+
+@node grefer, gsoelim, grap, Top
+@chapter @code{grefer}
+@cindex @code{refer}
+@cindex @code{grefer}
+
+
+@menu
+* Invoking grefer::             
+@end menu
+
+@node Invoking grefer,  , grefer, grefer
+@section Invoking @code{grefer}
+@cindex invoking @code{grefer}
+@cindex @code{grefer}, invoking
+
+
+
+@node gsoelim, Devices, grefer, Top
+@chapter @code{gsoelim}
+@cindex @code{soelim}
+@cindex @code{gsoelim}
+
+
+@menu
+* Invoking gsoelim::            
+@end menu
+
+@node Invoking gsoelim,  , gsoelim, gsoelim
+@section Invoking @code{gsoelim}
+@cindex invoking @code{gsoelim}
+@cindex @code{gsoelim}, invoking
+
+
+
+@node Devices, File formats, gsoelim, Top
+@chapter Devices
+@cindex devices
+
+
+
+@menu
+* Special Characters::          
+* grotty::                      
+* grops::                       
+* grodvi::                      
+* grolj4::                      
+* grohtml::                     
+* gxditview::                   
+@end menu
+
+@node Special Characters, grotty, Devices, Devices
+@section Special Characters
+@cindex special characters
+@cindex characters, special
+
+
+@c distribute these through the text
+@xref{Font Files}
+
+@node grotty, grops, Special Characters, Devices
+@section @code{grotty}
+@cindex @code{grotty}
+
+
+
+@menu
+* Invoking grotty::             
+@end menu
+
+@node Invoking grotty,  , grotty, grotty
+@subsection Invoking @code{grotty}
+@cindex invoking @code{grotty}
+@cindex @code{grotty}, invoking
+
+
+
+@node grops, grodvi, grotty, Devices
+@section @code{grops}
+@cindex @code{grops}
+
+
+
+@menu
+* Invoking grops::              
+* Embedding PostScript::        
+@end menu
+
+@node Invoking grops, Embedding PostScript, grops, grops
+@subsection Invoking @code{grops}
+@cindex invoking @code{grops}
+@cindex @code{grops}, invoking
+
+
+
+@node Embedding PostScript,  , Invoking grops, grops
+@subsection Embedding PostScript
+@cindex embedding postscript
+@cindex postscript, embedding
+
+
+
+@node grodvi, grolj4, grops, Devices
+@section @code{grodvi}
+@cindex @code{grodvi}
+
+
+
+@menu
+* Invoking grodvi::             
+@end menu
+
+@node Invoking grodvi,  , grodvi, grodvi
+@subsection Invoking @code{grodvi}
+@cindex invoking @code{grodvi}
+@cindex @code{grodvi}, invoking
+
+
+
+@node grolj4, grohtml, grodvi, Devices
+@section @code{grolj4}
+@cindex @code{grolj4}
+
+
+
+@menu
+* Invoking grolj4::             
+@end menu
+
+@node Invoking grolj4,  , grolj4, grolj4
+@subsection Invoking @code{grolj4}
+@cindex invoking @code{grolj4}
+@cindex @code{grolj4}, invoking
+
+
+
+@node grohtml, gxditview, grolj4, Devices
+@section @code{grohtml}
+@cindex @code{grohtml}
+
+
+
+@menu
+* Invoking grohtml::            
+@end menu
+
+@node Invoking grohtml,  , grohtml, grohtml
+@subsection Invoking @code{grohtml}
+@cindex invoking @code{grohtml}
+@cindex @code{grohtml}, invoking
+
+
+
+@node gxditview,  , grohtml, Devices
+@section @code{gxditview}
+@cindex @code{gxditview}
+
+
+
+@menu
+* Invoking gxditview::          
+@end menu
+
+@node Invoking gxditview,  , gxditview, gxditview
+@subsection Invoking @code{gxditview}
+@cindex invoking @code{gxditview}
+@cindex @code{gxditview}, invoking
+
+
+
+@node File formats, Installation, Devices, Top
+@chapter File formats
+@cindex file formats
+@cindex formats, file
+
+
+
+@menu
+* gtroff Output::               
+* Font Files::                  
+@end menu
+
+@node gtroff Output, Font Files, File formats, File formats
+@section @code{gtroff} Output
+@cindex @code{gtroff} output
+@cindex output, @code{gtroff}
+
+
+This section describes the format output by GNU troff.  The output
+format used by GNU troff is very similar to that used by @sc{Unix}
+device-independent troff.
+
+The output format is ascii based, as opposed to a binary format (like
+@TeX{} dvi).
+The output format is 8 bit clean, thus single characters can have the
+eighth bit set, as can the names of fonts and special characters.
+
+The output format consists of single command characters with attached
+parameters which are separated from subsequent text by whitespace, or
+a newline.
+
+The names of characters and fonts an be of arbitrary length; drivers
+should not assume that they will be only two characters long (as
+device-independent troff did).
+
+When a character is to be printed, that character will always be in the
+current font.
+Unlike device-independent troff, it is not necessary for
+drivers to search special fonts to find a character.
+
+@table @code
+@item H@var{n}
+@item V@var{n}
+@item h@var{n}
+@item v@var{n}
+@item c@var{n}
+@item C@var{n}
+@item @var{nn}@var{c}
+@item t@var{xxx}
+@var{xxx} is any sequence of characters terminated by a space or a
+newline; the first character should be printed at the current
+position, the the current horizontal position should be increased by
+the width of the first character, and so on for each character.
+The width of the character is that given in the font file,
+appropriately scaled for the current point size,
+and rounded so that it is a multiple of the horizontal resolution.
+Special characters cannot be printed using this command.
+
+This command is only allowed if the @samp{tcommand} line is present
+in the @file{DESC} file.
+@item u@var{n} @var{xxx}
+@pindex DESC
+This is same as the @code{t} command except that after printing each
+character, the current horizontal position is increased by the sum of
+the width of that character and @code{n}.
+
+This command is only allowed if the @samp{tcommand} line is present
+in the @file{DESC} file.
+@item n@var{a}@var{b}
+@item p@var{n}
+@item s@var{n}
+The argument to the s command is in scaled points (units of points/n,
+where n is the argument to the sizescale command  in the DESC file.)
+@item f@var{n}
+@item x @dots{} \n
+Device control.
+@item D@var{c} @var{x}@dots{}\n
+@end table
+
+@subsection Device Control
+
+The @code{x} command is normally followed by a letter or word
+indicating the function to perform, followed by white space separated
+arguments.
+
+The first argument can be abreviated to the first letter.
+
+@table @code
+@item x init
+@item x T
+@item x res @var{n} @var{h} @var{v}
+@item x H
+The argument to the x Height command is also in scaled points.
+@end table
+
+The first three output commands are guaranteed to be:
+
+@example
+x T device
+x res n h v
+x init
+@end example
+
+For example, the input @samp{crunchy \fH\s+2frog\s0\fP!?} will produce:
+
+@example
+... sample output here ...
+@end example
+
+@subsection Drawing Functions
+
+The D drawing command has been extended.  These extensions will only be
+used by GNU pic if the -x option is given.
+
+@table @code
+...
+@item Df n\n
+Set the shade of gray to be used for filling solid objects to n; n must
+be an integer between 0 and 1000, where 0 corresponds solid white and
+1000 to solid black, and values in between correspond to intermediate
+shades of gray.  This applies only to solid circles, solid ellipses and
+solid polygons.  By default, a level of 1000 will be used.  Whatever
+color a solid object has, it should completely obscure everything
+beneath it. A value greater than 1000 or less than 0 can also be used:
+this means fill with the shade of gray that is currently being used for
+lines and text.  Normally this will be black, but some drivers may
+provide a way of changing this.
+@item DC d\n
+Draw a solid circle with a diameter of d with the leftmost point at the
+current position.
+@item DE dx dy\n
+Draw a solid ellipse with a horizontal diameter of dx and a vertical
+diameter of dy with the leftmost point at the current position.
+@item Dp $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub
+n$\n
+Draw a polygon with, for $i = 1 ,..., n+1$, the i-th vertex at the
+current position $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. At
+the moment, GNU pic only uses this command to generate triangles and
+rectangles.
+@item DP $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub
+n$\n
+Like Dp but draw a solid rather than outlined polygon.
+@item Dt n\n
+Set the current line thickness to n machine units.  Traditionally @sc{Unix}
+troff drivers use a line thickness proportional to the current point
+size; drivers should continue to do this if no Dt command has been
+given, or if a Dt command has been given with a negative value of n.  A
+zero value of n selects the smallest available line thickness.
+@end table
+
+A difficulty arises in how the current position should be changed after
+the execution of these commands. This is not of great importance since
+the code generated by GNU pic does not depend on this. Given a drawing
+command of the form
+
+\D'c $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$'
+
+where c is not one of c, e, l, a or ~, @sc{Unix} troff will treat each of the
+$x sub i$ as a horizontal quantity, and each of the $y sub i$ as a
+vertical quantity and will assume that the width of the drawn object is
+$sum from i=1 to n x sub i$, and that the height is $sum from i=1 to n y
+sub i$.  (The assumption about the height can be seen by examining the
+st and sb registers after using such a D command in a \w escape
+sequence.)  This rule also holds for all the original drawing commands
+with the exception of De.  For the sake of compatibility GNU troff also
+follows this rule, even though it produces an ugly result in the case of
+the Df, Dt, and, to a lesser extent, DE commands.  Thus after executing
+a D command of the form
+
+Dc $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\n
+
+the current position should be increased by $( sum from i=1 to n x sub i
+, sum from i=1 to n y sub i )$.
+
+@subsection Line Continuation
+
+There is a continuation convention which permits the argument to the x X
+command to contain newlines: when outputting the argument to the x X
+command,  GNU troff will follow each newline in the argument with a +
+character (as usual, it will terminate the entire argument with a
+newline); thus if the line after the line containing the x X command
+starts with +, then the newline ending the line containing the x X
+command should be treated as part of the argument to the x X command,
+the + should be ignored, and the part of the line following the + should
+be treated like the part of the line following the x X command.
+
+
+
+
+@node Font Files,  , gtroff Output, File formats
+@section Font Files
+@cindex font files
+@cindex files, font
+
+
+The groff font format is roughly a superset of the ditroff font
+format.  Unlike the ditroff font format, there is no associated binary
+format.  The font files for device name are stored in a directory
+@file{dev@var{name}}.  There are two types of file: a device
+description file called @file{DESC} and for each font @samp{F} a font
+file called @file{F}.  These are text files; there is no associated
+binary format.
+
+@subsection @file{DESC} file format
+@pindex DESC
+
+The @file{DESC} file can contain the following types of line:
+
+@table @code
+@item res @var{n}
+There are @var{n} machine units per inch.
+@item hor @var{n}
+The horizontal resolution is @var{n} machine units.
+@item vert @var{n}
+The vertical resolution is @var{n} machine units.
+@item sizescale @var{n}
+The scale factor for pointsizes.  By default this has a value of 1.  One
+scaled point is equal to one point/@var{n}.  The arguments to the
+@code{unitwidth} and @code{sizes} commands are given in scaled points.
+@xref{Fractional Type Sizes}, for more information.
+@item unitwidth @var{n}
+Quantities in the font files are given in machine units for fonts  whose
+point size is @var{n} scaled points.
+@item tcommand
+This means that the postprocessor can handle the @code{t} and
+@code{u} output commands.
+@item sizes @var{s1} @var{s2}@dots{}@var{sn} 0
+This means that the device has fonts at @var{s1}, @var{s2},
+@dots{}@var{sn} scaled points.  The list of sizes must be terminated
+by a 0.  Each @var{si} can also be a range of
+sizes @var{m}-@var{n}.  The list can extend over more than one line.
+@item styles @var{S1 S2@dots{}Sm}
+The first @var{m} font positions will be associated with styles
+@var{S1}@dots{}@var{Sm}.
+@item fonts @var{n} @var{F1 F2 F3@dots{}Fn}
+Fonts @var{F1@dots{}Fn} will be mounted in the font positions
+@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m}
+is the number of styles.  This command may extend over more than one
+line. A font name of 0 will cause no font to be mounted on the
+corresponding font position.
+@item family @var{fam}
+The default font family is @var{fam}.
+@item charset
+This line and everything following in the file are ignored.  It is
+allowed for the sake of backwards compatibility.
+@end table
+
+The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
+are compulsory.  Other commands are ignored by troff but may be used
+by postprocessors to store arbitrary information about the device in
+the @file{DESC} file.
+
+
+@subsection Font file format
+
+A font file has two sections.  The first section is a sequence of lines
+each containing a sequence of blank delimited words; the first word in
+the line is a key, and subsequent words give a value for that key.
+
+@table @code
+@item name @var{F}
+The name of the font is @var{F}.
+@item spacewidth @var{n}
+The normal width of a space is @var{n}.
+@item slant @var{n}
+The characters of the font have a slant of @var{n} degrees.
+(Positive means forward.)
+@item ligatures @var{lig1} @var{lig2}@dots{}@var{lign} [0]
+Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
+possible ligatures are ff, fi, fl and ffl.  For backwards
+compatibiliy, the list of ligatures may be terminated with a 0.  The
+list of ligatures may not extend over more than one line.
+@item special
+The font is special; this means that when a character is requested that
+is not present in the current font, it will be searched for in any
+special fonts that are mounted.
+@end table
+
+Other commands are ignored by troff but may be used by postprocessors to
+store arbitrary information about the font in the font file.
+
+The first section can contain comments which start with the # character
+and extend to the end of a line.
+
+The second section contains one or two subsections.  It must contain a
+@code{charset} subsection and it may also contain a @code{kernpairs}
+subsection.  These subsections can appear in any order.  Each
+subsection starts with a word on a line by itself.
+
+The word @code{charset} starts the @code{charset} subsection. The
+@code{charset} line is followed by a sequence of lines. Each line
+gives information for one character.  A line comprises a number of
+fields separated by blanks or tabs. The format is
+
+@display
+@var{name} @var{metrics} @var{type} @var{code} @var{comment}
+@end display
+
+@var{name} identifies the character: if @var{name} is a single
+character @var{c} then it corresponds to the groff input character
+@var{c}; if it is of the form @samp{\@var{c}} where @var{c} is a
+single character, then it corresponds to the groff input character
+@samp{\@var{c}}; otherwise it corresponds to the groff input character
+@samp{\[@var{name}]} (if it is exactly two characters @var{xx} it can
+be entered as @samp{\(@var{xx}}.) Groff supports eight bit characters;
+however some utilities has difficulties with eight bit characters.
+For this reason, there is a convention that the @var{name}
+@samp{char@var{n}} is equivalent to the single character whose code is
+@var{n}. For example, @samp{char163} would be equivalent to the
+character with @var{code} 163 which is the pounds sterling sign in ISO
+Latin-1 character set.  The name @samp{---} is special and indicates
+that the character is unnamed; such characters can only be used by
+means of the @code{\N} escape sequence in troff.
+
+The @var{type} field gives the character type:
+
+@table @code
+@item 1
+means the character has an descender, for example, p;
+@item 2
+means the character has an ascender, for example, b;
+@item 3
+means the character has both an ascender and a descender, for example,
+@samp{(}.
+@end table
+
+The @var{code} field gives the code which the postprocessor uses to
+print the character.  The character can also be input to groff using
+this code by means of the @code{\N} escape sequence. The code can be any
+integer.  If it starts with a 0 it will be interpreted as octal; if it
+starts with 0x or 0X it will be intepreted as hexdecimal.
+
+Anything on the line after the @var{code} field will be ignored.
+
+The @var{metrics} field has the form:
+
+@smallexample
+@var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]}
+@end smallexample
+
+There must not be any spaces between these subfields.  Missing
+subfields are assumed to be 0.  The subfields are all decimal
+integers.  Since there is no associated binary format, these values
+are not required to fit into a variable of type @samp{char} as they
+are in ditroff.  The @var{width} subfields gives the width of the
+character.  The @var{height} subfield gives the height of the
+character (upwards is positive); if a character does not extend above
+the baseline, it should be given a zero height, rather than a negative
+height.  The @var{depth} subfield gives the depth of the character,
+that is, the distance below the lowest point below the baseline to
+which the character extends (downwards is positive); if a character
+does not extend below above the baseline, it should be given a zero
+depth, rather than a negative depth.  The @var{italic_correction}
+subfield gives the amount of space that should be added after the
+character when it is immediately to be followed by a character from a
+roman font.  The @var{left_italic_correction} subfield gives the
+amount of space that should be added before the character when it is
+immediately to be preceded by a character from a roman font.  The
+@var{subscript_correction} gives the amount of space that should be
+added after a character before adding a subscript. This should be less
+than the italic correction.
+
+A line in the @code{charset} section can also have the format
+
+@example
+@var{name} "
+@end example
+
+This indicates that @var{name} is just another name for the character
+mentioned in the preceding line.
+
+The word @code{kernpairs} starts the kernpairs section.  This contains a
+sequence of lines of the form:
+
+@display
+@var{c1 c2 n}
+@end display
+
+This means that when character @var{c1} appears next to character
+@var{c2} the space between them should be increased by @var{n}.  Most
+entries in kernpairs section will have a negative value for @var{n}.
+
+
+
+@node Installation, Request Index, File formats, Top
+@chapter Installation
+@cindex installation
+
+
+
+@node Request Index, Register Index, Installation, Top
+@chapter Request Index
+
+@printindex fn
+
+
+@node Register Index, String Index, Request Index, Top
+@chapter Register Index
+
+@printindex vr
+
+
+@node String Index, Macro Index, Register Index, Top
+@chapter String Index
+
+
+
+@node Macro Index, Program Index, String Index, Top
+@chapter Macro Index
+
+
+
+@node Program Index, Concept Index, Macro Index, Top
+@chapter Program Index
+
+@printindex pg
+
+
+
+@node Concept Index,  , Program Index, Top
+@chapter Concept Index
+
+@printindex cp
+
+
+
+@summarycontents
+@contents
+@bye
diff --git a/contrib/groff/doc/meref.me b/contrib/groff/doc/meref.me
index 9cc2c76..5a62ae1 100644
--- a/contrib/groff/doc/meref.me
+++ b/contrib/groff/doc/meref.me
@@ -1825,8 +1825,10 @@ or
 (the same,
 but as an ordinal number;
 for example, \*(mo is \n(mo),
+.NR (y4
+(the current year),
 and
-.NR (yr
+.NR (y2
 (the last two digits of the current year).
 .TL
 .ST (lq
@@ -2184,7 +2186,9 @@ NAME	TYPE	DESCRIPTION
 \&.xp	M	print index
 \en(xs	R	index entry prespace
 \en(xu	R	index undent (from right margin)
-\en(yr	R\(sc	year (last two digits only)
+\en(y2	R	year (last two digits only)
+\en(y4	R	year (all digits)
+\en(yr	R\(sc	year minus 1900
 \en(zs	R	floating keep pre/post space
 \e{	F\(sc	begin conditional group
 \e|	F\(sc	1/6 em narrow space
diff --git a/contrib/groff/doc/pic.ms b/contrib/groff/doc/pic.ms
index 59dcc08..948617c 100644
--- a/contrib/groff/doc/pic.ms
+++ b/contrib/groff/doc/pic.ms
@@ -10,7 +10,7 @@
 .\" This document was written for free use and redistribution by
 .\" Eric S. Raymond <esr@thyrsus.com> in August 1995.
 .\"
-.\"	$Id: pic.ms,v 1.27 1997/07/03 17:35:39 esr Exp $	
+.\"	$Id: pic.ms,v 1.2 1999/12/04 08:57:07 wlemb Exp $	
 .\"
 .\" Set a proper TeX
 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
@@ -299,7 +299,8 @@ possible to set a global style variable \fBscale\fP that changes the
 unit.  Setting \fBscale = 2.54\fP will effectively change the internal
 unit to centimeters (all other size variable valuess will be scaled
 correspondingly).
-.NH 2 Default Sizes of Objects
+.NH 2
+Default Sizes of Objects
 .PP
 Here are the default sizes for \fBpic\fP objects:
 .RS