5763 lines
181 KiB
Plaintext
5763 lines
181 KiB
Plaintext
\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
|