1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header (This is for running Texinfo on a region.)
4 @settitle The GNU Troff Manual
6 @footnotestyle separate
7 @c %**end of header (This is for running Texinfo on a region.)
10 @c We use the following indices:
13 @c findex: requests, escapes, and functions
15 @c kindex: commands in font files
17 @c tindex: environment variables
19 @c tindex and cindex are merged.
24 @c XXX comment all examples
27 @dircategory Miscellaneous
29 * Groff: (groff). The GNU troff document formatting system.
42 This Info file documents GNU troff version 1.16.
44 Published by the Free Software Foundation
45 59 Temple Place, Suite 330
46 Boston, MA 02111-1307 USA
48 Copyright (C) 1994-2000 Free Software Foundation, Inc.
50 Permission is granted to make and distribute verbatim copies of this
51 manual provided the copyright notice and this permission notice are
52 preserved on all copies.
55 Permission is granted to process this file through TeX and print the
56 results, provided the printed document carries copying permission notice
57 identical to this one except for the removal of this paragraph (this
58 paragraph not being relevant to the printed manual).
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided that the
63 entire resulting derived work is distributed under the terms of a
64 permission notice identical to this one.
66 Permission is granted to copy and distribute translations of this manual
67 into another language, under the above conditions for modified versions,
68 except that this permission notice may be stated in a translation
69 approved by the Foundation.
71 Permission is granted to copy and distribute modified versions of this
72 manual under the conditions for verbatim copying, provided also that the
73 section entitled ``GNU General Public License'' is included exactly as
74 in the original, and provided that the entire resulting derived work is
75 distributed under the terms of a permission notice identical to this
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions,
80 except that the section entitled ``GNU General Public License'' may be
81 included in a translation approved by the Free Software Foundation
82 instead of in the original English.
88 @subtitle The GNU implementation of @code{groff}
89 @subtitle Edition 1.16
91 @author by Trent A.@w{ }Fisher
92 @author and the maintainer of groff
94 @c Include the Distribution inside the titlepage environment so
95 @c that headings are turned off. Headings on and off do not work.
98 @vskip 0pt plus 1filll
99 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
101 Version 1.16 of @code{groff}, @*
104 Published by the Free Software Foundation @*
105 59 Temple Place, Suite 330 @*
106 Boston, MA 02111-1307 USA
109 Permission is granted to make and distribute verbatim copies of this
110 manual provided the copyright notice and this permission notice are
111 preserved on all copies.
113 Permission is granted to copy and distribute modified versions of this
114 manual under the conditions for verbatim copying, provided also that the
115 section entitled ``GNU General Public License'' is included exactly as
116 in the original, and provided that the entire resulting derived work is
117 distributed under the terms of a permission notice identical to this
120 Permission is granted to copy and distribute translations of this manual
121 into another language, under the above conditions for modified versions,
122 except that the section entitled ``GNU General Public License'' may be
123 included in a translation approved by the Free Software Foundation
124 instead of in the original English.
126 Cover art by Etienne Suvasa.
132 @node Top, Copying, (dir), (dir)
135 This Info file documents groff version 1.16, the GNU implementation of
136 the troff typesetting system.
138 This is an in-progress document; contributions, comments, or
139 contributions are welcome. Send them to bug-groff@@gnu.org.
146 * Tutorial for Macro Users::
148 * Programming Tutorial::
153 * Request and Operator Index::
155 * Font File Keyword Index::
156 * Program and File Index::
162 @node Copying, Introduction, Top, Top
164 @unnumbered GNU GENERAL PUBLIC LICENSE
165 @center Version 2, June 1991
168 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
169 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
171 Everyone is permitted to copy and distribute verbatim copies of this
172 license document, but changing it is not allowed.
175 @unnumberedsec Preamble
177 The licenses for most software are designed to take away your freedom to
178 share and change it. By contrast, the GNU General Public License is
179 intended to guarantee your freedom to share and change free software --
180 to make sure the software is free for all its users. This General
181 Public License applies to most of the Free Software Foundation's
182 software and to any other program whose authors commit to using it.
183 (Some other Free Software Foundation software is covered by the GNU
184 Library General Public License instead.) You can apply it to your
187 When we speak of free software, we are referring to freedom, not price.
188 Our General Public Licenses are designed to make sure that you have the
189 freedom to distribute copies of free software (and charge for this
190 service if you wish), that you receive source code or can get it if you
191 want it, that you can change the software or use pieces of it in new
192 free programs; and that you know you can do these things.
194 To protect your rights, we need to make restrictions that forbid anyone
195 to deny you these rights or to ask you to surrender the rights. These
196 restrictions translate to certain responsibilities for you if you
197 distribute copies of the software, or if you modify it.
199 For example, if you distribute copies of such a program, whether gratis
200 or for a fee, you must give the recipients all the rights that you have.
201 You must make sure that they, too, receive or can get the source code.
202 And you must show them these terms so they know their rights.
204 We protect your rights with two steps: (1)@w{ }copyright the software,
205 and (2)@w{ }offer you this license which gives you legal permission to
206 copy, distribute and/or modify the software.
208 Also, for each author's protection and ours, we want to make certain
209 that everyone understands that there is no warranty for this free
210 software. If the software is modified by someone else and passed on, we
211 want its recipients to know that what they have is not the original, so
212 that any problems introduced by others will not reflect on the original
213 authors' reputations.
215 Finally, any free program is threatened constantly by software patents.
216 We wish to avoid the danger that redistributors of a free program will
217 individually obtain patent licenses, in effect making the program
218 proprietary. To prevent this, we have made it clear that any patent
219 must be licensed for everyone's free use or not licensed at all.
221 The precise terms and conditions for copying, distribution and
225 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
228 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
233 This License applies to any program or other work which contains a
234 notice placed by the copyright holder saying it may be distributed under
235 the terms of this General Public License. The ``Program'', below,
236 refers to any such program or work, and a ``work based on the Program''
237 means either the Program or any derivative work under copyright law:
238 that is to say, a work containing the Program or a portion of it, either
239 verbatim or with modifications and/or translated into another language.
240 (Hereinafter, translation is included without limitation in the term
241 ``modification''.) Each licensee is addressed as ``you''.
243 Activities other than copying, distribution and modification are not
244 covered by this License; they are outside its scope. The act of running
245 the Program is not restricted, and the output from the Program is
246 covered only if its contents constitute a work based on the Program
247 (independent of having been made by running the Program). Whether that
248 is true depends on what the Program does.
251 You may copy and distribute verbatim copies of the Program's source code
252 as you receive it, in any medium, provided that you conspicuously and
253 appropriately publish on each copy an appropriate copyright notice and
254 disclaimer of warranty; keep intact all the notices that refer to this
255 License and to the absence of any warranty; and give any other
256 recipients of the Program a copy of this License along with the Program.
258 You may charge a fee for the physical act of transferring a copy, and
259 you may at your option offer warranty protection in exchange for a fee.
262 You may modify your copy or copies of the Program or any portion of it,
263 thus forming a work based on the Program, and copy and distribute such
264 modifications or work under the terms of Section@w{ }1 above, provided
265 that you also meet all of these conditions:
269 You must cause the modified files to carry prominent notices stating
270 that you changed the files and the date of any change.
273 You must cause any work that you distribute or publish, that in whole or
274 in part contains or is derived from the Program or any part thereof, to
275 be licensed as a whole at no charge to all third parties under the terms
279 If the modified program normally reads commands interactively when run,
280 you must cause it, when started running for such interactive use in the
281 most ordinary way, to print or display an announcement including an
282 appropriate copyright notice and a notice that there is no warranty (or
283 else, saying that you provide a warranty) and that users may
284 redistribute the program under these conditions, and telling the user
285 how to view a copy of this License. (Exception: if the Program itself
286 is interactive but does not normally print such an announcement, your
287 work based on the Program is not required to print an announcement.)
290 These requirements apply to the modified work as a whole. If
291 identifiable sections of that work are not derived from the Program, and
292 can be reasonably considered independent and separate works in
293 themselves, then this License, and its terms, do not apply to those
294 sections when you distribute them as separate works. But when you
295 distribute the same sections as part of a whole which is a work based on
296 the Program, the distribution of the whole must be on the terms of this
297 License, whose permissions for other licensees extend to the entire
298 whole, and thus to each and every part regardless of who wrote it.
300 Thus, it is not the intent of this section to claim rights or contest
301 your rights to work written entirely by you; rather, the intent is to
302 exercise the right to control the distribution of derivative or
303 collective works based on the Program.
305 In addition, mere aggregation of another work not based on the Program
306 with the Program (or with a work based on the Program) on a volume of a
307 storage or distribution medium does not bring the other work under the
308 scope of this License.
311 You may copy and distribute the Program (or a work based on it, under
312 Section@w{ }2) in object code or executable form under the terms of
313 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
318 Accompany it with the complete corresponding machine-readable source
319 code, which must be distributed under the terms of Sections@w{ }1 and@w{
320 }2 above on a medium customarily used for software interchange; or,
323 Accompany it with a written offer, valid for at least three years, to
324 give any third party, for a charge no more than your cost of physically
325 performing source distribution, a complete machine-readable copy of the
326 corresponding source code, to be distributed under the terms of
327 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
331 Accompany it with the information you received as to the offer to
332 distribute corresponding source code. (This alternative is allowed only
333 for noncommercial distribution and only if you received the program in
334 object code or executable form with such an offer, in accord with
335 Subsection@w{ }b above.)
338 The source code for a work means the preferred form of the work for
339 making modifications to it. For an executable work, complete source
340 code means all the source code for all modules it contains, plus any
341 associated interface definition files, plus the scripts used to control
342 compilation and installation of the executable. However, as a special
343 exception, the source code distributed need not include anything that is
344 normally distributed (in either source or binary form) with the major
345 components (compiler, kernel, and so on) of the operating system on
346 which the executable runs, unless that component itself accompanies the
349 If distribution of executable or object code is made by offering access
350 to copy from a designated place, then offering equivalent access to copy
351 the source code from the same place counts as distribution of the source
352 code, even though third parties are not compelled to copy the source
353 along with the object code.
356 You may not copy, modify, sublicense, or distribute the Program except
357 as expressly provided under this License. Any attempt otherwise to
358 copy, modify, sublicense or distribute the Program is void, and will
359 automatically terminate your rights under this License. However,
360 parties who have received copies, or rights, from you under this License
361 will not have their licenses terminated so long as such parties remain
365 You are not required to accept this License, since you have not signed
366 it. However, nothing else grants you permission to modify or distribute
367 the Program or its derivative works. These actions are prohibited by
368 law if you do not accept this License. Therefore, by modifying or
369 distributing the Program (or any work based on the Program), you
370 indicate your acceptance of this License to do so, and all its terms and
371 conditions for copying, distributing or modifying the Program or works
375 Each time you redistribute the Program (or any work based on the
376 Program), the recipient automatically receives a license from the
377 original licensor to copy, distribute or modify the Program subject to
378 these terms and conditions. You may not impose any further restrictions
379 on the recipients' exercise of the rights granted herein. You are not
380 responsible for enforcing compliance by third parties to this License.
383 If, as a consequence of a court judgment or allegation of patent
384 infringement or for any other reason (not limited to patent issues),
385 conditions are imposed on you (whether by court order, agreement or
386 otherwise) that contradict the conditions of this License, they do not
387 excuse you from the conditions of this License. If you cannot
388 distribute so as to satisfy simultaneously your obligations under this
389 License and any other pertinent obligations, then as a consequence you
390 may not distribute the Program at all. For example, if a patent license
391 would not permit royalty-free redistribution of the Program by all those
392 who receive copies directly or indirectly through you, then the only way
393 you could satisfy both it and this License would be to refrain entirely
394 from distribution of the Program.
396 If any portion of this section is held invalid or unenforceable under
397 any particular circumstance, the balance of the section is intended to
398 apply and the section as a whole is intended to apply in other
401 It is not the purpose of this section to induce you to infringe any
402 patents or other property right claims or to contest validity of any
403 such claims; this section has the sole purpose of protecting the
404 integrity of the free software distribution system, which is implemented
405 by public license practices. Many people have made generous
406 contributions to the wide range of software distributed through that
407 system in reliance on consistent application of that system; it is up to
408 the author/donor to decide if he or she is willing to distribute
409 software through any other system and a licensee cannot impose that
412 This section is intended to make thoroughly clear what is believed to be
413 a consequence of the rest of this License.
416 If the distribution and/or use of the Program is restricted in certain
417 countries either by patents or by copyrighted interfaces, the original
418 copyright holder who places the Program under this License may add an
419 explicit geographical distribution limitation excluding those countries,
420 so that distribution is permitted only in or among countries not thus
421 excluded. In such case, this License incorporates the limitation as if
422 written in the body of this License.
425 The Free Software Foundation may publish revised and/or new versions of
426 the General Public License from time to time. Such new versions will be
427 similar in spirit to the present version, but may differ in detail to
428 address new problems or concerns.
430 Each version is given a distinguishing version number. If the Program
431 specifies a version number of this License which applies to it and ``any
432 later version'', you have the option of following the terms and
433 conditions either of that version or of any later version published by
434 the Free Software Foundation. If the Program does not specify a version
435 number of this License, you may choose any version ever published by the
436 Free Software Foundation.
439 If you wish to incorporate parts of the Program into other free programs
440 whose distribution conditions are different, write to the author to ask
441 for permission. For software which is copyrighted by the Free Software
442 Foundation, write to the Free Software Foundation; we sometimes make
443 exceptions for this. Our decision will be guided by the two goals of
444 preserving the free status of all derivatives of our free software and
445 of promoting the sharing and reuse of software generally.
455 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
456 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
457 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
458 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
459 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
460 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
461 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
462 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
463 NECESSARY SERVICING, REPAIR OR CORRECTION.
466 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
467 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
468 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
469 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
470 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
471 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
472 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
473 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
474 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
478 @heading END OF TERMS AND CONDITIONS
481 @center END OF TERMS AND CONDITIONS
486 @unnumberedsec How to Apply These Terms to Your New Programs
488 If you develop a new program, and you want it to be of the greatest
489 possible use to the public, the best way to achieve this is to make it
490 free software which everyone can redistribute and change under these
493 To do so, attach the following notices to the program. It is safest to
494 attach them to the start of each source file to most effectively convey
495 the exclusion of warranty; and each file should have at least the
496 ``copyright'' line and a pointer to where the full notice is found.
499 @var{one line to give the program's name and an idea of what it does.}
500 Copyright (C) 19@var{yy} @var{name of author}
502 This program is free software; you can redistribute it and/or modify
503 it under the terms of the GNU General Public License as published by
504 the Free Software Foundation; either version 2 of the License, or (at
505 your option) any later version.
507 This program is distributed in the hope that it will be useful, but
508 WITHOUT ANY WARRANTY; without even the implied warranty of
509 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
510 General Public License for more details.
512 You should have received a copy of the GNU General Public License
513 along with this program; if not, write to the Free Software
514 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
517 Also add information on how to contact you by electronic and paper mail.
519 If the program is interactive, make it output a short notice like this
520 when it starts in an interactive mode:
523 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
524 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
525 `show w'. This is free software, and you are welcome to redistribute
526 it under certain conditions; type `show c' for details.
529 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
530 show the appropriate parts of the General Public License. Of course,
531 the commands you use may be called something other than @samp{show@w{
532 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu
533 items---whatever suits your program.
535 You should also get your employer (if you work as a programmer) or your
536 school, if any, to sign a ``copyright disclaimer'' for the program, if
537 necessary. Here is a sample; alter the names:
541 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
542 `Gnomovision' (which makes passes at compilers) written by James
545 @var{signature of Ty Coon}, 1 April 1989 Ty Coon, President of Vice
549 This General Public License does not permit incorporating your program
550 into proprietary programs. If your program is a subroutine library, you
551 may consider it more useful to permit linking proprietary applications
552 with the library. If this is what you want to do, use the GNU Library
553 General Public License instead of this License.
557 @node Introduction, Invoking groff, Copying, Top
558 @chapter Introduction
561 GNU @code{troff} (or @code{groff}) is a system for typesetting
562 documents. @code{troff} is very flexible and has been in existence (and
563 use) for about 3@w{ }decades. It is quite widespread and firmly
564 entrenched in the @sc{Unix} community.
569 * groff Capabilities::
570 * Macro Package Intro::
571 * Preprocessor Intro::
572 * Output device intro::
577 @node What Is groff?, History, Introduction, Introduction
578 @section What Is @code{groff}?
579 @cindex what is @code{groff}?
580 @cindex @code{groff} -- what is it?
582 @code{groff} is of an older generation of document preparation systems,
583 which operate more like compilers than the more recent interactive
584 WYSIWYG@footnote{What You See Is What You Get} systems. @code{groff}
585 and its contemporary counterpart, @TeX{}, both work using a @dfn{batch}
586 paradigm: The input (or @dfn{source}) files are normal text files with
587 embedded formatting commands. These files can then be processed by
588 @code{groff} to produce a typeset document on a variety of devices.
590 Likewise, @code{groff} should not be confused with a @dfn{word
591 processor}, since that term connotes an integrated system which includes
592 an editor and a text formatter. Also, many word processors follow the
593 WYSIWYG paradigm which was discussed earlier.
595 Although WYSIWYG systems may be easier to use, they have a number of
596 disadvantages compared to @code{troff}:
600 They must be used on a bitmapped display to do any operations on your
603 Most of the WYSIWYG systems are either non-free or are not very
606 @code{troff} is firmly entrenched in all @sc{Unix} systems.
608 It is difficult to have a wide range of capabilities available within
609 the confines of a GUI/window system.
611 It is more difficult to make global changes to a document.
615 ``GUIs normally make it simple to accomplish simple actions and
616 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
617 @code{comp.unix.wizards})
621 @node History, groff Capabilities, What Is groff?, Introduction
625 @cindex @code{runoff}
626 @code{troff} can trace its origins back to a formatting program called
627 @code{runoff} which ran on MIT's CTSS system. This name came from the
628 common phrase of the time ``I'll run off a document.''
631 The first version of @sc{Unix} was developed on a PDP-7 which was
632 sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11
633 for further work on the operating system. In order to justify the cost
634 for this system, they proposed that they would implement a document
635 formatting system for the AT&T patents division. This first formatting
636 program was a reimplementation of @code{runoff}. In accordance with
637 @sc{Unix}'s penchant for abbreviations, it was named @code{roff} (an
638 abbreviation of @code{runoff}).
641 When they needed a more flexible language, a new version of @code{roff}
642 called @code{nroff} (Newer @code{roff}) was written. It had a much more
643 complicated syntax, but provided the basis for all future versions.
644 When they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{
645 }Ossanna wrote a version of @code{nroff} which would drive it. It was
646 dubbed @code{troff} for typesetter @code{roff}, although many people
647 have speculated that it actually means Times @code{roff} because of the
648 use of the Times font family in @code{troff} by default. As such, the
649 name @code{troff} is pronounced t-roff rather than trough.
651 With @code{troff} came @code{nroff} (they were actually the same program
652 except for some @samp{#ifdefs}), which was for producing output for line
653 printers and character terminals. It understood everything @code{troff}
654 did, and ignored the commands which were not applicable (e.g.@: font
657 Since there are several things which cannot be done easily in
658 @code{troff}, work on several preprocessors began. These programs would
659 transform certain parts of a document into @code{troff}, which made a
660 very natural use of pipes in @sc{Unix}.
662 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
663 specified in a much simpler and more intuitive manner. @code{tbl} is a
664 preprocessor for formatting tables. The @code{refer} preprocessor (and
665 the similar program, @code{bib}) processes citations in a document
666 according to a bibliographic database.
668 Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
669 language and produced output specifically for the CAT phototypesetter.
670 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
671 code and still dependent on the CAT. As the CAT became less common, and
672 was no longer supported by the manufacturer, the need to make it support
673 other devices became a priority. However, before this could be done, he
674 was killed in an auto accident.
677 @cindex @code{ditroff}
678 So, Brian Kernighan took on the task of rewriting @code{troff}. The
679 newly rewritten version produced a device independent code which was
680 very easy for postprocessors to read and translate to the appropriate
681 printer codes. Also, this new version of @code{troff} (called
682 @code{ditroff}) had several extensions, which included drawing
685 Due to the additional abilities of the new version of @code{troff},
686 several new preprocessors appeared. The @code{pic} preprocessor
687 provides a wide range of drawing functions. Likewise the @code{ideal}
688 preprocessor did the same, although via a much different paradigm. The
689 @code{grap} preprocessor took specifications for graphs, but, unlike
690 other preprocessors, produced @code{pic} code.
692 James Clark began work on a GNU implementation of @code{ditroff} in
693 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
694 June@w{ }1990. @code{groff} included
698 A replacement for @code{ditroff} with many extensions.
700 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
702 Postprocessors for character devices, PostScript, @TeX{} DVI, and X@w{
703 }windows. GNU @code{troff} also eliminated the need for a separate
704 @code{nroff} program with a postprocessor which would produce @sc{ascii}
707 A version of the @code{-me} macros and an implementation of the
711 Also, a front-end was included which could construct the, sometimes
712 painfully long, pipelines required for all the post- and preprocessors.
714 Development of GNU @code{troff} progressed rapidly, and saw the
715 additions of a replacement for @code{refer}, an implementation of the
716 @code{-ms} and @code{-mm} macros, and a program to deduce how to format
717 a document (@code{grog}).
719 It was declared a stable (i.e.@: non beta) package with the release of
720 version@w{ }1.04 around November@w{ }1991.
722 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
723 an orphan for a few years). As a result, new features and programs like
724 @code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an
725 output device to produce HTML output, have been added.
728 @node groff Capabilities, Macro Package Intro, History, Introduction
729 @section @code{groff} Capabilities
730 @cindex @code{groff} capabilities
731 @cindex capabilities of @code{groff}
733 So what exactly is @code{groff} capable of doing? @code{groff} provides
734 a wide range of low-level text formatting operations. Using these, you
735 can perform a wide range of formatting tasks, such as footnotes, table
736 of contents, multiple columns, etc.
740 Text filling, adjusting, and centering
746 Font and character size control
748 Vertical spacing (i.e.@: double spacing)
750 Line length and indenting
752 Macros, strings, diversions, and traps
756 Tabs, leaders, and fields
758 Input and output conventions and character translation
760 Overstrike, bracket, line drawing, and zero-width functions
762 Local horizontal and vertical motions and the width function
766 Output line numbering
768 Conditional acceptance of input
770 Environment switching
772 Insertions from the standard input
774 Input/output file switching
776 Output and error messages
780 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
781 @section Macro Packages
782 @cindex macro packages
784 Since @code{groff} provides such low level facilities, it can be quite
785 difficult to use by itself. However, @code{groff} provides a
786 @dfn{macro} facility which allows you to specify how certain routine
787 operations (e.g.@w{ }starting paragraphs, printing headers and footers,
788 etc.)@: should be done. These macros can be collected together into a
789 @dfn{macro package}. There are a number of macro packages available;
790 the most common (and the ones described in this manual) are @code{-man},
791 @code{-mdoc}, @code{-me}, @code{-ms}, and @code{-mm}.
794 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
795 @section Preprocessors
796 @cindex preprocessors
798 Although @code{groff} provides most functions needed to format a
799 document, some operations would be unwieldy (i.e.@: drawing pictures).
800 Therefore, programs called preprocessors were written which understand
801 their own language and produce the necessary @code{groff} operations.
802 These preprocessors are able to differentiate their own input from the
803 rest of the document via markers.
805 To use a preprocessor, @sc{Unix} pipes are used to feed the output from
806 the preprocessor into @code{groff}. Any number of preprocessors may be
807 used on a given document; in this case, the preprocessors are linked
808 together into one pipeline. However, in @code{groff}, the user does not
809 need to construct the pipe, but only tell @code{groff} what
810 preprocessors to use.
812 @code{groff} currently has preprocessors for producing tables
813 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
814 (@code{pic} and @code{grn}), and for processing bibliographies
815 (@code{refer}). An associated program which is useful when dealing with
816 preprocessors is @code{soelim}.
818 There are other preprocessors in existence, but there are,
819 unfortunately, no free implementations available. They are for drawing
820 pictures (@code{ideal}) and chemical structures (@code{chem}).
822 A free implementation of @code{grap}, a preprocessor for drawing graphs,
823 can be obtained as an extra package.
826 @node Output device intro, Credits, Preprocessor Intro, Introduction
827 @section Output Devices
828 @cindex postprocessors
829 @cindex output devices
830 @cindex devices for output
832 @code{groff} actually produces device independent code which may be fed
833 into a postprocessor which will produce output for a particular device.
834 Currently, @code{groff} has postprocessors for PostScript, character
835 terminals, X@w{ }Windows (for previewing), @TeX{} DVI format, HP
836 LaserJet@w{ }4 printers, and HTML.
839 @node Credits, , Output device intro, Introduction
843 Large portions of this manual were taken from existing documents, most
844 notably, the manual pages for the @code{groff} package by James Clark,
845 and Eric Allman's papers on the @code{-me} macro package.
849 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
850 @chapter Invoking @code{groff}
851 @cindex invoking @code{groff}
852 @cindex @code{groff} invocation
856 This section focuses on how to invoke the @code{groff} front end. This
857 front end takes care of the details of constructing the pipeline among
858 the preprocessors, @code{gtroff} and the postprocessor.
860 It has become a tradition that GNU programs get the prefix @dfn{g} to
861 distinguish it from its original counterparts provided by the host
862 (@pxref{Environment}, for more details). Thus, for example, @code{geqn}
863 is GNU @code{eqn}. On operating systems like Linux or the Hurd, which
864 don't contain proprietary software, this prefix is omitted since GNU
865 @code{troff} is the only used incarnation of @code{troff}. Exception:
866 @code{groff} is never replaced by @code{roff}.
871 * Invocation Examples::
875 @node Options, Environment, Invoking groff, Invoking groff
887 @code{groff} is a front-end to the groff document formatting system.
888 Normally it runs the @code{gtroff} program and a postprocessor
889 appropriate for the selected device. The default device is @samp{ps}.
890 It can optionally preprocess with any of @code{gpic}, @code{geqn},
891 @code{gtbl}, @code{ggrn}, @code{grefer}, or @code{gsoelim}.
893 This section only documents options to the @code{groff} front end. Many
894 of the arguments to @code{groff} are passed on to @code{gtroff},
895 therefore those are also included. Arguments to pre- or postprocessors
896 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
897 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
898 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
899 grohtml}, @ref{Invoking grodvi}, and @ref{Invoking gxditview}.
901 The command line format for @code{groff} is:
904 groff [ -abeghilpstvzCENRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
905 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
906 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
907 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
908 [ @var{files}@dots{} ]
911 The command line format for @code{gtroff} is as follows. As you can
912 see, many of the options to @code{groff} are actually passed on to
916 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
917 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
918 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
919 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
922 Options without an argument can be grouped behind a single @samp{-}. A
923 filename of @samp{-} denotes the standard input.
926 The @code{grog} command can be used to guess the correct @code{groff}
927 command to use to format a file.
931 Print a help message.
933 Preprocess with @code{geqn}.
935 Preprocess with @code{gtbl}.
937 Preprocess with @code{ggrn}.
939 Preprocess with @code{gpic}.
941 Preprocess with @code{gsoelim}.
943 Preprocess with @code{grefer}. No mechanism is provided for passing
944 arguments to @code{grefer} because most @code{grefer} options have
945 equivalent commands which can be included in the file. @xref{grefer},
950 Note that @code{gtroff} also accepts a @samp{-R} option, which is not
951 accessible via @code{groff}. This option prevents the loading of the
952 @file{troffrc} and @file{troffrc-end} files.
954 Make programs run by @code{groff} print out their version number.
956 Print the pipeline on stdout instead of executing it.
958 Suppress output from @code{gtroff}. Only error messages will be
961 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
962 will automatically run the appropriate postprocessor.
964 Pass @var{arg} to the postprocessor. Each argument should be passed
965 with a separate @samp{-P} option. Note that @code{groff} does not
966 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
968 Send the output to a printer. The command used for this is specified by
969 the print command in the device description file.
971 Pass @var{arg} to the spooler. Each argument should be passed with a
972 separate @samp{-L} option. Note that @code{groff} does not prepend a
973 @samp{-} to @var{arg} before passing it to the postprocessor.
975 Prepare output for device @var{dev}. The default device is @samp{ps}.
976 The following are the output devices currently available:
979 For PostScript printers and previewers.
981 For @TeX{} DVI format.
983 For a 75@dmn{dpi} X11 previewer.
985 For a 100@dmn{dpi} X11 previewer.
987 For typewriter-like devices.
989 For typewriter-like devices using the @w{ISO Latin-1} (@w{ISO 8859-1})
992 For typewriter-like devices which use the Unicode (@w{ISO 10646})
993 character set with @w{UTF-8} encoding.
995 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
997 To produce HTML output.
1000 The postprocessor to be used for a device is specified by the
1001 @code{postpro} command in the device description file. (@xref{Font
1002 Files}, for more info.) This can be overridden with the @samp{-X}
1005 Preview with @code{gxditview} instead of using the usual postprocessor.
1006 This is unlikely to produce good results except with @samp{-Tps}.
1008 Don't allow newlines with @code{eqn} delimiters. This is the same as
1009 the @samp{-N} option in @code{geqn}.
1011 Safer mode. Pass the @samp{-S} option to @code{gpic} and use the
1012 @samp{-msafer} macros with @code{gtroff} (enabled by default).
1014 Unsafe mode. Reverts to the old unsafe behaviour.
1016 Generate an @sc{ascii} approximation of the typeset output.
1018 Print a backtrace with each warning or error message. This backtrace
1019 should help track down the cause of the error. The line numbers given
1020 in the backtrace may not always be correct: @code{gtroff} can get
1021 confused by @code{as} or @code{am} requests while counting line numbers.
1023 Read the standard input after all the named input files have been
1026 Enable warning @var{name}. Available warnings are described in
1027 @ref{Debugging}. Multiple @samp{-w} options are allowed.
1029 Inhibit warning @var{name}. Multiple @samp{-W} options are allowed.
1031 Inhibit all error messages.
1033 Enable compatibility mode.
1035 @itemx -d@var{name}=s
1036 Define @var{c} or @var{name} to be a string @var{s}; @var{c} must be a
1037 one-letter @var{name}.
1039 Use @var{fam} as the default font family.
1041 Read in the file @file{tmac.@var{name}}. Normally this will be searched
1042 for in the library directory of @code{groff}.
1044 Number the first page @var{num}.
1046 Output only pages in @var{list}, which is a comma-separated list of page
1047 ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
1048 print every page between @var{m} and @var{n}, @samp{-@var{n}} means
1049 print every page up to @var{n}, @samp{@var{n}-} means print every page
1050 from @var{n}. @code{gtroff} will exit after printing the last page in
1053 @itemx -r@var{name}=@var{n}
1054 Set number register @var{c} or @var{name} to @var{n}; @var{c} must be a
1055 one-letter @var{name}; @var{n} can be any troff numeric expression.
1057 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1058 name of the device) for the @file{DESC} file and font files before the
1061 Search directory @var{dir} for macro files before the normal directory.
1063 This option is as described in @ref{gsoelim}. It implies the @samp{-s}
1068 @node Environment, Invocation Examples, Options, Invoking groff
1069 @section Environment
1070 @cindex environment variables
1071 @cindex variables in environment
1073 There are also several environment variables which can modify the
1074 behavior of @code{groff}.
1077 @item GROFF_COMMAND_PREFIX
1078 @tindex GROFF_COMMAND_PREFIX
1079 If this is set to @var{X}, then @code{groff} will run
1080 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1081 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1082 @code{soelim}. It does not apply to @code{grops}, @code{grodvi},
1083 @code{grotty}, @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1084 @item GROFF_TMAC_PATH
1085 @tindex GROFF_TMAC_PATH
1086 A colon separated list of directories in which to search for macro
1088 @item GROFF_TYPESETTER
1089 @tindex GROFF_TYPESETTER
1090 The default output device.
1091 @item GROFF_FONT_PATH
1092 @tindex GROFF_FONT_PATH
1093 A colon separated list of directories in which to search for the
1094 @code{dev}@var{name} directory.
1097 The search path for commands executed by @code{groff}.
1099 @tindex GROFF_TMPDIR
1101 The directory in which temporary files will be created. If this is not
1102 set and @code{TMPDIR} is set, temporary files will be created in that
1103 directory. Otherwise temporary files will be created in @code{/tmp}.
1104 The @code{grops} and @code{grefer} commands can create temporary files.
1108 @node Invocation Examples, , Environment, Invoking groff
1109 @section Invocation Examples
1110 @cindex invocation examples
1111 @cindex examples of invocation
1113 This section will list several common uses of @code{groff} and the
1114 command line which will accomplish it.
1121 This command processes @var{file} without a macro package or a
1122 preprocessor. The output device is the default, @var{ps}, and the
1123 output is sent to stdout.
1126 groff -t -mandoc -Tascii file | less
1130 This is basically what a call to @code{man} does. The manual page
1131 @var{file} is processed with the @code{-mandoc} macros (which in turn
1132 either call the @code{-man} or the @code{-mdoc} macro package), using
1133 the @code{tbl} preprocessor and the @sc{ascii} output device. Finally,
1134 the result is displayed with the @code{less} pager.
1141 Preview @var{file} with @code{gxditview}, using the @code{-me} macro
1145 groff -man -rD1 -z file
1149 Check @var{file} with the @code{-man} macro package, forcing
1150 double-sided printing---don't produce any output.
1152 @subsection @code{grog}
1154 @code{grog} reads files and guesses which of the @code{groff}
1155 preprocessors and/or macro packages are are required for formatting
1156 them, and prints the @code{groff} command including those options on the
1157 standard output. The options generated are one of @samp{-e},
1158 @samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-R},
1159 @samp{-g}, @samp{-s}, and @samp{-t}.
1161 A filename of @samp{-} is taken to refer to the standard input. If no
1162 files are specified the standard input will be read. Any specified
1163 options will be included in the printed command. No space is allowed
1164 between options and their arguments. For example,
1171 will guess the appropriate command to print @file{paper.ms} and then
1172 print it to the command line after adding the @samp{-Tdvi} option. If
1173 you want to directly execute it, enclose the call to @code{grog} in
1174 backquotes on the @sc{Unix} shell prompt:
1177 `grog -Tdvi paper.ms` > paper.dvi
1181 As you can see, it is still necessary to redirect the output to
1182 something meaningful (i.e.@: either a file or a pager program like
1187 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1188 @chapter Tutorial for Macro Users
1189 @cindex tutorial for macro users
1190 @cindex macro tutorial for users
1191 @cindex user's tutorial for macros
1192 @cindex user's macro tutorial
1194 Most users tend to use a macro package to format their papers. This
1195 means that the whole breadth of @code{groff} is not necessary for most
1196 people. This chapter covers the material needed to efficiently use a
1205 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1209 This section covers some of the basic concepts you will need to
1210 understand to use a macro package.@footnote{This section is derived from
1211 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1212 References are made throughout to more detailed information, if desired.
1214 @code{gtroff} reads an input file prepared by the user and outputs a
1215 formatted paper suitable for publication or framing. The input consists
1216 of text, or words to be printed, and embedded commands (@dfn{requests}
1217 and @dfn{escapes}), which tell @code{gtroff} how to format the printed
1218 copy. For more detail on this @pxref{Embedded Commands}.
1220 The word @dfn{argument} is used in this manual to mean a word or number
1221 which appears on the same line as a request which modifies the meaning
1222 of that request. For example, the request
1229 spaces one line, but
1236 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1237 request which says to space four lines instead of one. Arguments are
1238 separated from the request and from each other by spaces. More details
1239 on this can be found in @ref{Request Arguments}.
1241 The primary function of @code{gtroff} is to collect words from input
1242 lines, fill output lines with those words, justify the right hand margin
1243 by inserting extra spaces in the line, and output the result. For
1251 Four score and seven
1256 will be read, packed onto output lines, and justified to produce:
1259 Now is the time for all good men to come to the aid of their party.
1260 Four score and seven years ago,...
1265 Sometimes you may want to start a new output line even though the line
1266 you are on is not yet full; for example, at the end of a paragraph. To
1267 do this you can cause a @dfn{break}, which starts a new output line.
1268 Some requests cause a break automatically, as do blank input lines and
1269 input lines beginning with a space.
1271 Not all input lines are text to be formatted. Some of the input lines
1272 are requests which describe how to format the text. Requests always
1273 have a period or an apostrophe (@samp{'}) as the first character of the
1276 The text formatter also does more complex things, such as automatically
1277 numbering pages, skipping over page boundaries putting footnotes in the
1278 correct place, and so forth.
1280 Here a few hints for preparing text for input to @code{gtroff}. First,
1281 keep the input lines short. Short input lines are easier to edit, and
1282 @code{gtroff} will pack words onto longer lines for you anyhow. In
1283 keeping with this, it is helpful to begin a new line after every period,
1284 comma, or phrase, since common corrections are to add or delete
1285 sentences or phrases. Secondly, do not hyphenate words at the end of
1286 lines---@code{gtroff} is smart enough to hyphenate words for you as
1287 needed, but is not smart enough to take hyphens out and join a word back
1288 together. Also, words such as ``mother-in-law'' should not be broken
1289 over a line, since then you will get a space where not wanted, such as
1290 ``@w{mother- in}-law''.
1293 @cindex double spacing
1295 @code{gtroff} will double space output text automatically if you use the
1296 request @w{@samp{.ls 2}}. You can revert to single spaced mode by
1297 typing @w{@samp{.ls 1}}.
1299 A number of requests allow you to change the way the printed copy looks,
1300 sometimes called the @dfn{layout} of the output page. Most of these
1301 requests adjust the placing of @dfn{white space} (blank lines or
1306 The @samp{.bp} request starts a new page.
1311 @cindex lines, empty
1312 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1313 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1314 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1315 @var{N}@w{ }centimeters). For example, the input:
1319 My thoughts on the subject
1324 leaves one and a half inches of space, followed by the line ``My
1325 thoughts on the subject'', followed by a single blank line.
1328 @cindex centering lines
1329 @cindex lines, centering
1330 Text lines can be centered by using the @samp{.ce} request. The line
1331 after @samp{.ce} is centered (horizontally) on the page. To center more
1332 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1333 of lines to center), followed by the @var{N}@w{ }lines. If you want to
1334 center many lines but don't want to count them, type:
1343 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1344 lines, in other words, stop centering.
1349 All of these requests cause a break; that is, they always start a new
1350 line. If you want to start a new line without performing any other
1351 action, use @samp{.br}.
1354 @node Common Features, , Basics, Tutorial for Macro Users
1355 @section Common Features
1356 @cindex common features
1357 @cindex features, common
1359 @code{gtroff} provides very low level operations for formatting a
1360 document. There are many common routine operations which are done in
1361 all documents. These common operations are written into @dfn{macros}
1362 and collected into a @dfn{macro package}.
1364 All macro packages provide certain common capabilities which fall into
1365 the following categories.
1367 @subsection Paragraphs
1370 One of the most common and most used capability is starting a paragraph.
1371 There are a number of different types of paragraphs, any of which can be
1372 initiated with macros supplied by the macro package. Normally,
1373 paragraphs start with a blank line and the first line indented, like the
1374 text in this manual. There are also block style paragraphs, which omit
1378 Some men look at constitutions with sanctimonious
1379 reverence, and deem them like the ark of the covenant, too
1380 sacred to be touched.
1384 And there are also indented paragraphs which begin with a tag or label
1385 at the margin and the remaining text indented.
1388 one This is the first paragraph. Notice how the first
1389 line of the resulting paragraph lines up with the
1390 other lines in the paragraph.
1392 This paragraph had a long label. The first
1393 character of text on the first line will not line up
1394 with the text on second and subsequent lines,
1395 although they will line up with each other.
1398 A variation of this is a bulleted list.
1401 @subsection Sections and Chapters
1403 Most macro packages supply some form of section headers. The simplest
1404 kind is simply the heading on a line by itself in bold type. Others
1405 supply automatically numbered section heading or different heading
1406 styles at different levels. Some, more sophisticated, macro packages
1407 supply macros for starting chapters and appendices.
1409 @subsection Headers and Footers
1411 Every macro packages gives you some way to manipulate the headers and
1412 footers (or @dfn{titles}) on each page. Some packages will allow you to
1413 have different ones on the even and odd pages (for material printed in a
1416 The titles are called three-part titles, that is, there is a
1417 left-justified part, a centered part, and a right-justified part. An
1418 automatically generated page number may be put in any of these fields
1419 with the @samp{%} character (@pxref{Page Layout} for more details).
1421 @subsection Page Layout
1423 Most macro packages let you specify top and bottom margins and other
1424 details about the appearance of the printed pages.
1426 @subsection Displays
1429 Displays are sections of text to be set off from the body of the paper.
1430 Major quotes, tables, and figures are types of displays, as are all the
1431 examples used in this document.
1433 @cindex quotes, major
1434 @cindex major quotes
1435 @dfn{Major quotes} are quotes which are several lines long, and hence
1436 are set in from the rest of the text without quote marks around them.
1439 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1440 should be used when the material to be printed should not be filled and
1441 justified like normal text, such as columns of figures or the examples
1445 A @dfn{keep} is a display of lines which are kept on a single page if
1446 possible. An example of where you would use a keep might be a diagram.
1447 Keeps differ from lists in that lists may be broken over a page boundary
1448 whereas keeps will not.
1450 @cindex keep, floating
1451 @cindex floating keep
1452 Floating keeps move relative to the text. Hence, they are good for
1453 things which will be referred to by name, such as ``See figure@w{ }3''.
1454 A floating keep will appear at the bottom of the current page if it will
1455 fit; otherwise, it will appear at the top of the next page. Meanwhile,
1456 the surrounding text will `flow' around the keep, thus leaving now blank
1459 @subsection Footnotes and annotations
1463 There are a number of requests to save text for later printing.
1464 @dfn{Footnotes} are printed at the bottom of the current page. Delayed
1465 text is intended to be a variant form of footnote; the text is printed
1466 only when explicitly called for, such as at the end of each chapter.
1468 @cindex delayed text
1469 @dfn{Delayed text} is very similar to a footnote except that it is
1470 printed when called for explicitly. This allows a list of references to
1471 appear (for example) at the end of each chapter, as is the convention in
1474 Most macro packages which supply this functionality also supply a means
1475 of automatically numbering either type of annotation.
1477 @subsection Table of Contents
1478 @cindex table of contents
1479 @cindex contents, table of
1481 @dfn{Tables of contents} are a type of delayed text having a tag
1482 (usually the page number) attached to each entry after a row of dots.
1483 The table accumulates throughout the paper until printed, usually after
1484 the paper has ended. Many macro packages will provide the ability to
1485 have several tables of contents (i.e.@: one standard one, one for
1491 While some macro packages will use the term @dfn{index}, none actually
1492 provide that functionality. The facilities they call indices are
1493 actually more appropriate for tables of contents.
1495 @subsection Paper formats
1496 @cindex paper formats
1498 Some macro packages provide stock formats for various kinds of
1499 documents. Many of them provide a common format for the title and
1500 opening pages of a technical paper. The @code{-mm} macros in particular
1501 provide formats for letters and memoranda.
1503 @subsection Multiple Columns
1505 Some macro packages (except @code{-man}) provide the ability to have two
1506 or more columns on a page.
1508 @subsection Font and Size changes
1510 The built-in font and size functions are not always intuitive, so all
1511 macro packages provide macros to make these operations simpler.
1513 @subsection Predefined Strings
1515 Most macro packages provide various predefined strings for a variety of
1516 uses, examples are sub- and superscripts, printable dates, quotes and
1517 various special characters.
1519 @subsection Preprocessor Support
1521 All macro packages provide support for the various preprocessors.
1523 @subsection Configuration and Customization
1525 Some macro packages provide means of customizing many of details of how
1526 the package behaves. This ranges from setting the default type size to
1527 changing the appearance of section headers.
1531 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1532 @chapter Macro Packages
1533 @cindex macro packages
1534 @cindex packages, macros
1536 This chapter documents the main macro packages that come with
1548 @node -man, -mdoc, Macro Packages, Macro Packages
1552 @c XXX documentation
1555 @node -mdoc, -ms, -man, Macro Packages
1557 @cindex @code{-mdoc}
1559 @c XXX documentation
1562 @node -ms, -me, -mdoc, Macro Packages
1566 @c XXX documentation
1569 @node -me, -mm, -ms, Macro Packages
1573 @c XXX documentation
1576 @node -mm, , -me, Macro Packages
1580 @c XXX documentation
1584 @node Programming Tutorial, Preprocessors, Macro Packages, Top
1585 @chapter Programming Tutorial
1586 @cindex programming tutorial
1587 @cindex tutorial for programming
1589 This chapter covers @strong{all} of the facilities of @code{gtroff}. If
1590 you are intending to use a macro package, you probably do not want to
1595 * Input Conventions::
1599 * Embedded Commands::
1601 * Manipulating Filling and Adjusting::
1602 * Manipulating Hyphenation::
1603 * Manipulating Spacing::
1605 * Character Translations::
1612 * Conditionals and Loops::
1615 * Drawing Requests::
1620 * Postprocessor Access::
1623 * Implementation Differences::
1628 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
1632 @code{gtroff} input files contain text with control commands
1633 interspersed throughout. But, even without control codes, @code{gtroff}
1634 will still do several things with your text: filling and adjusting,
1635 adding additional space after sentences, hyphenating and inserting
1636 implicit line breaks.
1639 * Filling and Adjusting::
1643 * Implicit Line Breaks::
1646 @node Filling and Adjusting, Hyphenation, Text, Text
1647 @subsection Filling and Adjusting
1648 @cindex filling and adjusting
1649 @cindex adjusting and filling
1651 When @code{gtroff} reads in text it collects words from input and fits
1652 as many of them together on one output line as it can. This is known as
1655 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
1656 it. which means it will widen the spacing between words until the text
1657 reaches the right margin (in the default adjustment mode). Extra spaces
1658 between words are preserved, but spaces at the end of lines are ignored.
1659 Spaces at the front of a line will cause a @dfn{break} (breaks will be
1660 explained in @ref{Implicit Line Breaks})
1662 @xref{Manipulating Filling and Adjusting}.
1664 @node Hyphenation, Sentences, Filling and Adjusting, Text
1665 @subsection Hyphenation
1668 Since the odds of finding a set of words, for every output line, which
1669 will fit nicely on a line without inserting excessive amounts of space
1670 between words is not great, @code{gtroff} will hyphenate words so that
1671 lines can be justified without there being too much space between words.
1672 It uses an internal hyphenation algorithm, to indicate which words can
1673 be hyphenated and how to do so. When a word is hyphenated the first
1674 part of the word will be added to the current filled line being output
1675 (with an attached hyphen), and the other portion will be added to the
1676 next line to be filled.
1678 @xref{Manipulating Hyphenation}.
1680 @node Sentences, Tab Stops, Hyphenation, Text
1681 @subsection Sentences
1684 Although it is often debated, some typesetting rules say there should be
1685 different amounts of space after various punctuation marks. For example,
1686 a period at the end of a sentence should have twice as much space
1687 following it as would a comma or a period as part of an abbreviation.
1689 @cindex sentence spaces
1690 @cindex spaces between sentences
1691 @cindex french-spacing
1692 @code{gtroff} does this by flagging certain characters (normally
1693 @samp{!}, @samp{?} and @samp{.}) as @dfn{end of sentence} characters.
1694 When @code{gtroff} encounters one of these characters at the end of a
1695 line it will append two @dfn{sentence spaces} in the formatted output.
1696 (Thus, one of the conventions mentioned in @ref{Input Conventions}).
1698 @c XXX also describe how characters like ) are treated here -jjc
1699 @c gotta do some research on this -trent
1701 @node Tab Stops, Implicit Line Breaks, Sentences, Text
1702 @subsection Tab Stops
1704 @cindex stops, tabulator
1706 @code{gtroff} translates @dfn{tabulator stops}, also called @dfn{tabs},
1707 in the input into movements to the next tab stop. These tab stops are
1708 initially located every half inch across the page. Using this you can
1709 make simple tables. However, this can often be deceptive as the
1710 appearance (and width) of your text on a terminal and the results from
1711 @code{gtroff} can vary greatly.
1713 Also, a possible sticking point is that lines beginning with tab
1714 characters will still be filled, again producing unexpected results.
1715 For example, the following input
1717 @multitable {12345678} {12345678} {12345678} {12345678}
1719 @tab 1 @tab 2 @tab 3
1727 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
1729 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
1732 @xref{Tabs and Fields}.
1734 @node Implicit Line Breaks, , Tab Stops, Text
1735 @subsection Implicit Line Breaks
1736 @cindex implicit line breaks
1737 @cindex implicit breaks of lines
1738 @cindex line, implicit breaks
1740 @cindex break, implicit
1743 An important concept in @code{gtroff} is the @dfn{break}. When a break
1744 occurs, @code{gtroff} will output the partially filled line
1745 (unadjusted), and resume collecting and filling text on the next output
1751 There are several ways to cause a break in @code{gtroff}. A blank line
1752 will not only cause a break, but it will also cause a one line vertical
1753 space (effectively a blank line) to be output.
1755 A line which begins with a space will cause a break and the space will
1756 be output at the beginning of the next line. Note that this space isn't
1757 adjusted, even in fill mode.
1759 The end of file will also cause a break (otherwise the last line of your
1760 document may vanish!)
1762 Certain requests also cause breaks, implicitly or explicity. This will
1765 @xref{Manipulating Filling and Adjusting}.
1768 @node Input Conventions, Measurements, Text, Programming Tutorial
1769 @section Input Conventions
1770 @cindex input conventions
1771 @cindex conventions for input
1773 Since @code{gtroff} does filling automatically, it is traditional in
1774 @code{groff} not to try and type things in as nicely formatted
1775 paragraphs. These are some conventions commonly used when typing
1780 Break lines after punctuation, particularly at the end of sentences,
1781 and in other logical places. Keep separate phrases on lines by
1782 themselves, as entire phrases are often added or deleted when editing.
1784 Try to keep lines less than 40-60@w{ }characters, to allow space for
1785 inserting more text.
1787 Do not try to do any formatting in a WYSIWYG manner (i.e.@: don't try
1788 and use spaces to get proper indentation).
1792 @node Measurements, Expressions, Input Conventions, Programming Tutorial
1793 @section Measurements
1794 @cindex measurements
1796 @cindex units of measurement
1798 @cindex machine units
1799 @cindex measurement units
1800 @code{gtroff} (like any other programs) requires numeric parameters to
1801 specify various measurements. Most numeric parameters@footnote{those
1802 that specify vertical or horizontal motion or a type size} may have a
1803 @dfn{measurement unit} attached. These units are specified as a single
1804 character which immediately follows the number or expression. Each of
1805 these units are understood, by @code{gtroff}, to be a multiple of its
1806 @dfn{basic unit}. So, whenever a different measurement unit is
1807 specified @code{gtroff} converts this into its @dfn{basic units}. This
1808 basic unit, represented by a @samp{u}, is a device dependent measurement
1809 which is quite small, ranging from 1/75th to 1/72000th of an inch; all
1810 other units are converted eventually to basic units. The values may be
1811 given as fractional numbers---nevertheless, fractional basic units are
1812 always rounded to integers.
1814 Some of the measurement units are completely independent of any of the
1815 current settings (e.g.@: type size) of @code{gtroff}.
1820 @cindex @code{i} unit
1821 @cindex unit, @code{i}
1822 Inches. An antiquated measurement unit still in use in certain
1823 backwards countries. One inch is equal to 2.54@dmn{cm}.
1826 @cindex @code{c} unit
1827 @cindex unit, @code{c}
1828 Centimeters. One centimeter is equal to 0.3937@dmn{in}.
1831 @cindex @code{p} unit
1832 @cindex unit, @code{p}
1833 Points. This is a typesetter's measurement used for measure type size.
1834 It is 72@w{ }points to an inch.
1837 @cindex @code{P} unit
1838 @cindex unit, @code{P}
1839 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
1840 12@w{ }points to a pica).
1843 @cindex @code{s} unit
1844 @cindex unit, @code{s}
1845 @cindex @code{z} unit
1846 @cindex unit, @code{z}
1847 @xref{Fractional Type Sizes}, for a discussion of these units.
1850 The other measurements understood by @code{gtroff} are dependent on
1851 settings currently in effect in @code{gtroff}. These are very useful
1852 for specifying measurements which should look proper with any size of
1858 @cindex @code{m} unit
1859 @cindex unit, @code{m}
1860 Ems. This unit is equal to the current font size in points. So called
1861 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
1862 in the current font.
1865 @cindex @code{n} unit
1866 @cindex unit, @code{n}
1867 Ens. This is half of an em.
1869 @cindex vertical space
1870 @cindex space, vertical
1871 @cindex @code{v} unit
1872 @cindex unit, @code{v}
1873 Vertical space. This is equivalent to the current line spacing.
1874 @xref{Sizes}, for more information about this.
1876 @cindex @code{M} unit
1877 @cindex unit, @code{M}
1881 @xref{Fractional Type Sizes}.
1887 @node Default Units, , Measurements, Measurements
1888 @subsection Default Units
1889 @cindex default units
1890 @cindex units, default
1892 Many requests take a default unit. While this can be helpful at times,
1893 it can cause strange errors in some expressions. For example, the line
1894 length request expects em's. Here are several attempts to get a line
1895 length of 3.5@w{ }inches and the results:
1902 7i/2u @result{} 3.5i
1906 As you can see, the safest way to specify measurements is to always
1907 attach a scaling indicator.
1910 @node Expressions, Identifiers, Measurements, Programming Tutorial
1911 @section Expressions
1914 @code{gtroff} has most of operators common to other languages:
1916 @c XXX more details; examples
1920 @cindex arithmetic operators
1921 @cindex operators, arithmetic
1927 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
1928 (division), @samp{*} (multiplication), @samp{%} (modulo).
1930 @cindex comparison operators
1931 @cindex operators, comparison
1938 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
1939 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
1940 (equal), @samp{==} (the same as @samp{=}).
1942 @cindex logical operators
1943 @cindex operators, logical
1946 Logical: @samp{&} (logical and), @samp{:} (logical or).
1948 @cindex unary operators
1949 @cindex operators, unary
1953 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
1954 (just for completeness; does nothing in expressions), @samp{!} (logical
1955 not). See below for the use of unary operators in motion requests.
1956 @c XXX (if/while only??)
1958 @cindex extremum operators
1959 @cindex operators, extremum
1962 Extremum: @samp{>?} (maximum), @samp{<?} (minimum). For example,
1963 @samp{5>?3} yields@w{ }@samp{5}.
1966 @cindex scaling operator
1967 @cindex operator, scaling
1968 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
1969 the default scaling indicator. If @var{c} is missing, ignore scaling
1970 indicators in the evaluation of @var{e}.
1976 Parentheses may be used as in any other language. However, in
1977 @code{gtroff} they are necessary to ensure order of evaluation.
1978 @code{gtroff} has no operator precedence; expressions are evaluated left
1979 to right. This means that @samp{3+5*4} is evaluated as if it were
1980 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may
1986 @cindex motion operators
1987 @cindex operators, motion
1988 For many requests which cause a motion on the page, the unary operators
1989 work differently. The @samp{+} and @samp{-} operators indicate a motion
1990 relative to the current position (down or up, respectively). The
1991 @samp{|} operator indicates an absolute position on the page or input
1994 @samp{+} and @samp{-} are also treated differently by the @code{nr}
1996 @c XXX (?), add xref
1998 @cindex space characters in expressions
1999 @cindex expressions and space characters
2000 Due to the way arguments are parsed, spaces are not allowed in
2001 expressions, unless the entire expression is surrounded by parentheses.
2003 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2006 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
2007 @section Identifiers
2014 Like any other language, @code{gtroff} has rules for properly formed
2015 @dfn{identifiers}. In @code{gtroff} an identifier can be made up of
2016 almost any printable character. The only exception are characters which
2017 are interpreted by @code{gtroff} (backslash, square brackets, and
2018 @samp{?}). So, for example, any of the following is valid.
2029 You can test whether an identifier is valid in @code{gtroff} with the
2030 @code{\A} escape. It expands to@w{ }1 or@w{ }0 according to whether its
2031 argument (given in quotes) is or is not acceptable as the name of a
2032 string, macro, diversion, number register, environment, or font. It
2033 will return@w{ }0 if no argument is given. This is useful if you want
2034 to look up user input in some sort of associative table.
2036 @c XXX add xrefs above
2038 Identifiers in @code{gtroff} can be any length, but, in some contexts,
2039 @code{gtroff} needs to be told where identifiers end and text begins
2040 (and in different ways depending on their length).
2049 Two characters. Must be prefixed with @samp{(} in some situations.
2051 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
2052 and@w{ }@samp{]} in some situations. Any length identifier can be put
2056 Unlike many other programming languages, undefined identifiers are
2057 silently ignored or expanded to nothing.
2059 @c XXX add info about -ww command line option.
2061 @xref{Interpolating Registers}, and @ref{Strings}.
2064 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
2065 @section Embedded Commands
2066 @cindex embedded commands
2067 @cindex commands, embedded
2069 With most documents you need more functionality beyond filling, adjusting
2070 and implicit line breaking. In order to gain further functionality,
2071 @code{gtroff} allows commands to be embedded into your text, in two
2074 The first is a @dfn{request} which takes up an entire line, and does
2075 some large scale operation (e.g.@: break lines, start new pages).
2077 The other is an @dfn{escape} which can be embedded anywhere in your
2078 text, or even as an argument to a request.
2079 @c XXX (Not always?)
2080 Escapes generally do more minor operations like sub- and superscripts,
2081 print a symbol, etc.
2089 @node Requests, Macros, Embedded Commands, Embedded Commands
2090 @subsection Requests
2093 @cindex control character
2094 @cindex character, control
2097 A request line begins with a control character, which is either a single
2098 quote (@samp{'}) or a period (@samp{.}). These can be changed;
2099 @xref{Character Translations}, for details. After this there may be
2100 optional tabs or spaces followed by an identifier which is the name of
2101 the request. This may be followed by any number of space separated
2105 If you want to begin a line with a control character without it being
2106 interpreted, precede it with @code{\&}. This represents a zero width
2107 space, which means it will not affect your output.
2109 In most cases you will use the period as a control character. Several
2110 requests will cause a break; using the single quote control character
2114 * Request Arguments::
2117 @node Request Arguments, , Requests, Requests
2118 @subsubsection Request Arguments
2119 @cindex request arguments
2120 @cindex arguments to requests
2122 Arguments to requests (and macros) are processed much like the shell:
2123 The line is split into arguments according to spaces. An argument which
2124 is intended to contain spaces can either be enclosed in quotes (single
2125 or double), or have the spaces @dfn{escaped} with backslashes.
2130 .uh The Mouse Problem
2131 .uh "The Mouse Problem"
2132 .uh The\ Mouse\ Problem
2136 The first line is the @code{uh} macro being called with 3 arguments,
2137 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
2138 same effect or calling the @code{uh} macro with one argument @samp{The
2141 Note, however, that the @code{ds} request works differently.
2145 @node Macros, Escapes, Requests, Embedded Commands
2149 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
2150 which can be invoked by name. They are called in the same manner as
2151 requests---arguments also may be passed in the same manner.
2153 @xref{Writing Macros}, and @ref{Request Arguments}.
2155 @node Escapes, , Macros, Embedded Commands
2161 Escapes may occur anywhere in the input to @code{gtroff}. They begin
2162 with a backslash and are followed by a single character which indicates
2163 the function to be performed. If you want to have a backslash appear in
2164 your document, you should use the escape sequence @code{\e}. Merely
2165 escaping the backslash with another backslash will work in @emph{some}
2168 Many escapes have no parameters; those that do, do so in one of two
2169 ways. For escapes which require an identifier there must be a way for
2170 @code{gtroff} to tell where the identifier ends and the text begins. It
2171 assumes that the next single character is the identifier, but if that
2172 character is an opening parenthesis, it takes the next two characters as
2173 the identifier; and if the next character is an opening bracket, all
2174 characters until a closing bracket are taken as the identifier. Note
2175 that in the second case there is no closing parenthesis. For example:
2184 Other escapes may require several arguments and/or some special format.
2185 In these cases the @dfn{argument} is enclosed in single quotes
2186 @c XXX (not required??)
2187 and the enclosing text is decoded according to what that escape expects.
2196 If you want to have a backslash appear in your output, you can use
2197 several escapes: @code{\\}, @code{\e} or @code{\E}. These are very
2198 similar, and only differ with respect to being used in macros or
2199 diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for more
2208 @node Comments, , Escapes, Escapes
2209 @subsubsection Comments
2213 Probably one of the most@footnote{Unfortunately, this is a lie. But
2214 hopefully future @code{gtroff} hackers will believe it :-)} common forms
2215 of escapes is the comment. They begin with the @code{\"} escape and end
2216 at the end of the input line.
2218 This may sound simple, but it can be tricky to keep the comments from
2219 interfering with the appearance of your final output.
2222 If the escape is to the right of some text or a request, that portion of
2223 the line will be ignored, but the space leading up to it will be noticed
2224 by @code{gtroff}. This only affects the @code{.ds} request.
2225 @c XXX (any others?)
2227 One possibly irritating idiosyncracy is that you must not use tabs to
2228 line up your comments. Tabs are not treated as white space between the
2229 request and macro arguments.
2231 @cindex undefined request
2232 @cindex request, undefined
2233 If you have a comment on a line by itself, it will be treated as a blank
2234 line, because after eliminating the comment, that is all that remains.
2235 So, it is common to start the line with @code{.\"} which will cause the
2236 line to be treated as an undefined request.
2238 Another commenting scheme seen sometimes is three consecutive single
2239 quotes (@code{'''}) at the beginning of a line. This works, but
2240 @code{gtroff} will give a warning about an undefined macro, which is
2241 harmless, but irritating.
2244 Now to avoid all this @code{gtroff} has a new comment mechanism using
2245 the @code{\#} escape. This escape works the same as @code{\"} except
2246 that the newline is also ignored.
2249 For large blocks of text, the @code{ig} request may be useful.
2253 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
2257 Numeric variables in @code{gtroff} are called @dfn{registers}. There
2258 are a number of built-in registers, supplying anything from the date to
2259 details of formatting parameters.
2264 * Setting Registers::
2265 * Interpolating Registers::
2267 * Assigning Formats::
2268 * Built-in Registers::
2271 @node Setting Registers, Interpolating Registers, Registers, Registers
2272 @subsection Setting Registers
2273 @cindex setting registers
2274 @cindex registers, setting
2278 Registers are defined resp.@: set via the @code{nr} request or the
2279 @code{\R} escape. For example, the following two lines are equivalent:
2287 The @code{rr} request will remove the register specified by the
2291 The @code{rnn} request will rename a number register. The format is
2292 @w{@samp{.rnn @var{x} @var{y}}}, which will rename number register
2296 Aliases can be created for a number register. The format is
2297 @w{@samp{.aln @var{xx} @var{yy}}}, which will create an alias @var{xx}
2298 for number register object named @var{yy}. The new name and the old
2299 name will be exactly equivalent. If @var{yy} is undefined, a warning of
2300 type @samp{reg} will be generated, and the request will be ignored.
2301 @xref{Debugging}, for information about warnings.
2303 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
2304 @subsection Interpolating Registers
2305 @cindex interpolating registers
2306 @cindex registers, interpolating
2309 Numeric registers are @dfn{interpolated} via the @code{\n} escape.
2311 @c XXX the following is wrong. Should I say any more than the above??
2312 @c This means that the value of the number register is expanded in-place
2313 @c on the input line before any other actions, i.e. before requests and
2314 @c escapes are interpreted.
2321 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
2322 @subsection Auto-increment
2323 @cindex auto-increment
2324 @cindex increment, automatic
2327 Number registers can also be auto-incremented and auto-decremented. You
2328 can specify the increment resp.@: decrement factor with a third argument
2329 to the @code{nr} request. The default value is@w{ }0. For example,
2334 \n+a, \n+a, \n+a, \n+a, \n+a
2336 \n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx
2347 If you want to change the increment factor without changing the value of
2348 a register, the following can be used.
2354 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
2355 @subsection Assigning Formats
2356 @cindex assigning formats
2357 @cindex formats, assigning
2360 When a register is used in the text of an input file (as opposed to part
2361 of an expression) it is textually replaced (or interpolated) with a
2362 representation of that number. This output format can be changed to a
2363 variety of formats (numbers, Roman numerals, etc). This is done using
2364 the @code{af} request. The first argument to @code{af} is the name of
2365 the number register to be changed, and the second argument is the output
2366 format. The following output formats are available:
2370 This is the default format, decimal numbers: 1, 2, 3,@w{ }@dots{}
2372 Decimal numbers with as many leading zeros as specified. So, @samp{001}
2373 would result in 001, 002, 003,@w{ }@dots{}
2375 @cindex roman numerals
2376 @cindex numerals, Roman
2377 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@dots{}
2379 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@dots{}
2381 Upper-case letters: A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@dots{}
2383 Lower-case letters: a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@dots{}
2386 The following example will produce @samp{10, X, j, 010}:
2390 .af a 1 \" the default format
2401 The @code{\g} escape returns the current format of the specified
2402 register. For example, @samp{\ga} after the previous example would
2405 @node Built-in Registers, , Assigning Formats, Registers
2406 @subsection Built-in Registers
2407 @cindex built-in registers
2408 @cindex registers, built-in
2410 The following lists some built-in registers which are not described
2411 elsewhere in this manual. Any register which begin with a @samp{.} is
2412 read-only. A complete listing of all built-in registers can be found in
2413 @ref{Register Index}.
2418 Horizontal resolution in basic units.
2421 Vertical resolution in basic units.
2424 Day of the week (1-7).
2427 Day of the year (1-31).
2430 Current month (1-12).
2436 The year minus@w{ }1900. Unfortunately, the @sc{Unix} Version@w{ }7
2437 troff documentation had a year@w{ }2000 bug: It incorrectly claimed that
2438 @samp{\n(yr} was the last two digits of the year. That claim has never
2439 been true of either traditional @code{troff} or GNU @code{troff}. If
2440 you see old @code{troff} input that looks like this:
2443 '\" The following line stopped working after 1999
2444 This document was formatted in 19\n(yr.
2448 you can correct it as follows:
2451 This document was formatted in \n[year].
2455 or, if you want to be portable to older @code{troff} versions, as
2460 This document was formatted in \n(y4.
2467 The current @emph{input} line number.
2470 The current @emph{output} line number.
2473 The major version number. For example, if the version number is@w{
2474 }1.03 then @code{.x} will contain@w{ }@samp{1}.
2477 The minor version number. For example, if the version number is@w{
2478 }1.03 then @code{.y} will contain@w{ }@samp{03}.
2481 The revision number of @code{groff}.
2484 Always@w{ }1. Macros should use this to determine whether they are
2485 running under GNU @code{troff}.
2488 If the current output device is @sc{ascii}, this is set to@w{ }1, zero
2492 This register indicates whether the current page is actually being
2493 printed, i.e., whether the @samp{-o} option is being used to only print
2494 selected pages. @xref{Options}, for more information.
2498 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
2499 @section Manipulating Filling and Adjusting
2500 @cindex manipulating filling and adjusting
2501 @cindex filling and adjusting, manipulating
2502 @cindex adjusting and filling, manipulating
2503 @cindex justifying text
2504 @cindex text, justifying
2509 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
2510 Breaks}. The @code{br} request will likewise cause a break. Several
2511 other requests will also cause breaks, but implicitly. They are
2512 @code{bp}, @code{ce}, @code{fi}, @code{fl}, @code{in}, @code{nf},
2513 @code{sp}, and @code{ti}.
2518 Initially, @code{gtroff} will fill and adjust text to both margins.
2519 Filling can be disabled via the @code{nf} request and re-enabled with
2520 the @code{fi} request. These implicitly disable and re-enable
2521 adjusting. Both of these will cause a break in the text currently being
2522 filled. The number register @code{.u} is equal to@w{ }1 in fill mode
2523 and@w{ }0 in no-fill mode.
2527 Adjusting can be disabled with the @code{ad} request and re-enabled with
2528 the @code{na} request. The @code{ad} request takes a single argument to
2529 indicate how to adjust text.
2533 @cindex ragged-right
2534 Adjust text to the left margin. This produces what is traditionally
2535 called ragged-right text.
2538 Adjust text to the right margin, producing ragged-left text.
2540 @cindex centered text
2542 @c XXX difference to .ce?
2545 Justify to both margins. This is default of @code{gtroff}.
2548 With no argument to @code{ad}, @code{gtroff} will adjust lines the same
2549 way it was the last time it was filling. For example:
2559 .ad \" back to centering
2564 The current adjustment mode is available in the number register
2568 The escape @code{\p} will cause a break and the remaining text to be
2571 @cindex word space size
2572 @cindex size of word space
2573 @cindex space between words
2574 @cindex sentence space size
2575 @cindex size of sentence space
2576 @cindex space between sentences
2578 The @code{ss} request allows you to change the minimum size of a space
2579 between filled words. This request takes its units as one twelfth of
2580 the space width parameter for the current font. Initially both the word
2581 space size and the sentence space size are@w{ }12.
2583 If two arguments are given to the @code{ss} request, the second argument
2584 gives the sentence space size. If the second argument is not given, the
2585 sentence space size will be the same as the word space size. The
2586 sentence space size is used in two circumstances: If the end of a
2587 sentence occurs at the end of a line in fill mode, then both an
2588 inter-word space and a sentence space will be added; if two spaces
2589 follow the end of a sentence in the middle of a line, then the second
2590 space will be a sentence space. Note that the behaviour of @sc{Unix}
2591 @code{troff} will be exactly that exhibited by GNU @code{troff} if a
2592 second argument is never given to the @code{ss} request. In GNU
2593 @code{troff}, as in @sc{Unix} @code{troff}, you should always follow a
2594 sentence with either a newline or two spaces.
2598 The number registers @code{.ss} and @code{.sss} are the values of the
2599 parameters set by the first and second arguments of the @code{ss}
2603 @cindex centering lines
2604 @cindex lines, centering
2605 The @code{ce} request will center text. While the @w{@samp{ad c}}
2606 request will also center text, it has the side effect of filling the
2607 text. The @code{.ce} request will not fill the text it affects. This
2608 request causes a break.
2610 With no arguments, @code{ce} will fill the next line of text. The
2611 single argument @code{ce} takes is a number indicating the number of
2612 lines to be centered. If the argument is zero, centering is disabled.
2614 A common idiom is to turn on centering for a large number of lines, and
2615 then turn off centering when you are done with the centered text. This
2616 is useful for any request which takes a number of lines as an argument.
2629 The @code{.ce} number register contains the number of lines remaining to
2630 be centered, as set by the @code{ce} request.
2632 @cindex justifying text
2633 @cindex text, justifying
2634 @cindex right-justifying
2637 A similar request is @code{rj} request which will justify unfilled text
2638 to the right margin. Its arguments are identical to the @code{ce}
2639 request. The @code{.rj} number register is the number of lines to be
2640 right-justified as set by the @code{rj} request.
2643 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
2644 @section Manipulating Hyphenation
2645 @cindex manipulating hyphenation
2646 @cindex hyphenation, manipulating
2648 As discussed in @ref{Hyphenation}, @code{gtroff} will hyphenate words.
2649 There are a number of ways to influence how hyphenation is done.
2654 Hyphenation can be turned off with the @code{nh} request, and turned
2655 back on with the @code{hy} request. However, the hyphenation facilities
2656 of @code{gtroff} are far more flexible than this. The @code{hy} request
2657 can be used to tell @code{gtroff} to restrict hyphenation to certain
2658 cases. The request takes a single numeric argument. The current
2659 hyphenation restrictions can be found in the number register @code{.hy}.
2663 The default argument, which indicates to hyphenate without restrictions.
2665 Do not hyphenate the last word on a page or column.
2667 Do not hyphenate the last two characters of a word.
2669 Do not hyphenate the first two characters of a word.
2672 The values in the previous table are additive. For example, the
2673 value@w{ }12 causes @code{gtroff} to neither hyphenate the last two nor
2674 the first two characters of a word.
2680 @cindex explicit hyphens
2681 @cindex hyphen, explicit
2682 The @code{hlm} request will set the maximum number of consecutive
2683 hyphenated lines to the value given as the first argument. If this
2684 number is negative, there is no maximum. The default value is@w{ }-1.
2685 This value is associated with the current environment. Only lines
2686 output from an environment count towards the maximum associated with
2687 that environment. Hyphens resulting from @code{\%} are counted;
2688 explicit hyphens are not. The current setting of this is available in
2689 the @code{.hlm} register. Also the number of immediately preceding
2690 consecutive hyphenated lines are available in the number register
2694 The @code{hw} request allows you to specify how a specific word is to be
2695 hyphenated. It takes only one argument which is the word with hyphens
2696 at the hyphenation points. For example:
2703 This request can be used more than once.
2706 @c In old versions of troff there was a
2707 @c limited amount of space to store such information, fortunately,
2708 @c with groff, this is no longer a restriction.
2711 @cindex hyphenation character
2712 @cindex character, hyphenation
2713 @cindex disabling hyphenation
2714 @cindex hyphenation, disabling
2715 You can also tell @code{gtroff} how to hyphenate words on the fly with
2716 the use of the @code{\%} escape, also known as the @dfn{hyphenation
2717 character}. Preceding a word with this character will prevent it from
2718 being hyphenated, putting it in a word will indicate to @code{gtroff}
2719 that the word may be hyphenated at that point. Note that this mechanism
2720 will only affect one word; if you want to change the hyphenation of a
2721 word for the entire document, use the @code{hw} request.
2724 The @code{hc} request allows you to change the hyphenation character.
2725 The character specified as an argument will then work the same as the
2726 @code{\%} escape, and, thus, no longer appear in the output. Without
2727 an argument it will return the hyphenation character to @code{\%}.
2729 @cindex hyphenation patterns
2730 @cindex pattern for hyphenation
2732 To further customize hyphenation the @code{hpf} request will read in a
2733 file of hyphenation patterns. This file will be searched for in the
2734 same way that @file{tmac.@var{name}} is searched for when the
2735 @samp{-m@var{name}} option is specified.
2737 It should have the same format as the argument to the @code{\patterns}
2738 primitive in @TeX{}; the letters appearing in this file are interpreted
2739 as hyphenation codes. A @samp{%} character in the patterns file
2740 introduces a comment that continues to the end of the line.
2746 The set of hyphenation patterns is associated with the current language
2747 set by the @code{hla} request. The @code{hpf} request is usually
2748 invoked by the @file{troffrc} or @file{troffrc-end} file.
2751 The @code{hcode} request has the following syntax:
2754 .hcode @var{c1 code1 c2 code2...}
2757 It sets the hyphenation code of character @var{c1} to @var{code1} and
2758 that of @var{c2} to @var{code2}. A hyphenation code must be a single
2759 input character (not a special character) other than a digit or a space.
2760 Initially each lower-case letter has a hyphenation code, which is
2761 itself, and each upper-case letter has a hyphenation code which is the
2762 lower-case version of itself.
2764 @cindex hyphenation margin
2765 @cindex margin for hyphenation
2768 The @code{hym} request will set the hyphenation margin to the value
2769 given as its argument: when the current adjustment mode is not@w{
2770 }@samp{b}, the line will not be hyphenated if the line is no more than
2771 that amount short. The default hyphenation margin is@w{ }0. The
2772 default scaling indicator for this request is@w{ }m. The hyphenation
2773 margin is associated with the current environment. The current
2774 hyphenation margin is available in the @code{.hym} register.
2776 @cindex hyphenation space
2779 The @code{hys} request sets the hyphenation space to the value given as
2780 the first argument: when the current adjustment mode is@w{ }@samp{b},
2781 don't hyphenate the line if the line can be justified by adding no more
2782 than that amount of extra space to each word space. The default
2783 hyphenation space is@w{ }0. The default scaling indicator for this
2784 request is@w{ }m. The hyphenation space is associated with the current
2785 environment. The current hyphenation space is available in the
2786 @code{.hys} register.
2788 @cindex soft hyphen character
2789 @cindex character, soft hyphen
2791 The @code{shc} request will set the soft hyphen character to the
2792 character given as an argument. If the argument is omitted, the soft
2793 hyphen character will be set to the default character @code{\(hy}. The
2794 soft hyphen character is the character which will be inserted when a
2795 word is hyphenated at a line break. If the soft hyphen character does
2796 not exist in the font of the character immediately preceding a potential
2797 break point, then the line will not be broken at that point. Neither
2798 definitions (specified with the @code{char} request) nor translations
2799 (specified with the @code{tr} request) are considered when finding the
2800 soft hyphen character.
2808 The @code{hla} request will set the current hyphenation language to that
2809 given by the first argument. Hyphenation exceptions specified with the
2810 @code{hw} request and hyphenation patterns specified with the @code{hpf}
2811 request are both associated with the current hyphenation language. The
2812 @code{hla} request is usually invoked by the @file{troffrc} or the
2813 @file{troffrc-end} files. The current hyphenation language is available
2814 in the number register @code{.hla}.
2817 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
2818 @section Manipulating Spacing
2819 @cindex manipulating spacing
2820 @cindex spacing, manipulating
2823 The @code{sp} request will cause @code{gtroff} to space downwards the
2824 distance specified as the first argument. With no argument it will
2825 advance 1@w{ }line. A negative argument will cause @code{gtroff} to
2826 move up the page the specified distance. If the argument is preceded by
2827 a @samp{|} @code{gtroff} will move that distance from the top of the
2830 @cindex double-spacing
2833 Often you may want your output to be double or triple spaced. The
2834 @code{ls} request will cause @code{troff} to output @var{n}-1 blank
2835 lines after each line of text, where @var{n} is the argument given to
2836 the @code{ls} request. With no argument @code{gtroff} will go back to
2837 single spacing. The number register @code{.L} contains the current line
2842 Sometimes, extra vertical spacing is only needed occasionally, i.e.@: to
2843 allow space for a tall construct (like an equation). The @code{\x}
2844 escape will do this. The escape is given a numerical argument (like
2845 @samp{\x'3p'}). If this number is positive extra vertical space will be
2846 inserted below the current line. A negative number will add space
2847 above. If this escape is used multiple times on the same line, the
2848 maximum of the values is used. The @code{.a} number register contains
2849 the most recent (nonnegative) extra vertical line space.
2853 ... example of inline equation ...
2858 @cindex no-space mode
2859 @cindex mode, no-space
2860 Spacing (either via @code{sp} or via blank lines) can be disabled with
2861 the @code{ns} request. This will enable @dfn{no-space mode}. This mode
2862 will end when actual text is output or the @code{rs} request is
2863 encountered. No-space mode will also prevent requests to advance to the
2864 next page unless they are accompanied by a page number (@pxref{Page
2865 Control}, for more information).
2868 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
2869 @section Tabs and Fields
2870 @cindex tabs and fields
2871 @cindex fields and tabs
2874 Tab stops are much like those on a typewriter: a tab character (or the
2875 @code{\t} escape) on input will cause horizontal motion to the next tab
2879 Tab stops can be changed with the @code{ta} request. This request takes
2880 a series of numbers as arguments which indicate where each tab stop is
2881 to be (overriding any previous settings). These can be specified
2882 absolutely, i.e.@: as the distance from the left margin. For example,
2883 the following will set tab stops every one inch.
2886 .ta 1i 2i 3i 4i 5i 6i
2889 Tab stops can also be specified relatively (using a leading @samp{+})
2890 which means that the specified tab stop will be set that distance from
2891 the previous tab stop. For example, the following is equivalent to the
2895 .ta 1i +1i +1i +1i +1i +1i
2898 After the specified tab stops repeat values may be set for tabs beyond
2899 the last one specified. This is most commonly used to specify tabs set
2900 at equal intervals. The complete syntax for setting tabs is
2903 ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2} @dots{} @var{rn}
2907 This will set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn}
2908 and then set tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{},
2909 @var{nn}+@var{rn} and then at @var{nn}+@var{rn}+@var{r1},
2910 @var{nn}+@var{rn}+@var{r2}, @dots{}, @var{nn}+@var{rn}+@var{rn}, and so
2911 on. For example the following is, yet again, the same as the previous
2918 The material in each tab column may be justified to the right or left
2919 or centered in the column. This is specified by appending an
2920 @samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop.
2921 The default justification is @samp{L}. Example:
2928 The number register @code{.tabs} contains a string representation of the
2929 current tab settings suitable for use as an argument to the @code{ta}
2933 Normally @code{gtroff} will fill the space to the next tab stop with
2934 spaces. In some cases you may wish to change this. The @code{tc}
2935 request will do this. With no argument @code{gtroff} will revert to
2942 Sometimes you may wish to use the @code{tc} request to fill a tab stop
2943 with a given character, but also, you want to use normal tab stops on
2944 the rest of the line. For this @code{gtroff} provides an alternate tab
2945 mechanism, called @dfn{leaders} which will do just that. They are used
2946 exclusively to produce a repeated run of characters to the next tab
2949 You can declare what character will be repeated with the @code{lc}
2950 request. If you do not give it an argument, the leaders will act the
2954 Leader are invoked by using the @code{\a} escape while specifying the
2957 @cindex table of contents
2958 @cindex contents, table of
2959 Thus for a table of contents you may want to have tab stops defined so
2960 that the section number is one tab stop, the title is the second with
2961 the remaining space being filled with a line of dots and then the page
2962 number slightly separated from the dots.
2974 Fields are a more general way of laying out tabular data.
2978 @c XXX add explanation
2980 @node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial
2981 @section Character Translations
2982 @cindex character translations
2983 @cindex translations of characters
2989 The control character (@samp{.}) and the no-break control character
2990 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
2991 respectively. The single argument is the new character to be used.
2992 With no argument the normal control character is restored.
2996 The @code{eo} request will completely disable the escape mechanism. The
2997 @code{ec} request can be used to change the escape character from the
2998 default @samp{\} to what is specified as an argument. It can be also
2999 used to re-enable the escape mechanism after an @code{eo} request.
3002 The @code{tr} request will translate characters.
3008 @code{trnt} is the same as the @code{tr} request except that the
3009 translations do not apply to text that is transparently throughput into
3010 a diversion with @code{\!}. @xref{Diversions}, for more information.
3022 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it will
3026 @node Line Layout, Page Layout, Character Translations, Programming Tutorial
3027 @section Line Layout
3029 @cindex layout, line
3031 @cindex dimensions, line
3032 @cindex line dimensions
3033 The following drawing shows the dimensions which @code{gtroff} uses for
3034 placing a line of output onto the page. They are labeled with the
3035 request which manipulates that dimension.
3040 -->| po |<-----------ll------------>|
3041 +----+----+----------------------+----+
3043 +----+----+----------------------+----+
3048 These dimensions are:
3053 @cindex margin, left
3055 @cindex offset, page
3057 @dfn{Page offset}--This is the leftmost position of text on the final
3058 output, defining the @dfn{left margin}. It can be adjusted with the
3059 @code{po} request, and the current setting can be found in the built-in
3060 number register @code{.o}. Note that this request does not cause a
3061 break, so changing the page offset in the middle of text being filled
3062 may not do what you expect.
3065 @cindex line indentation
3067 @dfn{Indentation}--This is the distance from the left margin where text
3068 will be printed. This can be adjusted with the @code{in} request, and
3069 the current setting can be found in the built-in number register.
3070 @code{.i}. This request causes a break.
3074 There is also the request @code{ti} which will cause one output line to
3075 be indented, after which the indentation returns to@w{ }0. This request
3076 causes a break. The number register @code{.in} is the indent that
3077 applies to the current output line.
3080 @cindex length of line
3083 @dfn{Line length}--This is the distance from the left margin to right
3084 margin. This can be adjusted with the @code{ll} request, and the
3085 current setting can be found in the built-in number register @code{.l}
3086 Note, as the figure implies, line length is not affected by the current
3087 indentation. The number register @code{.ll} is the line length that
3088 applies to the current output line.
3094 A bunch of really boring text which should
3095 be indented from both margins.
3096 Replace me with a better (and more) example!
3102 @node Page Layout, Page Control, Line Layout, Programming Tutorial
3103 @section Page Layout
3105 @cindex layout, page
3107 @code{gtroff} provides some very primitive operations for controlling
3111 @cindex length of page
3114 Troff lets you specify the @dfn{page length} via the @code{pl} request.
3115 This is the length of the physical output page. The current setting can
3116 be found in the built-in number register @code{.p}. Note that this only
3117 specifies the size of the page, not the top and bottom margins. Those
3118 are not done by groff directly. @xref{Traps}, for further information
3124 Troff provides several operations which help in setting up top and
3125 bottom titles (or headers and footers)
3128 @cindex three-part title
3131 The @code{tl} request will print a @dfn{title line}, which consists of
3132 three parts: a left justified portion, a centered portion and a right
3133 justified portion. The argument to @code{tl} is specified as
3134 @code{'@var{left}'@var{center}'@var{right}'}. The @samp{%} character is
3135 replaced with the current page number. You can change this character
3136 with the @code{pc} request (see below).
3138 @cindex length of title line
3139 @cindex title line, length
3142 The title line is printed using its own line length, which is specified
3143 with the @code{lt} request. The current setting of this is available in
3144 the @code{.lt} number register.
3147 @cindex number, page
3149 The @code{pn} request will change the page number of the @emph{next}
3150 page. The only argument is the page number.
3154 The current page number is stored in the number register @code{%}. The
3155 number register @code{.pn} contains the number of the next page: either
3156 the value set by a @code{pn} request, or the number of the current page
3159 @cindex changing the page number character
3160 @cindex page number character, changing
3162 The @code{pc} request will change the page number character (used by the
3163 @code{tl} request) to a different character. With no argument, this
3164 mechanism is disabled.
3169 @node Page Control, Fonts, Page Layout, Programming Tutorial
3170 @section Page Control
3171 @cindex page control
3172 @cindex control, page
3176 To stop processing the current page, and move to the next page, you can
3177 invoke the @code{bp} request. This request will also cause a break. It
3178 can also take an argument of what the next page should be numbered. The
3179 only difference between @code{bp} and @code{pn} is that @code{pn} does
3180 not cause a break or actually eject a page.
3186 .tl 'left top'center top'right top'
3193 Often you may want to make sure that you have a certain amount of space
3194 before a new page occurs. This is most useful to make sure that there
3195 is not a single @dfn{orphan} line left at the bottom of a page. The
3196 @code{ne} request will ensure that there is a certain distance,
3197 specified by the first argument, before the next page is triggered
3198 (@pxref{Traps}, for further information). The default unit for
3199 @code{ne} is @code{v} and the default argument is@w{ }1@dmn{v}.
3201 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
3202 you can do the following before each paragraph:
3213 @code{sv} is similar to the @code{ne} request; it reserves the specified
3214 amount of vertical space. If the desired amount of space exists before
3215 the next trap (bottom page boundary), the space will be output
3216 immediately. If there is not enough space, it is stored for later
3217 output via the @code{os} request. The default argument is@w{ }1@dmn{v}
3218 and the default unit is @code{v}.
3221 @node Fonts, Sizes, Page Control, Programming Tutorial
3227 @code{gtroff} gives you the ability to switch fonts at any point in your
3228 text. There are two ways to do this, via the @code{ft} request and the
3231 Fonts are generally specified as upper-case strings, which are usually
3232 1@w{ }to 4 characters representing an abbreviation or acronym of the font
3235 The basic set of fonts are @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
3236 These are Times Roman, Italic, Bold, and Bold Italic. There is also at
3237 least one symbol font which contains various special symbols (Greek,
3238 mathematics). Such symbols fonts cannot be used directly, but should be
3246 * Artificial Fonts::
3247 * Ligatures and Kerning::
3250 @node Changing Fonts, Font Families, Fonts, Fonts
3251 @subsection Changing Fonts
3252 @cindex changing fonts
3253 @cindex fonts, changing
3256 @cindex previous font
3257 @cindex font, previous
3258 You can change fonts with both the @code{ft} request. With no arguments
3259 it will switch to the previous font (also known as @samp{P}).
3270 The @code{\f} escape is useful for changing fonts in the middle of
3274 eggs, bacon, \fBspam\fP and sausage.
3278 Both of the above examples will produce the same output. Note the usage
3279 of @samp{P} to indicate the previous font---using @code{\f} it is not
3280 possible to omit this parameter.
3282 Sometimes when putting letters of different fonts, you need more or less
3283 space at such boundaries. There are two escapes to help with this.
3286 @cindex italic correction
3287 @cindex correction, italic
3288 The @code{\/} escape increases the width of the preceding character so
3289 that the spacing between that character and the following character will
3290 be correct if the following character is a Roman character. For
3291 example, if an italic@w{ }f is immediately followed by a Roman right
3292 parenthesis, then in many fonts the top right portion of the f will
3293 overlap the top left of the right parenthesis. It is a good idea to use
3294 this escape sequence whenever an italic character is immediately
3295 followed by a Roman character without any intervening space. This small
3296 amount of space is also called @dfn{italic correction}.
3299 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids
3303 @cindex left italic correction
3304 @cindex correction, left italic
3305 The @code{\,} escape modifies the spacing of the following character so
3306 that the spacing between that character and the preceding character will
3307 be correct if the preceding character is a Roman character. It is a
3308 good idea to use this escape sequence whenever a Roman character is
3309 immediately followed by an italic character without any intervening
3310 space. In analogy to above, this space could be called @dfn{left italic
3311 correction}, but this term isn't used widely.
3314 @c For example, inserting \, between the parenthesis and the f changes
3328 The @code{ftr} request will translate fonts; its syntax is
3331 .ftr @var{F} @var{G}
3335 which translates font@w{ }@var{F} to font@w{ }@var{G}. Whenever a font
3336 named @var{F} is referred to in a @code{\f} escape sequence, or in the
3337 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
3338 @code{fspecial}, @code{fp}, or @code{code} requests, font@w{ }@var{G} will
3339 be used. If @var{G} is missing, or equal to @var{F} then font@w{
3340 }@var{F} will not be translated.
3342 @node Font Families, Font Positions, Changing Fonts, Fonts
3343 @subsection Font Families
3344 @cindex font families
3345 @cindex families, font
3347 Due to the variety of fonts available, @code{gtroff} has added the
3348 concept of font families. Each of these families has four styles
3349 (@samp{R}, @samp{I}, @samp{B} and @samp{BI}).
3351 The fonts are specified as the concatenation of the font family and
3352 style. Specifying a font without the family part will cause
3353 @code{gtroff} to use that style of the current family. By default,
3354 @code{gtroff} uses the Times family.
3356 This way, you can just use the basic four fonts and select a different
3357 font family on the command line.
3361 You can also switch font families with the @code{fam} request. The
3362 current font family is available in the number register @code{.fam}.
3363 This is a string-valued register.
3379 @node Font Positions, Using Symbols, Font Families, Fonts
3380 @subsection Font Positions
3381 @cindex font positions
3382 @cindex positions, font
3384 For the sake of old phototypesetters and compatability with old versions
3385 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
3386 on which various fonts are mounted. The last one or two are reserved
3387 for the symbol font(s).
3390 New fonts can be mounted with the @code{fp} request. These numeric
3391 positions can then be referred to with font changing commands. When
3392 @code{gtroff} starts it is using font number one.
3408 Note that after these font changes have taken place the original font
3412 The current font in use, as a font position, is available in number
3413 register @code{.f}. This can be useful to remember the current font,
3418 ... lots 'o text ...
3423 The number of the next free font position is available in the number
3424 register @code{.fp}. This is useful when mounting a new font, like so:
3427 .fp \n[.fp] NEATOFONT
3431 Fonts not listed in the @file{DESC} file are automatically mounted on
3432 the next available font position when they are referenced. If a font is
3433 to be mounted explicitly with the @code{fp} request on an unused font
3434 position, it should be mounted on the first unused font position, which
3435 can be found in the @code{.fp} register. Although @code{gtroff} does
3436 not enforce this strictly, it will not allow a font to be mounted at a
3437 position whose number is much greater than that of any currently used
3441 The @code{fp} request has an optional third argument. This argument
3442 gives the external name of the font, which is used for finding the font
3443 description file. The second argument gives the internal name of the
3444 font which is used to refer to the font in @code{gtroff} after it has
3445 been mounted. If there is no third argument then the internal name will
3446 be used as the external name. This feature allows you to use fonts with
3447 long names in compatibility mode.
3449 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
3450 @subsection Using Symbols
3451 @cindex using symbols
3452 @cindex symbols, using
3456 Symbols can be inserted by using a special escape sequence. This escape
3457 is simply the escape character (usually a backslash) followed by an
3458 identifier. The symbol identifiers have to be two or more characters,
3459 since single characters conflict with all the other escapes. The
3460 identifier can be either preceded by a parenthesis if it is two
3461 characters long, or surrounded by square brackets. So, the symbol for
3462 the mathematical Greek letter `pi' can be produced either by @code{\(*p}
3466 area = \(*p\fIr\fP\u2\d
3470 The escape @code{\C'@var{xxx}'} will typeset the character named
3471 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
3472 But @code{\C} has the advantage that it is compatible with recent
3473 versions of @code{ditroff} and is available in compatibility mode.
3477 The escape @code{\N'@var{n}'} will typeset the character with code@w{
3478 }@var{n} in the current font. @var{n} can be any integer. Most devices
3479 only have characters with codes between 0 and@w{ }255. If the current
3480 font does not contain a character with that code, special fonts will
3481 @emph{not} be searched. The @code{\N} escape sequence can be
3482 conveniently used on conjunction with the @code{char} request:
3485 .char \[phone] \f(ZD\N'37'
3490 @cindex unnamed characters
3491 @cindex characters, unnamed
3492 The code of each character is given in the fourth column in the font
3493 description file after the charset command. It is possible to include
3494 unnamed characters in the font description file by using a name of
3495 @samp{---}; the @code{\N} escape sequence is the only way to use these.
3498 @cindex character properties
3499 @cindex properties of characters
3500 Each character has certain properties associated with it. These
3501 properties can be modified with the @code{cflags} request. The first
3502 argument is the the sum of the desired flags and the remaining arguments
3503 are the characters to have those properties.
3507 @cindex end of sentence characters
3508 @cindex characters, end of sentence
3509 the character ends sentences (initially characters @samp{.?!} have this
3512 @cindex hyphenating characters
3513 @cindex characters, hyphenation
3514 lines can be broken before the character (initially no characters have
3517 lines can be broken after the character (initially the characters
3518 @samp{-\(hy\(em} have this property)
3520 @cindex overlapping characters
3521 @cindex characters, overlapping
3522 the character overlaps horizontally (initially the characters
3523 @samp{\(ul\(rn\(ru} have this property)
3525 the character overlaps vertically (initially character @samp{\(br} has
3528 @cindex transparent characters
3529 @cindex characters, transparent
3530 an end of sentence character followed by any number of characters with
3531 this property will be treated as the end of a sentence if followed by a
3532 newline or two spaces; in other words the character is @dfn{transparent}
3533 for the purposes of end of sentence recognition---this is the same as
3534 having a zero space factor in @TeX{} (initially characters
3535 @samp{"')]*\(dg\(rq} have this property).
3539 @cindex defining characters
3540 @cindex characters, defining
3541 You can create new characters with the @code{char} request. It is
3545 .char @var{c} @var{string}
3554 This defines character@w{ }@var{c} to be @var{string}. Every time
3555 character@w{ }@var{c} needs to be printed, @var{string} will be
3556 processed in a temporary environment and the result will be wrapped up
3557 into a single object. Compatibility mode will be turned off and the
3558 escape character will be set to @samp{\} while @var{string} is being
3559 processed. Any emboldening, constant spacing or track kerning will be
3560 applied to this object rather than to individual characters in
3561 @var{string}. A character defined by this request can be used just like
3562 a normal character provided by the output device. In particular other
3563 characters can be translated to it with the @code{tr} request; it can be
3564 made the leader character by the @code{lc} request; repeated patterns
3565 can be drawn with the character using the @code{\l} and @code{\L} escape
3566 sequences; words containing the character can be hyphenated correctly,
3567 if the @code{hcode} request is used to give the character a hyphenation
3568 code. There is a special anti-recursion feature: use of character
3569 within the character's definition will be handled like normal characters
3570 not defined with @code{char}.
3573 @cindex removing character definition
3574 @cindex character, removing definition
3575 A character definition can be removed with the @code{rchar} request.
3576 Its arguments are the characters to be removed. This undoes the effect
3577 of a @code{char} request.
3579 @xref{Special Characters}.
3581 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
3582 @subsection Artificial Fonts
3583 @cindex artificial fonts
3584 @cindex fonts, artificial
3586 There are a number of requests for artificially creating fonts. These
3587 are largely vestigial remains from the days when output devices did not
3588 have a wide variety of fonts, and when @code{nroff} and @code{troff}
3589 were separate programs. These are no longer necessary in GNU
3594 The @code{ul} request will print subsequent lines in italics on a device
3595 capable of it, or underline the text on an character output device. The
3596 single argument is the number of lines to be ``underlined,'' with no
3597 argument, the next line will be underlined.
3600 @cindex continuous underlining
3601 @cindex underlining, continuous
3602 The @code{cu} request is similar to @code{ul} ...
3607 @cindex underline font
3608 @cindex font for underlining
3609 The @code{uf} request will set the underline font used by @code{ul} and
3613 @cindex imitating bold face
3614 @cindex bold face, imitating
3615 The @code{bd} request artificially creates a bold font by printing each
3616 character twice, slightly offset. The first argument specifies the font
3617 to embolden, and the second is the number of basic units, minus one, by
3618 which the two characters will be offset. If the second argument is
3619 missing, emboldening will be turned off.
3621 @node Ligatures and Kerning, , Artificial Fonts, Fonts
3622 @subsection Ligatures and Kerning
3623 @cindex ligatures and kerning
3624 @cindex kerning and ligatures
3632 You can switch the ligature mechanism on or off with the @code{lg}
3633 request; if the parameter is non-zero or missing, ligatures are enabled,
3634 otherwise disabled. Default is on. The current ligature mode can be
3635 found in the number register @code{.lg} (set to@w{ }1 if ligatures are
3636 enabled, 0@w{ }otherwise).
3642 If the font description file contains pairwise kerning information,
3643 characters from that font will be kerned. Kerning between two
3644 characters can be inhibited by placing @code{\&} between them.
3648 You can activate kerning with the @code{kern} request. If the parameter
3649 is non-zero or missing, enable pairwise kerning, otherwise disable it.
3650 The number register @code{.kern} is set to@w{ }1 if pairwise kerning is
3651 enabled, 0@w{ }otherwise.
3654 @cindex track kerning
3655 @cindex kerning, track
3656 What is track kerning?
3660 Track kerning must be used with great care since it is usually
3661 considered bad typography if the reader notices the effect. The syntax
3662 of the @code{tkf} request is
3665 .tkf @var{f} @var{s1} @var{n1} @var{s2} @var{n2}
3669 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
3670 }@var{f} the width of every character will be increased by an amount
3671 between @var{n1} and @var{n2}; if the current point size is less than or
3672 equal to @var{s1} the width will be increased by @var{n1}; if it is
3673 greater than or equal to @var{s2} the width will be increased by
3674 @var{n2}; if the point size is greater than or equal to @var{s1} and
3675 less than or equal to @var{s2} the increase in width is a linear
3676 function of the point size.
3679 @node Sizes, Strings, Fonts, Programming Tutorial
3685 @cindex size of type
3686 @cindex vertical spacing
3687 @cindex spacing, vertical
3688 @code{gtroff} uses two dimensions with each line of text, type size and
3689 vertical spacing. The @dfn{type size} is the height from the text
3690 @dfn{baseline} to the top of the tallest character (descenders may drop
3691 below this baseline). @dfn{Vertical spacing} is the amount of space
3692 @code{gtroff} allows for a line of text; normally, this is about 20%@w{
3693 }larger than the current type size. Ratios smaller than this can result
3694 in hard-to-read text; larger that this, it will spread your text out
3695 more vertically (useful for term papers). By default, @code{gtroff}
3696 uses 10@w{ }point type on 12@w{ }point spacing.
3699 The difference between type size and vertical spacing is known, by
3700 typesetters, as @dfn{leading}.
3703 * Changing Type Sizes::
3704 * Fractional Type Sizes::
3707 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
3708 @subsection Changing Type Sizes
3709 @cindex changing type sizes
3710 @cindex type sizes, changing
3717 Using the @code{ps} request and the @code{\s} escape you can change the
3718 type size. The @code{vs} request will change the vertical spacing. The
3719 default unit for the @code{ps} and @code{vs} requests are points. The
3720 number registers @code{.s} and @code{.v} contain the current type size
3721 and vertical spacing.
3723 These requests take parameters in units of points. You can specify
3724 sizes as an absolute size, or as a relative change from the current
3725 size. The size@w{ }0 means go back to the previous size. With no
3726 argument it will also revert to the previous size.
3733 wink, wink, \s+2nudge, nudge,\s+8 say no more!
3737 The @code{\s} escape may be called in a variety of ways. Much like
3738 other escapes there must be a way to determine where the argument ends
3739 and the text begins. Any of the following forms are valid:
3743 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 0
3744 or in the range 4 to@w{ }39.
3747 Increase resp.@: decrease the point size by @var{n}@w{ }points.
3748 @var{n}@w{ }must be exactly one digit.
3750 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly two
3756 Increase resp.@: decrease the point size by @var{nn}@w{ }points.
3757 @var{nn} must be exactly two digits.
3760 @xref{Fractional Type Sizes}, for yet another syntactical form of using
3761 the @code{\s} escape.
3763 Some devices may only have certain permissible sizes, in which case
3764 @code{gtroff} will round to the nearest permissible size.
3769 ... .sz macro example?? ...
3772 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
3773 @subsection Fractional Type Sizes
3774 @cindex fractional type sizes
3775 @cindex type sizes, fractional
3777 @cindex @code{s} unit
3778 @cindex unit, @code{s}
3779 @cindex @code{z} unit
3780 @cindex unit, @code{z}
3786 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
3787 @var{sizescale} is specified in the @file{DESC} file (1@w{ }by default.)
3788 There is a new scale indicator @samp{z} which has the effect of
3789 multiplying by @var{sizescale}. Requests and escape sequences in
3790 @code{gtroff} interpret arguments that represent a point size as being in
3791 units of scaled points, but they evaluate each such argument using a
3792 default scale indicator of @samp{z}. Arguments treated in this way are
3793 the argument to the @code{ps} request, the third argument to the
3794 @code{cs} request, the second and fourth arguments to the @code{tkf}
3795 request, the argument to the @code{\H} escape sequence, and those
3796 variants of the @code{\s} escape sequence that take a numeric expression
3797 as their argument (see below).
3799 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
3800 will be equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
3801 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 10250
3802 scaled points, which is equal to 10.25@w{ }points.
3804 It would make no sense to use the @samp{z} scale indicator in a numeric
3805 expression whose default scale indicator was neither @samp{u} nor
3806 @samp{z}, and so @code{gtroff} disallows this. Similarly it would make
3807 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
3808 numeric expression whose default scale indicator was @samp{z}, and so
3809 @code{gtroff} disallows this as well.
3811 There is also new scale indicator @samp{s} which multiplies by the
3812 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
3813 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
3818 The number register @code{.s} returns the point size in points as decimal
3819 fraction. There is also a new number register @code{.ps} that returns
3820 the point size in scaled points.
3824 The last-requested point size in scaled points is contained in the
3825 @code{.psr} number register. The last requested point size in points as
3826 a decimal fraction can be found in @code{.psr}. This is a string-valued
3832 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
3833 expression with a default scale indicator of @samp{z}.
3842 Increases resp.@: decreases the point size by @var{n} scaled points;
3843 @var{n} is a numeric expression with a default scale indicator of
3850 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
3855 @code{gtroff} has string variables, which are entirely for user
3856 convenience (i.e.@: there are no built-in strings). They are defined
3857 via the @code{ds} request.
3860 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
3864 @cindex string interpolation
3865 @cindex string expansion
3866 @cindex interpolation of strings
3867 @cindex expansion of strings
3868 They are interpolated, or expanded in-place, via the @code{\*} escape:
3871 The \*(UX Operating System
3874 If the string named by the @code{\*} does not exist, the escape will be
3875 replaced by nothing.
3877 @cindex comments, with @code{ds}
3878 @strong{Caution:} Unlike other requests, the second argument to the
3879 @code{ds} request takes up the entire line including trailing spaces.
3880 This means that comments on a line with such a request can introduce
3881 unwanted space into a string.
3884 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
3888 Instead you should either put the comment on another line or have the
3889 comment escape adjacent with the end of the string.
3892 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
3895 @cindex trailing quotes
3896 @cindex quotes, trailing
3897 @cindex leading spaces with @code{ds}
3898 @cindex spaces with @code{ds}
3899 If you need leading space you can start the string with a double quote.
3900 No trailing quote is needed; in fact, any trailing quote is included in
3904 .ds sign " Yours in a white wine sauce,
3908 @cindex appending to strings
3909 @cindex strings, appending
3910 You can also append onto a string with the @code{as} request. It works
3911 similar to the @code{ds} request except that it appends the second
3912 argument onto the string named by the first argument.
3915 .as sign " with shallots, onions and garlic,
3919 @cindex multi-line strings
3920 @cindex strings, multi-line
3921 @cindex newline character, escaping
3922 @cindex escaping newline characters
3923 Strings are not limited to a single line of text. A string can span
3924 several lines by escaping the newlines with a backslash. The resulting
3925 string will be stored @emph{without} the newlines.
3928 .ds foo lots and lots \
3929 of text are on these \
3935 Rudimentary string manipulation routines are given with the
3936 @code{substring} and @code{length} requests. The former has the
3940 .substring @var{xx} @var{n1} [@var{n2}]
3944 It replaces the string in register@w{ }@var{xx} with the substring
3945 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
3946 in the string has index one. If @var{n2} is omitted, it is taken to be
3947 equal to the string's length. If the index value @var{n1} or @var{n2}
3948 is negative or zero, it will be counted from the end of the string,
3949 going backwards: The last character has index@w{ }0, the character
3950 before the last character has index@w{ }-1, etc.
3953 @cindex length of a string
3954 @cindex string, length of
3955 Here the syntax of the @code{length} request:
3958 .length @var{xx} @var{string}
3962 It computes the length of @var{string} and returns it in the number
3963 register@w{ }@var{xx} (which is not necessarily defined before).
3985 @xref{Identifiers}, and @ref{Comments}.
3988 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
3989 @section Conditionals and Loops
3990 @cindex conditionals and loops
3991 @cindex loops and conditionals
3995 In @code{if} and @code{while} requests, there are several more operators
4001 True if the current page is even or odd numbered (respectively).
4004 True if the document is being processed by @code{nroff} (or a character
4005 device) resp.@: @code{troff}.
4006 @item '@var{xxx}'@var{yyy}'
4007 True if the string @var{xxx} is equal to the string @var{yyy}. Other
4008 characters can be used in place of the single quotes.
4010 The strings are `formatted' before being compared.
4013 True if there is a number register named @var{xxx}.
4015 True if there is a string, macro, diversion, or request named @var{xxx}.
4018 True if there is a character @var{ch} available; @var{ch} is either an
4019 @sc{ascii} character or a special character (@code{\(@var{ch}} or
4020 @code{\[@var{ch}]}); the condition will also be true if @var{ch} has
4021 been defined by the @code{char} request.
4029 @node if-else, while, Conditionals and Loops, Conditionals and Loops
4033 Troff has if-then-else constructs like other languages, although the
4034 formatting can be painful.
4037 The @code{if} request has the following syntax:
4040 .if @var{expr} @var{anything}
4044 where @var{expr} is the expression to be evaluated; @var{anything} (the
4045 remainder of the line) will be executed if @var{expr} evaluates to
4046 non-zero (true). @var{anything} will be interpreted as though it was on
4047 a line by itself. @xref{Expressions}, for more info.
4049 Here are some examples:
4052 .if t .ls 2 \" double spacing in troff
4053 .if 0 .ab how'd this happen?
4058 An if-then-else is written using two requests @code{ie} and @code{el}.
4059 The first request is the `if' part and the latter is the `else' part.
4070 In many cases you want more than one request to be executed as a result
4071 of any of these requests. This can be done using the @code{\@{} and
4072 @code{\@}} escapes. The following example shows the possible ways to
4073 use these escapes (note the position of the opening and closing braces).
4089 @node while, , if-else, Conditionals and Loops
4094 @code{gtroff} provides a looping construct using the @code{while}
4095 request, which is used much like the @code{if} (and related) requests.
4096 The first argument is an expression which will be evaluated. The
4097 @code{while} request will interpret the remainder of the line until the
4098 expression evaluates to 0 or false.
4102 .while (\na<9) \&\n+a,
4107 The preceding example produces:
4110 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
4115 Note the usage of the @code{\&} escape to avoid a control character at
4116 the beginning of a line.
4120 The @code{break} request will @dfn{break} out of a while loop. Be sure
4121 not to confuse this with the @code{br} request (causing a line break).
4122 The @code{continue} request will finish the current iteration of a while
4123 loop, immediately restarting the next iteration.
4128 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
4129 @section Writing Macros
4130 @cindex writing macros
4131 @cindex macros, writing
4134 A @dfn{macro} is a collection of text and embedded commands which can be
4135 invoked multiple times. Macros are used for defining common operations.
4136 Macros are defined using the @code{de} request. This request takes a
4137 name for the macro as the first argument. Subsequent lines are copied
4138 into an internal buffer until the line @code{..} is encountered. The
4139 optional second argument to @code{de} can change this ending token.
4141 For example, suppose at the beginning of each paragraph, you want cause
4142 a break, move down a partial line and indent the first line. Such a
4143 macro (it is called @code{P}) could be defined as follows:
4153 The @code{am} request works similarly to @code{de} except it appends
4154 onto the macro named by the first argument. So, if we decide we want
4155 our previously defined @code{P} macro to actually do indented instead of
4156 block paragraphs we can add the necessary code to our existing macro:
4165 @cindex aliases, macro
4166 @cindex macro aliases
4167 Macros can be aliased with the @code{als} request.
4176 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
4177 @subsection Copy-in Mode
4178 @cindex copy-in mode
4179 @cindex mode, copy-in
4186 When troff reads in the text for a macro or diversion it copies the text
4187 (including request lines, but excluding escapes) into an internal
4188 buffer. Escapes will be converted into an internal form, except for
4189 @code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which
4190 are evaluated and inserted into the text where the escape was located.
4191 This is known as @dfn{copy-in} mode.
4193 What this means is that you can specify when these escapes are to be
4194 evaluated (either at copy-in time or at the time of use) by insulating
4195 the escapes with an extra backslash. Compare this to the @code{\def}
4196 and @code{\edef} commands in @TeX{}.
4198 For example, the following will result in the numbers 20 and@c{ }10
4211 @node Parameters, , Copy-in Mode, Writing Macros
4212 @subsection Parameters
4217 The arguments to a macro can be examined using a variety of escapes.
4218 The number of arguments is available in the @code{.$} number register.
4219 Any individual argument can be retrieved with one of the following
4222 @cindex copy-in mode
4223 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
4224 @code{\$[@var{nnn}]} will result in the @var{n}th, @var{nn}th or
4225 @var{nnn}th argument. As usual, the first form only accepts a single
4226 number (larger than zero), the second only a two-digit number (larger or
4227 equal to@w{ }10), and the third any positive integer value (larger than
4228 zero). Macros can have an unlimited number of arguments. Note that due
4229 to copy-in mode, you will want to have two backslashes on these in
4230 actual use, since you do not want them interpolated until the macro is
4234 The request @code{shift} will shift the arguments 1@w{ }position, or as
4235 many positions as specified by its argument. After executing this
4236 request, argument@w{ }@var{i} will become argument @var{i}-@var{n};
4237 arguments 1 to@w{ }@var{n} will no longer be available. Shifting by
4238 negative amounts is currently undefined.
4242 In some cases you will want to just use all of the arguments at once.
4243 For example if you pass the arguments along to another macro. The
4244 @code{\$*} escape is the concatenation of all the arguments separated by
4245 spaces. A similar escape is @code{\$@@}, which is the concatenation of
4246 all the arguments with each surrounded by double quotes, and separated
4251 The @code{\$0} escape is the name by which the current macro was
4252 invoked. The @code{als} request can make a macro have more than one
4257 .ie \\n(.$=1 .ds Vl Pre-Release Version
4258 .el .ds Vl Version \\$3, \\$4.
4262 This would be called as
4268 @xref{Request Arguments}.
4271 @node Page Motions, Drawing Requests, Writing Macros, Programming Tutorial
4272 @section Page Motions
4273 @cindex page motions
4274 @cindex motions, page
4277 Motions up and down the page can be done with the @code{sp} request.
4278 However, this causes a break so that the actual effect is to move to the
4279 left margin and then to the specified location.
4283 The request @code{mk} can be used to mark a location on a page, for
4284 movement to later. This request takes a register name as an argument in
4285 which to store the current page location. With no argument it will
4286 store the location in an internal register. The results of this can be
4287 used later by the @code{rt} or the @code{sp} request. The @code{rt}
4288 request will return @emph{upwards} to the location given in the register
4289 name given as an argument, with no argument it will return to the
4290 location marked with the @code{mk} request
4295 ... dual column example ...
4298 The following escapes will give you much finer control of movements
4302 @cindex vertical motion
4303 @cindex motion, vertical
4304 The @code{\v'@var{e}'} will let you do arbitrary vertical motion from
4305 the current location on the page. The argument@w{ }@var{e} specifies
4306 the distance to move; positive is downwards and negative upwards. The
4307 default unit for this escape is vertical spaces, @code{v}'s. Beware,
4308 however, that @code{gtroff} will leave text processing to continue
4309 wherever the motion ends, so if you don't want to interfere with text
4310 processing, make sure your motions are balanced.
4312 There are some special case escapes for vertical motion.
4316 move upwards@w{ }1@dmn{v}.
4318 move upwards@w{ }.5@dmn{v}.
4320 move down@w{ }.5@dmn{v}.
4324 Horizontal motions can be done via the @code{\h'@var{e}'} escape. The
4325 expression@w{ }@var{e} indicates how far to move: positive is rightwards
4326 and negative leftwards.
4328 There are a number of special case escapes for horizontal motion:
4332 an unbreakable and unpaddable (i.e.@: not expanded during filling)
4333 space. (Note: It is a backslash followed by a space.)
4335 an unbreakable space that stretches like a normal inter-word space when a
4342 a space the size of a digit.
4346 Like @code{\&} except that it behaves like a character declared with the
4347 @code{cflags} request to be transparent for the purposes of end of
4348 sentence recognition.
4354 ... tex logo example ...
4358 @cindex width escape
4359 @cindex escape, width
4360 Often you will want to do horizontal movement based on the width of some
4361 arbitrary text (e.g.@: given as an argument to a macro). For that,
4362 there is the escape @code{\w'@var{text}'} which will interpolate to the
4363 width of the given @var{text} in basic units.
4368 ... strlen example ...
4371 Font changes may occur in @var{text} which don't affect current
4374 After use, @code{\w} sets several registers:
4381 The highest and lowest point, respectively, in @var{text}.
4386 Like the @code{st} and @code{sb} registers, but takes account of the
4387 heights and depths of characters.
4390 is set according to what kinds of characters occur in @var{text}:
4393 only short characters, no descenders or tall characters.
4399 both a descender and a tall character
4403 The amount of horizontal space (possibly negative) that should be added
4404 to the last character before a subscript.
4407 How far to right of the center of the last character in the @code{\w}
4408 argument, the center of an accent from a Roman font should be placed
4409 over that character.
4418 @c XXX documentation
4421 @node Drawing Requests, Traps, Page Motions, Programming Tutorial
4422 @section Drawing Requests
4423 @cindex drawing requests
4424 @cindex requests for drawing
4426 @code{gtroff} provides a number of ways to draw lines and other figures
4427 on the page. Used in combination with the page motion commands
4428 (@pxref{Page Motions}, for more info) you can draw a wide variety of
4429 figures. However, for complex drawings these operations can be quite
4430 cumbersome, and it may be wise to use graphic preprocessors like
4431 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
4434 All drawing is done via escapes.
4437 @cindex horizontal line
4438 @cindex line, horizontal
4439 The @code{\l} escape will draw a line rightwards from the current
4440 location. The full syntax for this escape is
4447 where @var{l} is the length of the line to be drawn, starting at the
4448 current location; positive numbers will draw to the right, and negative
4449 will draw towards the left. This can also be specified absolutely
4450 (i.e.@: with a leading @samp{|}) which will draw back to the beginning
4453 @cindex underscore character
4454 @cindex character, underscore
4455 @cindex line drawing character
4456 @cindex character for line drawing
4457 The optional second parameter @var{c} is a character to draw the line
4458 with. If this second argument is not specified, troff will use the
4459 underscore character.
4462 If you need to separate the two arguments (to prevent troff from
4463 interpreting a drawing character as a scaling indicator), you can
4464 separate them with @code{\&}.
4466 Here a small useful example:
4470 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
4476 Note that this works by outputting a box rule (a vertical line), then
4477 the text given as an argument and then another box rule. Then the line
4478 drawing escapes both draw from the current location to the beginning of
4479 the @emph{input} line.
4482 @cindex vertical line
4483 @cindex line, vertical
4484 @cindex line drawing character
4485 @cindex character for line drawing
4486 @cindex box rule character
4487 @cindex character, box rule
4488 Vertical lines are drawn using the @code{\L} escape. Its parameters are
4489 specified similar to the @code{\l} escape. If the length is positive,
4490 the movement will be downwards, and upwards for negative values. The
4491 default character is the box rule character. As with the vertical
4492 motion escapes, text processing will blindly continue where the line
4502 More flexible drawing functions are available via the @code{\D} escape.
4503 While the previous escapes will work on a character device, these
4507 @item \D'l @var{dx} @var{dy}'
4508 Draw a line from the current location to the relative point specified by
4509 (@var{dx},@var{dy}).
4514 ...revised box macro...
4519 Draw a circle with a diameter of @var{d} with the leftmost point at the
4522 Draw a solid circle with the same parameters as an outlined circle.
4523 @item \D'e @var{dx} @var{dy}'
4525 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
4526 diameter of @var{dy} with the leftmost point at the current position.
4527 @item \D'E @var{dx} @var{dy}'
4528 Draw a solid ellipse with the same parameters as an outlined ellipse.
4529 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
4531 Draw an arc clockwise from the current location through the two
4532 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
4533 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4535 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
4536 then to (@var{dx2},@var{dy2}), and so on.
4538 @cindex gray shading
4540 Set the shade of gray to be used for filling solid objects to@w{
4541 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
4542 corresponds solid white and 1000 to solid black, and values in between
4543 correspond to intermediate shades of gray. This applies only to solid
4544 circles, solid ellipses and solid polygons. By default, a level of@w{
4546 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4548 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
4549 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
4550 are exhausted, a line is drawn back to the starting point.
4555 ... box example (yes, again)...
4558 @itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4559 Draw a solid polygon with the same parameters as an outlined polygon.
4564 ... shaded box example ...
4568 @cindex line thickness
4569 @cindex thickness of lines
4570 Set the current line thickness to @var{n} machine units. A value of
4571 zero selects the smallest available line thickness. A negative value
4572 makes the line thickness proportional to the current point size (this is
4573 the default behaviour of @code{ditroff}).
4577 @cindex pile, character
4578 @cindex character pile
4579 The @code{\b} escape will @dfn{pile} a sequence of characters
4580 vertically, and center it vertically on the current line. This can be
4581 used to build large brackets and braces.
4584 \b'\(lt\(bv\(lk\(bv\(lb'
4587 @xref{Drawing Functions}.
4589 @node Traps, Diversions, Drawing Requests, Programming Tutorial
4593 @dfn{Traps} are locations, which, when reached, will call a specified
4594 macro. These traps can occur at a given location on the page, at a
4595 given location in the current diversion, after a certain number of input
4596 lines or at the end of input.
4599 * Page Location Traps::
4601 * Input Line Traps::
4602 * End-of-input Traps::
4605 @node Page Location Traps, Diversion Traps, Traps, Traps
4606 @subsection Page Location Traps
4607 @cindex page location traps
4608 @cindex traps, page location
4610 @c XXX definition of wh request
4612 @cindex page headers
4613 @cindex page footers
4616 Page location traps are frequently used for page headers and footers.
4617 The following is a simple example of this.
4620 .de hd \" Page header
4625 .de fo \" Page footer
4630 .wh 0 hd \" trap at top of the page
4631 .wh -1i fo \" trap one inch from bottom
4635 @cindex distance to next trap
4636 @cindex trap, distance
4637 The number register @code{.t} is the distance to the next trap.
4640 @cindex changing trap location
4641 @cindex trap, changing location
4642 The location of a trap can be changed later on with the @code{ch}
4643 request. The first argument is the name of the macro to be invoked at
4644 the trap and the second argument is the new location for the trap. This
4645 is useful when you are building up footnotes in a diversion, and you
4646 need to allow more space at the bottom of the page for them.
4651 ... (simplified) footnote example ...
4658 The @code{vpt} request will enable vertical position traps if the
4659 argument is non-zero, disable them otherwise. Vertical position traps
4660 are traps set by the @code{wh} or @code{dt} requests. Traps set by the
4661 @code{it} request are not vertical position traps. The parameter that
4662 controls whether vertical position traps are enabled is global.
4663 Initially vertical position traps are enabled. The current setting of
4664 this is available in the number register @code{.vpt}.
4668 The number register @code{.trunc} contains the amount of vertical space
4669 truncated by the most recently sprung vertical position trap, or, if the
4670 trap was sprung by a @code{ne} request, minus the amount of vertical
4671 motion produced by the @code{ne} request. In other words, at the point
4672 a trap is sprung, it represents the difference of what the vertical
4673 position would have been but for the trap, and what the vertical
4674 position actually is.
4677 The number register @code{.ne} contains the amount of space that was
4678 needed in the last @code{ne} request that caused a trap to be sprung.
4679 Useful in conjunction with the @code{.trunc} register. @xref{Page
4680 Control}, for more information.
4682 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
4683 @subsection Diversion Traps
4684 @cindex diversion traps
4685 @cindex traps, diversion
4689 Traps can also be set @emph{within} a diversion using the @code{dt}
4690 request. Like @code{wh} the first argument is the location of the trap
4691 and the second argument is the name of the macro to be invoked. The
4692 number register @code{.t} will still work within diversions.
4693 @xref{Diversions}, for more information.
4695 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
4696 @subsection Input Line Traps
4697 @cindex input line traps
4698 @cindex traps, input line
4701 The @code{it} request will set an input line trap. The format for
4705 .it @var{n} @var{name}
4709 where @var{n} is the number of lines of input which may be read before
4710 @dfn{springing} the trap, @var{name} is the macro to be invoked.
4711 Request lines are not counted as input lines.
4713 For example, one possible use is to have a macro which will print the
4714 next @var{n}@w{ }lines in a bold font.
4726 @node End-of-input Traps, , Input Line Traps, Traps
4727 @subsection End-of-input Traps
4728 @cindex end-of-input traps
4729 @cindex traps, end-of-input
4732 The @code{em} request will set a trap at the end of input. The macro
4733 specified as an argument will be executed after the last line of the
4734 input file has been processed.
4736 For example, if your document had to have a section at the bottom of the
4737 last page for someone to approve your document, you could set it up with
4755 @node Diversions, Environments, Traps, Programming Tutorial
4759 In @code{gtroff} you can @dfn{divert} text into a named storage area.
4760 Due to the similarity to defining macros it is sometimes said to be
4761 stored in a macro. This is used for saving text for output at a later
4762 time, which is useful for keeping blocks of text on the same page,
4763 footnotes, tables of contents and indices.
4767 A diversion is initiated by the @code{di} request. Like the @code{de}
4768 request, it takes an argument of a macro name to divert subsequent text
4769 into. The @code{da} macro will append to an existing diversion.
4771 @code{di} (resp.@: @code{da}) without an argument ends the diversion.
4776 ... end-note example ...
4783 @cindex nested diversions
4784 @cindex diversion, nested
4785 Diversions may be nested. The number register @code{.z} contains the
4786 name of the current diversion. The number register @code{.d} contains
4787 the current vertical place in the diversion. If not in a diversion it
4788 is the same as the register @code{nl}.
4796 After completing a diversion, the built-in number registers @code{dn}
4797 and @code{dl} contain the vertical and horizontal size of the diversion.
4800 .\" Center text both horizontally & vertically
4809 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
4824 @cindex transparent output
4825 @cindex output, transparent
4826 Requests, macros and escapes are interpreted when read into a diversion.
4827 There are two ways to prevent this; either way will take the given text
4828 and @dfn{transparently} embed it into the diversion. The first method
4829 is to prefix the line with @code{\!}. This will cause the entire line
4830 to be transparently inserted into the diversion. This is useful for
4831 macros you do not want invoked until the diverted text is actually
4834 @c XXX anything is read in copy mode. (what about \! ??)
4837 The other way is to surround the text by the @code{\?} escape, i.e.
4844 @var{anything} may not contain newlines; use @code{\!} if you want to
4845 embed newlines in a diversion. The escape sequence @code{\?} is also
4846 recognized in copy mode and turned into a single internal code; it is
4847 this code that terminates anything. Thus the following example will
4854 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
4869 @cindex unformatting diversions
4870 @cindex diversion, unformatting
4871 The @code{asciify} request only exists in order to make certain gross
4872 hacks work with GNU @code{troff}. It @dfn{unformats} the diversion
4873 specified as an argument in such a way that @sc{ascii} characters that
4874 were formatted and diverted will be treated like ordinary input
4875 characters when the diversion is reread. For example, the following
4876 will set register @code{n} to@w{ }1.
4889 @xref{Copy-in Mode}.
4892 @node Environments, I/O, Diversions, Programming Tutorial
4893 @section Environments
4894 @cindex environments
4896 Often you will need to print some text in a certain format regardless of
4897 what may be in effect at the time, for example, in a trap invoked macro
4898 to print headers and footers. To solve this @code{gtroff} has
4899 @dfn{environments} in which text is processed. An environment contains
4900 most of the parameters that control text processing. You can switch
4901 amongst these environments; by default @code{gtroff} processes text in
4902 environment@w{ }0. The following is the information kept in an
4909 font (family and style)
4917 partially collected lines
4920 These environments may be given arbitrary names (@pxref{Identifiers},
4921 for more info). Old versions of troff only had environments named
4922 @samp{0}, @samp{1} and@w{ }@samp{2}.
4926 The @code{ev} request will switch among environments. The single
4927 argument is the name of the environment to switch to. With no argument
4928 @code{gtroff} will switch back to the previous environment. There is no
4929 limit on the number of named environments; they will be created the
4930 first time that they are referenced. The @code{.ev} register contains
4931 the name or number of the current environment. This is a string-valued
4934 Note that a call to @code{ev} (with argument) will push the previously
4935 active environment onto a stack. If, say, environments @samp{foo},
4936 @samp{bar}, and @samp{zap} are called (in that order), the first
4937 @code{ev} request without parameter will switch back to environment
4938 @samp{bar} (which will be popped off the stack), and a second call will
4939 switch back to environment @samp{foo}.
4944 ... page break macro, revised ...
4947 Here another example:
4958 \(dg Note the large, friendly letters.
4963 To copy an environment into the current one, use the @code{evc} request,
4964 which takes the name of the environment to copy from as an argument.
4967 @node I/O, Postprocessor Access, Environments, Programming Tutorial
4970 @cindex input and output requests
4971 @cindex requests for input and output
4972 @cindex output and input requests
4975 The @code{so} request will read in the file given as an argument and
4976 include it in place of the @code{so} request. This is quite useful for
4977 large documents, i.e.@: keeping each chapter in a separate file.
4978 @xref{gsoelim}, for more information.
4981 The @code{mso} request is the same as the @code{so} request except that
4982 the file is searched for in the same way that @file{tmac.@var{name}} is
4983 searched for when the @samp{-m@var{name}} option is specified.
4986 @cindex transparent output
4987 @cindex output, transparent
4988 The @code{cf} and @code{trf} requests are to include a file. It will
4989 transparently output the contents of file filename. Each line is output
4990 as it were preceded by @code{\!}; however, the lines are not subject to
4991 copy-mode interpretation. If the file does not end with a newline, then
4992 a newline will be added. For example, you can define a macro@w{
4993 }@code{x} containing the contents of file@w{ }@file{f}, using
5001 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
5002 will embed in the diversion an object which, when reread, will cause the
5003 contents of @var{filename} to be transparently copied through to the
5004 output. In @sc{Unix} @code{troff}, the contents of @var{filename} is
5005 immediately copied through to the output regardless of whether there is
5006 a current diversion; this behaviour is so anomalous that it must be
5010 With @code{trf}, unlike @code{cf}, the file cannot contain characters
5011 such as NUL that are not legal troff input characters.
5014 The @code{nx} request will force @code{gtroff} to continue processing of
5015 the file specified as an argument.
5018 The @code{rd} request will read from standard input, and include what is
5019 read as though it were part of the input file. Text is read until a
5020 blank line is encountered.
5022 @cindex form letters
5023 @cindex letters, form
5024 Using these two requests you can set up form letters. The form letter
5025 template is constructed like this:
5043 When this is run, the following file should be redirected in. Note that
5044 requests included in this file are executed as though they were part of
5045 the form letter. The last block of input is the @code{ex} requests
5046 which tells groff to stop processing. If this was not there, groff
5047 would not know when to stop.
5051 708 NW 19th Av., #202
5068 @c XXX documentation
5071 The @code{sy} request will allow arbitrary system commands to be
5072 executed from within a @code{gtroff} document. The output is not saved
5073 anyplace, so it is up to you to do so.
5075 @c XXX add info about safer and unsafe mode
5077 For example, the following example will introduce the current time
5080 @cindex time, current
5081 @cindex current time
5084 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
5085 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
5092 Note that this works by having the @code{perl} script (run by @code{sy})
5093 print out the @code{nr} requests which will set the number registers
5094 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
5095 the @code{so} request.
5098 The @code{systat} number register contains the return value of the
5099 @code{system()} function executed by the last @code{sy} request.
5102 The @code{open} request will open a file (specified as the second
5103 argument) for writing and associate the stream (specified as the first
5107 The @code{opena} is like @code{open}, but if the file exists, append to
5108 it instead of truncating it.
5112 @cindex copy-in mode
5113 @cindex mode, copy-in
5114 The @code{write} request will write to the file associated with the
5115 stream specified by the first argument. The stream must previously have
5116 been the subject of an open request. The remainder of the line is
5117 interpreted as the @code{ds} request reads its second argument: A
5118 leading @samp{"} will be stripped, and it will be read in copy-in mode.
5121 The @code{close} request will close the stream specified by the first
5122 argument; stream will no longer be an acceptable argument to the
5123 @code{write} request.
5128 ... example of open write &c...
5132 The @code{\V} escape will interpolate the contents of the specified
5133 environment variable, as returned by @code{getenv()}. The argument to
5134 @code{\V} is specified as an identifier, i.e.@: @samp{\V@var{x}},
5135 @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} is interpreted in
5139 @node Postprocessor Access, Miscellaneous, I/O, Programming Tutorial
5140 @section Postprocessor Access
5141 @cindex postprocessor access
5142 @cindex access of postprocessor
5144 There are two escapes which will allow you to give information directly
5145 to the postprocessor. This is particularly useful for embedding
5146 @sc{PostScript} into your final document.
5149 The @code{\X} escape will embed its argument into the @code{gtroff}
5150 output preceded with @w{@samp{x X}}.
5153 The @code{\Y} escape is called with an identifier (i.e.@:
5154 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
5155 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
5156 contents of the string or macro @var{xxx} are not interpreted; also it
5157 is permitted for @var{xxx} to have been defined as a macro and thus
5158 contain newlines (it is not permitted for the argument to @code{\X} to
5159 contain newlines). The inclusion of newlines requires an extension to
5160 the @sc{Unix} @code{troff} output format, and will confuse drivers that
5161 do not know about this extension.
5163 @xref{Output Devices}.
5166 @node Miscellaneous, Debugging, Postprocessor Access, Programming Tutorial
5167 @section Miscellaneous
5168 @cindex miscellaneous
5170 This section contains parts of @code{gtroff} which cannot (yet) be
5171 categorized elsewhere in this manual.
5174 @cindex line numbers
5175 @cindex numbers, line
5176 Line numbers can be printed in the left margin using the @code{nm}
5177 request. The first argument is the line number of the @emph{next}
5178 output line; this defaults to@w{ }1. The second argument indicates on
5179 which lines numbers will be printed, i.e.@: 5 means put line numbers on
5180 every 5@w{ }lines; this defaults to@w{ }1. The third argument is the
5181 space to be left between the number and your text; this defaults to@w{
5182 }1. The fourth argument is the indentation of the line numbers.
5183 Without arguments, line numbers are turned off.
5186 The @code{nn} request will temporarily turn off line numbering. The
5187 first argument is the number of lines not to be numbered; this defaults
5190 @c XXX (does this disable incrementing or display?)
5195 ... line numbering example ...
5199 @cindex margin characters
5200 @cindex characters for margins
5201 Margin characters can be automatically printed to the right of your text
5202 with the @code{mc} request. The first argument is the character to be
5203 printed, and the second argument is the distance away from your text.
5204 With no arguments the margin characters are turned off. If this occurs
5205 before a break, no margin character will be printed.
5209 This is quite useful for indicating text that has changed, and, in fact,
5210 there are programs available for doing this (they are called
5211 @code{nrchbar} and @code{changebar} and can be found in any
5212 @samp{comp.sources.unix} archive.
5217 ... margin char example ...
5222 @cindex multi-file documents
5223 @cindex documents, multi-file
5224 The primary reason for the existence of @code{lf} is to make debugging
5225 documents which are split into many files, which are then put together
5226 with @code{soelim} and other preprocessors. The first argument is the
5227 name of the file and the second argument is the input line number in
5228 that file. This way troff can produce error messages which are
5229 intelligible to the user.
5234 ... example of soelim'ed doc ...
5238 @node Debugging, Implementation Differences, Miscellaneous, Programming Tutorial
5242 @code{gtroff} is not easy to debug, but there are some useful features
5243 and strategies for debugging.
5248 The @code{tm} request will send output to stderr; this is very useful
5249 for printing debugging output.
5251 When doing something involved it is useful to leave the debugging
5252 statements in the code and have them turned on by a command line flag.
5255 .if \n(DB .tm debugging output
5259 Then you can activate these statements with:
5268 The @code{ab} request is similar to the @code{tm} request, except that
5269 it will cause @code{gtroff} to stop processing. With no argument it
5270 will print @samp{User Abort}.
5274 The @code{ex} request will also cause @code{gtroff} to stop processing
5275 (if encountered at the topmost level; see also @ref{I/O}.
5277 If you know you are going to get many errors and no useful output, you
5278 can tell @code{gtroff} to suppress formatted output with the @samp{-z}
5282 @cindex dumping symbol table
5283 @cindex symbol table, dumping
5284 The @code{pm} request will dump out the entire symbol table.
5287 @cindex dumping number registers
5288 @cindex number registers, dumping
5289 The @code{pnr} request will print the names and contents of all
5290 currently defined number registers on stderr.
5293 @cindex dumping traps
5294 @cindex traps, dumping
5295 The @code{ptr} request will print the names and positions of all traps
5296 (not including input line traps and diversion traps) on stderr. Empty
5297 slots in the page trap list are printed as well, because they can affect
5298 the priority of subsequently planted traps.
5301 @cindex flush output
5302 @cindex output, flush
5303 @cindex interactive use of @code{gtroff}
5304 @cindex @code{gtroff}, interactive use
5305 The @code{fl} request instructs @code{gtroff} to flush its output
5306 immediately. The intention is that this be used when using
5307 @code{gtroff} interactively. There is little other use for it.
5310 @cindex backtrace of input stack
5311 @cindex input stack, backtrace
5312 The @code{backtrace} request will print a backtrace of the input stack
5316 @code{gtroff} has command line options for printing out more warnings
5317 (@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or an
5318 error occurs. The most verbose level of warnings is @samp{-ww}.
5322 @cindex level of warnings
5323 @cindex warnings, level
5324 The @code{warn} request controls the level of warnings checked for. The
5325 only argument is the sum of the numbers associated with each warning
5326 that is to be enabled; all other warnings will be disabled. The number
5327 associated with each warning is listed below. For example,
5328 @w{@code{.warn 0}} will disable all warnings, and @w{@code{.warn 1}}
5329 will disable all warnings except that about missing characters. If an
5330 argument is not given, all warnings will be enabled. The number
5331 register @code{.warn} contains the current warning level.
5334 @subsection Warnings
5337 The warnings that can be given to @code{gtroff} are divided into the
5338 following categories. The name associated with each warning is used by
5339 the @samp{-w} and @samp{-W} options; the number is used by the
5340 @code{warn} request and by the @code{.warn} register.
5345 Non-existent characters. This is enabled by default.
5348 Invalid numeric expressions. This is enabled by default.
5352 In fill mode, lines which could not be broken so that their length was
5353 less than the line length. This is enabled by default.
5356 Missing or mismatched closing delimiters.
5361 Use of the @code{el} request with no matching @code{ie} request.
5365 Meaningless scaling indicators.
5368 Out of range arguments.
5371 Dubious syntax in numeric expressions.
5376 Use of @code{di} or @code{da} without an argument when there is no
5381 @c XXX more findex entries
5382 Use of undefined strings, macros and diversions. When an undefined
5383 string, macro or diversion is used, that string is automatically defined
5384 as empty. So, in most cases, at most one warning will be given for each
5389 @c XXX more findex entries
5390 Use of undefined number registers. When an undefined number register is
5391 used, that register is automatically defined to have a value of@w{ }0.
5392 A definition is automatically made with a value of@w{ }0. So, in most
5393 cases, at most one warning will be given for use of a particular name.
5396 Use of a tab character where a number was expected.
5400 Use of @code{\@}} where a number was expected.
5403 Requests that are missing non-optional arguments.
5406 Illegal input characters.
5409 Unrecognized escape sequences. When an unrecognized escape sequence is
5410 encountered, the escape character is ignored.
5413 @cindex compatibility mode
5414 Missing space between a request or macro and its argument. This warning
5415 will be given when an undefined name longer than two characters is
5416 encountered, and the first two characters of the name make a defined
5417 name. The request or macro will not be invoked. When this warning is
5418 given, no macro is automatically defined. This is enabled by default.
5419 This warning will never occur in compatibility mode.
5422 Non-existent fonts. This is enabled by default.
5424 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
5425 intended that this covers all warnings that are useful with traditional
5432 @node Implementation Differences, Summary, Debugging, Programming Tutorial
5433 @section Implementation Differences
5434 @cindex implementation differences
5435 @cindex differences in implementation
5436 @cindex compatibility mode
5437 @cindex mode, compatibility
5439 GNU @code{troff} has a number of features which cause incompatibilities
5440 with documents written with old versions of @code{troff}.
5444 Long names cause some incompatibilities. @sc{Unix} @code{troff} will
5456 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
5457 @code{troff} will interpret this as a call of a macro named
5458 @code{dsabcd}. Also @sc{Unix} @code{troff} will interpret @code{\*[} or
5459 @code{\n[} as references to a string or number register called @samp{[}.
5460 In GNU @code{troff}, however, this will normally be interpreted as the
5461 start of a long name. In compatibility mode GNU @code{troff} will
5462 interpret these things in the traditional way. In compatibility mode,
5463 however, long names are not recognized. Compatibility mode can be
5464 turned on with the @samp{-C} command line option, and turned on or off
5465 with the @code{cp} request. The number register @code{.C} is@w{ }1 if
5466 compatibility mode is on, 0@w{ }otherwise.
5482 GNU @code{troff} does not allow the use of the escape sequences
5483 @code{\|}, @code{\^}, @code{\&}, @code{\@}}, @code{\@{},
5484 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5485 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
5486 registers, fonts or environments; @sc{Unix} @code{troff} does. The
5487 @code{\A} escape sequence may be helpful in avoiding use of these escape
5490 @cindex fractional point sizes
5491 @cindex point sizes, fractional
5493 Fractional point sizes cause one noteworthy incompatibility. In
5494 @sc{Unix} @code{troff} the @code{ps} request ignores scale indicators
5502 will set the point size to 10@w{ }points, whereas in GNU @code{troff} it
5503 will set the point size to 10@w{ }scaled points. @xref{Fractional Type
5504 Sizes}, for more information.
5511 @cindex input and output characters
5512 @cindex output characters
5513 @cindex characters, input and output
5514 In GNU @code{troff} there is a fundamental difference between
5515 unformatted, input characters, and formatted, output characters.
5516 Everything that affects how an output character will be output is stored
5517 with the character; once an output character has been constructed it is
5518 unaffected by any subsequent requests that are executed, including
5519 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
5520 Normally output characters are constructed from input characters at the
5521 moment immediately before the character is added to the current output
5522 line. Macros, diversions and strings are all, in fact, the same type of
5523 object; they contain lists of input characters and output characters in
5524 any combination. An output character does not behave like an input
5525 character for the purposes of macro processing; it does not inherit any
5526 of the special properties that the input character from which it was
5527 constructed might have had. For example,
5540 @cindex transparent output
5541 @cindex output, transparent
5543 will print @samp{\\} in GNU @code{troff}; each pair of input backslashes
5544 is turned into one output backslash and the resulting output backslashes
5545 are not interpreted as escape characters when they are reread.
5546 @sc{Unix} @code{troff} would interpret them as escape characters when
5547 they were reread and would end up printing one @samp{\}. The correct
5548 way to obtain a printable backslash is to use the @code{\e} escape
5549 sequence: This will always print a single instance of the current escape
5550 character, regardless of whether or not it is used in a diversion; it
5551 will also work in both GNU @code{troff} and @sc{Unix} @code{troff}. If
5552 you wish for some reason to store in a diversion an escape sequence that
5553 will be interpreted when the diversion is reread, you can either use the
5554 traditional @code{\!} transparent output facility, or, if this is
5555 unsuitable, the new @code{\?} escape sequence.
5557 @xref{Diversions}, for more information.
5560 @node Summary, , Implementation Differences, Programming Tutorial
5564 @c XXX documentation
5568 @node Preprocessors, Output Devices, Programming Tutorial, Top
5569 @chapter Preprocessors
5570 @cindex preprocessors
5572 This chapter describes all preprocessors that come with @code{groff} or
5573 which are freely available.
5586 @node geqn, gtbl, Preprocessors, Preprocessors
5587 @section @code{geqn}
5597 @node Invoking geqn, , geqn, geqn
5598 @subsection Invoking @code{geqn}
5599 @cindex invoking @code{geqn}
5600 @cindex @code{geqn}, invoking
5605 @node gtbl, gpic, geqn, Preprocessors
5606 @section @code{gtbl}
5616 @node Invoking gtbl, , gtbl, gtbl
5617 @subsection Invoking @code{gtbl}
5618 @cindex invoking @code{gtbl}
5619 @cindex @code{gtbl}, invoking
5624 @node gpic, ggrn, gtbl, Preprocessors
5625 @section @code{gpic}
5635 @node Invoking gpic, , gpic, gpic
5636 @subsection Invoking @code{gpic}
5637 @cindex invoking @code{gpic}
5638 @cindex @code{gpic}, invoking
5643 @node ggrn, grap, gpic, Preprocessors
5644 @section @code{ggrn}
5654 @node Invoking ggrn, , ggrn, ggrn
5655 @subsection Invoking @code{ggrn}
5656 @cindex invoking @code{ggrn}
5657 @cindex @code{ggrn}, invoking
5662 @node grap, grefer, ggrn, Preprocessors
5663 @section @code{grap}
5666 A freely available implementation of @code{grap}, written by Ted Faber,
5667 is available as an extra package from the following address:
5670 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
5674 @node grefer, gsoelim, grap, Preprocessors
5675 @section @code{grefer}
5676 @cindex @code{refer}
5677 @cindex @code{grefer}
5685 @node Invoking grefer, , grefer, grefer
5686 @subsection Invoking @code{grefer}
5687 @cindex invoking @code{grefer}
5688 @cindex @code{grefer}, invoking
5693 @node gsoelim, , grefer, Preprocessors
5694 @section @code{gsoelim}
5695 @cindex @code{soelim}
5696 @cindex @code{gsoelim}
5701 * Invoking gsoelim::
5704 @node Invoking gsoelim, , gsoelim, gsoelim
5705 @subsection Invoking @code{gsoelim}
5706 @cindex invoking @code{gsoelim}
5707 @cindex @code{gsoelim}, invoking
5713 @node Output Devices, File formats, Preprocessors, Top
5714 @chapter Output Devices
5715 @cindex output devices
5716 @cindex devices for output
5721 * Special Characters::
5732 @node Special Characters, grotty, Output Devices, Output Devices
5733 @section Special Characters
5734 @cindex special characters
5735 @cindex characters, special
5742 @node grotty, grops, Special Characters, Output Devices
5743 @section @code{grotty}
5744 @cindex @code{grotty}
5752 @node Invoking grotty, , grotty, grotty
5753 @subsection Invoking @code{grotty}
5754 @cindex invoking @code{grotty}
5755 @cindex @code{grotty}, invoking
5760 @node grops, grodvi, grotty, Output Devices
5761 @section @code{grops}
5762 @cindex @code{grops}
5768 * Embedding PostScript::
5771 @node Invoking grops, Embedding PostScript, grops, grops
5772 @subsection Invoking @code{grops}
5773 @cindex invoking @code{grops}
5774 @cindex @code{grops}, invoking
5778 @node Embedding PostScript, , Invoking grops, grops
5779 @subsection Embedding PostScript
5780 @cindex embedding postscript
5781 @cindex postscript, embedding
5786 @node grodvi, grolj4, grops, Output Devices
5787 @section @code{grodvi}
5788 @cindex @code{grodvi}
5796 @node Invoking grodvi, , grodvi, grodvi
5797 @subsection Invoking @code{grodvi}
5798 @cindex invoking @code{grodvi}
5799 @cindex @code{grodvi}, invoking
5804 @node grolj4, grolbp, grodvi, Output Devices
5805 @section @code{grolj4}
5806 @cindex @code{grolj4}
5814 @node Invoking grolj4, , grolj4, grolj4
5815 @subsection Invoking @code{grolj4}
5816 @cindex invoking @code{grolj4}
5817 @cindex @code{grolj4}, invoking
5822 @node grolbp, grohtml, grolj4, Output Devices
5823 @section @code{grolbp}
5824 @cindex @code{grolbp}
5832 @node Invoking grolbp, , grolbp, grolbp
5833 @subsection Invoking @code{grolbp}
5834 @cindex invoking @code{grolbp}
5835 @cindex @code{grolbp}, invoking
5840 @node grohtml, gxditview, grolbp, Output Devices
5841 @section @code{grohtml}
5842 @cindex @code{grohtml}
5847 * Invoking grohtml::
5850 @node Invoking grohtml, , grohtml, grohtml
5851 @subsection Invoking @code{grohtml}
5852 @cindex invoking @code{grohtml}
5853 @cindex @code{grohtml}, invoking
5858 @node gxditview, , grohtml, Output Devices
5859 @section @code{gxditview}
5860 @cindex @code{gxditview}
5865 * Invoking gxditview::
5868 @node Invoking gxditview, , gxditview, gxditview
5869 @subsection Invoking @code{gxditview}
5870 @cindex invoking @code{gxditview}
5871 @cindex @code{gxditview}, invoking
5878 @node File formats, Installation, Output Devices, Top
5879 @chapter File formats
5880 @cindex file formats
5881 @cindex formats, file
5891 @node gtroff Output, Font Files, File formats, File formats
5892 @section @code{gtroff} Output
5893 @cindex @code{gtroff} output
5894 @cindex output, @code{gtroff}
5896 This section describes the format output of GNU @code{troff}. The
5897 output format used by GNU @code{troff} is very similar to that used by
5898 @sc{Unix} device-independent @code{troff} (@code{ditroff}).
5903 * Drawing Functions::
5904 * Line Continuation::
5907 @node Output Format, Device Control, gtroff Output, gtroff Output
5908 @subsection Output Format
5909 @cindex output format
5910 @cindex format of output
5913 @cindex input, 8-bit
5914 The output format is text based, as opposed to a binary format (like
5915 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
5916 characters can have the eighth bit set, as can the names of fonts and
5919 The output format consists of single command characters with attached
5920 parameters which are separated from subsequent text by whitespace or a
5923 The names of characters and fonts can be of arbitrary length; drivers
5924 should not assume that they will be only two characters long (as
5925 @code{ditroff} does).
5927 When a character is to be printed, that character will always be in the
5928 current font. Unlike @code{ditroff}, it is not necessary for drivers to
5929 search special fonts to find a character.
5944 @item @var{nn}@var{c}
5947 @var{xxx} is any sequence of characters terminated by a space or a
5948 newline; the first character should be printed at the current position,
5949 the the current horizontal position should be increased by the width of
5950 the first character, and so on for each character. The width of the
5951 character is that given in the font file, appropriately scaled for the
5952 current point size, and rounded so that it is a multiple of the
5953 horizontal resolution. Special characters cannot be printed using this
5958 This command is only allowed if the @samp{tcommand} line is present in
5959 the @file{DESC} file.
5960 @item u@var{n} @var{xxx}
5961 This is same as the @samp{t} command except that after printing each
5962 character, the current horizontal position is increased by the sum of
5963 the width of that character and@w{ }@var{n}.
5965 This command is only allowed if the @samp{tcommand} line is present in
5966 the @file{DESC} file.
5967 @item n@var{a}@var{b}
5974 The argument to the @samp{s} command is in scaled points (units of
5975 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
5976 command in the @file{DESC} file).
5981 @item D@var{c} @var{x}@dots{}\n
5985 @node Device Control, Drawing Functions, Output Format, gtroff Output
5986 @subsection Device Control
5987 @cindex device control
5988 @cindex control of devices
5990 The @samp{x} command is normally followed by a letter or word indicating
5991 the function to perform, followed by white space separated arguments.
5993 The first argument can be abbreviated to the first letter.
6000 @item x res @var{n} @var{h} @var{v}
6004 The argument to the @w{@samp{x Height}} command is also in scaled
6008 The first three output commands are guaranteed to be:
6017 For example, the input
6020 crunchy \fH\s+2frog\s0\fP!?
6029 ... sample output here ...
6032 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
6033 @subsection Drawing Functions
6034 @cindex drawing functions
6035 @cindex functions for drawing
6038 The @samp{D} drawing command has been extended. These extensions will
6039 only be used by GNU @code{pic} if the @samp{-x} option is given.
6041 @xref{Drawing Requests}.
6046 Set the shade of gray to be used for filling solid objects to@w{
6047 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
6048 corresponds solid white and 1000 to solid black, and values in between
6049 correspond to intermediate shades of gray. This applies only to solid
6050 circles, solid ellipses and solid polygons. By default, a level of@w{
6051 }1000 will be used. Whatever color a solid object has, it should
6052 completely obscure everything beneath it. A value greater than@w{ }1000
6053 or less than@w{ }0 can also be used: this means fill with the shade of
6054 gray that is currently being used for lines and text. Normally this
6055 will be black, but some drivers may provide a way of changing this.
6057 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
6058 point at the current position.
6059 @item DE @var{dx} @var{dy}
6060 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
6061 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
6063 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
6064 Draw a polygon with. The first vertex is at the current position, the
6065 second vertex at an offset (@var{dx1},@var{dy1}) from the current
6066 position, the second vertex at an offset (@var{dx2},@var{dy2}) from the
6067 first vertex, and so on up to the @var{n}-th vertex. At the moment, GNU
6068 @code{pic} only uses this command to generate triangles and rectangles.
6069 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
6070 Like @code{Dp} but draw a solid rather than outlined polygon.
6072 @cindex line thickness
6073 @cindex thickness of lines
6074 Set the current line thickness to @var{n}@w{ }machine units.
6075 Traditionally, @sc{Unix} @code{troff} drivers use a line thickness
6076 proportional to the current point size; drivers should continue to do
6077 this if no @code{Dt} command has been given, or if a @code{Dt} command
6078 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
6079 }@var{n} selects the smallest available line thickness.
6083 A difficulty arises in how the current position should be changed after
6084 the execution of these commands. This is not of great importance since
6085 the code generated by GNU @code{pic} does not depend on this. Given a
6086 drawing command of the form
6089 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
6096 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
6097 @samp{~}, @sc{Unix} @code{troff} will treat each of the x@w{ }value as a
6098 horizontal quantity, and each of the y@w{ }values as a vertical quantity
6099 and will assume that the width of the drawn object is sum if all x@w{
6100 }values, and that the height is the sum of all y@w{ }values. (The
6101 assumption about the height can be seen by examining the @code{st} and
6102 @code{sb} registers after using such a @code{D}@w{ }command in a
6103 @code{\w} escape sequence.) This rule also holds for all the original
6104 drawing commands with the exception of @code{De}. For the sake of
6105 compatibility GNU @code{troff} also follows this rule, even though it
6106 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
6107 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
6108 @code{D}@w{ }command of the form
6111 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
6115 the current position should be increased horizontally by the sum of all
6116 x@w{ }values and vertically by the sum of all y@w{ }values.
6118 @node Line Continuation, , Drawing Functions, gtroff Output
6119 @subsection Line Continuation
6120 @cindex line continuation in output commands
6121 @cindex output commands, line continuation
6123 There is a continuation convention which permits the argument to the
6124 @w{@samp{x X}} command to contain newlines: When outputting the argument
6125 to the @w{@samp{x X}} command, GNU @code{troff} will follow each newline
6126 in the argument with a @samp{+} character (as usual, it will terminate
6127 the entire argument with a newline); thus if the line after the line
6128 containing the @w{@samp{x X}} command starts with @samp{+}, then the
6129 newline ending the line containing the @w{@samp{x X}} command should be
6130 treated as part of the argument to the @w{@samp{x X}} command, the
6131 @samp{+} should be ignored, and the part of the line following the
6132 @samp{+} should be treated like the part of the line following the
6133 @w{@samp{x X}} command.
6136 @node Font Files, , gtroff Output, File formats
6141 The @code{gtroff} font format is roughly a superset of the
6142 @code{ditroff} font format. Unlike the @code{ditroff} font format,
6143 there is no associated binary format; all files are text files. The
6144 font files for device @var{name} are stored in a directory
6145 @file{dev@var{name}}. There are two types of file: a device description
6146 file called @file{DESC} and for each font@w{ }@samp{F} a font file
6147 called@w{ }@file{F}.
6150 * DESC file format::
6151 * Font file format::
6154 @node DESC file format, Font file format, Font Files, Font Files
6155 @subsection @file{DESC} file format
6156 @cindex @file{DESC} file format
6157 @cindex font description file format
6158 @cindex format of font description file
6161 The @file{DESC} file can contain the following types of line:
6166 There are @var{n} machine units per inch.
6169 The horizontal resolution is @var{n} machine units.
6172 The vertical resolution is @var{n} machine units.
6174 @item sizescale @var{n}
6175 The scale factor for point sizes. By default this has a value of@w{ }1.
6176 One scaled point is equal to one point/@var{n}. The arguments to the
6177 @code{unitwidth} and @code{sizes} commands are given in scaled points.
6178 @xref{Fractional Type Sizes}, for more information.
6180 @item unitwidth @var{n}
6181 Quantities in the font files are given in machine units for fonts whose
6182 point size is @var{n}@w{ }scaled points.
6185 This means that the postprocessor can handle the @samp{t} and @samp{u}
6188 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
6189 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
6190 @var{sn} scaled points. The list of sizes must be terminated by a@w{
6191 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
6192 list can extend over more than one line.
6194 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
6195 The first @var{m}@w{ }font positions will be associated with styles
6196 @var{S1} @dots{} @var{Sm}.
6198 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
6199 Fonts @var{F1} @dots{} @var{Fn} will be mounted in the font positions
6200 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
6201 styles. This command may extend over more than one line. A font name
6202 of@var{ }0 will cause no font to be mounted on the corresponding font
6205 @item family @var{fam}
6206 The default font family is @var{fam}.
6209 This line and everything following in the file are ignored. It is
6210 allowed for the sake of backwards compatibility.
6213 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
6214 are compulsory. Other commands are ignored by @code{gtroff} but may be
6215 used by postprocessors to store arbitrary information about the device
6216 in the @file{DESC} file.
6218 @c XXX add other commands resp. xrefs to output devices
6219 @c XXX add obsolete commands
6221 @node Font file format, , DESC file format, Font Files
6222 @subsection Font file format
6223 @cindex font file format
6224 @cindex format of font files
6226 A font file has two sections. The first section is a sequence of lines
6227 each containing a sequence of blank delimited words; the first word in
6228 the line is a key, and subsequent words give a value for that key.
6233 The name of the font is@w{ }@var{F}.
6235 @item spacewidth @var{n}
6236 The normal width of a space is@w{ }@var{n}.
6239 The characters of the font have a slant of @var{n}@w{ }degrees.
6240 (Positive means forward.)
6242 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
6243 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
6244 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
6245 @samp{ffl}. For backwards compatibility, the list of ligatures may be
6246 terminated with a@w{ }0. The list of ligatures may not extend over more
6250 The font is special; this means that when a character is requested that
6251 is not present in the current font, it will be searched for in any
6252 special fonts that are mounted.
6255 Other commands are ignored by @code{gtroff} but may be used by
6256 postprocessors to store arbitrary information about the font in the font
6259 @cindex comments in font files
6260 @cindex font files, comments
6262 The first section can contain comments which start with the @samp{#}
6263 character and extend to the end of a line.
6265 The second section contains one or two subsections. It must contain a
6266 @code{charset} subsection and it may also contain a @code{kernpairs}
6267 subsection. These subsections can appear in any order. Each
6268 subsection starts with a word on a line by itself.
6271 The word @code{charset} starts the character set subsection. The
6272 @code{charset} line is followed by a sequence of lines. Each line gives
6273 information for one character. A line comprises a number of fields
6274 separated by blanks or tabs. The format is
6276 @c XXX fix it for new HTML additions
6279 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
6283 @cindex input, 8-bit
6287 @var{name} identifies the character: If @var{name} is a single
6288 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
6289 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
6290 a single character, then it corresponds to the @code{gtroff} input
6291 character@w{ }\@var{c}; otherwise it corresponds to the groff input
6292 character @samp{\[@var{name}]}. (If it is exactly two characters
6293 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
6294 supports 8-bit characters; however some utilities have difficulties with
6295 eight-bit characters. For this reason, there is a convention that the
6296 name @samp{char@var{n}} is equivalent to the single character whose code
6297 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
6298 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
6299 Latin-1} character set. The name @samp{---} is special and indicates
6300 that the character is unnamed; such characters can only be used by means
6301 of the @code{\N} escape sequence in troff.
6303 @c XXX input encodings vs. output encodings
6305 The @var{type} field gives the character type:
6309 the character has an descender, for example, `p';
6311 the character has an ascender, for example, `b';
6313 the character has both an ascender and a descender, for example, `('.
6316 The @var{code} field gives the code which the postprocessor uses to
6317 print the character. The character can also be input to @code{gtroff}
6318 using this code by means of the @code{\N} escape sequence. The code can
6319 be any integer. If it starts with @samp{0} it will be interpreted as
6320 octal; if it starts with @samp{0x} or @samp{0X} it will be interpreted as
6323 Anything on the line after the @var{code} field will be ignored.
6325 The @var{metrics} field has the form:
6328 @var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]}
6331 There must not be any spaces between these subfields. Missing subfields
6332 are assumed to be@w{ }0. The subfields are all decimal integers. Since
6333 there is no associated binary format, these values are not required to
6334 fit into a variable of type @samp{char} as they are in @code{ditroff}.
6335 The @var{width} subfield gives the width of the character. The
6336 @var{height} subfield gives the height of the character (upwards is
6337 positive); if a character does not extend above the baseline, it should
6338 be given a zero height, rather than a negative height. The @var{depth}
6339 subfield gives the depth of the character, that is, the distance below
6340 the lowest point below the baseline to which the character extends
6341 (downwards is positive); if a character does not extend below above the
6342 baseline, it should be given a zero depth, rather than a negative depth.
6343 The @var{italic_correction} subfield gives the amount of space that
6344 should be added after the character when it is immediately to be
6345 followed by a character from a Roman font. The
6346 @var{left_italic_correction} subfield gives the amount of space that
6347 should be added before the character when it is immediately to be
6348 preceded by a character from a Roman font. The
6349 @var{subscript_correction} gives the amount of space that should be
6350 added after a character before adding a subscript. This should be less
6351 than the italic correction.
6353 A line in the @code{charset} section can also have the format
6360 This indicates that @var{name} is just another name for the character
6361 mentioned in the preceding line.
6364 The word @code{kernpairs} starts the kernpairs section. This contains a
6365 sequence of lines of the form:
6368 @var{c1} @var{c2} @var{n}
6371 This means that when character @var{c1} appears next to character
6372 @var{c2} the space between them should be increased by@w{ }@var{n}.
6373 Most entries in kernpairs section will have a negative value for@w{
6378 @node Installation, Request and Operator Index, File formats, Top
6379 @chapter Installation
6380 @cindex installation
6386 @node Request and Operator Index, Register Index, Installation, Top
6387 @chapter Request and Operator Index
6393 @node Register Index, Font File Keyword Index, Request and Operator Index, Top
6394 @chapter Register Index
6400 @node Font File Keyword Index, Program and File Index, Register Index, Top
6401 @chapter Font File Keyword Index
6407 @node Program and File Index, Concept Index, Font File Keyword Index, Top
6408 @chapter Program and File Index
6414 @node Concept Index, , Program and File Index, Top
6415 @chapter Concept Index