1 \input texinfo @c -*-texinfo-*-
4 @c If you use texinfo.tex 1999-09-25.10 or earlier please convert this
5 @c manual with `texi2dvi -e groff.texinfo' due to a bug in expanding
6 @c user-defined macros.
9 @c %**start of header (This is for running Texinfo on a region.)
11 @settitle The GNU Troff Manual
12 @setchapternewpage odd
13 @footnotestyle separate
14 @c %**end of header (This is for running Texinfo on a region.)
17 @c We use the following indices:
20 @c findex: requests, escapes, and functions
22 @c kindex: commands in font files
23 @c pindex: programs and files
24 @c tindex: environment variables
25 @c maindex: macros and strings
26 @c glindex: glyph names
29 @c tindex and cindex are merged.
37 @macro Deffn{category, name, arg}
38 @deffn \category\ @t{\name\} \arg\
45 @macro Deffnx{category, name, arg}
46 @deffnx \category\ @t{\name\} \arg\
53 @macro Defmac{name, arg}
54 @defmac @t{\name\} \arg\
61 @macro Defmacx{name, arg}
62 @defmacx @t{\name\} \arg\
70 @c XXX comment all examples
73 @dircategory Miscellaneous
75 * Groff: (groff). The GNU troff document formatting system.
88 This Info file documents GNU troff version 1.16.
90 Published by the Free Software Foundation
91 59 Temple Place, Suite 330
92 Boston, MA 02111-1307 USA
94 Copyright (C) 1994-2000 Free Software Foundation, Inc.
96 Permission is granted to make and distribute verbatim copies of this
97 manual provided the copyright notice and this permission notice are
98 preserved on all copies.
101 Permission is granted to process this file through TeX and print the
102 results, provided the printed document carries copying permission notice
103 identical to this one except for the removal of this paragraph (this
104 paragraph not being relevant to the printed manual).
107 Permission is granted to copy and distribute modified versions of this
108 manual under the conditions for verbatim copying, provided that the
109 entire resulting derived work is distributed under the terms of a
110 permission notice identical to this one.
112 Permission is granted to copy and distribute translations of this manual
113 into another language, under the above conditions for modified versions,
114 except that this permission notice may be stated in a translation
115 approved by the Foundation.
117 Permission is granted to copy and distribute modified versions of this
118 manual under the conditions for verbatim copying, provided also that the
119 section entitled ``GNU General Public License'' is included exactly as
120 in the original, and provided that the entire resulting derived work is
121 distributed under the terms of a permission notice identical to this
124 Permission is granted to copy and distribute translations of this manual
125 into another language, under the above conditions for modified versions,
126 except that the section entitled ``GNU General Public License'' may be
127 included in a translation approved by the Free Software Foundation
128 instead of in the original English.
134 @subtitle The GNU implementation of @code{troff}
135 @subtitle Edition 1.16
136 @subtitle Spring 2000
137 @author by Trent A.@w{ }Fisher
138 @author and Werner Lemberg
140 @c Include the Distribution inside the titlepage environment so
141 @c that headings are turned off. Headings on and off do not work.
144 @vskip 0pt plus 1filll
145 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
147 Version 1.16 of @code{groff}, @*
150 Published by the Free Software Foundation @*
151 59 Temple Place, Suite 330 @*
152 Boston, MA 02111-1307 USA
155 Permission is granted to make and distribute verbatim copies of this
156 manual provided the copyright notice and this permission notice are
157 preserved on all copies.
159 Permission is granted to copy and distribute modified versions of this
160 manual under the conditions for verbatim copying, provided also that the
161 section entitled ``GNU General Public License'' is included exactly as
162 in the original, and provided that the entire resulting derived work is
163 distributed under the terms of a permission notice identical to this
166 Permission is granted to copy and distribute translations of this manual
167 into another language, under the above conditions for modified versions,
168 except that the section entitled ``GNU General Public License'' may be
169 included in a translation approved by the Free Software Foundation
170 instead of in the original English.
172 Cover art by Etienne Suvasa.
178 @node Top, Copying, (dir), (dir)
181 This Info file documents groff version 1.16, the GNU implementation of
182 the troff typesetting system.
184 This is an in-progress document; contributions, comments, or
185 contributions are welcome. Send them to bug-groff@@gnu.org.
192 * Tutorial for Macro Users::
194 * Programming Tutorial::
199 * Request and Escape Index::
202 * Macro and String Index::
204 * Font File Keyword Index::
205 * Program and File Index::
211 @node Copying, Introduction, Top, Top
213 @unnumbered GNU GENERAL PUBLIC LICENSE
214 @center Version 2, June 1991
217 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
218 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
220 Everyone is permitted to copy and distribute verbatim copies of this
221 license document, but changing it is not allowed.
224 @unnumberedsec Preamble
226 The licenses for most software are designed to take away your freedom to
227 share and change it. By contrast, the GNU General Public License is
228 intended to guarantee your freedom to share and change free software --
229 to make sure the software is free for all its users. This General
230 Public License applies to most of the Free Software Foundation's
231 software and to any other program whose authors commit to using it.
232 (Some other Free Software Foundation software is covered by the GNU
233 Library General Public License instead.) You can apply it to your
236 When we speak of free software, we are referring to freedom, not price.
237 Our General Public Licenses are designed to make sure that you have the
238 freedom to distribute copies of free software (and charge for this
239 service if you wish), that you receive source code or can get it if you
240 want it, that you can change the software or use pieces of it in new
241 free programs; and that you know you can do these things.
243 To protect your rights, we need to make restrictions that forbid anyone
244 to deny you these rights or to ask you to surrender the rights. These
245 restrictions translate to certain responsibilities for you if you
246 distribute copies of the software, or if you modify it.
248 For example, if you distribute copies of such a program, whether gratis
249 or for a fee, you must give the recipients all the rights that you have.
250 You must make sure that they, too, receive or can get the source code.
251 And you must show them these terms so they know their rights.
253 We protect your rights with two steps: (1)@w{ }copyright the software,
254 and (2)@w{ }offer you this license which gives you legal permission to
255 copy, distribute and/or modify the software.
257 Also, for each author's protection and ours, we want to make certain
258 that everyone understands that there is no warranty for this free
259 software. If the software is modified by someone else and passed on, we
260 want its recipients to know that what they have is not the original, so
261 that any problems introduced by others will not reflect on the original
262 authors' reputations.
264 Finally, any free program is threatened constantly by software patents.
265 We wish to avoid the danger that redistributors of a free program will
266 individually obtain patent licenses, in effect making the program
267 proprietary. To prevent this, we have made it clear that any patent
268 must be licensed for everyone's free use or not licensed at all.
270 The precise terms and conditions for copying, distribution and
274 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
277 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
282 This License applies to any program or other work which contains a
283 notice placed by the copyright holder saying it may be distributed under
284 the terms of this General Public License. The ``Program'', below,
285 refers to any such program or work, and a ``work based on the Program''
286 means either the Program or any derivative work under copyright law:
287 that is to say, a work containing the Program or a portion of it, either
288 verbatim or with modifications and/or translated into another language.
289 (Hereinafter, translation is included without limitation in the term
290 ``modification''.) Each licensee is addressed as ``you''.
292 Activities other than copying, distribution and modification are not
293 covered by this License; they are outside its scope. The act of running
294 the Program is not restricted, and the output from the Program is
295 covered only if its contents constitute a work based on the Program
296 (independent of having been made by running the Program). Whether that
297 is true depends on what the Program does.
300 You may copy and distribute verbatim copies of the Program's source code
301 as you receive it, in any medium, provided that you conspicuously and
302 appropriately publish on each copy an appropriate copyright notice and
303 disclaimer of warranty; keep intact all the notices that refer to this
304 License and to the absence of any warranty; and give any other
305 recipients of the Program a copy of this License along with the Program.
307 You may charge a fee for the physical act of transferring a copy, and
308 you may at your option offer warranty protection in exchange for a fee.
311 You may modify your copy or copies of the Program or any portion of it,
312 thus forming a work based on the Program, and copy and distribute such
313 modifications or work under the terms of Section@w{ }1 above, provided
314 that you also meet all of these conditions:
318 You must cause the modified files to carry prominent notices stating
319 that you changed the files and the date of any change.
322 You must cause any work that you distribute or publish, that in whole or
323 in part contains or is derived from the Program or any part thereof, to
324 be licensed as a whole at no charge to all third parties under the terms
328 If the modified program normally reads commands interactively when run,
329 you must cause it, when started running for such interactive use in the
330 most ordinary way, to print or display an announcement including an
331 appropriate copyright notice and a notice that there is no warranty (or
332 else, saying that you provide a warranty) and that users may
333 redistribute the program under these conditions, and telling the user
334 how to view a copy of this License. (Exception: if the Program itself
335 is interactive but does not normally print such an announcement, your
336 work based on the Program is not required to print an announcement.)
339 These requirements apply to the modified work as a whole. If
340 identifiable sections of that work are not derived from the Program, and
341 can be reasonably considered independent and separate works in
342 themselves, then this License, and its terms, do not apply to those
343 sections when you distribute them as separate works. But when you
344 distribute the same sections as part of a whole which is a work based on
345 the Program, the distribution of the whole must be on the terms of this
346 License, whose permissions for other licensees extend to the entire
347 whole, and thus to each and every part regardless of who wrote it.
349 Thus, it is not the intent of this section to claim rights or contest
350 your rights to work written entirely by you; rather, the intent is to
351 exercise the right to control the distribution of derivative or
352 collective works based on the Program.
354 In addition, mere aggregation of another work not based on the Program
355 with the Program (or with a work based on the Program) on a volume of a
356 storage or distribution medium does not bring the other work under the
357 scope of this License.
360 You may copy and distribute the Program (or a work based on it, under
361 Section@w{ }2) in object code or executable form under the terms of
362 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
367 Accompany it with the complete corresponding machine-readable source
368 code, which must be distributed under the terms of Sections@w{ }1 and@w{
369 }2 above on a medium customarily used for software interchange; or,
372 Accompany it with a written offer, valid for at least three years, to
373 give any third party, for a charge no more than your cost of physically
374 performing source distribution, a complete machine-readable copy of the
375 corresponding source code, to be distributed under the terms of
376 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
380 Accompany it with the information you received as to the offer to
381 distribute corresponding source code. (This alternative is allowed only
382 for noncommercial distribution and only if you received the program in
383 object code or executable form with such an offer, in accord with
384 Subsection@w{ }b above.)
387 The source code for a work means the preferred form of the work for
388 making modifications to it. For an executable work, complete source
389 code means all the source code for all modules it contains, plus any
390 associated interface definition files, plus the scripts used to control
391 compilation and installation of the executable. However, as a special
392 exception, the source code distributed need not include anything that is
393 normally distributed (in either source or binary form) with the major
394 components (compiler, kernel, and so on) of the operating system on
395 which the executable runs, unless that component itself accompanies the
398 If distribution of executable or object code is made by offering access
399 to copy from a designated place, then offering equivalent access to copy
400 the source code from the same place counts as distribution of the source
401 code, even though third parties are not compelled to copy the source
402 along with the object code.
405 You may not copy, modify, sublicense, or distribute the Program except
406 as expressly provided under this License. Any attempt otherwise to
407 copy, modify, sublicense or distribute the Program is void, and will
408 automatically terminate your rights under this License. However,
409 parties who have received copies, or rights, from you under this License
410 will not have their licenses terminated so long as such parties remain
414 You are not required to accept this License, since you have not signed
415 it. However, nothing else grants you permission to modify or distribute
416 the Program or its derivative works. These actions are prohibited by
417 law if you do not accept this License. Therefore, by modifying or
418 distributing the Program (or any work based on the Program), you
419 indicate your acceptance of this License to do so, and all its terms and
420 conditions for copying, distributing or modifying the Program or works
424 Each time you redistribute the Program (or any work based on the
425 Program), the recipient automatically receives a license from the
426 original licensor to copy, distribute or modify the Program subject to
427 these terms and conditions. You may not impose any further restrictions
428 on the recipients' exercise of the rights granted herein. You are not
429 responsible for enforcing compliance by third parties to this License.
432 If, as a consequence of a court judgment or allegation of patent
433 infringement or for any other reason (not limited to patent issues),
434 conditions are imposed on you (whether by court order, agreement or
435 otherwise) that contradict the conditions of this License, they do not
436 excuse you from the conditions of this License. If you cannot
437 distribute so as to satisfy simultaneously your obligations under this
438 License and any other pertinent obligations, then as a consequence you
439 may not distribute the Program at all. For example, if a patent license
440 would not permit royalty-free redistribution of the Program by all those
441 who receive copies directly or indirectly through you, then the only way
442 you could satisfy both it and this License would be to refrain entirely
443 from distribution of the Program.
445 If any portion of this section is held invalid or unenforceable under
446 any particular circumstance, the balance of the section is intended to
447 apply and the section as a whole is intended to apply in other
450 It is not the purpose of this section to induce you to infringe any
451 patents or other property right claims or to contest validity of any
452 such claims; this section has the sole purpose of protecting the
453 integrity of the free software distribution system, which is implemented
454 by public license practices. Many people have made generous
455 contributions to the wide range of software distributed through that
456 system in reliance on consistent application of that system; it is up to
457 the author/donor to decide if he or she is willing to distribute
458 software through any other system and a licensee cannot impose that
461 This section is intended to make thoroughly clear what is believed to be
462 a consequence of the rest of this License.
465 If the distribution and/or use of the Program is restricted in certain
466 countries either by patents or by copyrighted interfaces, the original
467 copyright holder who places the Program under this License may add an
468 explicit geographical distribution limitation excluding those countries,
469 so that distribution is permitted only in or among countries not thus
470 excluded. In such case, this License incorporates the limitation as if
471 written in the body of this License.
474 The Free Software Foundation may publish revised and/or new versions of
475 the General Public License from time to time. Such new versions will be
476 similar in spirit to the present version, but may differ in detail to
477 address new problems or concerns.
479 Each version is given a distinguishing version number. If the Program
480 specifies a version number of this License which applies to it and ``any
481 later version'', you have the option of following the terms and
482 conditions either of that version or of any later version published by
483 the Free Software Foundation. If the Program does not specify a version
484 number of this License, you may choose any version ever published by the
485 Free Software Foundation.
488 If you wish to incorporate parts of the Program into other free programs
489 whose distribution conditions are different, write to the author to ask
490 for permission. For software which is copyrighted by the Free Software
491 Foundation, write to the Free Software Foundation; we sometimes make
492 exceptions for this. Our decision will be guided by the two goals of
493 preserving the free status of all derivatives of our free software and
494 of promoting the sharing and reuse of software generally.
504 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
505 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
506 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
507 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
508 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
509 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
510 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
511 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
512 NECESSARY SERVICING, REPAIR OR CORRECTION.
515 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
516 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
517 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
518 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
519 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
520 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
521 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
522 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
523 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
527 @heading END OF TERMS AND CONDITIONS
530 @center END OF TERMS AND CONDITIONS
535 @unnumberedsec How to Apply These Terms to Your New Programs
537 If you develop a new program, and you want it to be of the greatest
538 possible use to the public, the best way to achieve this is to make it
539 free software which everyone can redistribute and change under these
542 To do so, attach the following notices to the program. It is safest to
543 attach them to the start of each source file to most effectively convey
544 the exclusion of warranty; and each file should have at least the
545 ``copyright'' line and a pointer to where the full notice is found.
548 @var{one line to give the program's name and an idea of what it does.}
549 Copyright (C) 19@var{yy} @var{name of author}
551 This program is free software; you can redistribute it and/or modify
552 it under the terms of the GNU General Public License as published by
553 the Free Software Foundation; either version 2 of the License, or (at
554 your option) any later version.
556 This program is distributed in the hope that it will be useful, but
557 WITHOUT ANY WARRANTY; without even the implied warranty of
558 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
559 General Public License for more details.
561 You should have received a copy of the GNU General Public License
562 along with this program; if not, write to the Free Software
563 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
566 Also add information on how to contact you by electronic and paper mail.
568 If the program is interactive, make it output a short notice like this
569 when it starts in an interactive mode:
572 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
573 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
574 `show w'. This is free software, and you are welcome to redistribute
575 it under certain conditions; type `show c' for details.
578 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
579 show the appropriate parts of the General Public License. Of course,
580 the commands you use may be called something other than @samp{show@w{
581 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items
582 -- whatever suits your program.
584 You should also get your employer (if you work as a programmer) or your
585 school, if any, to sign a ``copyright disclaimer'' for the program, if
586 necessary. Here is a sample; alter the names:
590 Yoyodyne, Inc., hereby disclaims all copyright interest
591 in the program `Gnomovision' (which makes passes at compilers)
592 written by James Hacker.
594 @var{signature of Ty Coon}, 1 April 1989
595 Ty Coon, President of Vice
599 This General Public License does not permit incorporating your program
600 into proprietary programs. If your program is a subroutine library, you
601 may consider it more useful to permit linking proprietary applications
602 with the library. If this is what you want to do, use the GNU Library
603 General Public License instead of this License.
607 @c =====================================================================
608 @c =====================================================================
610 @node Introduction, Invoking groff, Copying, Top
611 @chapter Introduction
614 GNU @code{troff} (or @code{groff}) is a system for typesetting
615 documents. @code{troff} is very flexible and has been in existence (and
616 use) for about 3@w{ }decades. It is quite widespread and firmly
617 entrenched in the @acronym{UNIX} community.
622 * groff Capabilities::
623 * Macro Package Intro::
624 * Preprocessor Intro::
625 * Output device intro::
630 @c =====================================================================
632 @node What Is groff?, History, Introduction, Introduction
633 @section What Is @code{groff}?
634 @cindex what is @code{groff}?
635 @cindex @code{groff} -- what is it?
637 @code{groff} is of an older generation of document preparation systems,
638 which operate more like compilers than the more recent interactive
639 @acronym{WYSIWYG}@footnote{What You See Is What You Get} systems.
640 @code{groff} and its contemporary counterpart, @TeX{}, both work using a
641 @dfn{batch} paradigm: The input (or @dfn{source}) files are normal text
642 files with embedded formatting commands. These files can then be
643 processed by @code{groff} to produce a typeset document on a variety of
646 Likewise, @code{groff} should not be confused with a @dfn{word
647 processor}, since that term connotes an integrated system which includes
648 an editor and a text formatter. Also, many word processors follow the
649 @acronym{WYSIWYG} paradigm which was discussed earlier.
651 Although @acronym{WYSIWYG} systems may be easier to use, they have a
652 number of disadvantages compared to @code{troff}:
656 They must be used on a graphics display to do any operations on a
660 Most of the @acronym{WYSIWYG} systems are either non-free or are not
664 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
667 It is difficult to have a wide range of capabilities available within
668 the confines of a GUI/window system.
671 It is more difficult to make global changes to a document.
675 ``GUIs normally make it simple to accomplish simple actions and
676 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
677 @code{comp.unix.wizards})
681 @c =====================================================================
683 @node History, groff Capabilities, What Is groff?, Introduction
687 @cindex @code{runoff}
689 @code{troff} can trace its origins back to a formatting program called
690 @code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS
691 system. This name came from the common phrase of the time ``I'll run
692 off a document.'' Bob Morris ported it to the 635 architecture and
693 called the program @code{roff} (an abbreviation of @code{runoff}). It
694 has then been rewritten as @code{rf} for the PDP-7 (before having
695 @acronym{UNIX}), and at the same time (1969), Doug McIllroy rewrote an
696 extended and simplified version of @code{roff} in the @acronym{BCPL}
697 programming language.
700 The first version of @acronym{UNIX} was developed on a PDP-7 which was
701 sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11
702 for further work on the operating system. In order to justify the cost
703 for this system, they proposed that they would implement a document
704 formatting system for the AT&T patents division. This first formatting
705 program was a reimplementation of McIllroy's @code{roff}, written by
706 J.@w{ }F.@w{ }Ossanna.
709 When they needed a more flexible language, a new version of @code{roff}
710 called @code{nroff} (Newer @code{roff}) was written. It had a much more
711 complicated syntax, but provided the basis for all future versions.
712 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
713 version of @code{nroff} which would drive it. It was dubbed
714 @code{troff} for typesetter @code{roff}, although many people have
715 speculated that it actually means Times @code{roff} because of the use
716 of the Times font family in @code{troff} by default. As such, the name
717 @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
719 With @code{troff} came @code{nroff} (they were actually the same program
720 except for some @samp{#ifdefs}), which was for producing output for line
721 printers and character terminals. It understood everything @code{troff}
722 did, and ignored the commands which were not applicable (e.g.@: font
725 Since there are several things which cannot be done easily in
726 @code{troff}, work on several preprocessors began. These programs would
727 transform certain parts of a document into @code{troff}, which made a
728 very natural use of pipes in @acronym{UNIX}.
730 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
731 specified in a much simpler and more intuitive manner. @code{tbl} is a
732 preprocessor for formatting tables. The @code{refer} preprocessor (and
733 the similar program, @code{bib}) processes citations in a document
734 according to a bibliographic database.
736 Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
737 language and produced output specifically for the CAT phototypesetter.
738 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
739 code and still dependent on the CAT. As the CAT became less common, and
740 was no longer supported by the manufacturer, the need to make it support
741 other devices became a priority. However, before this could be done, he
742 was killed in an auto accident.
745 @cindex @code{ditroff}
746 So, Brian Kernighan took on the task of rewriting @code{troff}. The
747 newly rewritten version produced a device independent code which was
748 very easy for postprocessors to read and translate to the appropriate
749 printer codes. Also, this new version of @code{troff} (called
750 @code{ditroff} for `device independent @code{troff}') had several
751 extensions, which included drawing functions.
753 Due to the additional abilities of the new version of @code{troff},
754 several new preprocessors appeared. The @code{pic} preprocessor
755 provides a wide range of drawing functions. Likewise the @code{ideal}
756 preprocessor did the same, although via a much different paradigm. The
757 @code{grap} preprocessor took specifications for graphs, but, unlike
758 other preprocessors, produced @code{pic} code.
760 James Clark began work on a GNU implementation of @code{ditroff} in
761 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
762 June@w{ }1990. @code{groff} included
766 A replacement for @code{ditroff} with many extensions.
769 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
772 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
773 X@w{ }windows. GNU @code{troff} also eliminated the need for a separate
774 @code{nroff} program with a postprocessor which would produce
775 @acronym{ASCII} output.
778 A version of the @file{me} macros and an implementation of the
782 Also, a front-end was included which could construct the, sometimes
783 painfully long, pipelines required for all the post- and preprocessors.
785 Development of GNU @code{troff} progressed rapidly, and saw the
786 additions of a replacement for @code{refer}, an implementation of the
787 @file{ms} and @file{mm} macros, and a program to deduce how to format a
788 document (@code{grog}).
790 It was declared a stable (i.e.@: non-beta) package with the release of
791 version@w{ }1.04 around November@w{ }1991.
793 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
794 an orphan for a few years). As a result, new features and programs like
795 @code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an
796 output device to produce @acronym{HTML} output, have been added.
799 @c =====================================================================
801 @node groff Capabilities, Macro Package Intro, History, Introduction
802 @section @code{groff} Capabilities
803 @cindex @code{groff} capabilities
804 @cindex capabilities of @code{groff}
806 So what exactly is @code{groff} capable of doing? @code{groff} provides
807 a wide range of low-level text formatting operations. Using these, it
808 is possible to perform a wide range of formatting tasks, such as
809 footnotes, table of contents, multiple columns, etc.
813 Text filling, adjusting, and centering
822 Font and character size control
825 Vertical spacing (i.e.@: double spacing)
828 Line length and indenting
831 Macros, strings, diversions, and traps
837 Tabs, leaders, and fields
840 Input and output conventions and character translation
843 Overstrike, bracket, line drawing, and zero-width functions
846 Local horizontal and vertical motions and the width function
852 Output line numbering
855 Conditional acceptance of input
858 Environment switching
861 Insertions from the standard input
864 Input/output file switching
867 Output and error messages
871 @c =====================================================================
873 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
874 @section Macro Packages
875 @cindex macro packages
877 Since @code{groff} provides such low level facilities, it can be quite
878 difficult to use by itself. However, @code{groff} provides a
879 @dfn{macro} facility to specify how certain routine operations (e.g.@w{
880 }starting paragraphs, printing headers and footers, etc.)@: should be
881 done. These macros can be collected together into a @dfn{macro
882 package}. There are a number of macro packages available; the most
883 common (and the ones described in this manual) are @file{man},
884 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
887 @c =====================================================================
889 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
890 @section Preprocessors
891 @cindex preprocessors
893 Although @code{groff} provides most functions needed to format a
894 document, some operations would be unwieldy (e.g.@: to draw pictures).
895 Therefore, programs called preprocessors were written which understand
896 their own language and produce the necessary @code{groff} operations.
897 These preprocessors are able to differentiate their own input from the
898 rest of the document via markers.
900 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
901 from the preprocessor into @code{groff}. Any number of preprocessors
902 may be used on a given document; in this case, the preprocessors are
903 linked together into one pipeline. However, in @code{groff}, the user
904 does not need to construct the pipe, but only tell @code{groff} what
905 preprocessors to use.
907 @code{groff} currently has preprocessors for producing tables
908 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
909 (@code{pic} and @code{grn}), and for processing bibliographies
910 (@code{refer}). An associated program which is useful when dealing with
911 preprocessors is @code{soelim}.
913 A free implementation of @code{grap}, a preprocessor for drawing graphs,
914 can be obtained as an extra package; @code{groff} can use @code{grap}
917 There are other preprocessors in existence, but, unfortunately, no free
918 implementations are available. Among them are preprocessors for drawing
919 mathematical pictures (@code{ideal}) and chemical structures
923 @c =====================================================================
925 @node Output device intro, Credits, Preprocessor Intro, Introduction
926 @section Output Devices
927 @cindex postprocessors
928 @cindex output devices
929 @cindex devices for output
931 @code{groff} actually produces device independent code which may be fed
932 into a postprocessor which will produce output for a particular device.
933 Currently, @code{groff} has postprocessors for @sc{PostScript},
934 character terminals, X@w{ }Windows (for previewing), @TeX{} DVI format,
935 HP LaserJet@w{ }4 and Canon LBP printers (which use @acronym{CAPSL}),
939 @c =====================================================================
941 @node Credits, , Output device intro, Introduction
945 Large portions of this manual were taken from existing documents, most
946 notably, the manual pages for the @code{groff} package by James Clark,
947 and Eric Allman's papers on the @file{me} macro package.
949 The section on the @file{man} macro package is partly based on Susan@w{
950 }G.@: Kleinmann's @file{groff_man} manual page written for the Debian
955 @c =====================================================================
956 @c =====================================================================
958 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
959 @chapter Invoking @code{groff}
960 @cindex invoking @code{groff}
961 @cindex @code{groff} invocation
965 This section focuses on how to invoke the @code{groff} front end. This
966 front end takes care of the details of constructing the pipeline among
967 the preprocessors, @code{gtroff} and the postprocessor.
969 It has become a tradition that GNU programs get the prefix @samp{g} to
970 distinguish it from its original counterparts provided by the host
971 (@pxref{Environment}, for more details). Thus, for example, @code{geqn}
972 is GNU @code{eqn}. On operating systems like Linux or the Hurd, which
973 don't contain proprietary software, this prefix is omitted since GNU
974 @code{troff} is the only used incarnation of @code{troff}. Exception:
975 @code{groff} is never replaced by @code{roff}.
980 * Invocation Examples::
984 @c =====================================================================
986 @node Groff Options, Environment, Invoking groff, Invoking groff
999 @code{groff} normally runs the @code{gtroff} program and a postprocessor
1000 appropriate for the selected device. The default device is @samp{ps}.
1001 It can optionally preprocess with any of @code{gpic}, @code{geqn},
1002 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
1004 This section only documents options to the @code{groff} front end. Many
1005 of the arguments to @code{groff} are passed on to @code{gtroff},
1006 therefore those are also included. Arguments to pre- or postprocessors
1007 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
1008 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
1009 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
1010 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
1011 grolbp}, and @ref{Invoking gxditview}.
1013 The command line format for @code{groff} is:
1016 groff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
1017 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
1018 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
1019 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
1020 [ @var{files}@dots{} ]
1023 The command line format for @code{gtroff} is as follows. As can be
1024 seen, many of the options to @code{groff} are actually passed on to
1028 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
1029 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
1030 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
1031 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
1034 Options without an argument can be grouped behind a single @option{-}.
1035 A filename of @samp{-} denotes the standard input. It is possible to
1036 have whitespace between an option and its parameter.
1039 The @code{grog} command can be used to guess the correct @code{groff}
1040 command to format a file.
1044 Print a help message.
1047 Preprocess with @code{geqn}.
1050 Preprocess with @code{gtbl}.
1053 Preprocess with @code{ggrn}.
1056 Preprocess with @code{grap}.
1059 Preprocess with @code{gpic}.
1062 Preprocess with @code{gsoelim}.
1065 Preprocess with @code{grefer}. No mechanism is provided for passing
1066 arguments to @code{grefer} because most @code{grefer} options have
1067 equivalent commands which can be included in the file. @xref{grefer},
1072 Note that @code{gtroff} also accepts a @option{-R} option, which is not
1073 accessible via @code{groff}. This option prevents the loading of the
1074 @file{troffrc} and @file{troffrc-end} files.
1077 Make programs run by @code{groff} print out their version number.
1080 Print the pipeline on stdout instead of executing it.
1083 Suppress output from @code{gtroff}. Only error messages will be
1087 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1088 will automatically run the appropriate postprocessor.
1091 Pass @var{arg} to the postprocessor. Each argument should be passed
1092 with a separate @option{-P} option. Note that @code{groff} does not
1093 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1096 Send the output to a printer. The command used for this is specified by
1097 the print command in the device description file.
1100 Pass @var{arg} to the spooler. Each argument should be passed with a
1101 separate @option{-L} option. Note that @code{groff} does not prepend a
1102 @samp{-} to @var{arg} before passing it to the postprocessor.
1105 Prepare output for device @var{dev}. The default device is @samp{ps}.
1106 The following are the output devices currently available:
1109 For @sc{PostScript} printers and previewers.
1112 For @TeX{} DVI format.
1115 For a 75@dmn{dpi} X11 previewer.
1118 For a 100@dmn{dpi} X11 previewer.
1121 For typewriter-like devices.
1124 For typewriter-like devices using the @w{ISO Latin-1} (@w{ISO 8859-1})
1128 For typewriter-like devices which use the Unicode (@w{ISO 10646})
1129 character set with @w{UTF-8} encoding.
1132 @cindex @acronym{EBCDIC} encoding
1135 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1139 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
1142 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1146 To produce @acronym{HTML} output.
1151 The predefined @code{gtroff} string register @code{.T} contains the
1152 current output device; the read-only number register @code{.T} is set
1153 to@w{ }1 if this option is used (which is always true if @code{groff} is
1154 used to call @code{gtroff}). @xref{Built-in Registers}.
1156 The postprocessor to be used for a device is specified by the
1157 @code{postpro} command in the device description file. (@xref{Font
1158 Files}, for more info.) This can be overridden with the @option{-X}
1162 Preview with @code{gxditview} instead of using the usual postprocessor.
1163 This is unlikely to produce good results except with @option{-Tps}.
1165 Note that this is not the same as using @option{-TX75} or
1166 @option{-TX100} to view a document with @code{gxditview}: The former
1167 will us the metrics of the specified device, whereas the latter will use
1168 X-specific fonts and metrics.
1171 Don't allow newlines with @code{eqn} delimiters. This is the same as
1172 the @option{-N} option in @code{geqn}.
1175 Safer mode. Pass the @option{-S} option to @code{gpic} and use the
1176 @option{-msafer} macros with @code{gtroff} (enabled by default).
1179 Unsafe mode. Reverts to the old unsafe behaviour.
1183 Generate an @acronym{ASCII} approximation of the typeset output. The
1184 read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
1188 Print a backtrace with each warning or error message. This backtrace
1189 should help track down the cause of the error. The line numbers given
1190 in the backtrace may not always be correct: @code{gtroff} can get
1191 confused by @code{as} or @code{am} requests while counting line numbers.
1194 Read the standard input after all the named input files have been
1198 Enable warning @var{name}. Available warnings are described in
1199 @ref{Debugging}. Multiple @option{-w} options are allowed.
1202 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1205 Inhibit all error messages.
1208 Enable compatibility mode.
1211 @itemx -d@var{name}=s
1212 Define @var{c} or @var{name} to be a string @var{s}. @var{c} must be a
1213 one-letter name; @var{name} can be of arbitrary length.
1216 Use @var{fam} as the default font family.
1219 Read in the file @file{tmac.@var{name}}. Normally this will be searched
1220 for in the library directory of @code{groff}.
1223 Number the first page @var{num}.
1227 Output only pages in @var{list}, which is a comma-separated list of page
1228 ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
1229 print every page between @var{m} and @var{n}, @samp{-@var{n}} means
1230 print every page up to @var{n}, @samp{@var{n}-} means print every page
1231 from @var{n}. @code{gtroff} will exit after printing the last page in
1234 Within @code{gtroff}, this information can be extracted with the
1235 @samp{.P} register. @xref{Built-in Registers}.
1238 @itemx -r@var{name}=@var{n}
1239 Set number register @var{c} or @var{name} to @var{n}. @var{c} must be a
1240 one-letter name; @var{name} can be of arbitrary length. @var{n} can be
1241 any @code{gtroff} numeric expression.
1244 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1245 name of the device) for the @file{DESC} file and font files before the
1249 Search directory @var{dir} for macro files before the normal directory.
1252 This option is as described in @ref{gsoelim}. It implies the
1257 @c =====================================================================
1259 @node Environment, Invocation Examples, Groff Options, Invoking groff
1260 @section Environment
1261 @cindex environment variables
1262 @cindex variables in environment
1264 There are also several environment variables (of the operating system,
1265 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1268 @item GROFF_COMMAND_PREFIX
1269 @tindex GROFF_COMMAND_PREFIX
1270 If this is set to @var{X}, then @code{groff} will run
1271 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1272 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1273 @code{soelim}. It does not apply to @code{grops}, @code{grodvi},
1274 @code{grotty}, @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1276 @item GROFF_TMAC_PATH
1277 @tindex GROFF_TMAC_PATH
1278 A colon separated list of directories in which to search for macro
1281 @item GROFF_TYPESETTER
1282 @tindex GROFF_TYPESETTER
1283 The default output device.
1285 @item GROFF_FONT_PATH
1286 @tindex GROFF_FONT_PATH
1287 A colon separated list of directories in which to search for the
1288 @code{dev}@var{name} directory.
1292 The search path for commands executed by @code{groff}.
1295 @tindex GROFF_TMPDIR
1297 The directory in which temporary files will be created. If this is not
1298 set and @env{TMPDIR} is set, temporary files will be created in that
1299 directory. Otherwise temporary files will be created in @code{/tmp}.
1300 The @code{grops} and @code{grefer} commands can create temporary files.
1304 @c =====================================================================
1306 @node Invocation Examples, , Environment, Invoking groff
1307 @section Invocation Examples
1308 @cindex invocation examples
1309 @cindex examples of invocation
1311 This section will list several common uses of @code{groff} and the
1312 command line which will accomplish it.
1319 This command processes @var{file} without a macro package or a
1320 preprocessor. The output device is the default, @var{ps}, and the
1321 output is sent to stdout.
1324 groff -t -mandoc -Tascii file | less
1328 This is basically what a call to the @code{man} program does. The
1329 manual page @var{file} is processed with the @file{mandoc} macros (which
1330 in turn either calls the @file{man} or the @file{mdoc} macro package),
1331 using the @code{tbl} preprocessor and the @acronym{ASCII} output device.
1332 Finally, the result is displayed with the @code{less} pager.
1339 Preview @var{file} with @code{gxditview}, using the @file{me} macro
1340 package. Since no @option{-T} option is specified, use the default
1341 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1342 @w{@samp{-me}}; the latter is an anachronism from the early days of
1343 @acronym{UNIX}.@footnote{The same is true for the other main macro
1344 packages that come with @code{groff}: @file{man}, @file{mdoc},
1345 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1346 for example, to load @file{tmac.safer}, either @samp{-msafer} or
1347 @w{@samp{-m safer}} must be used.}
1350 groff -man -rD1 -z file
1354 Check @var{file} with the @file{man} macro package, forcing double-sided
1355 printing -- don't produce any output.
1357 @c ---------------------------------------------------------------------
1363 @node grog, , Invocation Examples, Invocation Examples
1364 @subsection @code{grog}
1366 @code{grog} reads files and guesses which of the @code{groff}
1367 preprocessors and/or macro packages are are required for formatting
1368 them, and prints the @code{groff} command including those options on the
1369 standard output. The options generated are one of @option{-e},
1370 @option{-man}, @option{-me}, @option{-mm}, @option{-ms}, @option{-p},
1371 @option{-R}, @option{-g}, @option{-G}, @option{-s}, and @option{-t}.
1373 A filename of @samp{-} is taken to refer to the standard input. If no
1374 files are specified the standard input will be read. Any specified
1375 options will be included in the printed command. No space is allowed
1376 between options and their arguments. For example,
1383 will guess the appropriate command to print @file{paper.ms} and then
1384 print it to the command line after adding the @option{-Tdvi} option.
1385 For direct execution, enclose the call to @code{grog} in backquotes on
1386 the @acronym{UNIX} shell prompt:
1389 `grog -Tdvi paper.ms` > paper.dvi
1393 As seen in the example, it is still necessary to redirect the output to
1394 something meaningful (i.e.@: either a file or a pager program like
1399 @c =====================================================================
1400 @c =====================================================================
1402 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1403 @chapter Tutorial for Macro Users
1404 @cindex tutorial for macro users
1405 @cindex macro tutorial for users
1406 @cindex user's tutorial for macros
1407 @cindex user's macro tutorial
1409 Most users tend to use a macro package to format their papers. This
1410 means that the whole breadth of @code{groff} is not necessary for most
1411 people. This chapter covers the material needed to efficiently use a
1420 @c =====================================================================
1422 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1426 This section covers some of the basic concepts necessary to understand
1427 how to use a macro package.@footnote{This section is derived from
1428 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1429 References are made throughout to more detailed information, if desired.
1431 @code{gtroff} reads an input file prepared by the user and outputs a
1432 formatted document suitable for publication or framing. The input
1433 consists of text, or words to be printed, and embedded commands
1434 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1435 format the output. For more detail on this @pxref{Embedded Commands}.
1437 The word @dfn{argument} is used in this manual to mean a word or number
1438 which appears on the same line as a request which modifies the meaning
1439 of that request. For example, the request
1446 spaces one line, but
1453 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1454 request which says to space four lines instead of one. Arguments are
1455 separated from the request and from each other by spaces. More details
1456 on this can be found in @ref{Request Arguments}.
1458 The primary function of @code{gtroff} is to collect words from input
1459 lines, fill output lines with those words, justify the right hand margin
1460 by inserting extra spaces in the line, and output the result. For
1468 Four score and seven
1473 will be read, packed onto output lines, and justified to produce:
1476 Now is the time for all good men to come to the aid of their party.
1477 Four score and seven years ago,...
1482 Sometimes a new output line should be started even though the current
1483 line is not yet full; for example, at the end of a paragraph. To do
1484 this it is possible to cause a @dfn{break}, which starts a new output
1485 line. Some requests cause a break automatically, as do blank input
1486 lines and input lines beginning with a space.
1488 Not all input lines are text to be formatted. Some of the input lines
1489 are requests which describe how to format the text. Requests always
1490 have a period (@samp{.}) or an apostrophe (@samp{'}) as the first
1491 character of the input line.
1493 The text formatter also does more complex things, such as automatically
1494 numbering pages, skipping over page boundaries, putting footnotes in the
1495 correct place, and so forth.
1497 Here a few hints for preparing text for input to @code{gtroff}. First,
1498 keep the input lines short. Short input lines are easier to edit, and
1499 @code{gtroff} will pack words onto longer lines anyhow. In keeping with
1500 this, it is helpful to begin a new line after every period, comma, or
1501 phrase, since common corrections are to add or delete sentences or
1502 phrases. Secondly, do not hyphenate words at the end of lines --
1503 @code{gtroff} is smart enough to hyphenate words for the user as needed,
1504 but is not smart enough to take hyphens out and join a word back
1505 together. Also, words such as ``mother-in-law'' should not be broken
1506 over a line, since then a space can occur where not wanted, such as
1507 ``@w{mother- in}-law''.
1510 @cindex double spacing
1512 @code{gtroff} will double space output text automatically if using the
1513 request @w{@samp{.ls 2}}. Single spaced mode can be reactivated by
1514 typing @w{@samp{.ls 1}}.
1516 A number of requests allow to change the way the output looks, sometimes
1517 called the @dfn{layout} of the output page. Most of these requests
1518 adjust the placing of @dfn{white space} (blank lines or spaces).
1522 The @samp{.bp} request starts a new page, causing a line break.
1527 @cindex lines, empty
1528 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1529 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1530 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1531 @var{N}@w{ }centimeters). For example, the input:
1535 My thoughts on the subject
1540 leaves one and a half inches of space, followed by the line ``My
1541 thoughts on the subject'', followed by a single blank line.
1544 @cindex centering lines
1545 @cindex lines, centering
1546 Text lines can be centered by using the @code{ce} request. The line
1547 after @code{ce} is centered (horizontally) on the page. To center more
1548 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1549 of lines to center), followed by the @var{N}@w{ }lines. To center many
1550 lines without counting them, type:
1559 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1560 lines, in other words, stop centering.
1565 All of these requests cause a break; that is, they always start a new
1566 line. To start a new line without performing any other action, use
1570 @c =====================================================================
1572 @node Common Features, , Basics, Tutorial for Macro Users
1573 @section Common Features
1574 @cindex common features
1575 @cindex features, common
1577 @code{gtroff} provides very low level operations for formatting a
1578 document. There are many common routine operations which are done in
1579 all documents. These common operations are written into @dfn{macros}
1580 and collected into a @dfn{macro package}.
1582 All macro packages provide certain common capabilities which fall into
1583 the following categories.
1585 @c ---------------------------------------------------------------------
1589 * Sections and Chapters::
1590 * Headers and Footers::
1591 * Page Layout Adjustment::
1593 * Footnotes and Annotations::
1594 * Table of Contents::
1597 * Multiple Columns::
1598 * Font and Size Changes::
1599 * Predefined Strings::
1600 * Preprocessor Support::
1601 * Configuration and Customization::
1604 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1605 @subsection Paragraphs
1608 One of the most common and most used capability is starting a paragraph.
1609 There are a number of different types of paragraphs, any of which can be
1610 initiated with macros supplied by the macro package. Normally,
1611 paragraphs start with a blank line and the first line indented, like the
1612 text in this manual. There are also block style paragraphs, which omit
1616 Some men look at constitutions with sanctimonious
1617 reverence, and deem them like the ark of the covenant, too
1618 sacred to be touched.
1622 And there are also indented paragraphs which begin with a tag or label
1623 at the margin and the remaining text indented.
1626 one This is the first paragraph. Notice how the first
1627 line of the resulting paragraph lines up with the
1628 other lines in the paragraph.
1630 This paragraph had a long label. The first
1631 character of text on the first line will not line up
1632 with the text on second and subsequent lines,
1633 although they will line up with each other.
1636 A variation of this is a bulleted list.
1640 @c ---------------------------------------------------------------------
1642 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1643 @subsection Sections and Chapters
1645 Most macro packages supply some form of section headers. The simplest
1646 kind is simply the heading on a line by itself in bold type. Others
1647 supply automatically numbered section heading or different heading
1648 styles at different levels. Some, more sophisticated, macro packages
1649 supply macros for starting chapters and appendices.
1651 @c ---------------------------------------------------------------------
1653 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1654 @subsection Headers and Footers
1656 Every macro package gives some way to manipulate the headers and
1657 footers (or @dfn{titles}) on each page. Some packages will allow for
1658 different ones on the even and odd pages (for material printed in a book
1661 The titles are called three-part titles, that is, there is a
1662 left-justified part, a centered part, and a right-justified part. An
1663 automatically generated page number may be put in any of these fields
1664 with the @samp{%} character (@pxref{Page Layout} for more details).
1666 @c ---------------------------------------------------------------------
1668 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1669 @subsection Page Layout
1671 Most macro packages let the user specify top and bottom margins and
1672 other details about the appearance of the printed pages.
1674 @c ---------------------------------------------------------------------
1676 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1677 @subsection Displays
1680 Displays are sections of text to be set off from the body of the paper.
1681 Major quotes, tables, and figures are types of displays, as are all the
1682 examples used in this document.
1684 @cindex quotes, major
1685 @cindex major quotes
1686 @dfn{Major quotes} are quotes which are several lines long, and hence
1687 are set in from the rest of the text without quote marks around them.
1690 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1691 should be used when the material to be printed should not be filled and
1692 justified like normal text, such as columns of figures or the examples
1696 A @dfn{keep} is a display of lines which are kept on a single page if
1697 possible. An example for a keep might be a diagram. Keeps differ from
1698 lists in that lists may be broken over a page boundary whereas keeps
1701 @cindex keep, floating
1702 @cindex floating keep
1703 Floating keeps move relative to the text. Hence, they are good for
1704 things which will be referred to by name, such as ``See figure@w{ }3''.
1705 A floating keep will appear at the bottom of the current page if it will
1706 fit; otherwise, it will appear at the top of the next page. Meanwhile,
1707 the surrounding text will `flow' around the keep, thus leaving now blank
1710 @c ---------------------------------------------------------------------
1712 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1713 @subsection Footnotes and Annotations
1717 There are a number of requests to save text for later printing.
1719 @dfn{Footnotes} are printed at the bottom of the current page.
1721 @cindex delayed text
1722 @dfn{Delayed text} is very similar to a footnote except that it is
1723 printed when called for explicitly. This allows a list of references to
1724 appear (for example) at the end of each chapter, as is the convention in
1727 Most macro packages which supply this functionality also supply a means
1728 of automatically numbering either type of annotation.
1730 @c ---------------------------------------------------------------------
1732 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1733 @subsection Table of Contents
1734 @cindex table of contents
1735 @cindex contents, table of
1737 @dfn{Tables of contents} are a type of delayed text having a tag
1738 (usually the page number) attached to each entry after a row of dots.
1739 The table accumulates throughout the paper until printed, usually after
1740 the paper has ended. Many macro packages will provide the ability to
1741 have several tables of contents (i.e.@: one standard one, one for
1744 @c ---------------------------------------------------------------------
1746 @node Indices, Paper Formats, Table of Contents, Common Features
1750 While some macro packages will use the term @dfn{index}, none actually
1751 provide that functionality. The facilities they call indices are
1752 actually more appropriate for tables of contents.
1754 @c ---------------------------------------------------------------------
1756 @node Paper Formats, Multiple Columns, Indices, Common Features
1757 @subsection Paper Formats
1758 @cindex paper formats
1760 Some macro packages provide stock formats for various kinds of
1761 documents. Many of them provide a common format for the title and
1762 opening pages of a technical paper. The @file{mm} macros in particular
1763 provide formats for letters and memoranda.
1765 @c ---------------------------------------------------------------------
1767 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1768 @subsection Multiple Columns
1770 Some macro packages (except @file{man}) provide the ability to have two
1771 or more columns on a page.
1773 @c ---------------------------------------------------------------------
1775 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
1776 @subsection Font and Size Changes
1778 The built-in font and size functions are not always intuitive, so all
1779 macro packages provide macros to make these operations simpler.
1781 @c ---------------------------------------------------------------------
1783 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
1784 @subsection Predefined Strings
1786 Most macro packages provide various predefined strings for a variety of
1787 uses; examples are sub- and superscripts, printable dates, quotes and
1788 various special characters.
1790 @c ---------------------------------------------------------------------
1792 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
1793 @subsection Preprocessor Support
1795 All macro packages provide support for the various preprocessors.
1797 @c ---------------------------------------------------------------------
1799 @node Configuration and Customization, , Preprocessor Support, Common Features
1800 @subsection Configuration and Customization
1802 Some macro packages provide means of customizing many of details of how
1803 the package behaves. This ranges from setting the default type size to
1804 changing the appearance of section headers.
1808 @c =====================================================================
1809 @c =====================================================================
1811 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1812 @chapter Macro Packages
1813 @cindex macro packages
1814 @cindex packages, macros
1816 This chapter documents the main macro packages that come with
1828 @c =====================================================================
1830 @node man, mdoc, Macro Packages, Macro Packages
1833 @cindex manual pages
1837 This is the most popular and probably the most important macro package
1838 of @code{groff}. It is easy to use, and a vast majority of manual pages
1845 * Miscellaneous man stuff::
1848 @c ---------------------------------------------------------------------
1850 @node Man options, Man usage, man, man
1853 The command line format for using the @file{man} macros with
1856 @c XXX document @TMAC_AN_PREFIX@
1859 groff -m man [ -rC1 ] [ -rD1 ] [ -rP @var{nnn} ] [ -rX @var{nnn} ]
1860 [ @var{files}@dots{} ]
1863 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
1867 If more than one manual page is given on the command line, number the
1868 pages continuously, rather than starting each at@w{ }1.
1871 Double-sided printing. Footers for even and odd pages are formatted
1875 Enumeration of pages will start with @var{nnn} rather than with@w{ }1.
1878 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
1879 @var{nnn}c, etc. For example, the option @option{-rX2} will produce the
1880 following page numbers: 1, 2, 2a, 2b, 2c, etc.
1883 @c ---------------------------------------------------------------------
1885 @node Man usage, Man font macros, Man options, man
1889 This section describes the available macros for manual pages. For
1890 further customization, put additional macros and requests into the file
1891 @file{man.local} which will be loaded immediately after @file{tmac.an}.
1894 @Defmac{TH, title section [@var{extra1}] [@var{extra2}] [@var{extra3}]}
1895 Sets the title of the man page to @var{title} and the section to
1896 @var{section}, which must take on a value between 1 and@w{ }8. The
1897 value @var{section} may also have a string appended, e.g.@: @samp{.pm},
1898 to indicate a specific subsection of the man pages.
1900 Both @var{title} and @var{section} are positioned at the left and right
1901 in the header line (with @var{section} in parentheses immediately
1902 appended to @var{title}. @var{extra1} will be positioned in the middle
1903 of the footer line. @var{extra2} will be positioned at the left in the
1904 footer line (resp.@: at the left on even pages and at the right on odd
1905 pages if double-sided printing is active). @var{extra3} is centered in
1908 For @acronym{HTML} output, headers and footers are completely supressed.
1910 Additionally, this macro starts a new page; the new line number is@w{ }1
1911 again (except if the @option{-rC1} option is given on the command line)
1912 -- this feature is intended only for formatting multiple man pages; a
1913 single man page should contain exactly one @code{TH} macro at the
1914 beginning of the file.
1918 @Defmac{SH, [@var{heading}]}
1919 Sets up an unnumbered section heading sticking out to the left. Prints
1920 out all the text following @code{SH} up to the end of the line (resp.@:
1921 the text in the next line if there is no argument to @code{SH}) in bold
1922 face, at a default size of 9@w{ }point. Additionally, the left margin
1923 for the following text is reset to its default value.
1927 @Defmac{SS, [@var{heading}]}
1928 Sets up an unnumbered section heading. Prints out all the text
1929 following @code{SS} up to the end of the line (resp.@: the text in the
1930 next line if there is no argument to @code{SS}) in bold face, at a
1931 default size of 10@w{ }point. Additionally, the left margin for the
1932 following text is reset to its default value.
1936 @Defmac{TP, [@var{nnn}]}
1937 Sets up an indented paragraph with label. The indentation is set to
1938 @var{nnn} if that argument is supplied (the default unit is @samp{n} if
1939 omitted), otherwise it is set to the default indentation value.
1941 The first line of text following this macro is interpreted as a string
1942 to be printed flush-left, as it is appropriate for a label. It is not
1943 interpreted as part of a paragraph, so there is no attempt to fill the
1944 first line with text from the following input lines. Nevertheless, if
1945 the label is not as wide as the indentation, then the paragraph starts
1946 at the same line (but indented), continuing on the following lines. If
1947 the label is wider than the indentation, then the descriptive part of
1948 the paragraph begins on the line following the label, entirely indented.
1949 Note that neither font shape nor font size of the label is set to a
1950 default value; on the other hand, the rest of the text will have default
1960 These macros are mutual aliases. Any of them causes a line break at the
1961 current position, followed by a vertical space downwards by the amount
1962 specified by the @code{PD} macro. The font size and shape are reset to
1963 the default value (10@dmn{pt} resp.@: Roman). Finally, the current left
1968 @Defmac{IP, [@var{designator}] [@var{nnn}]}
1969 Sets up an indented paragraph, using @var{designator} as a tag to mark
1970 its beginning. The indentation is set to @var{nnn} if that argument is
1971 supplied (default unit is @samp{n}), otherwise the default indentation
1972 value is used. Font size and face of the paragraph (but not the
1973 designator) are reset to its default values. To start an indented
1974 paragraph with a particular indentation but without a designator, use
1975 @samp{""} (two doublequotes) as the first argument of @code{IP}.
1977 For example, to start a paragraph with bullets as the designator and
1978 4@dmn{en} indentation, write
1986 @Defmac{HP, [@var{nnn}]}
1987 Sets up a paragraph with hanging left indentation. The indentation is
1988 set to @var{nnn} if that argument is supplied (default unit is
1989 @samp{n}), otherwise the default indentation value is used. Font size
1990 and face are reset to its default values.
1994 @Defmac{RS, [@var{nnn}]}
1995 This macro moves the left margin to the right by the value @var{nnn} if
1996 specified (default unit is @samp{n}); otherwise the default indentation
1997 value is used. Calls to the @code{RS} macro can be nested.
2001 @Defmac{RE, [@var{nnn}]}
2002 This macro moves the left margin back to level @var{nnn}; if no argument
2003 is given, it moves one level back. The first level (i.e., no call to
2004 @code{RS} yet) has number@w{ }1, and each call to @code{RS} increases
2016 To summarize, the following macros cause a line break with the insertion
2017 of vertical space (which amount can be changed with the @code{PD}
2018 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2019 @code{P}), @code{IP}, and @code{HP}.
2023 The macros @code{RS} and @code{RE} also cause a break but no insertion
2026 @c ---------------------------------------------------------------------
2028 @node Man font macros, Miscellaneous man stuff, Man usage, man
2029 @subsection Macros to set fonts
2031 The standard font is Roman; the default text size is 10@w{ }point.
2034 @Defmac{SM, [@var{text}]}
2035 Causes the text on the same line or the text on the next line to appear
2036 in a font that is one point size smaller than the default font.
2040 @Defmac{SB, [@var{text}]}
2041 Causes the text on the same line or the text on the next line to appear
2042 in boldface font, one point size smaller than the default font.
2047 Causes text on the same line to appear alternately in bold face and
2048 italic. The text must be on the same line as the macro call. Thus
2051 .BI this "word and" that
2055 would cause `this' and `that' to appear in bold face, while `word and'
2061 Causes text to appear alternately in italic and bold face. The text
2062 must be on the same line as the macro call.
2067 Causes text on the same line to appear alternately in roman and italic.
2068 The text must be on the same line as the macro call.
2073 Causes text on the same line to appear alternately in italic and roman.
2074 The text must be on the same line as the macro call.
2079 Causes text on the same line to appear alternately in bold face and
2080 roman. The text must be on the same line as the macro call.
2085 Causes text on the same line to appear alternately in roman and bold
2086 face. The text must be on the same line as the macro call.
2090 @Defmac{R, [@var{text}]}
2091 Causes @var{text} to appear in roman font. If no text is present on the
2092 line where the macro is called, then the text of the next line appears
2093 in roman. This is the default font to which text is returned at the end
2094 of processing of the other macros.
2098 @Defmac{B, [@var{text}]}
2099 Causes @var{text} to appear in bold face. If no text is present on the
2100 line where the macro is called, then the text of the next line appears
2105 @Defmac{I, [@var{text}]}
2106 Causes @var{text} to appear in italic. If no text is present on the
2107 line where the macro is called, then the text of the next line appears
2111 @c ---------------------------------------------------------------------
2113 @node Miscellaneous man stuff, , Man font macros, man
2114 @subsection Miscellaneous
2117 @cindex @file{man}, default indentation
2118 @cindex default indentation, @file{man}
2119 The default indentation is 7.2@dmn{n} for all output devices except for
2120 @code{grohtml} which uses 1.2@dmn{i} instead.
2125 Sets tabs every 0.5@w{ }inches. Since this macro is always called
2126 during a @code{TH} request, it makes sense to call it only if the tab
2127 positions have been changed.
2131 @Defmac{PD, [@var{nnn}]}
2132 Adjusts the empty space before a new paragraph (resp.@: section). The
2133 optional argument gives the amount of space (default units are
2134 @samp{v}); without parameter, the value is reset to its default value
2135 (1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise).
2146 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP}
2147 (resp.@: @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2149 The following strings are defined:
2153 Switch back to the default font size.
2158 The `registered' sign.
2163 The `trademark' sign.
2172 Left and right quote.
2173 This is equal to @code{\(lq} and @code{\(rq}, respectively.
2176 @cindex preprocessor, calling convention
2177 @cindex calling convention of preprocessors
2178 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2179 become usage to make the first line of the man page look like this:
2189 Note the single space character after the double quote. @var{word}
2190 consists of letters for the needed preprocessors: @samp{e} for
2191 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2192 Modern implementations of the @code{man} program read this first line
2193 and automatically call the right preprocessor(s).
2196 @c =====================================================================
2198 @node mdoc, ms, man, Macro Packages
2199 @section @file{mdoc}
2202 @c XXX documentation
2205 @c =====================================================================
2207 @node ms, me, mdoc, Macro Packages
2211 @c XXX documentation
2214 @c =====================================================================
2216 @node me, mm, ms, Macro Packages
2220 @c XXX documentation
2223 @c =====================================================================
2225 @node mm, , me, Macro Packages
2229 @c XXX documentation
2233 @c =====================================================================
2234 @c =====================================================================
2236 @node Programming Tutorial, Preprocessors, Macro Packages, Top
2237 @chapter Programming Tutorial
2238 @cindex programming tutorial
2239 @cindex tutorial for programming
2241 This chapter covers @strong{all} of the facilities of @code{gtroff}.
2242 Users of macro packages may skip it if not interested in details.
2247 * Input Conventions::
2251 * Embedded Commands::
2253 * Manipulating Filling and Adjusting::
2254 * Manipulating Hyphenation::
2255 * Manipulating Spacing::
2257 * Character Translations::
2258 * Troff and Nroff Mode::
2265 * Conditionals and Loops::
2268 * Drawing Requests::
2273 * Postprocessor Access::
2276 * Implementation Differences::
2281 @c =====================================================================
2283 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
2287 @code{gtroff} input files contain text with control commands
2288 interspersed throughout. But, even without control codes, @code{gtroff}
2289 will still do several things with the input text: filling and adjusting,
2290 adding additional space after sentences, hyphenating and inserting
2291 implicit line breaks.
2294 * Filling and Adjusting::
2298 * Implicit Line Breaks::
2301 @c ---------------------------------------------------------------------
2303 @node Filling and Adjusting, Hyphenation, Text, Text
2304 @subsection Filling and Adjusting
2305 @cindex filling and adjusting
2306 @cindex adjusting and filling
2308 When @code{gtroff} reads in text it collects words from input and fits
2309 as many of them together on one output line as it can. This is known as
2312 @cindex leading spaces
2313 @cindex spaces, leading
2314 @cindex extra spaces
2315 @cindex spaces, extra
2316 @cindex trailing spaces
2317 @cindex spaces, trailing
2318 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
2319 it. Which means it will widen the spacing between words until the text
2320 reaches the right margin (in the default adjustment mode). Extra spaces
2321 between words are preserved, but spaces at the end of lines are ignored.
2322 Spaces at the front of a line will cause a @dfn{break} (breaks will be
2323 explained in @ref{Implicit Line Breaks})
2325 @xref{Manipulating Filling and Adjusting}.
2327 @c ---------------------------------------------------------------------
2329 @node Hyphenation, Sentences, Filling and Adjusting, Text
2330 @subsection Hyphenation
2333 Since the odds of finding a set of words, for every output line, which
2334 will fit nicely on a line without inserting excessive amounts of space
2335 between words is not great, @code{gtroff} will hyphenate words so that
2336 lines can be justified without there being too much space between words.
2337 It uses an internal hyphenation algorithm (a simplified version of the
2338 algorithm used within @TeX{}) to indicate which words can be hyphenated
2339 and how to do so. When a word is hyphenated the first part of the word
2340 will be added to the current filled line being output (with an attached
2341 hyphen), and the other portion will be added to the next line to be
2344 @xref{Manipulating Hyphenation}.
2346 @c ---------------------------------------------------------------------
2348 @node Sentences, Tab Stops, Hyphenation, Text
2349 @subsection Sentences
2352 Although it is often debated, some typesetting rules say there should be
2353 different amounts of space after various punctuation marks. For
2354 example, the @emph{Chicago typsetting manual} says that a period at the
2355 end of a sentence should have twice as much space following it as would
2356 a comma or a period as part of an abbreviation.
2358 @c XXX exact citation of Chigago manual
2360 @cindex sentence space
2361 @cindex space between sentences
2362 @cindex french-spacing
2363 @code{gtroff} does this by flagging certain characters (normally
2364 @samp{!}, @samp{?} and @samp{.}) as @dfn{end of sentence} characters.
2365 When @code{gtroff} encounters one of these characters at the end of a
2366 line it will append two @dfn{sentence spaces} in the formatted output.
2367 (Thus, one of the conventions mentioned in @ref{Input Conventions}.)
2369 @cindex transparent characters
2370 @cindex character, transparent
2378 In addition, the following characters resp.@: glyphs are treated
2379 transparently while handling end of sentence characters: @samp{"},
2380 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}.
2382 See the @code{cflags} request in @ref{Using Symbols}, for more details.
2385 To prevent the insertion of extra space after an end of sentence
2386 character (at the end of a line), append @code{\&}.
2388 @c ---------------------------------------------------------------------
2390 @node Tab Stops, Implicit Line Breaks, Sentences, Text
2391 @subsection Tab Stops
2393 @cindex stops, tabulator
2394 @cindex tab character
2395 @cindex character, tabulator
2397 @cindex @acronym{EBCDIC} encoding
2398 @code{gtroff} translates @dfn{tabulator characters}, also called
2399 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} resp.@:
2400 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
2401 tabulator stop. These tab stops are initially located every half inch
2402 across the page. Using this simple tables can easily be made. However,
2403 it can often be deceptive as the appearance (and width) of the text on a
2404 terminal and the results from @code{gtroff} can vary greatly.
2406 Also, a possible sticking point is that lines beginning with tab
2407 characters will still be filled, again producing unexpected results.
2408 For example, the following input
2410 @multitable {12345678} {12345678} {12345678} {12345678}
2412 @tab 1 @tab 2 @tab 3
2420 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
2422 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
2425 @xref{Tabs and Fields}.
2427 @c ---------------------------------------------------------------------
2429 @node Implicit Line Breaks, , Tab Stops, Text
2430 @subsection Implicit Line Breaks
2431 @cindex implicit line breaks
2432 @cindex line, implicit breaks
2434 @cindex break, implicit
2437 An important concept in @code{gtroff} is the @dfn{break}. When a break
2438 occurs, @code{gtroff} will output the partially filled line
2439 (unjustified), and resume collecting and filling text on the next output
2445 There are several ways to cause a break in @code{gtroff}. A blank line
2446 will not only cause a break, but it will also cause a one line vertical
2447 space (effectively a blank line) to be output.
2451 A line which begins with a space will cause a break and the space will
2452 be output at the beginning of the next line. Note that this space isn't
2453 adjusted, even in fill mode.
2455 The end of file will also cause a break -- otherwise the last line of
2456 the document may vanish!
2458 Certain requests also cause breaks, implicitly or explicitly. This will
2459 be discussed in @ref{Manipulating Filling and Adjusting}.
2462 @c =====================================================================
2464 @node Input Conventions, Measurements, Text, Programming Tutorial
2465 @section Input Conventions
2466 @cindex input conventions
2467 @cindex conventions for input
2469 Since @code{gtroff} does filling automatically, it is traditional in
2470 @code{groff} not to try and type things in as nicely formatted
2471 paragraphs. These are some conventions commonly used when typing
2476 Break lines after punctuation, particularly at the end of sentences,
2477 and in other logical places. Keep separate phrases on lines by
2478 themselves, as entire phrases are often added or deleted when editing.
2481 Try to keep lines less than 40-60@w{ }characters, to allow space for
2482 inserting more text.
2485 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
2486 don't try and use spaces to get proper indentation).
2490 @c =====================================================================
2492 @node Measurements, Expressions, Input Conventions, Programming Tutorial
2493 @section Measurements
2494 @cindex measurements
2496 @cindex units of measurement
2498 @cindex machine units
2499 @cindex measurement units
2500 @cindex @code{u} unit
2501 @cindex unit, @code{u}
2502 @code{gtroff} (like any other programs) requires numeric parameters to
2503 specify various measurements. Most numeric parameters@footnote{those
2504 that specify vertical or horizontal motion or a type size} may have a
2505 @dfn{measurement unit} attached. These units are specified as a single
2506 character which immediately follows the number or expression. Each of
2507 these units are understood, by @code{gtroff}, to be a multiple of its
2508 @dfn{basic unit}. So, whenever a different measurement unit is
2509 specified @code{gtroff} converts this into its @dfn{basic units}. This
2510 basic unit, represented by a @samp{u}, is a device dependent measurement
2511 which is quite small, ranging from 1/75th to 1/72000th of an inch. The
2512 values may be given as fractional numbers -- nevertheless, fractional
2513 basic units are always rounded to integers.
2515 Some of the measurement units are completely independent of any of the
2516 current settings (e.g.@: type size) of @code{gtroff}.
2521 @cindex @code{i} unit
2522 @cindex unit, @code{i}
2523 Inches. An antiquated measurement unit still in use in certain
2524 backwards countries. One inch is equal to@w{ }2.54@dmn{cm}.
2528 @cindex @code{c} unit
2529 @cindex unit, @code{c}
2530 Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
2534 @cindex @code{p} unit
2535 @cindex unit, @code{p}
2536 Points. This is a typesetter's measurement used for measure type size.
2537 It is 72@w{ }points to an inch.
2541 @cindex @code{P} unit
2542 @cindex unit, @code{P}
2543 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
2544 12@w{ }points to a pica).
2548 @cindex @code{s} unit
2549 @cindex unit, @code{s}
2550 @cindex @code{z} unit
2551 @cindex unit, @code{z}
2552 @xref{Fractional Type Sizes}, for a discussion of these units.
2555 The other measurements understood by @code{gtroff} are dependent on
2556 settings currently in effect in @code{gtroff}. These are very useful
2557 for specifying measurements which should look proper with any size of
2563 @cindex @code{m} unit
2564 @cindex unit, @code{m}
2565 Ems. This unit is equal to the current font size in points. So called
2566 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
2567 in the current font.
2571 @cindex @code{n} unit
2572 @cindex unit, @code{n}
2573 Ens. This is half of an em.
2576 @cindex vertical space
2577 @cindex space, vertical
2578 @cindex @code{v} unit
2579 @cindex unit, @code{v}
2580 Vertical space. This is equivalent to the current line spacing.
2581 @xref{Sizes}, for more information about this.
2584 @cindex @code{M} unit
2585 @cindex unit, @code{M}
2593 @c ---------------------------------------------------------------------
2595 @node Default Units, , Measurements, Measurements
2596 @subsection Default Units
2597 @cindex default units
2598 @cindex units, default
2600 Many requests take a default unit. While this can be helpful at times,
2601 it can cause strange errors in some expressions. For example, the line
2602 length request expects em units. Here are several attempts to get a
2603 line length of 3.5@w{ }inches and the results:
2610 7i/2u @result{} 3.5i
2614 Everything will be converted to basic units first. In the above example
2615 it is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m}
2616 equals@w{ }10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value
2617 7i/2 will be first handled as 7i/2m, then converted to 1680u/66u which
2618 is 25@dmn{u}, and this is approximately 0.1@dmn{i}.
2620 As a conclusion, the safest way to specify measurements is to always
2621 attach a scaling indicator. If you want to multiply or divide by a
2622 certain scalar value, use @samp{u} as the unit for that value.
2625 @c =====================================================================
2627 @node Expressions, Identifiers, Measurements, Programming Tutorial
2628 @section Expressions
2631 @code{gtroff} has most of operators common to other languages:
2633 @c XXX more details; examples
2637 @cindex arithmetic operators
2638 @cindex operators, arithmetic
2644 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
2645 (division), @samp{*} (multiplication), @samp{%} (modulo).
2647 @code{gtroff} only provides integer arithmetic. The internal type used
2648 for computing results is @samp{int}, which is usually a 32@dmn{bit}
2652 @cindex comparison operators
2653 @cindex operators, comparison
2660 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
2661 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
2662 (equal), @samp{==} (the same as @samp{=}).
2665 @cindex logical operators
2666 @cindex operators, logical
2669 Logical: @samp{&} (logical and), @samp{:} (logical or).
2672 @cindex unary operators
2673 @cindex operators, unary
2679 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
2680 (just for completeness; does nothing in expressions), @samp{!} (logical
2681 not; this works only within @code{if} and @code{while} requests). See
2682 below for the use of unary operators in motion requests.
2685 @cindex extremum operators
2686 @cindex operators, extremum
2689 Extrema: @samp{>?} (maximum), @samp{<?} (minimum). For example,
2690 @samp{5>?3} yields@w{ }@samp{5}.
2695 @cindex scaling operator
2696 @cindex operator, scaling
2697 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
2698 the default scaling indicator. If @var{c} is missing, ignore scaling
2699 indicators in the evaluation of @var{e}.
2703 @cindex order of evaluation in expressions
2704 @cindex expression, order of evaluation
2707 Parentheses may be used as in any other language. However, in
2708 @code{gtroff} they are necessary to ensure order of evaluation.
2709 @code{gtroff} has no operator precedence; expressions are evaluated left
2710 to right. This means that @samp{3+5*4} is evaluated as if it were
2711 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as expected.
2716 @cindex motion operators
2717 @cindex operators, motion
2718 For many requests which cause a motion on the page, the unary operators
2719 work differently. The @samp{+} and @samp{-} operators then indicate a
2720 motion relative to the current position (down or up, respectively), and
2721 the @samp{|} operator indicates an absolute position on the page or
2724 @samp{+} and @samp{-} are also treated differently by the following
2725 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
2726 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
2727 @code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus
2728 signs indicate increments resp.@: decrements.
2730 @c XXX add more xref
2731 @xref{Setting Registers}.
2733 @cindex space characters in expressions
2734 @cindex expressions and space characters
2735 Due to the way arguments are parsed, spaces are not allowed in
2736 expressions, unless the entire expression is surrounded by parentheses.
2738 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2741 @c =====================================================================
2743 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
2744 @section Identifiers
2747 Like any other language, @code{gtroff} has rules for properly formed
2748 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
2749 almost any printable character. The exception are the following
2754 @cindex whitespace characters
2755 @cindex newline character
2756 @cindex character, whitespace
2757 Whitespace characters (space, tabs, and newlines).
2760 @cindex character, backspace
2761 @cindex backspace character
2762 @cindex @acronym{EBCDIC} encoding
2763 Backspace (@acronym{ASCII}@w{ }@code{0x08} resp.@: @acronym{EBCDIC}@w{
2764 }@code{0x16}) and character code @code{0x01}.
2767 @cindex illegal input characters
2768 @cindex input characters, illegal
2769 @cindex characters, illegal input
2771 The following input characters are illegal and will be ignored if
2772 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
2773 warning message of type @samp{input} (@pxref{Debugging}, for more
2774 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
2775 @code{0x80}-@code{0x9F}.
2777 And here the illegal input characters if @code{groff} runs on an
2778 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
2779 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
2780 @code{0x30}-@code{0x3F}.
2782 Currently, some of these reserved codepoints are used internally, thus
2783 making it non-trivial to extend @code{gtroff} to cover Unicode or other
2784 character sets resp.@: encodings which use characters of these ranges.
2786 Note that illegal characters will be removed before parsing; an
2787 identifier `foo', followed by an illegal character, followed by `bar'
2788 will be treated as `foobar'.
2791 For example, any of the following is valid.
2802 Note that identifiers longer than two characters with a closing bracket
2803 (@samp{]}) in its name can't be accessed with escape sequences which
2804 expect an identifier as a parameter. For example, @samp{\[foo]]} will
2805 access the glyph @samp{foo}, followed by @samp{]}, whereas
2806 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
2810 @Deffn{Escape, \\A, ident}
2811 Whether an identifier @var{ident} is valid in @code{gtroff} can be
2812 tested with the @code{\A} escape. It expands to the character@w{ }1
2813 or@w{ }0 according to whether its argument (delimited by quotes usually)
2814 is or is not acceptable as the name of a string, macro, diversion,
2815 number register, environment, or font. It will return@w{ }0 if no
2816 argument is given. This is useful for looking up user input in some
2817 sort of associative table.
2825 @xref{Escapes}, for details on parameter delimiting characters.
2827 @c XXX add xrefs above
2829 Identifiers in @code{gtroff} can be any length, but, in some contexts,
2830 @code{gtroff} needs to be told where identifiers end and text begins
2831 (and in different ways depending on their length).
2841 Two characters. Must be prefixed with @samp{(} in some situations.
2844 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
2845 and@w{ }@samp{]} in some situations. Any length identifier can be put
2849 @cindex undefined identifiers
2850 @cindex indentifiers, undefined
2851 Unlike many other programming languages, undefined identifiers are
2852 silently ignored or expanded to nothing.
2854 @c XXX add info about -ww command line option.
2856 @xref{Interpolating Registers}, and @ref{Strings}.
2859 @c =====================================================================
2861 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
2862 @section Embedded Commands
2863 @cindex embedded commands
2864 @cindex commands, embedded
2866 Most documents need more functionality beyond filling, adjusting and
2867 implicit line breaking. In order to gain further functionality,
2868 @code{gtroff} allows commands to be embedded into the text, in two ways.
2870 The first is a @dfn{request} which takes up an entire line, and does
2871 some large scale operation (e.g.@: break lines, start new pages).
2873 The other is an @dfn{escape} which can be embedded anywhere in the text,
2874 or even as an argument to a request.
2875 @c XXX (Not always?)
2876 Escapes generally do more minor operations like sub- and superscripts,
2877 print a symbol, etc.
2885 @c ---------------------------------------------------------------------
2887 @node Requests, Macros, Embedded Commands, Embedded Commands
2888 @subsection Requests
2891 @cindex control character
2892 @cindex character, control
2893 @cindex no-break control character
2894 @cindex character, no-break control
2895 @cindex control character, no-break
2898 A request line begins with a control character, which is either a single
2899 quote (@samp{'}, the @dfn{no-break control character}) or a period
2900 (@samp{.}, the normal @dfn{control character}). These can be changed;
2901 see @ref{Character Translations}, for details. After this there may be
2902 optional tabs or spaces followed by an identifier which is the name of
2903 the request. This may be followed by any number of space-separated
2906 @cindex zero width space character
2907 @cindex character, zero width space
2908 @cindex space character, zero width
2910 To begin a line with a control character without it being interpreted,
2911 precede it with @code{\&}. This represents a zero width space, which
2912 means it will not affect the output.
2914 In most cases the period is used as a control character. Several
2915 requests will cause a break implicitly; using the single quote control
2916 character will prevent this.
2919 * Request Arguments::
2922 @node Request Arguments, , Requests, Requests
2923 @subsubsection Request Arguments
2924 @cindex request arguments
2925 @cindex arguments to requests
2927 Arguments to requests (and macros) are processed much like the shell:
2928 The line is split into arguments according to spaces. An argument which
2929 is intended to contain spaces can either be enclosed in quotes (single
2930 or double), or have the spaces @dfn{escaped} with backslashes.
2933 .uh The Mouse Problem
2934 .uh "The Mouse Problem"
2935 .uh The\ Mouse\ Problem
2941 The first line is the @code{uh} macro being called with 3 arguments,
2942 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
2943 same effect or calling the @code{uh} macro with one argument @samp{The
2944 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
2945 is `classical' in the sense that it can be found in most @code{troff}
2946 documents. Nevertheless, it is not optimal in all situations since
2947 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
2948 can't stretch. @code{gtroff} provides a different command @code{\~} to
2949 insert a stretchable, non-breaking space.}
2952 Note, however, that the @code{ds} request works differently.
2953 @xref{Strings}, for more details.
2955 @c ---------------------------------------------------------------------
2957 @node Macros, Escapes, Requests, Embedded Commands
2961 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
2962 which can be invoked by name. They are called in the same manner as
2963 requests -- arguments also may be passed in the same manner.
2965 @xref{Writing Macros}, and @ref{Request Arguments}.
2967 @c ---------------------------------------------------------------------
2969 @node Escapes, , Macros, Embedded Commands
2973 Escapes may occur anywhere in the input to @code{gtroff}. They begin
2974 with a backslash usually and are followed by a single character which
2975 indicates the function to be performed. The escape character can be
2976 changed; see @ref{Character Translations}.
2981 Escape sequences which require an identifier as a parameter accept three
2982 possible syntax forms.
2986 The next single character is the identifier.
2989 If this single character is an opening parenthesis, take the following
2990 two characters as the identifier. Note that there is no closing
2991 parenthesis after the identifier.
2994 If this single character is an opening bracket, take all characters
2995 until a closing bracket as the identifier.
3008 @cindex argument delimiting characters
3009 @cindex characters, argument delimiting
3010 @cindex delimiting characters for arguments
3011 Other escapes may require several arguments and/or some special format.
3012 In such cases the argument is traditionally enclosed in single quotes
3013 (and quotes are always used in this manual for the definitions of escape
3014 sequences). The enclosed text is then processed according to what that
3015 escape expects. Example:
3024 Note that the quote character can be replaced with any other character
3025 which does not occur in the argument (even a newline or a space
3026 character) in the following escapes: @code{\o}, @code{\b}, and
3027 @code{\X}. This makes e.g.
3036 @result{} A caf@'e in Paris
3040 possible, but it is better not to use this feature to avoid confusion.
3070 The following escapes sequences (which are handled similarly to
3071 characters since they don't take a parameter) are also allowed as
3072 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
3073 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
3074 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
3075 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
3076 @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't
3077 use these if possible.
3083 No newline characters as delimiters are allowed in the following
3084 escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}.
3097 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
3098 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
3099 @code{\x} can't use the following characters as delimiters:
3105 The digits @code{0}-@code{9}.
3122 The (single character) operators @samp{+-/*%<>=&:().}.
3125 @cindex space character
3126 @cindex character, space
3127 @cindex tab character
3128 @cindex character, tab
3129 @cindex newline character
3130 @cindex character, newline
3131 The space, tab, and newline characters.
3147 All escape sequences except @code{\%}, @code{\@{}, @code{\@}},
3148 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
3149 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
3155 To have a backslash (resp.@: the current escape character) appear in the
3156 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
3157 These are very similar, and only differ with respect to being used in
3158 macros or diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for
3161 @c XXX explanation of \E
3163 @xref{Identifiers}, and @ref{Character Translations}.
3169 @node Comments, , Escapes, Escapes
3170 @subsubsection Comments
3173 Probably one of the most@footnote{Unfortunately, this is a lie. But
3174 hopefully future @code{gtroff} hackers will believe it :-)} common forms
3175 of escapes is the comment.
3178 Start a comment. Everything to the end of the input line is ignored.
3180 This may sound simple, but it can be tricky to keep the comments from
3181 interfering with the appearance of the final output.
3184 If the escape is to the right of some text or a request, that portion of
3185 the line will be ignored, but the space leading up to it will be noticed
3186 by @code{gtroff}. This only affects the @code{.ds} request.
3187 @c XXX (any others?)
3189 One possibly irritating idiosyncracy is that tabs must not be used to
3190 line up comments. Tabs are not treated as white space between the
3191 request and macro arguments.
3193 @cindex undefined request
3194 @cindex request, undefined
3195 A comment on a line by itself will be treated as a blank line, because
3196 after eliminating the comment, that is all that remains:
3213 As a consequence, it is common to start the line with @code{.\"} which
3214 will cause the line to be treated as an undefined request and thus
3218 Another commenting scheme seen sometimes is three consecutive single
3219 quotes (@code{'''}) at the beginning of a line. This works, but
3220 @code{gtroff} will give a warning about an undefined macro (namely
3221 @code{''}), which is harmless, but irritating.
3225 Now to avoid all this @code{gtroff} has a new comment mechanism using
3226 the @code{\#} escape. This escape works the same as @code{\"} except
3227 that the newline is also ignored:
3247 For large blocks of text, the @code{ig} request may be useful.
3249 @c XXX definition of .ig
3254 @c =====================================================================
3256 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
3260 Numeric variables in @code{gtroff} are called @dfn{registers}. There
3261 are a number of built-in registers, supplying anything from the date to
3262 details of formatting parameters.
3264 @xref{Identifiers}, for details on register identifiers.
3267 * Setting Registers::
3268 * Interpolating Registers::
3270 * Assigning Formats::
3271 * Built-in Registers::
3274 @c ---------------------------------------------------------------------
3276 @node Setting Registers, Interpolating Registers, Registers, Registers
3277 @subsection Setting Registers
3278 @cindex setting registers
3279 @cindex registers, setting
3281 Registers are defined resp.@: set via the @code{nr} request or the
3284 @Deffn{Request, nr, ident value}
3285 @Deffnx{Escape, \\R, ident value}
3286 Set number register @var{ident} to @var{value}. If @var{ident} doesn't
3287 exist, it will be created.
3289 The argument to @code{\R} has to be enclosed in quotes usually.
3290 @xref{Escapes}, for details on parameter delimiting characters.
3293 For example, the following two lines are equivalent:
3300 Both @code{nr} and @code{\R} have two additional special forms to
3301 increment resp.@: decrement a register.
3303 @Deffn{Request, nr, ident +value}
3304 @Deffnx{Request, nr, ident -value}
3305 @Deffnx{Escape, \\R, ident +value}
3306 @Deffnx{Escape, \\R, ident -value}
3307 Increment (decrement) register @var{ident} by @var{value}.
3316 To assign the negated value of a register to another register, some care
3317 must be taken to get the desired result:
3331 The surrounding parentheses prevent the interpretation of the minus sign
3332 as a decrementing operator. An alternative is to start the assignment
3347 @Deffn{Request, rr, ident}
3348 Remove number register @var{ident}. If @var{ident} doesn't exist, the
3352 @Deffn{Request, rnn, ident1 ident2}
3353 Rename number register @var{ident1} to @var{ident2}. If either
3354 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
3357 @Deffn{Request, aln, ident1 ident2}
3358 This request creates an alias @var{ident1} for a number register
3359 @var{ident2}. The new name and the old name will be exactly equivalent.
3360 If @var{ident1} is undefined, a warning of type @samp{reg} will be
3361 generated, and the request will be ignored. @xref{Debugging}, for
3362 information about warnings.
3365 @c ---------------------------------------------------------------------
3367 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
3368 @subsection Interpolating Registers
3369 @cindex interpolating registers
3370 @cindex registers, interpolating
3372 Numeric registers can be accessed via the @code{\n} escape.
3374 @Deffn{Escape, \\n, ident}
3375 @c XXX is the following correct?
3376 Interpolate number register @var{ident}. This means that the value of
3377 the register is expanded in-place while @code{gtroff} is parsing the
3388 @c ---------------------------------------------------------------------
3390 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
3391 @subsection Auto-increment
3392 @cindex auto-increment
3393 @cindex increment, automatic
3395 Number registers can also be auto-incremented and auto-decremented. The
3396 increment resp.@: decrement factor can be specified with a third
3397 argument to the @code{nr} request or @code{\R} escape.
3400 @Deffn{Request, nr, ident value incr}
3401 Set number register @var{ident} to @var{value}; the increment for
3402 auto-incrementing is set to @var{incr}. Note that the @code{\R} escape
3403 doesn't support this notation.
3406 To activate auto-incrementing, the escape @code{\n} has a special syntax
3409 @Deffn{Escape, \\n, +ident}
3410 @Deffnx{Escape, \\n, -ident}
3411 Before interpolating, increment resp.@: decrement @var{ident} by the
3412 auto-increment value as specified with the @code{nr} request (or the
3413 @code{\R} escape). If no auto-increment value has been specified, both
3414 syntax forms are identical to @code{\n}.
3423 \n+a, \n+a, \n+a, \n+a, \n+a
3425 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
3427 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
3435 -5, -10, -15, -20, -25
3439 To change the increment value without changing the value of a register,
3440 the following can be used.
3446 @c ---------------------------------------------------------------------
3448 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
3449 @subsection Assigning Formats
3450 @cindex assigning formats
3451 @cindex formats, assigning
3453 When a register is used in the text of an input file (as opposed to part
3454 of an expression) it is textually replaced (or interpolated) with a
3455 representation of that number. This output format can be changed to a
3456 variety of formats (numbers, Roman numerals, etc). This is done using
3457 the @code{af} request.
3459 @Deffn{Request, af, ident format}
3460 Change the output format of a number register. The first argument
3461 @var{ident} is the name of the number register to be changed, and the
3462 second argument @var{format} is the output format. The following output
3463 formats are available:
3467 Decimal arabic numbers. This is the default format: 1, 2, 3,@w{
3471 Decimal numbers with as many digits as specified. So, @samp{00} would
3472 result in printing numbers as 01, 02, 03,@w{ }@dots{}
3474 In fact, any digit instead of zero will do; @code{gtroff} only counts
3475 how many digits are specified. As a consequence, @code{af}'s default
3476 format @samp{1} could be specified as @samp{0} also (and exactly this is
3477 returned by the @code{\g} escape).
3480 @cindex roman numerals
3481 @cindex numerals, Roman
3482 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@dots{}
3485 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@dots{}
3488 Upper-case letters: A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@dots{}
3491 Lower-case letters: a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@dots{}
3494 Omitting the number register format will cause a warning of type
3495 @samp{missing}. @xref{Debugging}, for more details. Specifying a
3496 nonexistent format causes an error.
3498 The following example will produce @samp{10, X, j, 010}:
3502 .af a 1 \" the default format
3512 The largest number representable for the @samp{i} and @samp{I} formats
3513 is 39999 (resp.@: -39999); @acronym{UNIX} @code{troff} uses @samp{z} and
3514 @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
3515 @code{gtroff}. Currently, the correct glyphs (Unicode code points
3516 @code{U+2182} and @code{U+2181}, respectively) are not available.
3518 If @var{ident} doesn't exist, it will be created.
3520 Changing the output format of a read-only register causes an error. It
3521 is necessary to first copy the register's value to a writeable register,
3522 then apply the @code{af} request to this other register.
3525 @Deffn{Escape, \\g, ident}
3526 Return the current format of the specified register @var{ident}. For
3527 example, @samp{\ga} after the previous example would produce the string
3528 @samp{000}. If the register hasn't been defined yet, nothing is
3532 @c ---------------------------------------------------------------------
3534 @node Built-in Registers, , Assigning Formats, Registers
3535 @subsection Built-in Registers
3536 @cindex built-in registers
3537 @cindex registers, built-in
3539 The following lists some built-in registers which are not described
3540 elsewhere in this manual. Any register which begin with a @samp{.} is
3541 read-only. A complete listing of all built-in registers can be found in
3542 @ref{Register Index}.
3546 @cindex horizontal resolution
3547 @cindex resolution, horizontal
3549 Horizontal resolution in basic units.
3552 @cindex vertical resolution
3553 @cindex resolution, vertical
3555 Vertical resolution in basic units.
3558 @cindex day of the week
3559 @cindex date, day of the week
3561 Day of the week (1-7).
3564 @cindex day of the month
3565 @cindex date, day of the month
3567 Day of the month (1-31).
3570 @cindex month of the year
3571 @cindex date, month of the year
3573 Current month (1-12).
3577 @cindex year, current
3583 The current year minus@w{ }1900. Unfortunately, the documentation of
3584 @acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
3585 incorrectly claimed that @code{yr} contains the last two digits of the
3586 year. That claim has never been true of either traditional @code{troff}
3587 or GNU @code{troff}. Old @code{troff} input that looks like this:
3590 '\" The following line stopped working after 1999
3591 This document was formatted in 19\n(yr.
3595 can be corrected as follows:
3598 This document was formatted in \n[year].
3602 or, to be portable to older @code{troff} versions, as follows:
3606 This document was formatted in \n(y4.
3613 @cindex input line number
3614 @cindex line number, input
3615 The current @emph{input} line number. Register @samp{.c} is read-only,
3616 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
3617 affecting both @samp{.c} and @samp{c.}.
3622 @cindex output line number
3623 @cindex line number, output
3624 The current @emph{output} line number after a call to the @code{nm}
3625 request to activate line numbering.
3627 @c XXX xref nm request
3631 @cindex major version number
3632 @cindex version number, major
3633 The major version number. For example, if the version number is@w{
3634 }1.03 then @code{.x} will contain@w{ }@samp{1}.
3638 @cindex minor version number
3639 @cindex version number, minor
3640 The minor version number. For example, if the version number is@w{
3641 }1.03 then @code{.y} will contain@w{ }@samp{03}.
3645 @cindex revision number
3646 The revision number of @code{groff}.
3650 Always@w{ }1. Macros should use this to determine whether they are
3651 running under GNU @code{troff}.
3655 If the command line option @option{-a} is used to produce an
3656 @acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
3657 otherwise. @xref{Groff Options}.
3661 This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current
3662 page is actually being printed, i.e., if the @option{-o} option is being
3663 used to only print selected pages. @xref{Groff Options}, for more
3668 If @code{gtroff} is called with the @option{-T} command line option, the
3669 number register @code{.T} is set to@w{ }1, and zero otherwise.
3670 @xref{Groff Options}.
3673 Additionally, @code{gtroff} predefines a single (read/write) string
3674 register @code{.T} which contains the current output device (for
3675 example, @samp{latin1} or @samp{ps}).
3679 @c =====================================================================
3681 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
3682 @section Manipulating Filling and Adjusting
3683 @cindex manipulating filling and adjusting
3684 @cindex filling and adjusting, manipulating
3685 @cindex adjusting and filling, manipulating
3686 @cindex justifying text
3687 @cindex text, justifying
3702 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
3703 Breaks}. The @code{br} request will likewise cause a break. Several
3704 other requests will also cause breaks, but implicitly. These are
3705 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
3706 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
3708 @Deffn{Request, br, }
3709 Break the current line, i.e., the input collected so far will be emitted
3712 If the no-break control character is used, no break will happen:
3722 Initially, @code{gtroff} will fill and adjust text to both margins.
3723 Filling can be disabled via the @code{nf} request and re-enabled with
3724 the @code{fi} request.
3729 @Deffn{Request, fi, }
3730 Activate fill mode (which is the default). This request implicitly
3731 enables adjusting; it will also cause a break in the text currently
3732 being filled. The number register @code{.u} is set to@w{ }1.
3734 The fill mode status is associated with the current environment
3735 (@pxref{Environments}).
3738 @cindex no-fill mode
3739 @cindex mode, no-fill
3740 @Deffn{Request, nf, }
3741 Activate no-fill mode. Input lines are output as-is, retaining line
3742 breaks. The current line length will be ignored. This command
3743 implicitly disables adjusting; it also causes a break. The number
3744 register @code{.u} will be set to@w{ }0.
3746 The fill mode status is associated with the current environment
3747 (@pxref{Environments}).
3750 @Deffn{Request, ad, [@var{mode}]}
3753 Activation and deactivation of adjusting will be implicitly done with
3754 calls to the @code{fi} resp.@: @code{nf} requests.
3756 @var{mode} can have one of the following values:
3760 @cindex ragged-right
3761 Adjust text to the left margin. This produces what is traditionally
3762 called ragged-right text.
3766 Adjust text to the right margin, producing ragged-left text.
3769 @cindex centered text
3771 Center filled text. This is different to the @code{ce} request which
3772 only centers text without filling.
3776 Justify to both margins. This is default of @code{gtroff}.
3779 With no argument, @code{gtroff} will adjust lines the same way before
3780 adjusting has been deactivated (with a call to @code{na}, for example).
3790 .ad \" back to centering
3795 The current adjustment mode is available in the number register
3796 @code{.j}; it can be stored and subsequently used to set adjustment.
3798 The adjustment mode status is associated with the current environment
3799 (@pxref{Environments}).
3802 @Deffn{Request, na, }
3803 Disable adjusting. This request won't change the current adjustment
3804 mode: A call to @code{ad} afterwards will use the previous adjustment
3807 The adjustment mode status is associated with the current environment
3808 (@pxref{Environments}).
3811 @Deffn{Escape, \\p, }
3812 Adjust the current line and cause a break.
3814 In most cases this will produce very ugly results, since @code{gtroff}
3815 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
3816 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
3820 This is an uninteresting sentence.
3821 This is an uninteresting sentence.\p
3822 This is an uninteresting sentence.
3828 This is an uninteresting sentence. This is an
3829 uninteresting sentence.
3830 This is an uninteresting sentence.
3834 @cindex word space size
3835 @cindex size of word space
3836 @cindex space between words
3837 @cindex sentence space size
3838 @cindex size of sentence space
3839 @cindex space between sentences
3840 @Deffn{Request, ss, word_space_size [@var{sentence_space_size}]}
3841 Change the minimum size of a space between filled words. It takes its
3842 units as one twelfth of the space width parameter for the current font.
3843 Initially both the @var{word_space_size} and @var{sentence_space_size}
3848 If two arguments are given to the @code{ss} request, the second argument
3849 sets the sentence space size. If the second argument is not given,
3850 @var{sentence_space_size} will be the same as @var{word_space_size}.
3851 The sentence space size is used in two circumstances: If the end of a
3852 sentence occurs at the end of a line in fill mode, then both an
3853 inter-word space and a sentence space will be added; if two spaces
3854 follow the end of a sentence in the middle of a line, then the second
3855 space will be a sentence space. Note that the behaviour of
3856 @acronym{UNIX} @code{troff} will be exactly that exhibited by GNU
3857 @code{troff} if a second argument is never given to the @code{ss}
3858 request. In GNU @code{troff}, as in @acronym{UNIX} @code{troff}, a
3859 sentence should always be followed with either a newline or two spaces.
3863 The number registers @code{.ss} and @code{.sss} are the values of the
3864 parameters set by the first and second arguments of the @code{ss}
3867 The space and sentence space values are associated with the current
3868 environment (@pxref{Environments}).
3870 This request is ignored in nroff mode; it is also ignored if there is no
3874 @cindex centering lines
3875 @cindex lines, centering
3876 @Deffn{Request, ce, [@var{nnn}]}
3877 Center text. While the @w{@samp{ad c}} request will also center text,
3878 it has the side effect of filling the text. @code{ce} will not fill the
3879 text it affects. This request causes a break.
3881 With no arguments, @code{ce} will center the next line of text.
3882 @var{nnn} is a number indicating the number of lines to be centered. If
3883 the argument is zero or negative, centering is disabled.
3888 The basic length for centering text is the line length (as set with the
3889 @code{ll} request) minus the indentation (as set with the @code{in}
3890 request). Temporary indentation is ignored.
3892 A common idiom is to turn on centering for a large number of lines, and
3893 to turn off centering after text to be centered. This is useful for any
3894 request which takes a number of lines as an argument.
3907 The @code{.ce} number register contains the number of lines remaining to
3908 be centered, as set by the @code{ce} request.
3911 @cindex justifying text
3912 @cindex text, justifying
3913 @cindex right-justifying
3915 @Deffn{Request, rj, [@var{nnn}]}
3916 Justify unfilled text to the right margin. Its arguments are identical
3917 to the @code{ce} request. The @code{.rj} number register is the number
3918 of lines to be right-justified as set by the @code{rj} request. This
3919 request causes a line break.
3923 @c =====================================================================
3925 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
3926 @section Manipulating Hyphenation
3927 @cindex manipulating hyphenation
3928 @cindex hyphenation, manipulating
3930 As discussed in @ref{Hyphenation}, @code{gtroff} will hyphenate words.
3931 There are a number of ways to influence how hyphenation is done.
3933 @Deffn{Request, hy, [@var{mode}]}
3934 Enable hyphenation. The request has an optional numeric argument,
3935 @var{mode}, to restrict hyphenation if necessary:
3939 The default argument if @var{mode} is omitted. Hyphenate without
3940 restrictions. This is also the start-up value of @code{gtroff}.
3943 Do not hyphenate the last word on a page or column.
3946 Do not hyphenate the last two characters of a word.
3949 Do not hyphenate the first two characters of a word.
3952 Values in the previous table are additive. For example, the value@w{
3953 }12 causes @code{gtroff} to neither hyphenate the last two nor the first
3954 two characters of a word.
3957 The current hyphenation restrictions can be found in the number register
3960 The hyphenation mode is associated with the current environment
3961 (@pxref{Environments}).
3964 @Deffn{Request, nh, }
3965 Disable hyphenation (i.e., set the hyphenation mode to zero). Note that
3966 the hyphenation mode of the last call to @code{hy} is not remembered.
3968 The hyphenation mode is associated with the current environment
3969 (@pxref{Environments}).
3975 @cindex explicit hyphens
3976 @cindex hyphen, explicit
3977 @cindex consecutive hyphenated lines
3978 @cindex lines, consecutive hyphenated
3979 @cindex hyphenated lines, consecutive
3980 @Deffn{Request, hlm, [@var{nnn}]}
3981 Set the maximum number of consecutive hyphenated lines to @var{nnn}. If
3982 this number is negative, there is no maximum. The default value is@w{
3983 }-1 if @var{nnn} is omitted. This value is associated with the current
3984 environment (@pxref{Environments}). Only lines output from a given
3985 environment count towards the maximum associated with that environment.
3986 Hyphens resulting from @code{\%} are counted; explicit hyphens are not.
3988 The current setting of @code{hlm} is available in the @code{.hlm}
3989 register. Also the number of immediately preceding consecutive
3990 hyphenated lines are available in the number register @samp{.hlc}.
3993 @Deffn{Request, hw, word1 word2 @dots{}}
3994 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
3995 words must be given with hyphens at the hyphenation points. For
4003 Besides the space character, any character which hyphenation code value
4004 is zero can be used to separate the arguments of @code{hw} (see the
4005 documentation for the @code{hcode} request below for more information).
4006 In addition, this request can be used more than once.
4008 Hyphenation exceptions specified with the @code{hw} request are
4009 associated with the current hyphenation language; it will cause an error
4010 if there is no current hyphenation language.
4012 This request is ignored if there is no parameter.
4014 In old versions of @code{troff} there was a limited amount of space to
4015 store such information; fortunately, with @code{gtroff}, this is no
4016 longer a restriction.
4019 @cindex hyphenation character
4020 @cindex character, hyphenation
4021 @cindex disabling hyphenation
4022 @cindex hyphenation, disabling
4023 @Deffn{Escape, \\%, }
4024 To tell @code{gtroff} how to hyphenate words on the fly, the @code{\%}
4025 escape, also known as the @dfn{hyphenation character}, can be used.
4026 Preceding a word with this character will prevent it from being
4027 hyphenated, putting it in a word will indicate to @code{gtroff} that the
4028 word may be hyphenated at that point. Note that this mechanism will
4029 only affect one word; to change the hyphenation of a word for the entire
4030 document, use the @code{hw} request.
4033 @Deffn{Request, hc, [@var{char}]}
4034 Change the hyphenation character to @var{char}. This character will
4035 then work the same as the @code{\%} escape, and, thus, no longer appear
4036 in the output. Without an argument, @code{hc} will reset the
4037 hyphenation character to be @code{\%} (the default) only.
4039 The hyphenation character is associated with the current environment
4040 (@pxref{Environments}).
4043 @cindex hyphenation patterns
4044 @cindex patterns for hyphenation
4045 @Deffn{Request, hpf, pattern_file}
4046 Read in a file of hyphenation patterns. This file will be searched for
4047 in the same way as @file{tmac.@var{name}} is searched for if the
4048 @option{-m@var{name}} option is specified.
4050 It should have the same format as the argument to the @code{\patterns}
4051 primitive in @TeX{} (without using @TeX{}'s macro expansion); the
4052 letters appearing in this file are interpreted as hyphenation codes. A
4053 @samp{%} character in the patterns file introduces a comment that
4054 continues to the end of the line.
4056 If no @code{hpf} request is specified (either in the document or in a
4057 macro package), @code{gtroff} won't hyphenate at all.
4063 The set of hyphenation patterns is associated with the current language
4064 set by the @code{hla} request. The @code{hpf} request is usually
4065 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
4066 @file{troffrc} loads hyphenation patterns for American English (in file
4069 It will cause an error if there is no current hyphenation language.
4072 @cindex hyphenation code
4073 @cindex code, hyphenation
4074 @Deffn{Request, hcode, c1 code1 c2 code2 @dots{}}
4075 Sets the hyphenation code of character @var{c1} to @var{code1}, that of
4076 @var{c2} to @var{code2}, etc. A hyphenation code must be a single input
4077 character (not a special character) other than a digit or a space.
4078 Initially each lower-case letter (@samp{a}-@samp{z}) has a hyphenation
4079 code, which is itself, and each upper-case letter (@samp{A}-@samp{Z})
4080 has a hyphenation code which is the lower-case version of itself.
4082 This request will be ignored if it has no parameter.
4085 @cindex hyphenation margin
4086 @cindex margin for hyphenation
4088 @Deffn{Request, hym, [@var{length}]}
4089 Set the (right) hyphenation margin to @var{length}. If the current
4090 adjustment mode is not@w{ }@samp{b}, the line will not be hyphenated if
4091 it is shorter than @var{length}. Without argument, the hyphenation
4092 margin will be reset to its default value, which is@w{ }0. The default
4093 scaling indicator for this request is@w{ }@code{m}. The hyphenation
4094 margin is associated with the current environment
4095 (@pxref{Environments}).
4097 A negative argument will reset the hyphenation margin to zero, emitting
4098 a warning of type @samp{range}.
4101 The current hyphenation margin is available in the @code{.hym} register.
4104 @cindex hyphenation space
4106 @Deffn{Request, hys, [@var{hyphenation_space}]}
4107 Set the hyphenation space to @var{hyphenation_space}. If the current
4108 adjustment mode is@w{ }@samp{b}, don't hyphenate the line if the line
4109 can be justified by adding no more than @var{hyphenation_space} extra
4110 space to each word space. Without argument, the hyphenation space is
4111 set to its default value, which is@w{ }0. The default scaling indicator
4112 for this request is@w{ }@code{m}. The hyphenation space is associated
4113 with the current environment (@pxref{Environments}).
4115 A negative argument will reset the hyphenation space to zero, emitting a
4116 warning of type @samp{range}.
4119 The current hyphenation space is available in the @code{.hys} register.
4122 @cindex soft hyphen character
4123 @cindex character, soft hyphen
4127 @Deffn{Request, shc, [@var{char}]}
4128 Set the soft hyphen character to @var{char}. If the argument is
4129 omitted, the soft hyphen character will be set to the default character
4130 @code{\(hy} (this is the start-up value of @code{gtroff} also). The
4131 soft hyphen character is the character which will be inserted when a
4132 word is hyphenated at a line break. If the soft hyphen character does
4133 not exist in the font of the character immediately preceding a potential
4134 break point, then the line will not be broken at that point. Neither
4135 definitions (specified with the @code{char} request) nor translations
4136 (specified with the @code{tr} request) are considered when finding the
4137 soft hyphen character.
4144 @Deffn{Request, hla, language}
4145 Set the current hyphenation language to the string @var{language}.
4146 Hyphenation exceptions specified with the @code{hw} request and
4147 hyphenation patterns specified with the @code{hpf} request are both
4148 associated with the current hyphenation language. The @code{hla}
4149 request is usually invoked by the @file{troffrc} or the
4150 @file{troffrc-end} files; @file{troffrc} sets the default language to
4154 The current hyphenation language is available as a string in the
4155 read-only number register @samp{.hla}.
4158 .ds curr_language \n[.hla]
4165 @c =====================================================================
4167 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
4168 @section Manipulating Spacing
4169 @cindex manipulating spacing
4170 @cindex spacing, manipulating
4172 @Deffn{Request, sp, [@var{distance}]}
4173 Space downwards @var{distance}. With no argument it will advance 1@w{
4174 }line. A negative argument will cause @code{gtroff} to move up the page
4175 the specified distance. If the argument is preceded by a @samp{|}
4176 @code{gtroff} will move that distance from the top of the page. This
4177 request causes a line break. The default scaling indicator is@w{
4181 @cindex double-spacing
4182 @Deffn{Request, ls, [@var{nnn}]}
4183 Output @w{@var{nnn}-1} blank lines after each line of text. With no
4184 argument @code{gtroff} will use the previous value before the last
4188 .ls 2 \" This causes double-spaced output
4189 .ls 3 \" This causes triple-spaced output
4190 .ls \" Again double spaced
4193 The line spacing is associated with the current environment
4194 (@pxref{Environments}).
4197 The number register @code{.L} contains the current line spacing setting.
4200 @Deffn{Escape, \\x, spacing}
4201 Sometimes, extra vertical spacing is only needed occasionally, e.g.@: to
4202 allow space for a tall construct (like an equation). The @code{\x}
4203 escape will do this. The escape is given a numerical argument, usually
4204 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
4205 is@w{ }@code{v}. If this number is positive extra vertical space will
4206 be inserted below the current line. A negative number will add space
4207 above. If this escape is used multiple times on the same line, the
4208 maximum of the values is used.
4210 @xref{Escapes}, for details on parameter delimiting characters.
4213 The @code{.a} number register contains the most recent (nonnegative)
4214 extra vertical line space.
4218 ... example of inline equation ...
4223 @cindex no-space mode
4224 @cindex mode, no-space
4226 @cindex lines, blank
4227 @Deffn{Request, ns, }
4228 Enable @dfn{no-space mode}. In this mode, spacing (either via @code{sp}
4229 or via blank lines) is disabled. The @code{bp} request to advance to
4230 the next page is also disabled, except if it is accompanied by a page
4231 number (@pxref{Page Control}, for more information). This mode will end
4232 when actual text is output or the @code{rs} request is encountered.
4234 This request is useful for macros which want to avoid that subsequent
4235 macros inadvertently insert some vertical space before the text starts
4236 (for example, to set up the first paragraph after a section header). It
4237 is associated with the current diversion level.
4243 @Deffn{Request, rs, }
4244 Disable no-space mode. This request is associated with the current
4252 @c =====================================================================
4254 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
4255 @section Tabs and Fields
4256 @cindex tabs and fields
4257 @cindex fields and tabs
4259 @cindex @acronym{EBCDIC} encoding
4260 A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
4261 }5) causes a horizontal movement to the next tab stop (which is much
4262 like that on a typewriter).
4264 @Deffn{Escape, \\t, }
4265 This escape is a non-interpreted tab character. In copy mode
4266 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
4269 @Deffn{Request, ta, [@var{n1} @var{n2} @dots{} @var{nn} @t{T} @var{r1} @var{r2} @dots{} @var{rn}]}
4270 Change tab stop positions. This request takes a series of tab
4271 specifiers as arguments (optionally divided into two groups with the
4272 letter @samp{T}) which indicate where each tab stop is to be (overriding
4273 any previous settings).
4275 Tab stops can be specified absolutely, i.e., as the distance from the
4276 left margin. For example, the following will set 6@w{ }tab stops every
4280 .ta 1i 2i 3i 4i 5i 6i
4283 Tab stops can also be specified relatively (using a leading @samp{+})
4284 which means that the specified tab stop will be set that distance from
4285 the previous tab stop. For example, the following is equivalent to the
4289 .ta 1i +1i +1i +1i +1i +1i
4292 @code{gtroff} supports an extended syntax to specify repeat values after
4293 the @samp{T} mark (these values are always taken as relative) -- this is
4294 the usual way to specify tabs set at equal intervals. The following is,
4295 yet again, the same as the previous examples. It does even more since
4296 it defines an infinite number of tab stops separated by one inch.
4302 Now we are ready to interpret the full syntax given at the beginning:
4303 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
4304 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
4305 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
4306 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
4308 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
4309 20c 23c 28c 30c @dots{}}.
4311 The material in each tab column (i.e., the column between two tab stops)
4312 may be justified to the right or left or centered in the column. This
4313 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
4314 specifier. The default justification is @samp{L}. Example:
4324 The default unit of the @code{ta} request is @samp{m}.
4327 A tab stop is converted into a non-breakable horizontal movement which
4328 can be neither stretched nor squeezed. For example,
4337 creates a single line which is a bit longer than 10@w{ }inches (a string
4338 is used to show exactly where the tab characters are). Now consider the
4348 @code{gtroff} first converts the tab stops of the line into unbreakable
4349 horizontal movements, then splits the line after the second @samp{b}
4350 (assuming a sufficiently short line length). Usually, this isn't what
4354 Superfluous tabs (i.e., tab characters which do not correspond to a tab
4355 stop) are ignored except the first one which delimits the characters
4356 belonging to the last tab stop for right-justifying resp.@: centering.
4357 Consider the following example
4361 .ds ZZ foo\tbar\tfoobar
4362 .ds ZZZ foo\tbar\tfoo\tbar
4373 which produces the following output:
4382 The first line right-justifies the second `foo' relative to the tab
4383 stop. The second line right-justifies `foobar'. The third line finally
4384 right-justifies only `foo' because of the additional tab character which
4385 marks the end of the string belonging to the last defined tab stop.
4388 Tab stops are associated with the current environment
4389 (@pxref{Environments}).
4392 Calling @code{ta} without an argument will unset all tab stops.
4395 The start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. Even in nroff
4396 mode this value is used (contrary to @acronym{UNIX} @code{nroff} which
4397 has tab stops preset every 0.8@dmn{i}).
4401 The number register @code{.tabs} contains a string representation of the
4402 current tab settings suitable for use as an argument to the @code{ta}
4406 .ds tab-string \n[.tabs]
4412 @cindex tab repitition character
4413 @cindex character, tab repitition
4414 @Deffn{Request, tc, [@var{fill-char}]}
4415 Normally @code{gtroff} will fill the space to the next tab stop with
4416 space. This can be changed with the @code{tc} request. With no
4417 argument @code{gtroff} will revert to using space, which is the default.
4418 The value of this @dfn{tab repitition} character is associated with the
4419 current environment (@pxref{Environments}).
4427 @c ---------------------------------------------------------------------
4429 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
4433 Sometimes it may may be desirable to use the @code{tc} request to fill a
4434 particular tab stop with a given character (for example dots in a table
4435 of contents), but also normal tab stops on the rest of the line. For
4436 this @code{gtroff} provides an alternate tab mechanism, called
4437 @dfn{leaders} which will do just that.
4439 @cindex leader character
4440 A leader character (character code@w{ }1) behaves similarly to a tab
4441 character: It moves to the next tab stop. The only difference is that
4442 for this movement, the fill character defaults to a period character and
4445 @Deffn{Escape, \\a, }
4446 This escape is a non-interpreted leader character. In copy mode
4447 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
4451 @cindex leader repitition character
4452 @cindex character, leader repitition
4453 @Deffn{Request, lc, [@var{fill-char}]}
4454 The character that will be repeated can be declared with the @code{lc}
4455 request. Without an argument, leaders will act the same as tabs (i.e.,
4456 using space for filling). @code{gtroff}'s start-up value is @samp{.}.
4457 The value of this @dfn{leader repitition} character is associated with
4458 the current environment (@pxref{Environments}).
4461 @cindex table of contents
4462 @cindex contents, table of
4463 For a table of contents, to name an example, tab stops may be defined so
4464 that the section number is one tab stop, the title is the second with
4465 the remaining space being filled with a line of dots, and then the page
4466 number slightly separated from the dots.
4469 .ds entry 1.1\tFoo\a\t12
4479 1.1 Foo.......................................... 12
4482 @c ---------------------------------------------------------------------
4484 @node Fields, , Leaders, Tabs and Fields
4488 @cindex field delimiting character
4489 @cindex delimiting character for fields
4490 @cindex character, field delimiting
4491 @cindex field padding character
4492 @cindex padding character for fields
4493 @cindex character, field padding
4494 @dfn{Fields} are a more general way of laying out tabular data. A field
4495 is defined as the data between a pair of @dfn{delimiting characters}.
4496 It contains substrings which are separated by @dfn{padding characters}.
4497 The width of a field is the distance on the @emph{input} line from the
4498 position where the field starts to the next tab stop. A padding
4499 character inserts stretchable space similar to @TeX{}'s @code{\hss}
4500 command (thus it can even be negative) to make the sum of all substring
4501 lengths plus the stretchable space equal to the field width. If more
4502 than one padding character is inserted, the available space is evenly
4503 distributed among them.
4505 @Deffn{Request, fc, [@var{delim-char} [@var{padding-char}]]}
4506 Define a delimiting and a padding character for fields. If the latter
4507 is missing, the padding character defaults to a space character. If
4508 there is no argument at all, the field mechanism is disabled (which is
4509 the default). Note that contrary to e.g.@: the tab repitition
4510 character, delimiting and padding characters are not associated to the
4511 current environment (@pxref{Environments}).
4524 and here the result:
4533 @c =====================================================================
4535 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, Programming Tutorial
4536 @section Character Translations
4537 @cindex character translations
4538 @cindex translations of characters
4542 @cindex control character
4543 @cindex character, control
4544 @cindex no-break control character
4545 @cindex character, no-break control
4546 @cindex control character, no-break
4547 The control character (@samp{.}) and the no-break control character
4548 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
4551 @Deffn{Request, cc, [@var{c}]}
4552 Set the control character to @var{c}. With no argument the default
4553 control character @samp{.} is restored. The value of the control
4554 character is associated with the current environment
4555 (@pxref{Environments}).
4558 @Deffn{Request, c2, [@var{c}]}
4559 Set the no-break control character to @var{c}. With no argument the
4560 default control character @samp{'} is restored. The value of the
4561 no-break control character is associated with the current environment
4562 (@pxref{Environments}).
4566 @Deffn{Request, eo, }
4567 Disable the escape mechanism completely. After executing this request,
4568 the backslash character @samp{\} no longer starts an escape sequence.
4571 @cindex escape character
4572 @cindex character, escape
4573 @Deffn{Request, ec, [@var{c}]}
4574 Set the escape character to @var{c}. With no argument the default
4575 escape character @samp{\} is restored. It can be also used to re-enable
4576 the escape mechanism after an @code{eo} request.
4578 Note that changing the escape character globally will likely break macro
4579 packages since @code{gtroff} has no mechanism (like @TeX{}) to `intern'
4580 macros, i.e., to convert a macro definition into an internal form which
4581 is independent of its representation. If a macro is called, it will be
4585 @Deffn{Escape, \\e, }
4586 This escape sequence prints the current escape character (which is the
4587 backslash character @samp{\} by default).
4590 A @dfn{translation} is a mapping of an input character to an output
4591 character. The default mappings are given in the font definition files
4592 for the specific output device (@pxref{Font Files}); all mappings (both
4593 with @code{tr} and in the font definition files) occur at output time,
4594 i.e., the input character gets assigned the metric information of the
4595 mapped output character.
4597 @Deffn{Request, tr, @var{a}@var{b}@var{c}@var{d}@dots{}}
4598 Translate character @var{a} to @var{b}, character @var{c} to @var{d},
4599 etc. If there is an odd number of arguments, the last one will be
4600 translated to the space character.
4615 @cindex special character
4616 @cindex character, special
4617 @cindex numbered character
4618 @cindex character, numbered
4619 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
4620 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
4621 characters defined with the @code{char} request, and numbered characters
4622 (@code{\N'@var{xxx}'}) can be translated also.
4626 The @code{\e} escape can be translated also.
4630 Characters can be mapped onto the @code{\%} escape (but @code{\%} can't
4631 be mapped onto another character).
4634 @cindex backspace character
4635 @cindex character, backspace
4636 @cindex leader character
4637 @cindex character, leader
4638 @cindex newline character
4639 @cindex character, newline
4640 @cindex tab character
4641 @cindex character, tab
4644 The following characters can't be translated: space (with one exception,
4645 see below), backspace, newline, leader (and @code{\a}), tab (and
4650 Translations are not considered for finding the soft hyphen character
4651 set with the @code{shc} request.
4655 The character pair @samp{@var{c}\&} (this is an arbitrary character@w{
4656 }@var{c} followed by the zero width space character) will map this
4657 character to nothing.
4666 It is even possible to map the space character to nothing:
4675 As shown in the example, the space character can't be the first
4676 character pair as an argument of @code{tr}. Additionally, it is not
4677 possible to map the space character to any other character; requests
4678 like @w{@samp{.tr aa x}} will undo @w{@samp{.tr aa \&}} instead.
4680 If justification is active, lines will be justified inspite of the
4681 `empty' space character (but there is no minimal distance, i.e.@: the
4682 space character, between words).
4685 After an output character has been constructed (this happens at the
4686 moment immediately before the character is appended to an output
4687 character list, either by direct output, in a macro, diversion, or
4688 string), it is no longer affected by @code{tr}.
4693 Without an argument, the @code{tr} request is ignored.
4699 @Deffn{Request, trnt, @var{a}@var{b}@var{c}@var{d}@dots{}}
4700 @code{trnt} is the same as the @code{tr} request except that the
4701 translations do not apply to text that is transparently throughput into
4702 a diversion with @code{\!}. @xref{Diversions}, for more information.
4715 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it will
4720 @c =====================================================================
4722 @node Troff and Nroff Mode, Line Layout, Character Translations, Programming Tutorial
4723 @section Troff and Nroff Mode
4729 Originally, @code{nroff} and @code{troff} were two separate programs,
4730 the former for tty output, the latter for everything else. With GNU
4731 @code{troff}, both programs are merged into one executable.
4733 Usually, a macro package can be used with both @code{nroff} and
4734 @code{troff}. Nevertheless, it is sometimes necessary to make a
4735 distinction between the two programs (resp.@: modes), and @code{gtroff}
4736 provides two built-in conditions @samp{n} and @samp{t} for the
4737 @code{if}, @code{ie}, and @code{while} requests to decide whether
4738 @code{gtroff} shall behave like @code{nroff} or like @code{troff}.
4742 @Deffn{Request, troff, }
4743 Make the @samp{t} built-in condition true (and the @samp{n} built-in
4744 condition false) for @code{if}, @code{ie}, and @code{while} conditional
4745 requests. This is the default if @code{gtroff} (@emph{not}
4746 @code{groff}) is started with the @option{-R} switch to avoid loading of
4747 the start-up files @file{troffrc} and @file{troffrc-end}. Without
4748 @option{-R}, @code{gtroff} stays in troff mode if the output device is
4749 not a tty (e.g.@: `ps').
4753 @Deffn{Request, nroff, }
4754 Make the @samp{n} built-in condition true (and the @samp{t} built-in
4755 condition false) for @code{if}, @code{ie}, and @code{while} conditional
4756 requests. This is the default if @code{gtroff} uses a tty output
4757 device; the code for switching to nroff mode is in the file
4758 @file{tmac.tty} which will be loaded by the start-up file
4762 @xref{Conditionals and Loops}, for more details on built-in conditions.
4765 @c =====================================================================
4767 @node Line Layout, Page Layout, Troff and Nroff Mode, Programming Tutorial
4768 @section Line Layout
4770 @cindex layout, line
4772 @cindex dimensions, line
4773 @cindex line dimensions
4774 The following drawing shows the dimensions which @code{gtroff} uses for
4775 placing a line of output onto the page. They are labeled with the
4776 request which manipulates that dimension.
4781 |<-----------ll------------>|
4782 +----+----+----------------------+----+
4784 +----+----+----------------------+----+
4786 |<--------paper width---------------->|
4791 These dimensions are:
4796 @cindex margin, left
4798 @cindex offset, page
4799 @dfn{Page offset} -- This is the leftmost position of text on the final
4800 output, defining the @dfn{left margin}.
4804 @cindex line indentation
4805 @dfn{Indentation} -- This is the distance from the left margin where
4806 text will be printed.
4810 @cindex length of line
4811 @dfn{Line length} -- This is the distance from the left margin to right
4815 @c XXX improve example
4820 A bunch of really boring text which should
4821 be indented from both margins.
4822 Replace me with a better (and more) example!
4831 @Deffn{Request, po, [@var{offset}]}
4832 @Deffnx{Request, po, +offset}
4833 @Deffnx{Request, po, -offset}
4834 Set horizontal page offset to @var{offset} (resp.@: increment or
4835 decrement the current value by @var{offset}). Note that this request
4836 does not cause a break, so changing the page offset in the middle of
4837 text being filled may not yield the expected result. The initial value
4838 is 1@dmn{i} if in troff mode, and 0 if in nroff mode (@pxref{Troff and
4839 Nroff Mode}); the default scaling indicator is@w{ }@code{m} (and not@w{
4840 }@code{v} as incorrectly documented in the original @acronym{UNIX} troff
4844 The current page offset can be found in the built-in number register
4847 If @code{po} is called without an argument, the page offset is reset to
4848 the previous value before the last call to @code{po}.
4863 @Deffn{Request, in, [@var{indent}]}
4864 @Deffnx{Request, in, +indent}
4865 @Deffnx{Request, in, -indent}
4866 Set indentation to @var{indent} (resp.@: increment or decrement the
4867 current value by @var{indent}). This request causes a break.
4868 Initially, there is no indentation.
4870 If @code{in} is called without an argument, the indentation is reset to
4871 the previous value before the last call to @code{in}. The default
4872 scaling indicator is@w{ }@code{m}.
4874 The indentation is associated with the current environment.
4876 If a negative indentation value is specified (which is not allowed),
4877 @code{gtroff} emits a warning of type @samp{range} and sets the
4878 indentation to zero.
4880 The effect of @code{in} is delayed until a partially collected line (if
4881 it exists) is output.
4884 The current indentation (as set by @code{in}) can be found in the
4885 built-in number register @samp{.i}.
4888 @Deffn{Request, ti, offset}
4889 @Deffnx{Request, ti, +offset}
4890 @Deffnx{Request, ti, -offset}
4891 Temporarily indent the next output line by @var{offset}. If an
4892 increment or decrement value is specified, adjust the temporary
4893 indentation relative to the value set by the @code{in} request.
4895 This request causes a break; its value is associated with the current
4896 environment. The default scaling indicator is@w{ }@code{m}. A call of
4897 @code{ti} without an argument is ignored.
4899 If the total indentation value is negative (which is not allowed),
4900 @code{gtroff} emits a warning of type @samp{range} and sets the
4901 temporary indentation to zero. `Total indentation' is either
4902 @var{offset} if specified as an absolute value, or the temporary plus
4903 normal indentation, if @var{offset} is given as a relative value.
4905 The effect of @code{ti} is delayed until a partially collected line (if
4906 it exists) is output.
4909 The number register @code{.in} is the indentation that applies to the
4910 current output line.
4912 The difference between @code{.i} and @code{.in} is that the latter takes
4913 into account whether a partially collected line still uses the old
4914 indentation value resp.@: a temporary indentation value is active.
4917 @Deffn{Request, ll, [@var{length}]}
4918 @Deffnx{Request, ll, +length}
4919 @Deffnx{Request, ll, -length}
4920 Set the line length to @var{length} (resp.@: increment or decrement the
4921 current value by @var{length}). Initially, the line length is set to
4922 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
4923 collected line (if it exists) is output. The default scaling indicator
4926 If @code{ll} is called without an argument, the line length is reset to
4927 the previous value before the last call to @code{ll}. If a negative
4928 line length is specified (which is not allowed), @code{gtroff} emits a
4929 warning of type @samp{range} and sets the line length to zero.
4931 The line length is associated with the current environment.
4935 The current line length (as set by @code{ll}) can be found in the
4936 built-in number register @code{.l}. The number register @code{.ll} is
4937 the line length that applies to the current output line.
4939 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
4940 and @code{.ll} is that the latter takes into account whether a partially
4941 collected line still uses the old line length value.
4945 @c =====================================================================
4947 @node Page Layout, Page Control, Line Layout, Programming Tutorial
4948 @section Page Layout
4950 @cindex layout, page
4952 @code{gtroff} provides some very primitive operations for controlling
4956 @cindex length of page
4957 @Deffn{Request, pl, [@var{length}]}
4958 @Deffnx{Request, pl, +length}
4959 @Deffnx{Request, pl, -length}
4960 Set the @dfn{page length} to @var{length} (resp.@: increment or
4961 decrement the current value by @var{length}). This is the length of the
4962 physical output page. The default scaling indicator is@w{ }@code{v}.
4965 The current setting can be found in the built-in number register
4970 @cindex bottom margin
4971 @cindex margin, bottom
4972 Note that this only specifies the size of the page, not the top and
4973 bottom margins. Those are not set by groff directly. @xref{Traps}, for
4974 further information on how to do this.
4976 @c XXX negative .pl values
4983 @code{gtroff} provides several operations which help in setting up top
4984 and bottom titles (or headers and footers)
4987 @cindex three-part title
4990 The @code{tl} request will print a @dfn{title line}, which consists of
4991 three parts: a left justified portion, a centered portion and a right
4992 justified portion. The argument to @code{tl} is specified as
4993 @code{'@var{left}'@var{center}'@var{right}'}. The @samp{%} character is
4994 replaced with the current page number. This character can be changed
4995 with the @code{pc} request (see below).
4997 @cindex length of title line
4998 @cindex title line, length
5001 The title line is printed using its own line length, which is specified
5002 with the @code{lt} request. The current setting of this is available in
5003 the @code{.lt} number register.
5006 @cindex number, page
5008 The @code{pn} request will change the page number of the @emph{next}
5009 page. The only argument is the page number.
5013 The current page number is stored in the number register @code{%}. The
5014 number register @code{.pn} contains the number of the next page: either
5015 the value set by a @code{pn} request, or the number of the current page
5018 @cindex changing the page number character
5019 @cindex page number character, changing
5021 The @code{pc} request will change the page number character (used by the
5022 @code{tl} request) to a different character. With no argument, this
5023 mechanism is disabled.
5028 @c =====================================================================
5030 @node Page Control, Fonts, Page Layout, Programming Tutorial
5031 @section Page Control
5032 @cindex page control
5033 @cindex control, page
5037 To stop processing the current page, and move to the next page, invoke
5038 the @code{bp} request. This request will also cause a break. It can
5039 also take an argument of what the next page should be numbered. The
5040 only difference between @code{bp} and @code{pn} is that @code{pn} does
5041 not cause a break or actually eject a page.
5047 .tl 'left top'center top'right top'
5054 It is often necessary to force a certain amount of space before a new
5055 page occurs. This is most useful to make sure that there is not a
5056 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
5057 request will ensure that there is a certain distance, specified by the
5058 first argument, before the next page is triggered (@pxref{Traps}, for
5059 further information). The default unit for @code{ne} is @code{v} and
5060 the default argument is@w{ }1@dmn{v}.
5062 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
5063 do the following before each paragraph:
5074 @code{sv} is similar to the @code{ne} request; it reserves the specified
5075 amount of vertical space. If the desired amount of space exists before
5076 the next trap (bottom page boundary), the space will be output
5077 immediately. If there is not enough space, it is stored for later
5078 output via the @code{os} request. The default argument is@w{ }1@dmn{v}
5079 and the default unit is @code{v}.
5082 @c =====================================================================
5084 @node Fonts, Sizes, Page Control, Programming Tutorial
5090 @code{gtroff} has the ability to switch fonts at any point in the text.
5091 There are two ways to do this, via the @code{ft} request and the
5094 Fonts are generally specified as upper-case strings, which are usually
5095 1@w{ }to 4 characters representing an abbreviation or acronym of the font
5098 The basic set of fonts are @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
5099 These are Times Roman, Italic, Bold, and Bold Italic. There is also at
5100 least one symbol font which contains various special symbols (Greek,
5101 mathematics). Such symbols fonts cannot be used directly, but should be
5109 * Artificial Fonts::
5110 * Ligatures and Kerning::
5113 @c ---------------------------------------------------------------------
5115 @node Changing Fonts, Font Families, Fonts, Fonts
5116 @subsection Changing Fonts
5117 @cindex changing fonts
5118 @cindex fonts, changing
5121 @cindex previous font
5122 @cindex font, previous
5123 Font changes can be done either with the @code{ft} request or the
5124 @code{\f} request. With no arguments it will switch to the previous
5125 font (also known as @samp{P}).
5136 The @code{\f} escape is useful for changing fonts in the middle of
5140 eggs, bacon, \fBspam\fP and sausage.
5144 Both of the above examples will produce the same output. Note the usage
5145 of @samp{P} to indicate the previous font -- using @code{\f} it is not
5146 possible to omit this parameter.
5148 Sometimes when putting letters of different fonts, more or less space at
5149 such boundaries are needed. There are two escapes to help with this.
5152 @cindex italic correction
5153 @cindex correction, italic
5154 The @code{\/} escape increases the width of the preceding character so
5155 that the spacing between that character and the following character will
5156 be correct if the following character is a Roman character. For
5157 example, if an italic@w{ }f is immediately followed by a Roman right
5158 parenthesis, then in many fonts the top right portion of the f will
5159 overlap the top left of the right parenthesis. It is a good idea to use
5160 this escape sequence whenever an italic character is immediately
5161 followed by a Roman character without any intervening space. This small
5162 amount of space is also called @dfn{italic correction}.
5165 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids
5169 @cindex left italic correction
5170 @cindex correction, left italic
5171 The @code{\,} escape modifies the spacing of the following character so
5172 that the spacing between that character and the preceding character will
5173 be correct if the preceding character is a Roman character. It is a
5174 good idea to use this escape sequence whenever a Roman character is
5175 immediately followed by an italic character without any intervening
5176 space. In analogy to above, this space could be called @dfn{left italic
5177 correction}, but this term isn't used widely.
5180 @c For example, inserting \, between the parenthesis and the f changes
5194 The @code{ftr} request will translate fonts; its syntax is
5197 .ftr @var{F} @var{G}
5201 which translates font@w{ }@var{F} to font@w{ }@var{G}. Whenever a font
5202 named @var{F} is referred to in a @code{\f} escape sequence, or in the
5203 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
5204 @code{fspecial}, @code{fp}, or @code{code} requests, font@w{ }@var{G} will
5205 be used. If @var{G} is missing, or equal to @var{F} then font@w{
5206 }@var{F} will not be translated.
5208 @c ---------------------------------------------------------------------
5210 @node Font Families, Font Positions, Changing Fonts, Fonts
5211 @subsection Font Families
5212 @cindex font families
5213 @cindex families, font
5215 Due to the variety of fonts available, @code{gtroff} has added the
5216 concept of font families. Each of these families has four styles
5217 (@samp{R}, @samp{I}, @samp{B} and @samp{BI}).
5219 The fonts are specified as the concatenation of the font family and
5220 style. Specifying a font without the family part will cause
5221 @code{gtroff} to use that style of the current family. By default,
5222 @code{gtroff} uses the Times family.
5224 This way, it is possible to use the basic four fonts and to select a
5225 different font family on the command line.
5229 Font families can be switched with the @code{fam} request. The current
5230 font family is available in the number register @code{.fam}. This is a
5231 string-valued register.
5247 @c ---------------------------------------------------------------------
5249 @node Font Positions, Using Symbols, Font Families, Fonts
5250 @subsection Font Positions
5251 @cindex font positions
5252 @cindex positions, font
5254 For the sake of old phototypesetters and compatability with old versions
5255 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
5256 on which various fonts are mounted. The last one or two are reserved
5257 for the symbol font(s).
5260 New fonts can be mounted with the @code{fp} request. These numeric
5261 positions can then be referred to with font changing commands. When
5262 @code{gtroff} starts it is using font number one.
5278 Note that after these font changes have taken place the original font
5282 The current font in use, as a font position, is available in number
5283 register @code{.f}. This can be useful to remember the current font,
5288 ... lots 'o text ...
5293 The number of the next free font position is available in the number
5294 register @code{.fp}. This is useful when mounting a new font, like so:
5297 .fp \n[.fp] NEATOFONT
5301 Fonts not listed in the @file{DESC} file are automatically mounted on
5302 the next available font position when they are referenced. If a font is
5303 to be mounted explicitly with the @code{fp} request on an unused font
5304 position, it should be mounted on the first unused font position, which
5305 can be found in the @code{.fp} register. Although @code{gtroff} does
5306 not enforce this strictly, it will not allow a font to be mounted at a
5307 position whose number is much greater than that of any currently used
5311 The @code{fp} request has an optional third argument. This argument
5312 gives the external name of the font, which is used for finding the font
5313 description file. The second argument gives the internal name of the
5314 font which is used to refer to the font in @code{gtroff} after it has
5315 been mounted. If there is no third argument then the internal name will
5316 be used as the external name. This feature make it possible to use
5317 fonts with long names in compatibility mode.
5319 @c ---------------------------------------------------------------------
5321 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
5322 @subsection Using Symbols
5323 @cindex using symbols
5324 @cindex symbols, using
5328 Symbols can be inserted by using a special escape sequence. This escape
5329 is simply the escape character (usually a backslash) followed by an
5330 identifier. The symbol identifiers have to be two or more characters,
5331 since single characters conflict with all the other escapes. The
5332 identifier can be either preceded by a parenthesis if it is two
5333 characters long, or surrounded by square brackets. So, the symbol for
5334 the mathematical Greek letter `pi' can be produced either by @code{\(*p}
5338 area = \(*p\fIr\fP\u2\d
5342 The escape @code{\C'@var{xxx}'} will typeset the character named
5343 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
5344 But @code{\C} has the advantage that it is compatible with recent
5345 versions of @code{ditroff} and is available in compatibility mode.
5349 The escape @code{\N'@var{n}'} will typeset the character with code@w{
5350 }@var{n} in the current font. @var{n} can be any integer. Most devices
5351 only have characters with codes between 0 and@w{ }255. If the current
5352 font does not contain a character with that code, special fonts will
5353 @emph{not} be searched. The @code{\N} escape sequence can be
5354 conveniently used on conjunction with the @code{char} request:
5357 .char \[phone] \f(ZD\N'37'
5362 @cindex unnamed characters
5363 @cindex characters, unnamed
5364 The code of each character is given in the fourth column in the font
5365 description file after the charset command. It is possible to include
5366 unnamed characters in the font description file by using a name of
5367 @samp{---}; the @code{\N} escape sequence is the only way to use these.
5369 @c XXX should be `glyph', not `character'
5372 @cindex character properties
5373 @cindex properties of characters
5374 Each character has certain properties associated with it. These
5375 properties can be modified with the @code{cflags} request. The first
5376 argument is the the sum of the desired flags and the remaining arguments
5377 are the characters to have those properties.
5381 @cindex end of sentence characters
5382 @cindex characters, end of sentence
5383 the character ends sentences (initially characters @samp{.?!} have this
5387 @cindex hyphenating characters
5388 @cindex characters, hyphenation
5389 lines can be broken before the character (initially no characters have
5395 lines can be broken after the character (initially the characters
5396 @samp{-\(hy\(em} have this property)
5399 @cindex overlapping characters
5400 @cindex characters, overlapping
5404 the character overlaps horizontally (initially the characters
5405 @samp{\(ul\(rn\(ru} have this property)
5409 the character overlaps vertically (initially character @samp{\(br} has
5413 @cindex transparent characters
5414 @cindex character, transparent
5422 an end of sentence character followed by any number of characters with
5423 this property will be treated as the end of a sentence if followed by a
5424 newline or two spaces; in other words the character is @dfn{transparent}
5425 for the purposes of end of sentence recognition -- this is the same as
5426 having a zero space factor in @TeX{} (initially characters
5427 @samp{"')]*\(dg\(rq} have this property).
5431 @cindex defining characters
5432 @cindex characters, defining
5433 New characters can be created with the @code{char} request. It is
5437 .char @var{c} @var{string}
5446 This defines character@w{ }@var{c} to be @var{string}. Every time
5447 character@w{ }@var{c} needs to be printed, @var{string} will be
5448 processed in a temporary environment and the result will be wrapped up
5449 into a single object. Compatibility mode will be turned off and the
5450 escape character will be set to @samp{\} while @var{string} is being
5451 processed. Any emboldening, constant spacing or track kerning will be
5452 applied to this object rather than to individual characters in
5453 @var{string}. A character defined by this request can be used just like
5454 a normal character provided by the output device. In particular other
5455 characters can be translated to it with the @code{tr} request; it can be
5456 made the leader character by the @code{lc} request; repeated patterns
5457 can be drawn with the character using the @code{\l} and @code{\L} escape
5458 sequences; words containing the character can be hyphenated correctly,
5459 if the @code{hcode} request is used to give the character a hyphenation
5460 code. There is a special anti-recursion feature: use of character
5461 within the character's definition will be handled like normal characters
5462 not defined with @code{char}.
5465 @cindex removing character definition
5466 @cindex character, removing definition
5467 A character definition can be removed with the @code{rchar} request.
5468 Its arguments are the characters to be removed. This undoes the effect
5469 of a @code{char} request.
5471 @xref{Special Characters}.
5473 @c ---------------------------------------------------------------------
5475 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
5476 @subsection Artificial Fonts
5477 @cindex artificial fonts
5478 @cindex fonts, artificial
5480 There are a number of requests for artificially creating fonts. These
5481 are largely vestigial remains from the days when output devices did not
5482 have a wide variety of fonts, and when @code{nroff} and @code{troff}
5483 were separate programs. These are no longer necessary in GNU
5488 The @code{ul} request will print subsequent lines in italics on a device
5489 capable of it, or underline the text on an character output device. The
5490 single argument is the number of lines to be ``underlined,'' with no
5491 argument, the next line will be underlined.
5494 @cindex continuous underlining
5495 @cindex underlining, continuous
5496 The @code{cu} request is similar to @code{ul} ...
5501 @cindex underline font
5502 @cindex font for underlining
5503 The @code{uf} request will set the underline font used by @code{ul} and
5507 @cindex imitating bold face
5508 @cindex bold face, imitating
5509 The @code{bd} request artificially creates a bold font by printing each
5510 character twice, slightly offset. The first argument specifies the font
5511 to embolden, and the second is the number of basic units, minus one, by
5512 which the two characters will be offset. If the second argument is
5513 missing, emboldening will be turned off.
5515 @c ---------------------------------------------------------------------
5517 @node Ligatures and Kerning, , Artificial Fonts, Fonts
5518 @subsection Ligatures and Kerning
5519 @cindex ligatures and kerning
5520 @cindex kerning and ligatures
5528 The ligature mechanism can be switched on or off with the @code{lg}
5529 request; if the parameter is non-zero or missing, ligatures are enabled,
5530 otherwise disabled. Default is on. The current ligature mode can be
5531 found in the number register @code{.lg} (set to@w{ }1 if ligatures are
5532 enabled, 0@w{ }otherwise).
5538 @cindex zero width space character
5539 @cindex character, zero width space
5540 @cindex space character, zero width
5541 If the font description file contains pairwise kerning information,
5542 characters from that font will be kerned. Kerning between two
5543 characters can be inhibited by placing @code{\&} between them.
5547 Kerning can be activated with the @code{kern} request. If the parameter
5548 is non-zero or missing, enable pairwise kerning, otherwise disable it.
5549 The number register @code{.kern} is set to@w{ }1 if pairwise kerning is
5550 enabled, 0@w{ }otherwise.
5553 @cindex track kerning
5554 @cindex kerning, track
5555 What is track kerning?
5559 Track kerning must be used with great care since it is usually
5560 considered bad typography if the reader notices the effect. The syntax
5561 of the @code{tkf} request is
5564 .tkf @var{f} @var{s1} @var{n1} @var{s2} @var{n2}
5568 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
5569 }@var{f} the width of every character will be increased by an amount
5570 between @var{n1} and @var{n2}; if the current point size is less than or
5571 equal to @var{s1} the width will be increased by @var{n1}; if it is
5572 greater than or equal to @var{s2} the width will be increased by
5573 @var{n2}; if the point size is greater than or equal to @var{s1} and
5574 less than or equal to @var{s2} the increase in width is a linear
5575 function of the point size.
5578 @c =====================================================================
5580 @node Sizes, Strings, Fonts, Programming Tutorial
5586 @cindex size of type
5587 @cindex vertical spacing
5588 @cindex spacing, vertical
5589 @code{gtroff} uses two dimensions with each line of text, type size and
5590 vertical spacing. The @dfn{type size} is the height from the text
5591 @dfn{baseline} to the top of the tallest character (descenders may drop
5592 below this baseline). @dfn{Vertical spacing} is the amount of space
5593 @code{gtroff} allows for a line of text; normally, this is about 20%@w{
5594 }larger than the current type size. Ratios smaller than this can result
5595 in hard-to-read text; larger that this, it will spread the text out more
5596 vertically (useful for term papers). By default, @code{gtroff} uses
5597 10@w{ }point type on 12@w{ }point spacing.
5600 The difference between type size and vertical spacing is known, by
5601 typesetters, as @dfn{leading}.
5604 * Changing Type Sizes::
5605 * Fractional Type Sizes::
5608 @c ---------------------------------------------------------------------
5610 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
5611 @subsection Changing Type Sizes
5612 @cindex changing type sizes
5613 @cindex type sizes, changing
5620 Using the @code{ps} request and the @code{\s} escape the type size can
5621 be changed. The @code{vs} request will change the vertical spacing.
5622 The default unit for the @code{ps} and @code{vs} requests are points.
5623 The number registers @code{.s} and @code{.v} contain the current type
5624 size and vertical spacing.
5626 These requests take parameters in units of points. It is possible to
5627 specify sizes as an absolute size, or as a relative change from the
5628 current size. The size@w{ }0 means go back to the previous size. With
5629 no argument it will also revert to the previous size.
5636 wink, wink, \s+2nudge, nudge,\s+8 say no more!
5640 The @code{\s} escape may be called in a variety of ways. Much like
5641 other escapes there must be a way to determine where the argument ends
5642 and the text begins. Any of the following forms are valid:
5646 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 0
5647 or in the range 4 to@w{ }39.
5651 Increase resp.@: decrease the point size by @var{n}@w{ }points.
5652 @var{n}@w{ }must be exactly one digit.
5655 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly two
5662 Increase resp.@: decrease the point size by @var{nn}@w{ }points.
5663 @var{nn} must be exactly two digits.
5666 @xref{Fractional Type Sizes}, for yet another syntactical form of using
5667 the @code{\s} escape.
5669 Some devices may only have certain permissible sizes, in which case
5670 @code{gtroff} will round to the nearest permissible size.
5675 ... .sz macro example?? ...
5678 @c ---------------------------------------------------------------------
5680 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
5681 @subsection Fractional Type Sizes
5682 @cindex fractional type sizes
5683 @cindex type sizes, fractional
5685 @cindex @code{s} unit
5686 @cindex unit, @code{s}
5687 @cindex @code{z} unit
5688 @cindex unit, @code{z}
5694 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
5695 @var{sizescale} is specified in the @file{DESC} file (1@w{ }by default.)
5696 There is a new scale indicator @samp{z} which has the effect of
5697 multiplying by @var{sizescale}. Requests and escape sequences in
5698 @code{gtroff} interpret arguments that represent a point size as being in
5699 units of scaled points, but they evaluate each such argument using a
5700 default scale indicator of @samp{z}. Arguments treated in this way are
5701 the argument to the @code{ps} request, the third argument to the
5702 @code{cs} request, the second and fourth arguments to the @code{tkf}
5703 request, the argument to the @code{\H} escape sequence, and those
5704 variants of the @code{\s} escape sequence that take a numeric expression
5705 as their argument (see below).
5707 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
5708 will be equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
5709 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 10250
5710 scaled points, which is equal to 10.25@w{ }points.
5712 It would make no sense to use the @samp{z} scale indicator in a numeric
5713 expression whose default scale indicator was neither @samp{u} nor
5714 @samp{z}, and so @code{gtroff} disallows this. Similarly it would make
5715 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
5716 numeric expression whose default scale indicator was @samp{z}, and so
5717 @code{gtroff} disallows this as well.
5719 There is also new scale indicator @samp{s} which multiplies by the
5720 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
5721 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
5726 The number register @code{.s} returns the point size in points as decimal
5727 fraction. There is also a new number register @code{.ps} that returns
5728 the point size in scaled points.
5732 The last-requested point size in scaled points is contained in the
5733 @code{.psr} number register. The last requested point size in points as
5734 a decimal fraction can be found in @code{.psr}. This is a string-valued
5740 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
5741 expression with a default scale indicator of @samp{z}.
5751 Increases resp.@: decreases the point size by @var{n} scaled points;
5752 @var{n} is a numeric expression with a default scale indicator of
5759 @c =====================================================================
5761 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
5766 @code{gtroff} has string variables, which are entirely for user
5767 convenience (i.e.@: there are no built-in strings). They are defined
5768 via the @code{ds} request.
5771 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
5775 @cindex string interpolation
5776 @cindex string expansion
5777 @cindex interpolation of strings
5778 @cindex expansion of strings
5779 They are interpolated, or expanded in-place, via the @code{\*} escape:
5782 The \*(UX Operating System
5785 If the string named by the @code{\*} does not exist, the escape will be
5786 replaced by nothing.
5788 @cindex comments, with @code{ds}
5789 @strong{Caution:} Unlike other requests, the second argument to the
5790 @code{ds} request takes up the entire line including trailing spaces.
5791 This means that comments on a line with such a request can introduce
5792 unwanted space into a string.
5795 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
5799 Instead the comment should be put on another line or have the comment
5800 escape adjacent with the end of the string.
5803 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
5806 @cindex trailing quotes
5807 @cindex quotes, trailing
5808 @cindex leading spaces with @code{ds}
5809 @cindex spaces with @code{ds}
5810 To produce leading space the string can be started with a double quote.
5811 No trailing quote is needed; in fact, any trailing quote is included in
5815 .ds sign " Yours in a white wine sauce,
5819 @cindex appending to strings
5820 @cindex strings, appending
5821 The @code{as} request will append a string to another string. It works
5822 similar to the @code{ds} request except that it appends the second
5823 argument onto the string named by the first argument.
5826 .as sign " with shallots, onions and garlic,
5830 @cindex multi-line strings
5831 @cindex strings, multi-line
5832 @cindex newline character, escaping
5833 @cindex escaping newline characters
5834 Strings are not limited to a single line of text. A string can span
5835 several lines by escaping the newlines with a backslash. The resulting
5836 string will be stored @emph{without} the newlines.
5839 .ds foo lots and lots \
5840 of text are on these \
5846 Rudimentary string manipulation routines are given with the
5847 @code{substring} and @code{length} requests. The former has the
5851 .substring @var{xx} @var{n1} [@var{n2}]
5855 It replaces the string in register@w{ }@var{xx} with the substring
5856 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
5857 in the string has index one. If @var{n2} is omitted, it is taken to be
5858 equal to the string's length. If the index value @var{n1} or @var{n2}
5859 is negative or zero, it will be counted from the end of the string,
5860 going backwards: The last character has index@w{ }0, the character
5861 before the last character has index@w{ }-1, etc.
5864 @cindex length of a string
5865 @cindex string, length of
5866 Here the syntax of the @code{length} request:
5869 .length @var{xx} @var{string}
5873 It computes the length of @var{string} and returns it in the number
5874 register@w{ }@var{xx} (which is not necessarily defined before).
5896 @xref{Identifiers}, and @ref{Comments}.
5899 @c =====================================================================
5901 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
5902 @section Conditionals and Loops
5903 @cindex conditionals and loops
5904 @cindex loops and conditionals
5908 In @code{if} and @code{while} requests, there are several more operators
5914 True if the current page is even or odd numbered (respectively).
5918 True if the document is being processed in nroff mode.
5922 True if the document is being processed in troff mode.
5924 @item '@var{xxx}'@var{yyy}'
5925 True if the string @var{xxx} is equal to the string @var{yyy}. Other
5926 characters can be used in place of the single quotes.
5928 The strings are `formatted' before being compared.
5932 True if there is a number register named @var{xxx}.
5935 True if there is a string, macro, diversion, or request named @var{xxx}.
5939 True if there is a character @var{ch} available; @var{ch} is either an
5940 @acronym{ASCII} character or a special character (@code{\(@var{ch}} or
5941 @code{\[@var{ch}]}); the condition will also be true if @var{ch} has
5942 been defined by the @code{char} request.
5950 @c ---------------------------------------------------------------------
5952 @node if-else, while, Conditionals and Loops, Conditionals and Loops
5956 @code{gtroff} has if-then-else constructs like other languages, although
5957 the formatting can be painful.
5960 The @code{if} request has the following syntax:
5963 .if @var{expr} @var{anything}
5967 where @var{expr} is the expression to be evaluated; @var{anything} (the
5968 remainder of the line) will be executed if @var{expr} evaluates to
5969 non-zero (true). @var{anything} will be interpreted as though it was on
5970 a line by itself. @xref{Expressions}, for more info.
5972 Here are some examples:
5975 .if t .ls 2 \" double spacing in troff
5976 .if 0 .ab how'd this happen?
5981 An if-then-else is written using two requests @code{ie} and @code{el}.
5982 The first request is the `if' part and the latter is the `else' part.
5993 In many cases more than one request is to be executed as a result of any
5994 of these requests. This can be done using the @code{\@{} and @code{\@}}
5995 escapes. The following example shows the possible ways to use these
5996 escapes (note the position of the opening and closing braces).
6012 @c ---------------------------------------------------------------------
6014 @node while, , if-else, Conditionals and Loops
6019 @code{gtroff} provides a looping construct using the @code{while}
6020 request, which is used much like the @code{if} (and related) requests.
6021 The first argument is an expression which will be evaluated. The
6022 @code{while} request will interpret the remainder of the line until the
6023 expression evaluates to 0 or false.
6027 .while (\na<9) \&\n+a,
6032 The preceding example produces:
6035 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
6038 @cindex zero width space character
6039 @cindex character, zero width space
6040 @cindex space character, zero width
6043 Note the usage of the @code{\&} escape to avoid a control character at
6044 the beginning of a line.
6048 The @code{break} request will @dfn{break} out of a while loop. Be sure
6049 not to confuse this with the @code{br} request (causing a line break).
6050 The @code{continue} request will finish the current iteration of a while
6051 loop, immediately restarting the next iteration.
6056 @c =====================================================================
6058 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
6059 @section Writing Macros
6060 @cindex writing macros
6061 @cindex macros, writing
6064 A @dfn{macro} is a collection of text and embedded commands which can be
6065 invoked multiple times. Macros are used for defining common operations.
6066 Macros are defined using the @code{de} request. This request takes a
6067 name for the macro as the first argument. Subsequent lines are copied
6068 into an internal buffer until the line @code{..} is encountered. The
6069 optional second argument to @code{de} can change this ending token.
6071 Here a small example macro called @samp{P} which will cause a break and
6072 the insertion of some vertical space. It could be used to separate
6083 The @code{am} request works similarly to @code{de} except it appends
6084 onto the macro named by the first argument. So, to make the previously
6085 defined @samp{P} macro actually do indented instead of block paragraphs,
6086 is is possible to add the necessary code to the existing macro like
6096 @cindex aliases, macro
6097 @cindex macro aliases
6098 Macros can be aliased with the @code{als} request.
6107 @c ---------------------------------------------------------------------
6109 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
6110 @subsection Copy-in Mode
6111 @cindex copy-in mode
6112 @cindex mode, copy-in
6119 When @code{gtroff} reads in the text for a macro or diversion it copies
6120 the text (including request lines, but excluding escapes) into an
6121 internal buffer. Escapes will be converted into an internal form,
6122 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
6123 @code{\@key{RET}} which are evaluated and inserted into the text where
6124 the escape was located. This is known as @dfn{copy-in} mode or
6127 What this means is that you can specify when these escapes are to be
6128 evaluated (either at copy-in time or at the time of use) by insulating
6129 the escapes with an extra backslash. Compare this to the @code{\def}
6130 and @code{\edef} commands in @TeX{}.
6132 For example, the following will result in the numbers 20 and@c{ }10
6145 @c ---------------------------------------------------------------------
6147 @node Parameters, , Copy-in Mode, Writing Macros
6148 @subsection Parameters
6153 The arguments to a macro can be examined using a variety of escapes.
6154 The number of arguments is available in the @code{.$} number register.
6155 Any individual argument can be retrieved with one of the following
6158 @cindex copy-in mode
6159 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
6160 @code{\$[@var{nnn}]} will result in the @var{n}th, @var{nn}th or
6161 @var{nnn}th argument. As usual, the first form only accepts a single
6162 number (larger than zero), the second only a two-digit number (larger or
6163 equal to@w{ }10), and the third any positive integer value (larger than
6164 zero). Macros can have an unlimited number of arguments. Note that due
6165 to copy-in mode, two backslashes should be used on these in actual use
6166 to prevent interpolation until the macro is actually invoked.
6169 The request @code{shift} will shift the arguments 1@w{ }position, or as
6170 many positions as specified by its argument. After executing this
6171 request, argument@w{ }@var{i} will become argument @var{i}-@var{n};
6172 arguments 1 to@w{ }@var{n} will no longer be available. Shifting by
6173 negative amounts is currently undefined.
6177 In some cases it is convenient to use all of the arguments at once (for
6178 example, to pass the arguments along to another macro). The @code{\$*}
6179 escape is the concatenation of all the arguments separated by spaces. A
6180 similar escape is @code{\$@@}, which is the concatenation of all the
6181 arguments with each surrounded by double quotes, and separated by
6186 The @code{\$0} escape is the name by which the current macro was
6187 invoked. The @code{als} request can make a macro have more than one
6192 .ie \\n(.$=1 .ds Vl Pre-Release Version
6193 .el .ds Vl Version \\$3, \\$4.
6197 This would be called as
6203 @xref{Request Arguments}.
6206 @c =====================================================================
6208 @node Page Motions, Drawing Requests, Writing Macros, Programming Tutorial
6209 @section Page Motions
6210 @cindex page motions
6211 @cindex motions, page
6214 Motions up and down the page can be done with the @code{sp} request.
6215 However, this causes a break so that the actual effect is to move to the
6216 left margin and then to the specified location.
6220 The request @code{mk} can be used to mark a location on a page, for
6221 movement to later. This request takes a register name as an argument in
6222 which to store the current page location. With no argument it will
6223 store the location in an internal register. The results of this can be
6224 used later by the @code{rt} or the @code{sp} request. The @code{rt}
6225 request will return @emph{upwards} to the location given in the register
6226 name given as an argument, with no argument it will return to the
6227 location marked with the @code{mk} request
6232 ... dual column example ...
6235 The following escapes give fine control of movements about the page.
6238 @cindex vertical motion
6239 @cindex motion, vertical
6240 The @code{\v'@var{e}'} enables arbitrary vertical motion from the
6241 current location on the page. The argument@w{ }@var{e} specifies the
6242 distance to move; positive is downwards and negative upwards. The
6243 default unit for this escape is vertical spaces, @code{v}'s. Beware,
6244 however, that @code{gtroff} will leave text processing to continue
6245 wherever the motion ends, so to avoid interference with text processing,
6246 motions should be balanced.
6248 There are some special case escapes for vertical motion.
6252 move upwards@w{ }1@dmn{v}.
6255 move upwards@w{ }.5@dmn{v}.
6258 move down@w{ }.5@dmn{v}.
6262 Horizontal motions can be done via the @code{\h'@var{e}'} escape. The
6263 expression@w{ }@var{e} indicates how far to move: positive is rightwards
6264 and negative leftwards.
6266 There are a number of special case escapes for horizontal motion:
6270 an unbreakable and unpaddable (i.e.@: not expanded during filling)
6271 space. (Note: It is a backslash followed by a space.)
6274 an unbreakable space that stretches like a normal inter-word space when a
6284 a space the size of a digit.
6287 @cindex zero width space character
6288 @cindex character, zero width space
6289 @cindex space character, zero width
6293 Like @code{\&} except that it behaves like a character declared with the
6294 @code{cflags} request to be transparent for the purposes of end of
6295 sentence recognition.
6301 ... tex logo example ...
6305 @cindex width escape
6306 @cindex escape, width
6307 A frequent need is to do horizontal movement based on the width of some
6308 arbitrary text (e.g.@: given as an argument to a macro). For that,
6309 there is the escape @code{\w'@var{text}'} which will interpolate to the
6310 width of the given @var{text} in basic units.
6315 ... strlen example ...
6318 Font changes may occur in @var{text} which don't affect current
6321 After use, @code{\w} sets several registers:
6328 The highest and lowest point, respectively, in @var{text}.
6334 Like the @code{st} and @code{sb} registers, but takes account of the
6335 heights and depths of characters.
6339 is set according to what kinds of characters occur in @var{text}:
6342 only short characters, no descenders or tall characters.
6351 both a descender and a tall character
6356 The amount of horizontal space (possibly negative) that should be added
6357 to the last character before a subscript.
6361 How far to right of the center of the last character in the @code{\w}
6362 argument, the center of an accent from a Roman font should be placed
6363 over that character.
6372 @c XXX documentation
6375 @c =====================================================================
6377 @node Drawing Requests, Traps, Page Motions, Programming Tutorial
6378 @section Drawing Requests
6379 @cindex drawing requests
6380 @cindex requests for drawing
6382 @code{gtroff} provides a number of ways to draw lines and other figures
6383 on the page. Used in combination with the page motion commands
6384 (@pxref{Page Motions}, for more info), a wide variety of figures can be
6385 drawn. However, for complex drawings these operations can be quite
6386 cumbersome, and it may be wise to use graphic preprocessors like
6387 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
6390 All drawing is done via escapes.
6393 @cindex horizontal line
6394 @cindex line, horizontal
6395 The @code{\l} escape will draw a line rightwards from the current
6396 location. The full syntax for this escape is
6403 where @var{l} is the length of the line to be drawn, starting at the
6404 current location; positive numbers will draw to the right, and negative
6405 will draw towards the left. This can also be specified absolutely
6406 (i.e.@: with a leading @samp{|}) which will draw back to the beginning
6409 @cindex underscore character
6410 @cindex character, underscore
6411 @cindex line drawing character
6412 @cindex character for line drawing
6413 The optional second parameter @var{c} is a character to draw the line
6414 with. If this second argument is not specified, @code{gtroff} will use
6415 the underscore character.
6417 @cindex zero width space character
6418 @cindex character, zero width space
6419 @cindex space character, zero width
6421 To separate the two arguments (to prevent @code{gtroff} from
6422 interpreting a drawing character as a scaling indicator) use @code{\&}.
6424 Here a small useful example:
6428 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
6434 Note that this works by outputting a box rule (a vertical line), then
6435 the text given as an argument and then another box rule. Then the line
6436 drawing escapes both draw from the current location to the beginning of
6437 the @emph{input} line.
6440 @cindex vertical line
6441 @cindex line, vertical
6442 @cindex line drawing character
6443 @cindex character for line drawing
6444 @cindex box rule character
6445 @cindex character, box rule
6446 Vertical lines are drawn using the @code{\L} escape. Its parameters are
6447 specified similar to the @code{\l} escape. If the length is positive,
6448 the movement will be downwards, and upwards for negative values. The
6449 default character is the box rule character. As with the vertical
6450 motion escapes, text processing will blindly continue where the line
6460 More flexible drawing functions are available via the @code{\D} escape.
6461 While the previous escapes will work on a character device, these
6465 @item \D'l @var{dx} @var{dy}'
6466 Draw a line from the current location to the relative point specified by
6467 (@var{dx},@var{dy}).
6472 ...revised box macro...
6477 Draw a circle with a diameter of @var{d} with the leftmost point at the
6481 Draw a solid circle with the same parameters as an outlined circle.
6483 @item \D'e @var{dx} @var{dy}'
6485 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
6486 diameter of @var{dy} with the leftmost point at the current position.
6488 @item \D'E @var{dx} @var{dy}'
6489 Draw a solid ellipse with the same parameters as an outlined ellipse.
6491 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
6493 Draw an arc clockwise from the current location through the two
6494 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
6496 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
6498 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
6499 then to (@var{dx2},@var{dy2}), and so on.
6502 @cindex gray shading
6504 Set the shade of gray to be used for filling solid objects to@w{
6505 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
6506 corresponds solid white and 1000 to solid black, and values in between
6507 correspond to intermediate shades of gray. This applies only to solid
6508 circles, solid ellipses and solid polygons. By default, a level of@w{
6511 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
6513 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
6514 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
6515 are exhausted, a line is drawn back to the starting point.
6520 ... box example (yes, again)...
6523 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
6524 Draw a solid polygon with the same parameters as an outlined polygon.
6529 ... shaded box example ...
6533 @cindex line thickness
6534 @cindex thickness of lines
6535 Set the current line thickness to @var{n} machine units. A value of
6536 zero selects the smallest available line thickness. A negative value
6537 makes the line thickness proportional to the current point size (this is
6538 the default behaviour of @code{ditroff}).
6542 @cindex pile, character
6543 @cindex character pile
6544 The @code{\b} escape will @dfn{pile} a sequence of characters
6545 vertically, and center it vertically on the current line. This can be
6546 used to build large brackets and braces.
6549 \b'\(lt\(bv\(lk\(bv\(lb'
6552 @xref{Drawing Functions}.
6555 @c =====================================================================
6557 @node Traps, Diversions, Drawing Requests, Programming Tutorial
6561 @dfn{Traps} are locations, which, when reached, will call a specified
6562 macro. These traps can occur at a given location on the page, at a
6563 given location in the current diversion, after a certain number of input
6564 lines or at the end of input.
6567 * Page Location Traps::
6569 * Input Line Traps::
6570 * End-of-input Traps::
6573 @c ---------------------------------------------------------------------
6575 @node Page Location Traps, Diversion Traps, Traps, Traps
6576 @subsection Page Location Traps
6577 @cindex page location traps
6578 @cindex traps, page location
6580 @c XXX definition of wh request
6582 @cindex page headers
6583 @cindex page footers
6586 Page location traps are frequently used for page headers and footers.
6587 The following is a simple example of this.
6590 .de hd \" Page header
6595 .de fo \" Page footer
6600 .wh 0 hd \" trap at top of the page
6601 .wh -1i fo \" trap one inch from bottom
6605 @cindex distance to next trap
6606 @cindex trap, distance
6607 The number register @code{.t} is the distance to the next trap.
6610 @cindex changing trap location
6611 @cindex trap, changing location
6612 The location of a trap can be changed later on with the @code{ch}
6613 request. The first argument is the name of the macro to be invoked at
6614 the trap, and the second argument is the new location for the trap.
6615 This is useful for building up footnotes in a diversion to allow more
6616 space at the bottom of the page for them.
6621 ... (simplified) footnote example ...
6628 The @code{vpt} request will enable vertical position traps if the
6629 argument is non-zero, disable them otherwise. Vertical position traps
6630 are traps set by the @code{wh} or @code{dt} requests. Traps set by the
6631 @code{it} request are not vertical position traps. The parameter that
6632 controls whether vertical position traps are enabled is global.
6633 Initially vertical position traps are enabled. The current setting of
6634 this is available in the number register @code{.vpt}.
6638 The number register @code{.trunc} contains the amount of vertical space
6639 truncated by the most recently sprung vertical position trap, or, if the
6640 trap was sprung by a @code{ne} request, minus the amount of vertical
6641 motion produced by the @code{ne} request. In other words, at the point
6642 a trap is sprung, it represents the difference of what the vertical
6643 position would have been but for the trap, and what the vertical
6644 position actually is.
6647 The number register @code{.ne} contains the amount of space that was
6648 needed in the last @code{ne} request that caused a trap to be sprung.
6649 Useful in conjunction with the @code{.trunc} register. @xref{Page
6650 Control}, for more information.
6652 @c ---------------------------------------------------------------------
6654 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
6655 @subsection Diversion Traps
6656 @cindex diversion traps
6657 @cindex traps, diversion
6661 Traps can also be set @emph{within} a diversion using the @code{dt}
6662 request. Like @code{wh} the first argument is the location of the trap
6663 and the second argument is the name of the macro to be invoked. The
6664 number register @code{.t} will still work within diversions.
6665 @xref{Diversions}, for more information.
6667 @c ---------------------------------------------------------------------
6669 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
6670 @subsection Input Line Traps
6671 @cindex input line traps
6672 @cindex traps, input line
6675 The @code{it} request will set an input line trap. The format for
6679 .it @var{n} @var{name}
6683 where @var{n} is the number of lines of input which may be read before
6684 @dfn{springing} the trap, @var{name} is the macro to be invoked.
6685 Request lines are not counted as input lines.
6687 For example, one possible use is to have a macro which will print the
6688 next @var{n}@w{ }lines in a bold font.
6700 @c ---------------------------------------------------------------------
6702 @node End-of-input Traps, , Input Line Traps, Traps
6703 @subsection End-of-input Traps
6704 @cindex end-of-input traps
6705 @cindex traps, end-of-input
6708 The @code{em} request will set a trap at the end of input. The macro
6709 specified as an argument will be executed after the last line of the
6710 input file has been processed.
6712 For example, if the document had to have a section at the bottom of the
6713 last page for someone to approve it, the @code{em} request could be
6731 @c =====================================================================
6733 @node Diversions, Environments, Traps, Programming Tutorial
6737 In @code{gtroff} it is possible to @dfn{divert} text into a named
6738 storage area. Due to the similarity to defining macros it is sometimes
6739 said to be stored in a macro. This is used for saving text for output
6740 at a later time, which is useful for keeping blocks of text on the same
6741 page, footnotes, tables of contents and indices.
6745 A diversion is initiated by the @code{di} request. Like the @code{de}
6746 request, it takes an argument of a macro name to divert subsequent text
6747 into. The @code{da} macro will append to an existing diversion.
6749 @code{di} (resp.@: @code{da}) without an argument ends the diversion.
6754 ... end-note example ...
6761 @cindex nested diversions
6762 @cindex diversion, nested
6763 Diversions may be nested. The number register @code{.z} contains the
6764 name of the current diversion. The number register @code{.d} contains
6765 the current vertical place in the diversion. If not in a diversion it
6766 is the same as the register @code{nl}.
6774 After completing a diversion, the built-in number registers @code{dn}
6775 and @code{dl} contain the vertical and horizontal size of the diversion.
6778 .\" Center text both horizontally & vertically
6787 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
6802 @cindex transparent output
6803 @cindex output, transparent
6804 Requests, macros and escapes are interpreted when read into a diversion.
6805 There are two ways to prevent this; either way will take the given text
6806 and @dfn{transparently} embed it into the diversion. The first method
6807 is to prefix the line with @code{\!}. This will cause the entire line
6808 to be transparently inserted into the diversion. This is useful for
6809 macros which shouldn't be invoked until the diverted text is actually
6812 @c XXX anything is read in copy mode. (what about \! ??)
6815 The other way is to surround the text by the @code{\?} escape, i.e.
6822 @var{anything} may not contain newlines; use @code{\!} to embed
6823 newlines in a diversion. The escape sequence @code{\?} is also
6824 recognized in copy mode and turned into a single internal code; it is
6825 this code that terminates anything. Thus the following example will
6832 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
6847 @cindex unformatting diversions
6848 @cindex diversion, unformatting
6849 The @code{asciify} request only exists in order to make certain gross
6850 hacks work with GNU @code{troff}. It @dfn{unformats} the diversion
6851 specified as an argument in such a way that @acronym{ASCII} characters
6852 that were formatted and diverted will be treated like ordinary input
6853 characters when the diversion is reread. For example, the following
6854 will set register @code{n} to@w{ }1.
6867 @xref{Copy-in Mode}.
6870 @c =====================================================================
6872 @node Environments, I/O, Diversions, Programming Tutorial
6873 @section Environments
6874 @cindex environments
6876 It happens frequently that some text should be printed in a certain
6877 format regardless of what may be in effect at the time, for example, in
6878 a trap invoked macro to print headers and footers. To solve this
6879 @code{gtroff} has @dfn{environments} in which text is processed. An
6880 environment contains most of the parameters that control text
6881 processing. It is possible to switch amongst these environments; by
6882 default @code{gtroff} processes text in environment@w{ }0. The
6883 following is the information kept in an environment.
6887 font parameters (size, family, style, character height and slant, space
6888 and sentence space size)
6891 page parameters (line length, title length, vertical spacing,
6892 line spacing, indentation, line numbering, hyphenation data)
6895 fill and adjust mode
6898 tab stops, tab and leader characters, escape character, no-break and
6899 hyphen indicators, margin character data
6902 partially collected lines
6905 These environments may be given arbitrary names (@pxref{Identifiers},
6906 for more info). Old versions of @code{troff} only had environments
6907 named @samp{0}, @samp{1} and@w{ }@samp{2}.
6911 The @code{ev} request will switch among environments. The single
6912 argument is the name of the environment to switch to. With no argument
6913 @code{gtroff} will switch back to the previous environment. There is no
6914 limit on the number of named environments; they will be created the
6915 first time that they are referenced. The @code{.ev} register contains
6916 the name or number of the current environment. This is a string-valued
6919 Note that a call to @code{ev} (with argument) will push the previously
6920 active environment onto a stack. If, say, environments @samp{foo},
6921 @samp{bar}, and @samp{zap} are called (in that order), the first
6922 @code{ev} request without parameter will switch back to environment
6923 @samp{bar} (which will be popped off the stack), and a second call will
6924 switch back to environment @samp{foo}.
6929 ... page break macro, revised ...
6932 Here another example:
6943 \(dg Note the large, friendly letters.
6948 To copy an environment into the current one, use the @code{evc} request,
6949 which takes the name of the environment to copy from as an argument.
6952 @c =====================================================================
6954 @node I/O, Postprocessor Access, Environments, Programming Tutorial
6957 @cindex input and output requests
6958 @cindex requests for input and output
6959 @cindex output and input requests
6962 The @code{so} request will read in the file given as an argument and
6963 include it in place of the @code{so} request. This is quite useful for
6964 large documents, i.e.@: keeping each chapter in a separate file.
6965 @xref{gsoelim}, for more information.
6968 The @code{mso} request is the same as the @code{so} request except that
6969 the file is searched for in the same directories as
6970 @file{tmac.@var{name}} is searched for when the @option{-m@var{name}}
6971 option is specified.
6974 @cindex transparent output
6975 @cindex output, transparent
6976 The @code{cf} and @code{trf} requests are to include a file. It will
6977 transparently output the contents of file filename. Each line is output
6978 as it were preceded by @code{\!}; however, the lines are not subject to
6979 copy mode interpretation. If the file does not end with a newline, then
6980 a newline will be added. For example, to define a macro@w{ }@code{x}
6981 containing the contents of file@w{ }@file{f}, use
6989 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
6990 will embed in the diversion an object which, when reread, will cause the
6991 contents of @var{filename} to be transparently copied through to the
6992 output. In @acronym{UNIX} @code{troff}, the contents of @var{filename}
6993 is immediately copied through to the output regardless of whether there
6994 is a current diversion; this behaviour is so anomalous that it must be
6995 considered a bug. This request causes a line break.
6998 With @code{trf}, unlike @code{cf}, the file cannot contain characters
6999 such as NUL that are not legal @code{gtroff} input characters. This
7000 request causes a line break.
7002 @c XXX xref to illegal input characters
7005 The @code{nx} request will force @code{gtroff} to continue processing of
7006 the file specified as an argument.
7009 The @code{rd} request will read from standard input, and include what is
7010 read as though it were part of the input file. Text is read until a
7011 blank line is encountered.
7013 @cindex form letters
7014 @cindex letters, form
7015 Using these two requests it is easy to set up form letters. The form
7016 letter template is constructed like this:
7034 When this is run, the following file should be redirected in. Note that
7035 requests included in this file are executed as though they were part of
7036 the form letter. The last block of input is the @code{ex} requests
7037 which tells groff to stop processing. If this was not there, groff
7038 would not know when to stop.
7042 708 NW 19th Av., #202
7059 @c XXX documentation
7062 The @code{sy} request will allow arbitrary system commands to be
7063 executed from within a @code{gtroff} document. The output is not saved
7064 anyplace, so it is up to the user to do so.
7066 @c XXX add info about safer and unsafe mode
7068 For example, the following example will introduce the current time
7071 @cindex time, current
7072 @cindex current time
7075 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
7076 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
7083 Note that this works by having the @code{perl} script (run by @code{sy})
7084 print out the @code{nr} requests which will set the number registers
7085 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
7086 the @code{so} request.
7089 The @code{systat} number register contains the return value of the
7090 @code{system()} function executed by the last @code{sy} request.
7093 The @code{open} request will open a file (specified as the second
7094 argument) for writing and associate the stream (specified as the first
7098 The @code{opena} is like @code{open}, but if the file exists, append to
7099 it instead of truncating it.
7103 @cindex copy-in mode
7104 @cindex mode, copy-in
7105 The @code{write} request will write to the file associated with the
7106 stream specified by the first argument. The stream must previously have
7107 been the subject of an open request. The remainder of the line is
7108 interpreted as the @code{ds} request reads its second argument: A
7109 leading @samp{"} will be stripped, and it will be read in copy-in mode.
7112 The @code{close} request will close the stream specified by the first
7113 argument; stream will no longer be an acceptable argument to the
7114 @code{write} request.
7119 ... example of open write &c...
7123 The @code{\V} escape will interpolate the contents of the specified
7124 environment variable, as returned by @code{getenv()}. The argument to
7125 @code{\V} is specified as an identifier, i.e.@: @samp{\V@var{x}},
7126 @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} is interpreted in
7130 @c =====================================================================
7132 @node Postprocessor Access, Miscellaneous, I/O, Programming Tutorial
7133 @section Postprocessor Access
7134 @cindex postprocessor access
7135 @cindex access of postprocessor
7137 There are two escapes which will allow information to be directly given
7138 to the postprocessor. This is particularly useful for embedding
7139 @sc{PostScript} into the final document.
7142 The @code{\X} escape will embed its argument into the @code{gtroff}
7143 output preceded with @w{@samp{x X}}.
7146 The @code{\Y} escape is called with an identifier (i.e.@:
7147 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
7148 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
7149 contents of the string or macro @var{xxx} are not interpreted; also it
7150 is permitted for @var{xxx} to have been defined as a macro and thus
7151 contain newlines (it is not permitted for the argument to @code{\X} to
7152 contain newlines). The inclusion of newlines requires an extension to
7153 the @acronym{UNIX} @code{troff} output format, and will confuse drivers
7154 that do not know about this extension.
7156 @xref{Output Devices}.
7159 @c =====================================================================
7161 @node Miscellaneous, Debugging, Postprocessor Access, Programming Tutorial
7162 @section Miscellaneous
7163 @cindex miscellaneous
7165 This section contains parts of @code{gtroff} which cannot (yet) be
7166 categorized elsewhere in this manual.
7169 @cindex line numbers
7170 @cindex numbers, line
7171 Line numbers can be printed in the left margin using the @code{nm}
7172 request. The first argument is the line number of the @emph{next}
7173 output line; this defaults to@w{ }1. The second argument indicates on
7174 which lines numbers will be printed, i.e.@: 5 means put line numbers on
7175 every 5@w{ }lines; this defaults to@w{ }1. The third argument is the
7176 space to be left between the number and the text; this defaults to@w{
7177 }1. The fourth argument is the indentation of the line numbers.
7178 Without arguments, line numbers are turned off.
7180 @c XXX xref ln register
7183 The @code{nn} request will temporarily turn off line numbering. The
7184 first argument is the number of lines not to be numbered; this defaults
7187 @c XXX (does this disable incrementing or display?)
7192 ... line numbering example ...
7196 @cindex margin characters
7197 @cindex characters for margins
7198 Margin characters can be automatically printed to the right of the text
7199 with the @code{mc} request. The first argument is the character to be
7200 printed, and the second argument is the distance away from the main body
7201 text. With no arguments the margin characters are turned off. If this
7202 occurs before a break, no margin character will be printed.
7206 This is quite useful for indicating text that has changed, and, in fact,
7207 there are programs available for doing this (they are called
7208 @code{nrchbar} and @code{changebar} and can be found in any
7209 @samp{comp.sources.unix} archive.
7214 ... margin char example ...
7219 @cindex multi-file documents
7220 @cindex documents, multi-file
7221 The primary reason for the existence of @code{lf} is to make debugging
7222 documents which are split into many files, which are then put together
7223 with @code{soelim} and other preprocessors. The first argument is the
7224 name of the file and the second argument is the input line number in
7225 that file. This way @code{gtroff} can produce error messages which are
7226 intelligible to the user.
7231 ... example of soelim'ed doc ...
7235 @c =====================================================================
7237 @node Debugging, Implementation Differences, Miscellaneous, Programming Tutorial
7241 @code{gtroff} is not easy to debug, but there are some useful features
7242 and strategies for debugging.
7247 The @code{tm} request will send output to stderr; this is very useful
7248 for printing debugging output.
7251 When doing something involved it is useful to leave the debugging
7252 statements in the code and have them turned on by a command line flag.
7255 .if \n(DB .tm debugging output
7259 To activate these statements say
7268 The @code{ab} request is similar to the @code{tm} request, except that
7269 it will cause @code{gtroff} to stop processing. With no argument it
7270 will print @samp{User Abort}.
7275 The @code{ex} request will also cause @code{gtroff} to stop processing
7276 (if encountered at the topmost level; see also @ref{I/O}.
7279 If it is known in advance that there will be many errors and no useful
7280 output, @code{gtroff} can be forced to suppress formatted output with
7281 the @option{-z} flag.
7285 @cindex dumping symbol table
7286 @cindex symbol table, dumping
7287 The @code{pm} request will dump out the entire symbol table.
7291 @cindex dumping number registers
7292 @cindex number registers, dumping
7293 The @code{pnr} request will print the names and contents of all
7294 currently defined number registers on stderr.
7298 @cindex dumping traps
7299 @cindex traps, dumping
7300 The @code{ptr} request will print the names and positions of all traps
7301 (not including input line traps and diversion traps) on stderr. Empty
7302 slots in the page trap list are printed as well, because they can affect
7303 the priority of subsequently planted traps.
7307 @cindex flush output
7308 @cindex output, flush
7309 @cindex interactive use of @code{gtroff}
7310 @cindex @code{gtroff}, interactive use
7311 The @code{fl} request instructs @code{gtroff} to flush its output
7312 immediately. The intention is that this be used when using
7313 @code{gtroff} interactively. There is little other use for it. This
7314 request causes a line break.
7318 @cindex backtrace of input stack
7319 @cindex input stack, backtrace
7320 The @code{backtrace} request will print a backtrace of the input stack
7325 @code{gtroff} has command line options for printing out more warnings
7326 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
7327 or an error occurs. The most verbose level of warnings is @option{-ww}.
7332 @cindex level of warnings
7333 @cindex warnings, level
7334 The @code{warn} request controls the level of warnings checked for. The
7335 only argument is the sum of the numbers associated with each warning
7336 that is to be enabled; all other warnings will be disabled. The number
7337 associated with each warning is listed below. For example,
7338 @w{@code{.warn 0}} will disable all warnings, and @w{@code{.warn 1}}
7339 will disable all warnings except that about missing characters. If an
7340 argument is not given, all warnings will be enabled. The number
7341 register @code{.warn} contains the current warning level.
7344 @c ---------------------------------------------------------------------
7350 @node Warnings, , Debugging, Debugging
7351 @subsection Warnings
7354 The warnings that can be given to @code{gtroff} are divided into the
7355 following categories. The name associated with each warning is used by
7356 the @option{-w} and @option{-W} options; the number is used by the
7357 @code{warn} request and by the @code{.warn} register.
7362 Non-existent characters. This is enabled by default.
7366 Invalid numeric expressions. This is enabled by default.
7373 In fill mode, lines which could not be broken so that their length was
7374 less than the line length. This is enabled by default.
7378 Missing or mismatched closing delimiters.
7384 Use of the @code{el} request with no matching @code{ie} request.
7389 Meaningless scaling indicators.
7393 Out of range arguments.
7397 Dubious syntax in numeric expressions.
7403 Use of @code{di} or @code{da} without an argument when there is no
7409 @c XXX more findex entries
7410 Use of undefined strings, macros and diversions. When an undefined
7411 string, macro or diversion is used, that string is automatically defined
7412 as empty. So, in most cases, at most one warning will be given for each
7418 @c XXX more findex entries
7419 Use of undefined number registers. When an undefined number register is
7420 used, that register is automatically defined to have a value of@w{ }0.
7421 A definition is automatically made with a value of@w{ }0. So, in most
7422 cases, at most one warning will be given for use of a particular name.
7426 Use of a tab character where a number was expected.
7431 Use of @code{\@}} where a number was expected.
7435 Requests that are missing non-optional arguments.
7439 Illegal input characters.
7443 Unrecognized escape sequences. When an unrecognized escape sequence is
7444 encountered, the escape character is ignored.
7448 @cindex compatibility mode
7449 Missing space between a request or macro and its argument. This warning
7450 will be given when an undefined name longer than two characters is
7451 encountered, and the first two characters of the name make a defined
7452 name. The request or macro will not be invoked. When this warning is
7453 given, no macro is automatically defined. This is enabled by default.
7454 This warning will never occur in compatibility mode.
7458 Non-existent fonts. This is enabled by default.
7461 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
7462 intended that this covers all warnings that are useful with traditional
7470 @c =====================================================================
7472 @node Implementation Differences, Summary, Debugging, Programming Tutorial
7473 @section Implementation Differences
7474 @cindex implementation differences
7475 @cindex differences in implementation
7476 @cindex compatibility mode
7477 @cindex mode, compatibility
7479 GNU @code{troff} has a number of features which cause incompatibilities
7480 with documents written with old versions of @code{troff}.
7484 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
7496 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
7497 @code{troff} will interpret this as a call of a macro named
7498 @code{dsabcd}. Also @acronym{UNIX} @code{troff} will interpret
7499 @code{\*[} or @code{\n[} as references to a string or number register
7500 called @samp{[}. In GNU @code{troff}, however, this will normally be
7501 interpreted as the start of a long name. In compatibility mode GNU
7502 @code{troff} will interpret these things in the traditional way. In
7503 compatibility mode, however, long names are not recognized.
7504 Compatibility mode can be turned on with the @option{-C} command line
7505 option, and turned on or off with the @code{cp} request. The number
7506 register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{
7523 GNU @code{troff} does not allow the use of the escape sequences
7524 @code{\|}, @code{\^}, @code{\&}, @code{\@}}, @code{\@{},
7525 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
7526 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
7527 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
7528 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
7529 avoiding use of these escape sequences in names.
7531 @cindex fractional point sizes
7532 @cindex point sizes, fractional
7534 Fractional point sizes cause one noteworthy incompatibility. In
7535 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
7543 will set the point size to 10@w{ }points, whereas in GNU @code{troff} it
7544 will set the point size to 10@w{ }scaled points. @xref{Fractional Type
7545 Sizes}, for more information.
7552 @cindex input and output characters
7553 @cindex output characters
7554 @cindex characters, input and output
7555 In GNU @code{troff} there is a fundamental difference between
7556 unformatted, input characters, and formatted, output characters.
7557 Everything that affects how an output character will be output is stored
7558 with the character; once an output character has been constructed it is
7559 unaffected by any subsequent requests that are executed, including
7560 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
7561 Normally output characters are constructed from input characters at the
7562 moment immediately before the character is added to the current output
7563 line. Macros, diversions and strings are all, in fact, the same type of
7564 object; they contain lists of input characters and output characters in
7565 any combination. An output character does not behave like an input
7566 character for the purposes of macro processing; it does not inherit any
7567 of the special properties that the input character from which it was
7568 constructed might have had. For example,
7581 @cindex transparent output
7582 @cindex output, transparent
7584 will print @samp{\\} in GNU @code{troff}; each pair of input backslashes
7585 is turned into one output backslash and the resulting output backslashes
7586 are not interpreted as escape characters when they are reread.
7587 @acronym{UNIX} @code{troff} would interpret them as escape characters
7588 when they were reread and would end up printing one @samp{\}. The
7589 correct way to obtain a printable backslash is to use the @code{\e}
7590 escape sequence: This will always print a single instance of the current
7591 escape character, regardless of whether or not it is used in a
7592 diversion; it will also work in both GNU @code{troff} and @acronym{UNIX}
7593 @code{troff}. To store, for some reason, an escape sequence in a
7594 diversion that will be interpreted when the diversion is reread, either
7595 use the traditional @code{\!} transparent output facility, or, if this
7596 is unsuitable, the new @code{\?} escape sequence.
7598 @xref{Diversions}, for more information.
7601 @c =====================================================================
7603 @node Summary, , Implementation Differences, Programming Tutorial
7607 @c XXX documentation
7611 @c =====================================================================
7612 @c =====================================================================
7614 @node Preprocessors, Output Devices, Programming Tutorial, Top
7615 @chapter Preprocessors
7616 @cindex preprocessors
7618 This chapter describes all preprocessors that come with @code{groff} or
7619 which are freely available.
7632 @c =====================================================================
7634 @node geqn, gtbl, Preprocessors, Preprocessors
7635 @section @code{geqn}
7645 @c ---------------------------------------------------------------------
7647 @node Invoking geqn, , geqn, geqn
7648 @subsection Invoking @code{geqn}
7649 @cindex invoking @code{geqn}
7650 @cindex @code{geqn}, invoking
7655 @c =====================================================================
7657 @node gtbl, gpic, geqn, Preprocessors
7658 @section @code{gtbl}
7668 @c ---------------------------------------------------------------------
7670 @node Invoking gtbl, , gtbl, gtbl
7671 @subsection Invoking @code{gtbl}
7672 @cindex invoking @code{gtbl}
7673 @cindex @code{gtbl}, invoking
7678 @c =====================================================================
7680 @node gpic, ggrn, gtbl, Preprocessors
7681 @section @code{gpic}
7691 @c ---------------------------------------------------------------------
7693 @node Invoking gpic, , gpic, gpic
7694 @subsection Invoking @code{gpic}
7695 @cindex invoking @code{gpic}
7696 @cindex @code{gpic}, invoking
7701 @c =====================================================================
7703 @node ggrn, grap, gpic, Preprocessors
7704 @section @code{ggrn}
7714 @c ---------------------------------------------------------------------
7716 @node Invoking ggrn, , ggrn, ggrn
7717 @subsection Invoking @code{ggrn}
7718 @cindex invoking @code{ggrn}
7719 @cindex @code{ggrn}, invoking
7724 @c =====================================================================
7726 @node grap, grefer, ggrn, Preprocessors
7727 @section @code{grap}
7730 A freely available implementation of @code{grap}, written by Ted Faber,
7731 is available as an extra package from the following address:
7734 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
7738 @c =====================================================================
7740 @node grefer, gsoelim, grap, Preprocessors
7741 @section @code{grefer}
7742 @cindex @code{refer}
7743 @cindex @code{grefer}
7751 @c ---------------------------------------------------------------------
7753 @node Invoking grefer, , grefer, grefer
7754 @subsection Invoking @code{grefer}
7755 @cindex invoking @code{grefer}
7756 @cindex @code{grefer}, invoking
7761 @c =====================================================================
7763 @node gsoelim, , grefer, Preprocessors
7764 @section @code{gsoelim}
7765 @cindex @code{soelim}
7766 @cindex @code{gsoelim}
7771 * Invoking gsoelim::
7774 @c ---------------------------------------------------------------------
7776 @node Invoking gsoelim, , gsoelim, gsoelim
7777 @subsection Invoking @code{gsoelim}
7778 @cindex invoking @code{gsoelim}
7779 @cindex @code{gsoelim}, invoking
7785 @c =====================================================================
7786 @c =====================================================================
7788 @node Output Devices, File formats, Preprocessors, Top
7789 @chapter Output Devices
7790 @cindex output devices
7791 @cindex devices for output
7796 * Special Characters::
7807 @c =====================================================================
7809 @node Special Characters, grotty, Output Devices, Output Devices
7810 @section Special Characters
7811 @cindex special characters
7812 @cindex characters, special
7819 @c =====================================================================
7821 @node grotty, grops, Special Characters, Output Devices
7822 @section @code{grotty}
7823 @cindex @code{grotty}
7831 @c ---------------------------------------------------------------------
7833 @node Invoking grotty, , grotty, grotty
7834 @subsection Invoking @code{grotty}
7835 @cindex invoking @code{grotty}
7836 @cindex @code{grotty}, invoking
7841 @c =====================================================================
7843 @node grops, grodvi, grotty, Output Devices
7844 @section @code{grops}
7845 @cindex @code{grops}
7851 * Embedding PostScript::
7854 @c ---------------------------------------------------------------------
7856 @node Invoking grops, Embedding PostScript, grops, grops
7857 @subsection Invoking @code{grops}
7858 @cindex invoking @code{grops}
7859 @cindex @code{grops}, invoking
7863 @c ---------------------------------------------------------------------
7865 @node Embedding PostScript, , Invoking grops, grops
7866 @subsection Embedding @sc{PostScript}
7867 @cindex embedding postscript
7868 @cindex postscript, embedding
7873 @c =====================================================================
7875 @node grodvi, grolj4, grops, Output Devices
7876 @section @code{grodvi}
7877 @cindex @code{grodvi}
7885 @c ---------------------------------------------------------------------
7887 @node Invoking grodvi, , grodvi, grodvi
7888 @subsection Invoking @code{grodvi}
7889 @cindex invoking @code{grodvi}
7890 @cindex @code{grodvi}, invoking
7895 @c =====================================================================
7897 @node grolj4, grolbp, grodvi, Output Devices
7898 @section @code{grolj4}
7899 @cindex @code{grolj4}
7907 @c ---------------------------------------------------------------------
7909 @node Invoking grolj4, , grolj4, grolj4
7910 @subsection Invoking @code{grolj4}
7911 @cindex invoking @code{grolj4}
7912 @cindex @code{grolj4}, invoking
7917 @c =====================================================================
7919 @node grolbp, grohtml, grolj4, Output Devices
7920 @section @code{grolbp}
7921 @cindex @code{grolbp}
7929 @c ---------------------------------------------------------------------
7931 @node Invoking grolbp, , grolbp, grolbp
7932 @subsection Invoking @code{grolbp}
7933 @cindex invoking @code{grolbp}
7934 @cindex @code{grolbp}, invoking
7939 @c =====================================================================
7941 @node grohtml, gxditview, grolbp, Output Devices
7942 @section @code{grohtml}
7943 @cindex @code{grohtml}
7948 * Invoking grohtml::
7951 @c ---------------------------------------------------------------------
7953 @node Invoking grohtml, , grohtml, grohtml
7954 @subsection Invoking @code{grohtml}
7955 @cindex invoking @code{grohtml}
7956 @cindex @code{grohtml}, invoking
7961 @c =====================================================================
7963 @node gxditview, , grohtml, Output Devices
7964 @section @code{gxditview}
7965 @cindex @code{gxditview}
7970 * Invoking gxditview::
7973 @c ---------------------------------------------------------------------
7975 @node Invoking gxditview, , gxditview, gxditview
7976 @subsection Invoking @code{gxditview}
7977 @cindex invoking @code{gxditview}
7978 @cindex @code{gxditview}, invoking
7985 @c =====================================================================
7986 @c =====================================================================
7988 @node File formats, Installation, Output Devices, Top
7989 @chapter File formats
7990 @cindex file formats
7991 @cindex formats, file
8001 @c =====================================================================
8003 @node gtroff Output, Font Files, File formats, File formats
8004 @section @code{gtroff} Output
8005 @cindex @code{gtroff} output
8006 @cindex output, @code{gtroff}
8008 This section describes the format output of GNU @code{troff}. The
8009 output format used by GNU @code{troff} is very similar to that used by
8010 @acronym{UNIX} device-independent @code{troff} (@code{ditroff}).
8015 * Drawing Functions::
8016 * Line Continuation::
8019 @c ---------------------------------------------------------------------
8021 @node Output Format, Device Control, gtroff Output, gtroff Output
8022 @subsection Output Format
8023 @cindex output format
8024 @cindex format of output
8027 @cindex input, 8-bit
8028 The output format is text based, as opposed to a binary format (like
8029 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
8030 characters can have the eighth bit set, as can the names of fonts and
8033 The output format consists of single command characters with attached
8034 parameters which are separated from subsequent text by whitespace or a
8037 The names of characters and fonts can be of arbitrary length; drivers
8038 should not assume that they will be only two characters long (as
8039 @code{ditroff} does).
8041 When a character is to be printed, that character will always be in the
8042 current font. Unlike @code{ditroff}, it is not necessary for drivers to
8043 search special fonts to find a character.
8064 @item @var{nn}@var{c}
8068 @var{xxx} is any sequence of characters terminated by a space or a
8069 newline; the first character should be printed at the current position,
8070 the the current horizontal position should be increased by the width of
8071 the first character, and so on for each character. The width of the
8072 character is that given in the font file, appropriately scaled for the
8073 current point size, and rounded so that it is a multiple of the
8074 horizontal resolution. Special characters cannot be printed using this
8079 This command is only allowed if the @samp{tcommand} line is present in
8080 the @file{DESC} file.
8082 @item u@var{n} @var{xxx}
8083 This is same as the @samp{t} command except that after printing each
8084 character, the current horizontal position is increased by the sum of
8085 the width of that character and@w{ }@var{n}.
8087 This command is only allowed if the @samp{tcommand} line is present in
8088 the @file{DESC} file.
8090 @item n@var{a}@var{b}
8099 The argument to the @samp{s} command is in scaled points (units of
8100 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
8101 command in the @file{DESC} file).
8108 @item D@var{c} @var{x}@dots{}\n
8112 @c ---------------------------------------------------------------------
8114 @node Device Control, Drawing Functions, Output Format, gtroff Output
8115 @subsection Device Control
8116 @cindex device control
8117 @cindex control of devices
8119 The @samp{x} command is normally followed by a letter or word indicating
8120 the function to perform, followed by white space separated arguments.
8122 The first argument can be abbreviated to the first letter.
8131 @item x res @var{n} @var{h} @var{v}
8136 The argument to the @w{@samp{x Height}} command is also in scaled
8140 The first three output commands are guaranteed to be:
8149 For example, the input
8152 crunchy \fH\s+2frog\s0\fP!?
8161 ... sample output here ...
8164 @c ---------------------------------------------------------------------
8166 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
8167 @subsection Drawing Functions
8168 @cindex drawing functions
8169 @cindex functions for drawing
8172 The @samp{D} drawing command has been extended. These extensions will
8173 only be used by GNU @code{pic} if the @option{-x} option is given.
8175 @xref{Drawing Requests}.
8180 Set the shade of gray to be used for filling solid objects to@w{
8181 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
8182 corresponds solid white and 1000 to solid black, and values in between
8183 correspond to intermediate shades of gray. This applies only to solid
8184 circles, solid ellipses and solid polygons. By default, a level of@w{
8185 }1000 will be used. Whatever color a solid object has, it should
8186 completely obscure everything beneath it. A value greater than@w{ }1000
8187 or less than@w{ }0 can also be used: this means fill with the shade of
8188 gray that is currently being used for lines and text. Normally this
8189 will be black, but some drivers may provide a way of changing this.
8192 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
8193 point at the current position.
8195 @item DE @var{dx} @var{dy}
8196 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
8197 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
8200 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
8201 Draw a polygon with. The first vertex is at the current position, the
8202 second vertex at an offset (@var{dx1},@var{dy1}) from the current
8203 position, the second vertex at an offset (@var{dx2},@var{dy2}) from the
8204 first vertex, and so on up to the @var{n}-th vertex. At the moment, GNU
8205 @code{pic} only uses this command to generate triangles and rectangles.
8207 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
8208 Like @code{Dp} but draw a solid rather than outlined polygon.
8211 @cindex line thickness
8212 @cindex thickness of lines
8213 Set the current line thickness to @var{n}@w{ }machine units.
8214 Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness
8215 proportional to the current point size; drivers should continue to do
8216 this if no @code{Dt} command has been given, or if a @code{Dt} command
8217 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
8218 }@var{n} selects the smallest available line thickness.
8222 A difficulty arises in how the current position should be changed after
8223 the execution of these commands. This is not of great importance since
8224 the code generated by GNU @code{pic} does not depend on this. Given a
8225 drawing command of the form
8228 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
8235 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
8236 @samp{~}, @acronym{UNIX} @code{troff} will treat each of the x@w{ }value
8237 as a horizontal quantity, and each of the y@w{ }values as a vertical
8238 quantity and will assume that the width of the drawn object is sum if
8239 all x@w{ }values, and that the height is the sum of all y@w{ }values.
8240 (The assumption about the height can be seen by examining the @code{st}
8241 and @code{sb} registers after using such a @code{D}@w{ }command in a
8242 @code{\w} escape sequence.) This rule also holds for all the original
8243 drawing commands with the exception of @code{De}. For the sake of
8244 compatibility GNU @code{troff} also follows this rule, even though it
8245 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
8246 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
8247 @code{D}@w{ }command of the form
8250 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
8254 the current position should be increased horizontally by the sum of all
8255 x@w{ }values and vertically by the sum of all y@w{ }values.
8257 @c ---------------------------------------------------------------------
8259 @node Line Continuation, , Drawing Functions, gtroff Output
8260 @subsection Line Continuation
8261 @cindex line continuation in output commands
8262 @cindex output commands, line continuation
8264 There is a continuation convention which permits the argument to the
8265 @w{@samp{x X}} command to contain newlines: When outputting the argument
8266 to the @w{@samp{x X}} command, GNU @code{troff} will follow each newline
8267 in the argument with a @samp{+} character (as usual, it will terminate
8268 the entire argument with a newline); thus if the line after the line
8269 containing the @w{@samp{x X}} command starts with @samp{+}, then the
8270 newline ending the line containing the @w{@samp{x X}} command should be
8271 treated as part of the argument to the @w{@samp{x X}} command, the
8272 @samp{+} should be ignored, and the part of the line following the
8273 @samp{+} should be treated like the part of the line following the
8274 @w{@samp{x X}} command.
8277 @c =====================================================================
8279 @node Font Files, , gtroff Output, File formats
8284 The @code{gtroff} font format is roughly a superset of the
8285 @code{ditroff} font format. Unlike the @code{ditroff} font format,
8286 there is no associated binary format; all files are text files. The
8287 font files for device @var{name} are stored in a directory
8288 @file{dev@var{name}}. There are two types of file: a device description
8289 file called @file{DESC} and for each font@w{ }@samp{F} a font file
8290 called@w{ }@file{F}.
8293 * DESC file format::
8294 * Font file format::
8297 @c ---------------------------------------------------------------------
8299 @node DESC file format, Font file format, Font Files, Font Files
8300 @subsection @file{DESC} file format
8301 @cindex @file{DESC} file format
8302 @cindex font description file format
8303 @cindex format of font description file
8306 The @file{DESC} file can contain the following types of line:
8311 There are @var{n} machine units per inch.
8315 The horizontal resolution is @var{n} machine units.
8319 The vertical resolution is @var{n} machine units.
8321 @item sizescale @var{n}
8323 The scale factor for point sizes. By default this has a value of@w{ }1.
8324 One scaled point is equal to one point/@var{n}. The arguments to the
8325 @code{unitwidth} and @code{sizes} commands are given in scaled points.
8326 @xref{Fractional Type Sizes}, for more information.
8328 @item unitwidth @var{n}
8330 Quantities in the font files are given in machine units for fonts whose
8331 point size is @var{n}@w{ }scaled points.
8335 This means that the postprocessor can handle the @samp{t} and @samp{u}
8338 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
8340 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
8341 @var{sn} scaled points. The list of sizes must be terminated by a@w{
8342 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
8343 list can extend over more than one line.
8345 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
8347 The first @var{m}@w{ }font positions will be associated with styles
8348 @var{S1} @dots{} @var{Sm}.
8350 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
8352 Fonts @var{F1} @dots{} @var{Fn} will be mounted in the font positions
8353 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
8354 styles. This command may extend over more than one line. A font name
8355 of@var{ }0 will cause no font to be mounted on the corresponding font
8358 @item family @var{fam}
8360 The default font family is @var{fam}.
8364 This line and everything following in the file are ignored. It is
8365 allowed for the sake of backwards compatibility.
8368 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
8369 are compulsory. Other commands are ignored by @code{gtroff} but may be
8370 used by postprocessors to store arbitrary information about the device
8371 in the @file{DESC} file.
8373 @c XXX add other commands resp. xrefs to output devices
8374 @c XXX add obsolete commands
8376 @c ---------------------------------------------------------------------
8378 @node Font file format, , DESC file format, Font Files
8379 @subsection Font file format
8380 @cindex font file format
8381 @cindex format of font files
8383 A font file has two sections. The first section is a sequence of lines
8384 each containing a sequence of blank delimited words; the first word in
8385 the line is a key, and subsequent words give a value for that key.
8390 The name of the font is@w{ }@var{F}.
8392 @item spacewidth @var{n}
8394 The normal width of a space is@w{ }@var{n}.
8398 The characters of the font have a slant of @var{n}@w{ }degrees.
8399 (Positive means forward.)
8401 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
8403 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
8404 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
8405 @samp{ffl}. For backwards compatibility, the list of ligatures may be
8406 terminated with a@w{ }0. The list of ligatures may not extend over more
8411 The font is special; this means that when a character is requested that
8412 is not present in the current font, it will be searched for in any
8413 special fonts that are mounted.
8416 Other commands are ignored by @code{gtroff} but may be used by
8417 postprocessors to store arbitrary information about the font in the font
8420 @cindex comments in font files
8421 @cindex font files, comments
8423 The first section can contain comments which start with the @samp{#}
8424 character and extend to the end of a line.
8426 The second section contains one or two subsections. It must contain a
8427 @code{charset} subsection and it may also contain a @code{kernpairs}
8428 subsection. These subsections can appear in any order. Each
8429 subsection starts with a word on a line by itself.
8432 The word @code{charset} starts the character set subsection. The
8433 @code{charset} line is followed by a sequence of lines. Each line gives
8434 information for one character. A line comprises a number of fields
8435 separated by blanks or tabs. The format is
8437 @c XXX fix it for new HTML additions
8440 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
8444 @cindex input, 8-bit
8448 @var{name} identifies the character: If @var{name} is a single
8449 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
8450 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
8451 a single character, then it corresponds to the @code{gtroff} input
8452 character@w{ }\@var{c}; otherwise it corresponds to the groff input
8453 character @samp{\[@var{name}]}. (If it is exactly two characters
8454 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
8455 supports 8-bit characters; however some utilities have difficulties with
8456 eight-bit characters. For this reason, there is a convention that the
8457 name @samp{char@var{n}} is equivalent to the single character whose code
8458 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
8459 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
8460 Latin-1} character set. The name @samp{---} is special and indicates
8461 that the character is unnamed; such characters can only be used by means
8462 of the @code{\N} escape sequence in @code{gtroff}.
8464 @c XXX input encodings vs. output encodings
8466 The @var{type} field gives the character type:
8470 the character has an descender, for example, `p';
8473 the character has an ascender, for example, `b';
8476 the character has both an ascender and a descender, for example, `('.
8479 The @var{code} field gives the code which the postprocessor uses to
8480 print the character. The character can also be input to @code{gtroff}
8481 using this code by means of the @code{\N} escape sequence. The code can
8482 be any integer. If it starts with @samp{0} it will be interpreted as
8483 octal; if it starts with @samp{0x} or @samp{0X} it will be interpreted as
8486 Anything on the line after the @var{code} field will be ignored.
8488 The @var{metrics} field has the form:
8491 @var{width}[,@var{height}[,@var{depth}[,@var{italic_correction}
8492 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]]
8496 There must not be any spaces between these subfields (it has been split
8497 here into two lines for better legibility only). Missing subfields are
8498 assumed to be@w{ }0. The subfields are all decimal integers. Since
8499 there is no associated binary format, these values are not required to
8500 fit into a variable of type @samp{char} as they are in @code{ditroff}.
8501 The @var{width} subfield gives the width of the character. The
8502 @var{height} subfield gives the height of the character (upwards is
8503 positive); if a character does not extend above the baseline, it should
8504 be given a zero height, rather than a negative height. The @var{depth}
8505 subfield gives the depth of the character, that is, the distance below
8506 the lowest point below the baseline to which the character extends
8507 (downwards is positive); if a character does not extend below above the
8508 baseline, it should be given a zero depth, rather than a negative depth.
8509 The @var{italic_correction} subfield gives the amount of space that
8510 should be added after the character when it is immediately to be
8511 followed by a character from a Roman font. The
8512 @var{left_italic_correction} subfield gives the amount of space that
8513 should be added before the character when it is immediately to be
8514 preceded by a character from a Roman font. The
8515 @var{subscript_correction} gives the amount of space that should be
8516 added after a character before adding a subscript. This should be less
8517 than the italic correction.
8519 A line in the @code{charset} section can also have the format
8526 This indicates that @var{name} is just another name for the character
8527 mentioned in the preceding line.
8530 The word @code{kernpairs} starts the kernpairs section. This contains a
8531 sequence of lines of the form:
8534 @var{c1} @var{c2} @var{n}
8537 This means that when character @var{c1} appears next to character
8538 @var{c2} the space between them should be increased by@w{ }@var{n}.
8539 Most entries in kernpairs section will have a negative value for@w{
8544 @c =====================================================================
8545 @c =====================================================================
8547 @node Installation, Request and Escape Index, File formats, Top
8548 @chapter Installation
8549 @cindex installation
8555 @c =====================================================================
8556 @c =====================================================================
8558 @node Request and Escape Index, Operator Index, Installation, Top
8559 @chapter Request and Escape Index
8561 In this index, escapes are listed with a leading backslash (@samp{\}) to
8562 distinguish them from requests which appear without the leading control
8563 character (normally either @samp{.} or @samp{'}).
8569 @c =====================================================================
8570 @c =====================================================================
8572 @node Operator Index, Register Index, Request and Escape Index, Top
8573 @chapter Operator Index
8579 @c =====================================================================
8580 @c =====================================================================
8582 @node Register Index, Macro and String Index, Operator Index, Top
8583 @chapter Register Index
8589 @c =====================================================================
8590 @c =====================================================================
8592 @node Macro and String Index, Glyph Name Index, Register Index, Top
8593 @chapter Macro and String Index
8595 In this index, strings are listed with the calling escape sequence
8596 (@samp{\*}) to distinguish them from macros which appear without the
8597 leading control character (normally either @samp{.} or @samp{'}).
8603 @c =====================================================================
8604 @c =====================================================================
8606 @node Glyph Name Index, Font File Keyword Index, Macro and String Index, Top
8607 @chapter Glyph Name Index
8609 A glyph name @code{xx} consisting of exactly two characters can be
8610 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
8611 accessed as @samp{\[xxx]}.
8617 @c =====================================================================
8618 @c =====================================================================
8620 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
8621 @chapter Font File Keyword Index
8627 @c =====================================================================
8628 @c =====================================================================
8630 @node Program and File Index, Concept Index, Font File Keyword Index, Top
8631 @chapter Program and File Index
8637 @c =====================================================================
8638 @c =====================================================================
8640 @node Concept Index, , Program and File Index, Top
8641 @chapter Concept Index