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
542 in the program `Gnomovision' (which makes passes at compilers)
543 written by James Hacker.
545 @var{signature of Ty Coon}, 1 April 1989
546 Ty Coon, President of Vice
550 This General Public License does not permit incorporating your program
551 into proprietary programs. If your program is a subroutine library, you
552 may consider it more useful to permit linking proprietary applications
553 with the library. If this is what you want to do, use the GNU Library
554 General Public License instead of this License.
558 @node Introduction, Invoking groff, Copying, Top
559 @chapter Introduction
562 GNU @code{troff} (or @code{groff}) is a system for typesetting
563 documents. @code{troff} is very flexible and has been in existence (and
564 use) for about 3@w{ }decades. It is quite widespread and firmly
565 entrenched in the @sc{Unix} community.
570 * groff Capabilities::
571 * Macro Package Intro::
572 * Preprocessor Intro::
573 * Output device intro::
578 @node What Is groff?, History, Introduction, Introduction
579 @section What Is @code{groff}?
580 @cindex what is @code{groff}?
581 @cindex @code{groff} -- what is it?
583 @code{groff} is of an older generation of document preparation systems,
584 which operate more like compilers than the more recent interactive
585 WYSIWYG@footnote{What You See Is What You Get} systems. @code{groff}
586 and its contemporary counterpart, @TeX{}, both work using a @dfn{batch}
587 paradigm: The input (or @dfn{source}) files are normal text files with
588 embedded formatting commands. These files can then be processed by
589 @code{groff} to produce a typeset document on a variety of devices.
591 Likewise, @code{groff} should not be confused with a @dfn{word
592 processor}, since that term connotes an integrated system which includes
593 an editor and a text formatter. Also, many word processors follow the
594 WYSIWYG paradigm which was discussed earlier.
596 Although WYSIWYG systems may be easier to use, they have a number of
597 disadvantages compared to @code{troff}:
601 They must be used on a bitmapped display to do any operations on your
604 Most of the WYSIWYG systems are either non-free or are not very
607 @code{troff} is firmly entrenched in all @sc{Unix} systems.
609 It is difficult to have a wide range of capabilities available within
610 the confines of a GUI/window system.
612 It is more difficult to make global changes to a document.
616 ``GUIs normally make it simple to accomplish simple actions and
617 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
618 @code{comp.unix.wizards})
622 @node History, groff Capabilities, What Is groff?, Introduction
626 @cindex @code{runoff}
627 @code{troff} can trace its origins back to a formatting program called
628 @code{runoff} which ran on MIT's CTSS system. This name came from the
629 common phrase of the time ``I'll run off a document.''
632 The first version of @sc{Unix} was developed on a PDP-7 which was
633 sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11
634 for further work on the operating system. In order to justify the cost
635 for this system, they proposed that they would implement a document
636 formatting system for the AT&T patents division. This first formatting
637 program was a reimplementation of @code{runoff}. In accordance with
638 @sc{Unix}'s penchant for abbreviations, it was named @code{roff} (an
639 abbreviation of @code{runoff}).
642 When they needed a more flexible language, a new version of @code{roff}
643 called @code{nroff} (Newer @code{roff}) was written. It had a much more
644 complicated syntax, but provided the basis for all future versions.
645 When they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{
646 }Ossanna wrote a version of @code{nroff} which would drive it. It was
647 dubbed @code{troff} for typesetter @code{roff}, although many people
648 have speculated that it actually means Times @code{roff} because of the
649 use of the Times font family in @code{troff} by default. As such, the
650 name @code{troff} is pronounced t-roff rather than trough.
652 With @code{troff} came @code{nroff} (they were actually the same program
653 except for some @samp{#ifdefs}), which was for producing output for line
654 printers and character terminals. It understood everything @code{troff}
655 did, and ignored the commands which were not applicable (e.g.@: font
658 Since there are several things which cannot be done easily in
659 @code{troff}, work on several preprocessors began. These programs would
660 transform certain parts of a document into @code{troff}, which made a
661 very natural use of pipes in @sc{Unix}.
663 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
664 specified in a much simpler and more intuitive manner. @code{tbl} is a
665 preprocessor for formatting tables. The @code{refer} preprocessor (and
666 the similar program, @code{bib}) processes citations in a document
667 according to a bibliographic database.
669 Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
670 language and produced output specifically for the CAT phototypesetter.
671 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
672 code and still dependent on the CAT. As the CAT became less common, and
673 was no longer supported by the manufacturer, the need to make it support
674 other devices became a priority. However, before this could be done, he
675 was killed in an auto accident.
678 @cindex @code{ditroff}
679 So, Brian Kernighan took on the task of rewriting @code{troff}. The
680 newly rewritten version produced a device independent code which was
681 very easy for postprocessors to read and translate to the appropriate
682 printer codes. Also, this new version of @code{troff} (called
683 @code{ditroff}) had several extensions, which included drawing
686 Due to the additional abilities of the new version of @code{troff},
687 several new preprocessors appeared. The @code{pic} preprocessor
688 provides a wide range of drawing functions. Likewise the @code{ideal}
689 preprocessor did the same, although via a much different paradigm. The
690 @code{grap} preprocessor took specifications for graphs, but, unlike
691 other preprocessors, produced @code{pic} code.
693 James Clark began work on a GNU implementation of @code{ditroff} in
694 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
695 June@w{ }1990. @code{groff} included
699 A replacement for @code{ditroff} with many extensions.
701 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
703 Postprocessors for character devices, PostScript, @TeX{} DVI, and X@w{
704 }windows. GNU @code{troff} also eliminated the need for a separate
705 @code{nroff} program with a postprocessor which would produce @sc{ascii}
708 A version of the @code{-me} macros and an implementation of the
712 Also, a front-end was included which could construct the, sometimes
713 painfully long, pipelines required for all the post- and preprocessors.
715 Development of GNU @code{troff} progressed rapidly, and saw the
716 additions of a replacement for @code{refer}, an implementation of the
717 @code{-ms} and @code{-mm} macros, and a program to deduce how to format
718 a document (@code{grog}).
720 It was declared a stable (i.e.@: non beta) package with the release of
721 version@w{ }1.04 around November@w{ }1991.
723 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
724 an orphan for a few years). As a result, new features and programs like
725 @code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an
726 output device to produce HTML output, have been added.
729 @node groff Capabilities, Macro Package Intro, History, Introduction
730 @section @code{groff} Capabilities
731 @cindex @code{groff} capabilities
732 @cindex capabilities of @code{groff}
734 So what exactly is @code{groff} capable of doing? @code{groff} provides
735 a wide range of low-level text formatting operations. Using these, you
736 can perform a wide range of formatting tasks, such as footnotes, table
737 of contents, multiple columns, etc.
741 Text filling, adjusting, and centering
747 Font and character size control
749 Vertical spacing (i.e.@: double spacing)
751 Line length and indenting
753 Macros, strings, diversions, and traps
757 Tabs, leaders, and fields
759 Input and output conventions and character translation
761 Overstrike, bracket, line drawing, and zero-width functions
763 Local horizontal and vertical motions and the width function
767 Output line numbering
769 Conditional acceptance of input
771 Environment switching
773 Insertions from the standard input
775 Input/output file switching
777 Output and error messages
781 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
782 @section Macro Packages
783 @cindex macro packages
785 Since @code{groff} provides such low level facilities, it can be quite
786 difficult to use by itself. However, @code{groff} provides a
787 @dfn{macro} facility which allows you to specify how certain routine
788 operations (e.g.@w{ }starting paragraphs, printing headers and footers,
789 etc.)@: should be done. These macros can be collected together into a
790 @dfn{macro package}. There are a number of macro packages available;
791 the most common (and the ones described in this manual) are @code{-man},
792 @code{-mdoc}, @code{-me}, @code{-ms}, and @code{-mm}.
795 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
796 @section Preprocessors
797 @cindex preprocessors
799 Although @code{groff} provides most functions needed to format a
800 document, some operations would be unwieldy (i.e.@: drawing pictures).
801 Therefore, programs called preprocessors were written which understand
802 their own language and produce the necessary @code{groff} operations.
803 These preprocessors are able to differentiate their own input from the
804 rest of the document via markers.
806 To use a preprocessor, @sc{Unix} pipes are used to feed the output from
807 the preprocessor into @code{groff}. Any number of preprocessors may be
808 used on a given document; in this case, the preprocessors are linked
809 together into one pipeline. However, in @code{groff}, the user does not
810 need to construct the pipe, but only tell @code{groff} what
811 preprocessors to use.
813 @code{groff} currently has preprocessors for producing tables
814 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
815 (@code{pic} and @code{grn}), and for processing bibliographies
816 (@code{refer}). An associated program which is useful when dealing with
817 preprocessors is @code{soelim}.
819 There are other preprocessors in existence, but there are,
820 unfortunately, no free implementations available. They are for drawing
821 pictures (@code{ideal}) and chemical structures (@code{chem}).
823 A free implementation of @code{grap}, a preprocessor for drawing graphs,
824 can be obtained as an extra package.
827 @node Output device intro, Credits, Preprocessor Intro, Introduction
828 @section Output Devices
829 @cindex postprocessors
830 @cindex output devices
831 @cindex devices for output
833 @code{groff} actually produces device independent code which may be fed
834 into a postprocessor which will produce output for a particular device.
835 Currently, @code{groff} has postprocessors for PostScript, character
836 terminals, X@w{ }Windows (for previewing), @TeX{} DVI format, HP
837 LaserJet@w{ }4 printers, and HTML.
840 @node Credits, , Output device intro, Introduction
844 Large portions of this manual were taken from existing documents, most
845 notably, the manual pages for the @code{groff} package by James Clark,
846 and Eric Allman's papers on the @code{-me} macro package.
850 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
851 @chapter Invoking @code{groff}
852 @cindex invoking @code{groff}
853 @cindex @code{groff} invocation
857 This section focuses on how to invoke the @code{groff} front end. This
858 front end takes care of the details of constructing the pipeline among
859 the preprocessors, @code{gtroff} and the postprocessor.
861 It has become a tradition that GNU programs get the prefix @dfn{g} to
862 distinguish it from its original counterparts provided by the host
863 (@pxref{Environment}, for more details). Thus, for example, @code{geqn}
864 is GNU @code{eqn}. On operating systems like Linux or the Hurd, which
865 don't contain proprietary software, this prefix is omitted since GNU
866 @code{troff} is the only used incarnation of @code{troff}. Exception:
867 @code{groff} is never replaced by @code{roff}.
872 * Invocation Examples::
876 @node Options, Environment, Invoking groff, Invoking groff
888 @code{groff} is a front-end to the groff document formatting system.
889 Normally it runs the @code{gtroff} program and a postprocessor
890 appropriate for the selected device. The default device is @samp{ps}.
891 It can optionally preprocess with any of @code{gpic}, @code{geqn},
892 @code{gtbl}, @code{ggrn}, @code{grefer}, or @code{gsoelim}.
894 This section only documents options to the @code{groff} front end. Many
895 of the arguments to @code{groff} are passed on to @code{gtroff},
896 therefore those are also included. Arguments to pre- or postprocessors
897 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
898 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
899 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
900 grohtml}, @ref{Invoking grodvi}, and @ref{Invoking gxditview}.
902 The command line format for @code{groff} is:
905 groff [ -abeghilpstvzCENRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
906 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
907 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
908 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
909 [ @var{files}@dots{} ]
912 The command line format for @code{gtroff} is as follows. As you can
913 see, many of the options to @code{groff} are actually passed on to
917 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
918 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
919 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
920 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
923 Options without an argument can be grouped behind a single @samp{-}. A
924 filename of @samp{-} denotes the standard input.
927 The @code{grog} command can be used to guess the correct @code{groff}
928 command to use to format a file.
932 Print a help message.
934 Preprocess with @code{geqn}.
936 Preprocess with @code{gtbl}.
938 Preprocess with @code{ggrn}.
940 Preprocess with @code{gpic}.
942 Preprocess with @code{gsoelim}.
944 Preprocess with @code{grefer}. No mechanism is provided for passing
945 arguments to @code{grefer} because most @code{grefer} options have
946 equivalent commands which can be included in the file. @xref{grefer},
951 Note that @code{gtroff} also accepts a @samp{-R} option, which is not
952 accessible via @code{groff}. This option prevents the loading of the
953 @file{troffrc} and @file{troffrc-end} files.
955 Make programs run by @code{groff} print out their version number.
957 Print the pipeline on stdout instead of executing it.
959 Suppress output from @code{gtroff}. Only error messages will be
962 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
963 will automatically run the appropriate postprocessor.
965 Pass @var{arg} to the postprocessor. Each argument should be passed
966 with a separate @samp{-P} option. Note that @code{groff} does not
967 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
969 Send the output to a printer. The command used for this is specified by
970 the print command in the device description file.
972 Pass @var{arg} to the spooler. Each argument should be passed with a
973 separate @samp{-L} option. Note that @code{groff} does not prepend a
974 @samp{-} to @var{arg} before passing it to the postprocessor.
976 Prepare output for device @var{dev}. The default device is @samp{ps}.
977 The following are the output devices currently available:
980 For PostScript printers and previewers.
982 For @TeX{} DVI format.
984 For a 75@dmn{dpi} X11 previewer.
986 For a 100@dmn{dpi} X11 previewer.
988 For typewriter-like devices.
990 For typewriter-like devices using the @w{ISO Latin-1} (@w{ISO 8859-1})
993 For typewriter-like devices which use the Unicode (@w{ISO 10646})
994 character set with @w{UTF-8} encoding.
996 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
998 To produce HTML output.
1001 The postprocessor to be used for a device is specified by the
1002 @code{postpro} command in the device description file. (@xref{Font
1003 Files}, for more info.) This can be overridden with the @samp{-X}
1006 Preview with @code{gxditview} instead of using the usual postprocessor.
1007 This is unlikely to produce good results except with @samp{-Tps}.
1009 Don't allow newlines with @code{eqn} delimiters. This is the same as
1010 the @samp{-N} option in @code{geqn}.
1012 Safer mode. Pass the @samp{-S} option to @code{gpic} and use the
1013 @samp{-msafer} macros with @code{gtroff} (enabled by default).
1015 Unsafe mode. Reverts to the old unsafe behaviour.
1017 Generate an @sc{ascii} approximation of the typeset output.
1019 Print a backtrace with each warning or error message. This backtrace
1020 should help track down the cause of the error. The line numbers given
1021 in the backtrace may not always be correct: @code{gtroff} can get
1022 confused by @code{as} or @code{am} requests while counting line numbers.
1024 Read the standard input after all the named input files have been
1027 Enable warning @var{name}. Available warnings are described in
1028 @ref{Debugging}. Multiple @samp{-w} options are allowed.
1030 Inhibit warning @var{name}. Multiple @samp{-W} options are allowed.
1032 Inhibit all error messages.
1034 Enable compatibility mode.
1036 @itemx -d@var{name}=s
1037 Define @var{c} or @var{name} to be a string @var{s}; @var{c} must be a
1038 one-letter @var{name}.
1040 Use @var{fam} as the default font family.
1042 Read in the file @file{tmac.@var{name}}. Normally this will be searched
1043 for in the library directory of @code{groff}.
1045 Number the first page @var{num}.
1047 Output only pages in @var{list}, which is a comma-separated list of page
1048 ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
1049 print every page between @var{m} and @var{n}, @samp{-@var{n}} means
1050 print every page up to @var{n}, @samp{@var{n}-} means print every page
1051 from @var{n}. @code{gtroff} will exit after printing the last page in
1054 @itemx -r@var{name}=@var{n}
1055 Set number register @var{c} or @var{name} to @var{n}; @var{c} must be a
1056 one-letter @var{name}; @var{n} can be any troff numeric expression.
1058 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1059 name of the device) for the @file{DESC} file and font files before the
1062 Search directory @var{dir} for macro files before the normal directory.
1064 This option is as described in @ref{gsoelim}. It implies the @samp{-s}
1069 @node Environment, Invocation Examples, Options, Invoking groff
1070 @section Environment
1071 @cindex environment variables
1072 @cindex variables in environment
1074 There are also several environment variables which can modify the
1075 behavior of @code{groff}.
1078 @item GROFF_COMMAND_PREFIX
1079 @tindex GROFF_COMMAND_PREFIX
1080 If this is set to @var{X}, then @code{groff} will run
1081 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1082 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1083 @code{soelim}. It does not apply to @code{grops}, @code{grodvi},
1084 @code{grotty}, @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1085 @item GROFF_TMAC_PATH
1086 @tindex GROFF_TMAC_PATH
1087 A colon separated list of directories in which to search for macro
1089 @item GROFF_TYPESETTER
1090 @tindex GROFF_TYPESETTER
1091 The default output device.
1092 @item GROFF_FONT_PATH
1093 @tindex GROFF_FONT_PATH
1094 A colon separated list of directories in which to search for the
1095 @code{dev}@var{name} directory.
1098 The search path for commands executed by @code{groff}.
1100 @tindex GROFF_TMPDIR
1102 The directory in which temporary files will be created. If this is not
1103 set and @code{TMPDIR} is set, temporary files will be created in that
1104 directory. Otherwise temporary files will be created in @code{/tmp}.
1105 The @code{grops} and @code{grefer} commands can create temporary files.
1109 @node Invocation Examples, , Environment, Invoking groff
1110 @section Invocation Examples
1111 @cindex invocation examples
1112 @cindex examples of invocation
1114 This section will list several common uses of @code{groff} and the
1115 command line which will accomplish it.
1122 This command processes @var{file} without a macro package or a
1123 preprocessor. The output device is the default, @var{ps}, and the
1124 output is sent to stdout.
1127 groff -t -mandoc -Tascii file | less
1131 This is basically what a call to @code{man} does. The manual page
1132 @var{file} is processed with the @code{-mandoc} macros (which in turn
1133 either call the @code{-man} or the @code{-mdoc} macro package), using
1134 the @code{tbl} preprocessor and the @sc{ascii} output device. Finally,
1135 the result is displayed with the @code{less} pager.
1142 Preview @var{file} with @code{gxditview}, using the @code{-me} macro
1146 groff -man -rD1 -z file
1150 Check @var{file} with the @code{-man} macro package, forcing
1151 double-sided printing---don't produce any output.
1153 @subsection @code{grog}
1155 @code{grog} reads files and guesses which of the @code{groff}
1156 preprocessors and/or macro packages are are required for formatting
1157 them, and prints the @code{groff} command including those options on the
1158 standard output. The options generated are one of @samp{-e},
1159 @samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-R},
1160 @samp{-g}, @samp{-s}, and @samp{-t}.
1162 A filename of @samp{-} is taken to refer to the standard input. If no
1163 files are specified the standard input will be read. Any specified
1164 options will be included in the printed command. No space is allowed
1165 between options and their arguments. For example,
1172 will guess the appropriate command to print @file{paper.ms} and then
1173 print it to the command line after adding the @samp{-Tdvi} option. If
1174 you want to directly execute it, enclose the call to @code{grog} in
1175 backquotes on the @sc{Unix} shell prompt:
1178 `grog -Tdvi paper.ms` > paper.dvi
1182 As you can see, it is still necessary to redirect the output to
1183 something meaningful (i.e.@: either a file or a pager program like
1188 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1189 @chapter Tutorial for Macro Users
1190 @cindex tutorial for macro users
1191 @cindex macro tutorial for users
1192 @cindex user's tutorial for macros
1193 @cindex user's macro tutorial
1195 Most users tend to use a macro package to format their papers. This
1196 means that the whole breadth of @code{groff} is not necessary for most
1197 people. This chapter covers the material needed to efficiently use a
1206 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1210 This section covers some of the basic concepts you will need to
1211 understand to use a macro package.@footnote{This section is derived from
1212 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1213 References are made throughout to more detailed information, if desired.
1215 @code{gtroff} reads an input file prepared by the user and outputs a
1216 formatted paper suitable for publication or framing. The input consists
1217 of text, or words to be printed, and embedded commands (@dfn{requests}
1218 and @dfn{escapes}), which tell @code{gtroff} how to format the printed
1219 copy. For more detail on this @pxref{Embedded Commands}.
1221 The word @dfn{argument} is used in this manual to mean a word or number
1222 which appears on the same line as a request which modifies the meaning
1223 of that request. For example, the request
1230 spaces one line, but
1237 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1238 request which says to space four lines instead of one. Arguments are
1239 separated from the request and from each other by spaces. More details
1240 on this can be found in @ref{Request Arguments}.
1242 The primary function of @code{gtroff} is to collect words from input
1243 lines, fill output lines with those words, justify the right hand margin
1244 by inserting extra spaces in the line, and output the result. For
1252 Four score and seven
1257 will be read, packed onto output lines, and justified to produce:
1260 Now is the time for all good men to come to the aid of their party.
1261 Four score and seven years ago,...
1266 Sometimes you may want to start a new output line even though the line
1267 you are on is not yet full; for example, at the end of a paragraph. To
1268 do this you can cause a @dfn{break}, which starts a new output line.
1269 Some requests cause a break automatically, as do blank input lines and
1270 input lines beginning with a space.
1272 Not all input lines are text to be formatted. Some of the input lines
1273 are requests which describe how to format the text. Requests always
1274 have a period or an apostrophe (@samp{'}) as the first character of the
1277 The text formatter also does more complex things, such as automatically
1278 numbering pages, skipping over page boundaries putting footnotes in the
1279 correct place, and so forth.
1281 Here a few hints for preparing text for input to @code{gtroff}. First,
1282 keep the input lines short. Short input lines are easier to edit, and
1283 @code{gtroff} will pack words onto longer lines for you anyhow. In
1284 keeping with this, it is helpful to begin a new line after every period,
1285 comma, or phrase, since common corrections are to add or delete
1286 sentences or phrases. Secondly, do not hyphenate words at the end of
1287 lines---@code{gtroff} is smart enough to hyphenate words for you as
1288 needed, but is not smart enough to take hyphens out and join a word back
1289 together. Also, words such as ``mother-in-law'' should not be broken
1290 over a line, since then you will get a space where not wanted, such as
1291 ``@w{mother- in}-law''.
1294 @cindex double spacing
1296 @code{gtroff} will double space output text automatically if you use the
1297 request @w{@samp{.ls 2}}. You can revert to single spaced mode by
1298 typing @w{@samp{.ls 1}}.
1300 A number of requests allow you to change the way the printed copy looks,
1301 sometimes called the @dfn{layout} of the output page. Most of these
1302 requests adjust the placing of @dfn{white space} (blank lines or
1307 The @samp{.bp} request starts a new page.
1312 @cindex lines, empty
1313 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1314 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1315 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1316 @var{N}@w{ }centimeters). For example, the input:
1320 My thoughts on the subject
1325 leaves one and a half inches of space, followed by the line ``My
1326 thoughts on the subject'', followed by a single blank line.
1329 @cindex centering lines
1330 @cindex lines, centering
1331 Text lines can be centered by using the @samp{.ce} request. The line
1332 after @samp{.ce} is centered (horizontally) on the page. To center more
1333 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1334 of lines to center), followed by the @var{N}@w{ }lines. If you want to
1335 center many lines but don't want to count them, type:
1344 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1345 lines, in other words, stop centering.
1350 All of these requests cause a break; that is, they always start a new
1351 line. If you want to start a new line without performing any other
1352 action, use @samp{.br}.
1355 @node Common Features, , Basics, Tutorial for Macro Users
1356 @section Common Features
1357 @cindex common features
1358 @cindex features, common
1360 @code{gtroff} provides very low level operations for formatting a
1361 document. There are many common routine operations which are done in
1362 all documents. These common operations are written into @dfn{macros}
1363 and collected into a @dfn{macro package}.
1365 All macro packages provide certain common capabilities which fall into
1366 the following categories.
1368 @subsection Paragraphs
1371 One of the most common and most used capability is starting a paragraph.
1372 There are a number of different types of paragraphs, any of which can be
1373 initiated with macros supplied by the macro package. Normally,
1374 paragraphs start with a blank line and the first line indented, like the
1375 text in this manual. There are also block style paragraphs, which omit
1379 Some men look at constitutions with sanctimonious
1380 reverence, and deem them like the ark of the covenant, too
1381 sacred to be touched.
1385 And there are also indented paragraphs which begin with a tag or label
1386 at the margin and the remaining text indented.
1389 one This is the first paragraph. Notice how the first
1390 line of the resulting paragraph lines up with the
1391 other lines in the paragraph.
1393 This paragraph had a long label. The first
1394 character of text on the first line will not line up
1395 with the text on second and subsequent lines,
1396 although they will line up with each other.
1399 A variation of this is a bulleted list.
1402 @subsection Sections and Chapters
1404 Most macro packages supply some form of section headers. The simplest
1405 kind is simply the heading on a line by itself in bold type. Others
1406 supply automatically numbered section heading or different heading
1407 styles at different levels. Some, more sophisticated, macro packages
1408 supply macros for starting chapters and appendices.
1410 @subsection Headers and Footers
1412 Every macro packages gives you some way to manipulate the headers and
1413 footers (or @dfn{titles}) on each page. Some packages will allow you to
1414 have different ones on the even and odd pages (for material printed in a
1417 The titles are called three-part titles, that is, there is a
1418 left-justified part, a centered part, and a right-justified part. An
1419 automatically generated page number may be put in any of these fields
1420 with the @samp{%} character (@pxref{Page Layout} for more details).
1422 @subsection Page Layout
1424 Most macro packages let you specify top and bottom margins and other
1425 details about the appearance of the printed pages.
1427 @subsection Displays
1430 Displays are sections of text to be set off from the body of the paper.
1431 Major quotes, tables, and figures are types of displays, as are all the
1432 examples used in this document.
1434 @cindex quotes, major
1435 @cindex major quotes
1436 @dfn{Major quotes} are quotes which are several lines long, and hence
1437 are set in from the rest of the text without quote marks around them.
1440 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1441 should be used when the material to be printed should not be filled and
1442 justified like normal text, such as columns of figures or the examples
1446 A @dfn{keep} is a display of lines which are kept on a single page if
1447 possible. An example of where you would use a keep might be a diagram.
1448 Keeps differ from lists in that lists may be broken over a page boundary
1449 whereas keeps will not.
1451 @cindex keep, floating
1452 @cindex floating keep
1453 Floating keeps move relative to the text. Hence, they are good for
1454 things which will be referred to by name, such as ``See figure@w{ }3''.
1455 A floating keep will appear at the bottom of the current page if it will
1456 fit; otherwise, it will appear at the top of the next page. Meanwhile,
1457 the surrounding text will `flow' around the keep, thus leaving now blank
1460 @subsection Footnotes and annotations
1464 There are a number of requests to save text for later printing.
1465 @dfn{Footnotes} are printed at the bottom of the current page. Delayed
1466 text is intended to be a variant form of footnote; the text is printed
1467 only when explicitly called for, such as at the end of each chapter.
1469 @cindex delayed text
1470 @dfn{Delayed text} is very similar to a footnote except that it is
1471 printed when called for explicitly. This allows a list of references to
1472 appear (for example) at the end of each chapter, as is the convention in
1475 Most macro packages which supply this functionality also supply a means
1476 of automatically numbering either type of annotation.
1478 @subsection Table of Contents
1479 @cindex table of contents
1480 @cindex contents, table of
1482 @dfn{Tables of contents} are a type of delayed text having a tag
1483 (usually the page number) attached to each entry after a row of dots.
1484 The table accumulates throughout the paper until printed, usually after
1485 the paper has ended. Many macro packages will provide the ability to
1486 have several tables of contents (i.e.@: one standard one, one for
1492 While some macro packages will use the term @dfn{index}, none actually
1493 provide that functionality. The facilities they call indices are
1494 actually more appropriate for tables of contents.
1496 @subsection Paper formats
1497 @cindex paper formats
1499 Some macro packages provide stock formats for various kinds of
1500 documents. Many of them provide a common format for the title and
1501 opening pages of a technical paper. The @code{-mm} macros in particular
1502 provide formats for letters and memoranda.
1504 @subsection Multiple Columns
1506 Some macro packages (except @code{-man}) provide the ability to have two
1507 or more columns on a page.
1509 @subsection Font and Size changes
1511 The built-in font and size functions are not always intuitive, so all
1512 macro packages provide macros to make these operations simpler.
1514 @subsection Predefined Strings
1516 Most macro packages provide various predefined strings for a variety of
1517 uses, examples are sub- and superscripts, printable dates, quotes and
1518 various special characters.
1520 @subsection Preprocessor Support
1522 All macro packages provide support for the various preprocessors.
1524 @subsection Configuration and Customization
1526 Some macro packages provide means of customizing many of details of how
1527 the package behaves. This ranges from setting the default type size to
1528 changing the appearance of section headers.
1532 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1533 @chapter Macro Packages
1534 @cindex macro packages
1535 @cindex packages, macros
1537 This chapter documents the main macro packages that come with
1549 @node -man, -mdoc, Macro Packages, Macro Packages
1553 @c XXX documentation
1556 @node -mdoc, -ms, -man, Macro Packages
1558 @cindex @code{-mdoc}
1560 @c XXX documentation
1563 @node -ms, -me, -mdoc, Macro Packages
1567 @c XXX documentation
1570 @node -me, -mm, -ms, Macro Packages
1574 @c XXX documentation
1577 @node -mm, , -me, Macro Packages
1581 @c XXX documentation
1585 @node Programming Tutorial, Preprocessors, Macro Packages, Top
1586 @chapter Programming Tutorial
1587 @cindex programming tutorial
1588 @cindex tutorial for programming
1590 This chapter covers @strong{all} of the facilities of @code{gtroff}. If
1591 you are intending to use a macro package, you probably do not want to
1596 * Input Conventions::
1600 * Embedded Commands::
1602 * Manipulating Filling and Adjusting::
1603 * Manipulating Hyphenation::
1604 * Manipulating Spacing::
1606 * Character Translations::
1613 * Conditionals and Loops::
1616 * Drawing Requests::
1621 * Postprocessor Access::
1624 * Implementation Differences::
1629 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
1633 @code{gtroff} input files contain text with control commands
1634 interspersed throughout. But, even without control codes, @code{gtroff}
1635 will still do several things with your text: filling and adjusting,
1636 adding additional space after sentences, hyphenating and inserting
1637 implicit line breaks.
1640 * Filling and Adjusting::
1644 * Implicit Line Breaks::
1647 @node Filling and Adjusting, Hyphenation, Text, Text
1648 @subsection Filling and Adjusting
1649 @cindex filling and adjusting
1650 @cindex adjusting and filling
1652 When @code{gtroff} reads in text it collects words from input and fits
1653 as many of them together on one output line as it can. This is known as
1656 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
1657 it. Which means it will widen the spacing between words until the text
1658 reaches the right margin (in the default adjustment mode). Extra spaces
1659 between words are preserved, but spaces at the end of lines are ignored.
1660 Spaces at the front of a line will cause a @dfn{break} (breaks will be
1661 explained in @ref{Implicit Line Breaks})
1663 @xref{Manipulating Filling and Adjusting}.
1665 @node Hyphenation, Sentences, Filling and Adjusting, Text
1666 @subsection Hyphenation
1669 Since the odds of finding a set of words, for every output line, which
1670 will fit nicely on a line without inserting excessive amounts of space
1671 between words is not great, @code{gtroff} will hyphenate words so that
1672 lines can be justified without there being too much space between words.
1673 It uses an internal hyphenation algorithm, to indicate which words can
1674 be hyphenated and how to do so. When a word is hyphenated the first
1675 part of the word will be added to the current filled line being output
1676 (with an attached hyphen), and the other portion will be added to the
1677 next line to be filled.
1679 @xref{Manipulating Hyphenation}.
1681 @node Sentences, Tab Stops, Hyphenation, Text
1682 @subsection Sentences
1685 Although it is often debated, some typesetting rules say there should be
1686 different amounts of space after various punctuation marks. For example,
1687 a period at the end of a sentence should have twice as much space
1688 following it as would a comma or a period as part of an abbreviation.
1690 @cindex sentence spaces
1691 @cindex spaces between sentences
1692 @cindex french-spacing
1693 @code{gtroff} does this by flagging certain characters (normally
1694 @samp{!}, @samp{?} and @samp{.}) as @dfn{end of sentence} characters.
1695 When @code{gtroff} encounters one of these characters at the end of a
1696 line it will append two @dfn{sentence spaces} in the formatted output.
1697 (Thus, one of the conventions mentioned in @ref{Input Conventions}).
1699 @c XXX also describe how characters like ) are treated here -jjc
1700 @c gotta do some research on this -trent
1702 @node Tab Stops, Implicit Line Breaks, Sentences, Text
1703 @subsection Tab Stops
1705 @cindex stops, tabulator
1707 @code{gtroff} translates @dfn{tabulator stops}, also called @dfn{tabs},
1708 in the input into movements to the next tab stop. These tab stops are
1709 initially located every half inch across the page. Using this you can
1710 make simple tables. However, this can often be deceptive as the
1711 appearance (and width) of your text on a terminal and the results from
1712 @code{gtroff} can vary greatly.
1714 Also, a possible sticking point is that lines beginning with tab
1715 characters will still be filled, again producing unexpected results.
1716 For example, the following input
1718 @multitable {12345678} {12345678} {12345678} {12345678}
1720 @tab 1 @tab 2 @tab 3
1728 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
1730 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
1733 @xref{Tabs and Fields}.
1735 @node Implicit Line Breaks, , Tab Stops, Text
1736 @subsection Implicit Line Breaks
1737 @cindex implicit line breaks
1738 @cindex implicit breaks of lines
1739 @cindex line, implicit breaks
1741 @cindex break, implicit
1744 An important concept in @code{gtroff} is the @dfn{break}. When a break
1745 occurs, @code{gtroff} will output the partially filled line
1746 (unadjusted), and resume collecting and filling text on the next output
1752 There are several ways to cause a break in @code{gtroff}. A blank line
1753 will not only cause a break, but it will also cause a one line vertical
1754 space (effectively a blank line) to be output.
1756 A line which begins with a space will cause a break and the space will
1757 be output at the beginning of the next line. Note that this space isn't
1758 adjusted, even in fill mode.
1760 The end of file will also cause a break (otherwise the last line of your
1761 document may vanish!)
1763 Certain requests also cause breaks, implicitly or explicity. This will
1766 @xref{Manipulating Filling and Adjusting}.
1769 @node Input Conventions, Measurements, Text, Programming Tutorial
1770 @section Input Conventions
1771 @cindex input conventions
1772 @cindex conventions for input
1774 Since @code{gtroff} does filling automatically, it is traditional in
1775 @code{groff} not to try and type things in as nicely formatted
1776 paragraphs. These are some conventions commonly used when typing
1781 Break lines after punctuation, particularly at the end of sentences,
1782 and in other logical places. Keep separate phrases on lines by
1783 themselves, as entire phrases are often added or deleted when editing.
1785 Try to keep lines less than 40-60@w{ }characters, to allow space for
1786 inserting more text.
1788 Do not try to do any formatting in a WYSIWYG manner (i.e.@: don't try
1789 and use spaces to get proper indentation).
1793 @node Measurements, Expressions, Input Conventions, Programming Tutorial
1794 @section Measurements
1795 @cindex measurements
1797 @cindex units of measurement
1799 @cindex machine units
1800 @cindex measurement units
1801 @code{gtroff} (like any other programs) requires numeric parameters to
1802 specify various measurements. Most numeric parameters@footnote{those
1803 that specify vertical or horizontal motion or a type size} may have a
1804 @dfn{measurement unit} attached. These units are specified as a single
1805 character which immediately follows the number or expression. Each of
1806 these units are understood, by @code{gtroff}, to be a multiple of its
1807 @dfn{basic unit}. So, whenever a different measurement unit is
1808 specified @code{gtroff} converts this into its @dfn{basic units}. This
1809 basic unit, represented by a @samp{u}, is a device dependent measurement
1810 which is quite small, ranging from 1/75th to 1/72000th of an inch; all
1811 other units are converted eventually to basic units. The values may be
1812 given as fractional numbers---nevertheless, fractional basic units are
1813 always rounded to integers.
1815 Some of the measurement units are completely independent of any of the
1816 current settings (e.g.@: type size) of @code{gtroff}.
1821 @cindex @code{i} unit
1822 @cindex unit, @code{i}
1823 Inches. An antiquated measurement unit still in use in certain
1824 backwards countries. One inch is equal to 2.54@dmn{cm}.
1827 @cindex @code{c} unit
1828 @cindex unit, @code{c}
1829 Centimeters. One centimeter is equal to 0.3937@dmn{in}.
1832 @cindex @code{p} unit
1833 @cindex unit, @code{p}
1834 Points. This is a typesetter's measurement used for measure type size.
1835 It is 72@w{ }points to an inch.
1838 @cindex @code{P} unit
1839 @cindex unit, @code{P}
1840 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
1841 12@w{ }points to a pica).
1844 @cindex @code{s} unit
1845 @cindex unit, @code{s}
1846 @cindex @code{z} unit
1847 @cindex unit, @code{z}
1848 @xref{Fractional Type Sizes}, for a discussion of these units.
1851 The other measurements understood by @code{gtroff} are dependent on
1852 settings currently in effect in @code{gtroff}. These are very useful
1853 for specifying measurements which should look proper with any size of
1859 @cindex @code{m} unit
1860 @cindex unit, @code{m}
1861 Ems. This unit is equal to the current font size in points. So called
1862 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
1863 in the current font.
1866 @cindex @code{n} unit
1867 @cindex unit, @code{n}
1868 Ens. This is half of an em.
1870 @cindex vertical space
1871 @cindex space, vertical
1872 @cindex @code{v} unit
1873 @cindex unit, @code{v}
1874 Vertical space. This is equivalent to the current line spacing.
1875 @xref{Sizes}, for more information about this.
1877 @cindex @code{M} unit
1878 @cindex unit, @code{M}
1882 @xref{Fractional Type Sizes}.
1888 @node Default Units, , Measurements, Measurements
1889 @subsection Default Units
1890 @cindex default units
1891 @cindex units, default
1893 Many requests take a default unit. While this can be helpful at times,
1894 it can cause strange errors in some expressions. For example, the line
1895 length request expects em's. Here are several attempts to get a line
1896 length of 3.5@w{ }inches and the results:
1903 7i/2u @result{} 3.5i
1907 As you can see, the safest way to specify measurements is to always
1908 attach a scaling indicator.
1911 @node Expressions, Identifiers, Measurements, Programming Tutorial
1912 @section Expressions
1915 @code{gtroff} has most of operators common to other languages:
1917 @c XXX more details; examples
1921 @cindex arithmetic operators
1922 @cindex operators, arithmetic
1928 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
1929 (division), @samp{*} (multiplication), @samp{%} (modulo).
1931 @cindex comparison operators
1932 @cindex operators, comparison
1939 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
1940 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
1941 (equal), @samp{==} (the same as @samp{=}).
1943 @cindex logical operators
1944 @cindex operators, logical
1947 Logical: @samp{&} (logical and), @samp{:} (logical or).
1949 @cindex unary operators
1950 @cindex operators, unary
1954 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
1955 (just for completeness; does nothing in expressions), @samp{!} (logical
1956 not). See below for the use of unary operators in motion requests.
1957 @c XXX (if/while only??)
1959 @cindex extremum operators
1960 @cindex operators, extremum
1963 Extremum: @samp{>?} (maximum), @samp{<?} (minimum). For example,
1964 @samp{5>?3} yields@w{ }@samp{5}.
1967 @cindex scaling operator
1968 @cindex operator, scaling
1969 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
1970 the default scaling indicator. If @var{c} is missing, ignore scaling
1971 indicators in the evaluation of @var{e}.
1977 Parentheses may be used as in any other language. However, in
1978 @code{gtroff} they are necessary to ensure order of evaluation.
1979 @code{gtroff} has no operator precedence; expressions are evaluated left
1980 to right. This means that @samp{3+5*4} is evaluated as if it were
1981 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may
1987 @cindex motion operators
1988 @cindex operators, motion
1989 For many requests which cause a motion on the page, the unary operators
1990 work differently. The @samp{+} and @samp{-} operators indicate a motion
1991 relative to the current position (down or up, respectively). The
1992 @samp{|} operator indicates an absolute position on the page or input
1995 @samp{+} and @samp{-} are also treated differently by the @code{nr}
1997 @c XXX (?), add xref
1999 @cindex space characters in expressions
2000 @cindex expressions and space characters
2001 Due to the way arguments are parsed, spaces are not allowed in
2002 expressions, unless the entire expression is surrounded by parentheses.
2004 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2007 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
2008 @section Identifiers
2015 Like any other language, @code{gtroff} has rules for properly formed
2016 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
2017 almost any printable character. The exception are the following
2022 Whitespace characters (space, tabs, and newlines).
2024 Backspace (@code{0x08}) and character code @code{0x01}.
2025 @cindex illegal input characters
2026 @cindex input characters, illegal
2027 @cindex characters, illegal input
2029 The following input characters are illegal and will be ignored, causing
2030 a warning message: @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
2031 @code{0x80}-@code{0x9F}.
2034 @samp{\} (backslash),
2035 , and the character codes @code{0x00}@footnote{The null
2036 character is an invalid character which causes a warning message and
2037 will be ignored.} and @code{0x01}. So, for example, any of the
2048 Note that identifiers longer than two characters and containing a
2049 closing bracket (@samp{]}) can't be accessed with escape sequences which
2050 expect an identifier as a parameter.
2054 @deffn Escape \A ident
2055 You can test whether an identifier @var{ident} is valid in @code{gtroff}
2056 with the @code{\A} escape. It expands to the character@w{ }1 or@w{ }0
2057 according to whether its argument (given in quotes) is or is not
2058 acceptable as the name of a string, macro, diversion, number register,
2059 environment, or font. It will return@w{ }0 if no argument is given.
2060 This is useful if you want to look up user input in some sort of
2069 @c XXX add xrefs above
2071 Identifiers in @code{gtroff} can be any length, but, in some contexts,
2072 @code{gtroff} needs to be told where identifiers end and text begins
2073 (and in different ways depending on their length).
2082 Two characters. Must be prefixed with @samp{(} in some situations.
2084 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
2085 and@w{ }@samp{]} in some situations. Any length identifier can be put
2089 Unlike many other programming languages, undefined identifiers are
2090 silently ignored or expanded to nothing.
2092 @c XXX add info about -ww command line option.
2094 @xref{Interpolating Registers}, and @ref{Strings}.
2097 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
2098 @section Embedded Commands
2099 @cindex embedded commands
2100 @cindex commands, embedded
2102 With most documents you need more functionality beyond filling, adjusting
2103 and implicit line breaking. In order to gain further functionality,
2104 @code{gtroff} allows commands to be embedded into your text, in two
2107 The first is a @dfn{request} which takes up an entire line, and does
2108 some large scale operation (e.g.@: break lines, start new pages).
2110 The other is an @dfn{escape} which can be embedded anywhere in your
2111 text, or even as an argument to a request.
2112 @c XXX (Not always?)
2113 Escapes generally do more minor operations like sub- and superscripts,
2114 print a symbol, etc.
2122 @node Requests, Macros, Embedded Commands, Embedded Commands
2123 @subsection Requests
2126 @cindex control character
2127 @cindex character, control
2130 A request line begins with a control character, which is either a single
2131 quote (@samp{'}) or a period (@samp{.}). These can be changed;
2132 @xref{Character Translations}, for details. After this there may be
2133 optional tabs or spaces followed by an identifier which is the name of
2134 the request. This may be followed by any number of space-separated
2137 @cindex zero width space character
2138 @cindex character, zero width space
2139 @cindex space character, zero width
2141 If you want to begin a line with a control character without it being
2142 interpreted, precede it with @code{\&}. This represents a zero width
2143 space, which means it will not affect your output.
2145 In most cases you will use the period as a control character. Several
2146 requests will cause a break; using the single quote control character
2150 * Request Arguments::
2153 @node Request Arguments, , Requests, Requests
2154 @subsubsection Request Arguments
2155 @cindex request arguments
2156 @cindex arguments to requests
2158 Arguments to requests (and macros) are processed much like the shell:
2159 The line is split into arguments according to spaces. An argument which
2160 is intended to contain spaces can either be enclosed in quotes (single
2161 or double), or have the spaces @dfn{escaped} with backslashes.
2164 .uh The Mouse Problem
2165 .uh "The Mouse Problem"
2166 .uh The\ Mouse\ Problem
2170 The first line is the @code{uh} macro being called with 3 arguments,
2171 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
2172 same effect or calling the @code{uh} macro with one argument @samp{The
2176 Note, however, that the @code{ds} request works differently.
2177 @xref{Strings}, for more details.
2179 @node Macros, Escapes, Requests, Embedded Commands
2183 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
2184 which can be invoked by name. They are called in the same manner as
2185 requests---arguments also may be passed in the same manner.
2187 @xref{Writing Macros}, and @ref{Request Arguments}.
2189 @node Escapes, , Macros, Embedded Commands
2193 Escapes may occur anywhere in the input to @code{gtroff}. They begin
2194 with a backslash usually and are followed by a single character which
2195 indicates the function to be performed. The escape character can be
2196 changed; @xref{Character Translations}.
2201 Escape sequences which require an identifier as a parameter accept three
2202 possibilities of syntax.
2206 The next single character is the identifier.
2208 If this single character is an opening parenthesis, take the following
2209 two characters as the identifier. Note that there is no closing
2210 parenthesis after the identifier.
2212 If this single character is an opening bracket, take all characters
2213 until a closing bracket as the identifier.
2226 @cindex argument delimiting characters
2227 @cindex characters, argument delimiting
2228 @cindex delimiting characters for arguments
2229 Other escapes may require several arguments and/or some special format.
2230 In such cases the argument is traditionally enclosed in single quotes
2231 (and quotes are always used in this manual for the definitions of the
2232 escape sequences). The enclosed text is then processed according to
2233 what that escape expects. Example:
2242 Note that the quote character can be replaced with any other character
2243 which does not occur in the argument (even a newline or a space
2244 character) in the following escapes: @samp{\o}, @samp{\b}, and
2245 @samp{\X}. This makes e.g.
2254 @result{} A caf@'e in Paris
2258 possible, but it is better to avoid this feature to avoid confusion.
2288 The following escapes sequences (which are handled similar to characters
2289 since they don't take a parameter) are also allowed as delimiters:
2290 @samp{\%}, @samp{\ }, @samp{\|}, @samp{\^}, @samp{\@{}, @samp{\@}},
2291 @samp{\'}, @samp{\`}, @samp{\-}, @samp{\_}, @samp{\!}, @samp{\?},
2292 @samp{\@@}, @samp{\)}, @samp{\/}, @samp{\,}, @samp{\&}, @samp{\~},
2293 @samp{\0}, @samp{\a}, @samp{\c}, @samp{\d}, @samp{\e}, @samp{\E},
2294 @samp{\p}, @samp{\r}, @samp{\t}, and @samp{\u}. Again, don't use these
2301 No newline characters as delimiters are allowed in the following
2302 escapes: @samp{\A}, @samp{\Z}, @samp{\C}, and @samp{\w}.
2315 Finally, the escapes @samp{\D}, @samp{\h}, @samp{\H}, @samp{\l},
2316 @samp{\L}, @samp{\N}, @samp{\R}, @samp{\s}, @samp{\S}, @samp{\v}, and
2317 @samp{\x} can't use the following characters as delimiters:
2323 The digits @samp{0}-@samp{9}.
2339 The operators @samp{+-/*%<>=&:().}.
2341 @cindex space character
2342 @cindex character, space
2343 @cindex tab character
2344 @cindex character, tab
2345 @cindex newline character
2346 @cindex character, newline
2347 The space, tab, and newline characters.
2362 All escape sequences except @samp{\%}, @samp{\@{}, @samp{\@}},
2363 @samp{\'}, @samp{\`}, @samp{\-}, @samp{\_}, @samp{\!}, @samp{\@@},
2364 @samp{\/}, @samp{\c}, @samp{\e}, and @samp{\p}.
2370 If you want to have a backslash appear in your output, you can use
2371 several escapes: @code{\\}, @code{\e} or @code{\E}. These are very
2372 similar, and only differ with respect to being used in macros or
2373 diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for more
2382 @node Comments, , Escapes, Escapes
2383 @subsubsection Comments
2387 Probably one of the most@footnote{Unfortunately, this is a lie. But
2388 hopefully future @code{gtroff} hackers will believe it :-)} common forms
2389 of escapes is the comment. They begin with the @code{\"} escape and end
2390 at the end of the input line.
2392 This may sound simple, but it can be tricky to keep the comments from
2393 interfering with the appearance of your final output.
2396 If the escape is to the right of some text or a request, that portion of
2397 the line will be ignored, but the space leading up to it will be noticed
2398 by @code{gtroff}. This only affects the @code{.ds} request.
2399 @c XXX (any others?)
2401 One possibly irritating idiosyncracy is that you must not use tabs to
2402 line up your comments. Tabs are not treated as white space between the
2403 request and macro arguments.
2405 @cindex undefined request
2406 @cindex request, undefined
2407 If you have a comment on a line by itself, it will be treated as a blank
2408 line, because after eliminating the comment, that is all that remains.
2409 So, it is common to start the line with @code{.\"} which will cause the
2410 line to be treated as an undefined request.
2412 Another commenting scheme seen sometimes is three consecutive single
2413 quotes (@code{'''}) at the beginning of a line. This works, but
2414 @code{gtroff} will give a warning about an undefined macro, which is
2415 harmless, but irritating.
2418 Now to avoid all this @code{gtroff} has a new comment mechanism using
2419 the @code{\#} escape. This escape works the same as @code{\"} except
2420 that the newline is also ignored.
2423 For large blocks of text, the @code{ig} request may be useful.
2427 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
2431 Numeric variables in @code{gtroff} are called @dfn{registers}. There
2432 are a number of built-in registers, supplying anything from the date to
2433 details of formatting parameters.
2438 * Setting Registers::
2439 * Interpolating Registers::
2441 * Assigning Formats::
2442 * Built-in Registers::
2445 @node Setting Registers, Interpolating Registers, Registers, Registers
2446 @subsection Setting Registers
2447 @cindex setting registers
2448 @cindex registers, setting
2452 Registers are defined resp.@: set via the @code{nr} request or the
2453 @code{\R} escape. For example, the following two lines are equivalent:
2461 The @code{rr} request will remove the register specified by the
2465 The @code{rnn} request will rename a number register. The format is
2466 @w{@samp{.rnn @var{x} @var{y}}}, which will rename number register
2470 Aliases can be created for a number register. The format is
2471 @w{@samp{.aln @var{xx} @var{yy}}}, which will create an alias @var{xx}
2472 for number register object named @var{yy}. The new name and the old
2473 name will be exactly equivalent. If @var{yy} is undefined, a warning of
2474 type @samp{reg} will be generated, and the request will be ignored.
2475 @xref{Debugging}, for information about warnings.
2477 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
2478 @subsection Interpolating Registers
2479 @cindex interpolating registers
2480 @cindex registers, interpolating
2483 Numeric registers are @dfn{interpolated} via the @code{\n} escape.
2485 @c XXX the following is wrong. Should I say any more than the above??
2486 @c This means that the value of the number register is expanded in-place
2487 @c on the input line before any other actions, i.e. before requests and
2488 @c escapes are interpreted.
2495 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
2496 @subsection Auto-increment
2497 @cindex auto-increment
2498 @cindex increment, automatic
2501 Number registers can also be auto-incremented and auto-decremented. You
2502 can specify the increment resp.@: decrement factor with a third argument
2503 to the @code{nr} request. The default value is@w{ }0. For example,
2508 \n+a, \n+a, \n+a, \n+a, \n+a
2510 \n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx
2521 If you want to change the increment factor without changing the value of
2522 a register, the following can be used.
2528 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
2529 @subsection Assigning Formats
2530 @cindex assigning formats
2531 @cindex formats, assigning
2534 When a register is used in the text of an input file (as opposed to part
2535 of an expression) it is textually replaced (or interpolated) with a
2536 representation of that number. This output format can be changed to a
2537 variety of formats (numbers, Roman numerals, etc). This is done using
2538 the @code{af} request. The first argument to @code{af} is the name of
2539 the number register to be changed, and the second argument is the output
2540 format. The following output formats are available:
2544 This is the default format, decimal numbers: 1, 2, 3,@w{ }@dots{}
2546 Decimal numbers with as many leading zeros as specified. So, @samp{001}
2547 would result in 001, 002, 003,@w{ }@dots{}
2549 @cindex roman numerals
2550 @cindex numerals, Roman
2551 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@dots{}
2553 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@dots{}
2555 Upper-case letters: A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@dots{}
2557 Lower-case letters: a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@dots{}
2560 The following example will produce @samp{10, X, j, 010}:
2564 .af a 1 \" the default format
2575 The @code{\g} escape returns the current format of the specified
2576 register. For example, @samp{\ga} after the previous example would
2579 @node Built-in Registers, , Assigning Formats, Registers
2580 @subsection Built-in Registers
2581 @cindex built-in registers
2582 @cindex registers, built-in
2584 The following lists some built-in registers which are not described
2585 elsewhere in this manual. Any register which begin with a @samp{.} is
2586 read-only. A complete listing of all built-in registers can be found in
2587 @ref{Register Index}.
2592 Horizontal resolution in basic units.
2595 Vertical resolution in basic units.
2598 Day of the week (1-7).
2601 Day of the year (1-31).
2604 Current month (1-12).
2610 The year minus@w{ }1900. Unfortunately, the @sc{Unix} Version@w{ }7
2611 troff documentation had a year@w{ }2000 bug: It incorrectly claimed that
2612 @samp{\n(yr} was the last two digits of the year. That claim has never
2613 been true of either traditional @code{troff} or GNU @code{troff}. If
2614 you see old @code{troff} input that looks like this:
2617 '\" The following line stopped working after 1999
2618 This document was formatted in 19\n(yr.
2622 you can correct it as follows:
2625 This document was formatted in \n[year].
2629 or, if you want to be portable to older @code{troff} versions, as
2634 This document was formatted in \n(y4.
2641 The current @emph{input} line number.
2644 The current @emph{output} line number.
2647 The major version number. For example, if the version number is@w{
2648 }1.03 then @code{.x} will contain@w{ }@samp{1}.
2651 The minor version number. For example, if the version number is@w{
2652 }1.03 then @code{.y} will contain@w{ }@samp{03}.
2655 The revision number of @code{groff}.
2658 Always@w{ }1. Macros should use this to determine whether they are
2659 running under GNU @code{troff}.
2662 If the current output device is @sc{ascii}, this is set to@w{ }1, zero
2666 This register indicates whether the current page is actually being
2667 printed, i.e., whether the @samp{-o} option is being used to only print
2668 selected pages. @xref{Options}, for more information.
2672 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
2673 @section Manipulating Filling and Adjusting
2674 @cindex manipulating filling and adjusting
2675 @cindex filling and adjusting, manipulating
2676 @cindex adjusting and filling, manipulating
2677 @cindex justifying text
2678 @cindex text, justifying
2683 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
2684 Breaks}. The @code{br} request will likewise cause a break. Several
2685 other requests will also cause breaks, but implicitly. They are
2686 @code{bp}, @code{ce}, @code{fi}, @code{fl}, @code{in}, @code{nf},
2687 @code{sp}, and @code{ti}.
2692 Initially, @code{gtroff} will fill and adjust text to both margins.
2693 Filling can be disabled via the @code{nf} request and re-enabled with
2694 the @code{fi} request. These implicitly disable and re-enable
2695 adjusting. Both of these will cause a break in the text currently being
2696 filled. The number register @code{.u} is equal to@w{ }1 in fill mode
2697 and@w{ }0 in no-fill mode.
2701 Adjusting can be disabled with the @code{ad} request and re-enabled with
2702 the @code{na} request. The @code{ad} request takes a single argument to
2703 indicate how to adjust text.
2707 @cindex ragged-right
2708 Adjust text to the left margin. This produces what is traditionally
2709 called ragged-right text.
2712 Adjust text to the right margin, producing ragged-left text.
2714 @cindex centered text
2716 @c XXX difference to .ce?
2719 Justify to both margins. This is default of @code{gtroff}.
2722 With no argument to @code{ad}, @code{gtroff} will adjust lines the same
2723 way it was the last time it was filling. For example:
2733 .ad \" back to centering
2738 The current adjustment mode is available in the number register
2742 The escape @code{\p} will cause a break and the remaining text to be
2745 @cindex word space size
2746 @cindex size of word space
2747 @cindex space between words
2748 @cindex sentence space size
2749 @cindex size of sentence space
2750 @cindex space between sentences
2752 The @code{ss} request allows you to change the minimum size of a space
2753 between filled words. This request takes its units as one twelfth of
2754 the space width parameter for the current font. Initially both the word
2755 space size and the sentence space size are@w{ }12.
2757 If two arguments are given to the @code{ss} request, the second argument
2758 gives the sentence space size. If the second argument is not given, the
2759 sentence space size will be the same as the word space size. The
2760 sentence space size is used in two circumstances: If the end of a
2761 sentence occurs at the end of a line in fill mode, then both an
2762 inter-word space and a sentence space will be added; if two spaces
2763 follow the end of a sentence in the middle of a line, then the second
2764 space will be a sentence space. Note that the behaviour of @sc{Unix}
2765 @code{troff} will be exactly that exhibited by GNU @code{troff} if a
2766 second argument is never given to the @code{ss} request. In GNU
2767 @code{troff}, as in @sc{Unix} @code{troff}, you should always follow a
2768 sentence with either a newline or two spaces.
2772 The number registers @code{.ss} and @code{.sss} are the values of the
2773 parameters set by the first and second arguments of the @code{ss}
2777 @cindex centering lines
2778 @cindex lines, centering
2779 The @code{ce} request will center text. While the @w{@samp{ad c}}
2780 request will also center text, it has the side effect of filling the
2781 text. The @code{.ce} request will not fill the text it affects. This
2782 request causes a break.
2784 With no arguments, @code{ce} will fill the next line of text. The
2785 single argument @code{ce} takes is a number indicating the number of
2786 lines to be centered. If the argument is zero, centering is disabled.
2788 A common idiom is to turn on centering for a large number of lines, and
2789 then turn off centering when you are done with the centered text. This
2790 is useful for any request which takes a number of lines as an argument.
2803 The @code{.ce} number register contains the number of lines remaining to
2804 be centered, as set by the @code{ce} request.
2806 @cindex justifying text
2807 @cindex text, justifying
2808 @cindex right-justifying
2811 A similar request is @code{rj} request which will justify unfilled text
2812 to the right margin. Its arguments are identical to the @code{ce}
2813 request. The @code{.rj} number register is the number of lines to be
2814 right-justified as set by the @code{rj} request.
2817 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
2818 @section Manipulating Hyphenation
2819 @cindex manipulating hyphenation
2820 @cindex hyphenation, manipulating
2822 As discussed in @ref{Hyphenation}, @code{gtroff} will hyphenate words.
2823 There are a number of ways to influence how hyphenation is done.
2828 Hyphenation can be turned off with the @code{nh} request, and turned
2829 back on with the @code{hy} request. However, the hyphenation facilities
2830 of @code{gtroff} are far more flexible than this. The @code{hy} request
2831 can be used to tell @code{gtroff} to restrict hyphenation to certain
2832 cases. The request takes a single numeric argument. The current
2833 hyphenation restrictions can be found in the number register @code{.hy}.
2837 The default argument, which indicates to hyphenate without restrictions.
2839 Do not hyphenate the last word on a page or column.
2841 Do not hyphenate the last two characters of a word.
2843 Do not hyphenate the first two characters of a word.
2846 The values in the previous table are additive. For example, the
2847 value@w{ }12 causes @code{gtroff} to neither hyphenate the last two nor
2848 the first two characters of a word.
2854 @cindex explicit hyphens
2855 @cindex hyphen, explicit
2856 The @code{hlm} request will set the maximum number of consecutive
2857 hyphenated lines to the value given as the first argument. If this
2858 number is negative, there is no maximum. The default value is@w{ }-1.
2859 This value is associated with the current environment. Only lines
2860 output from an environment count towards the maximum associated with
2861 that environment. Hyphens resulting from @code{\%} are counted;
2862 explicit hyphens are not. The current setting of this is available in
2863 the @code{.hlm} register. Also the number of immediately preceding
2864 consecutive hyphenated lines are available in the number register
2868 The @code{hw} request allows you to specify how a specific word is to be
2869 hyphenated. It takes only one argument which is the word with hyphens
2870 at the hyphenation points. For example:
2877 This request can be used more than once.
2880 @c In old versions of troff there was a
2881 @c limited amount of space to store such information, fortunately,
2882 @c with groff, this is no longer a restriction.
2885 @cindex hyphenation character
2886 @cindex character, hyphenation
2887 @cindex disabling hyphenation
2888 @cindex hyphenation, disabling
2889 You can also tell @code{gtroff} how to hyphenate words on the fly with
2890 the use of the @code{\%} escape, also known as the @dfn{hyphenation
2891 character}. Preceding a word with this character will prevent it from
2892 being hyphenated, putting it in a word will indicate to @code{gtroff}
2893 that the word may be hyphenated at that point. Note that this mechanism
2894 will only affect one word; if you want to change the hyphenation of a
2895 word for the entire document, use the @code{hw} request.
2898 The @code{hc} request allows you to change the hyphenation character.
2899 The character specified as an argument will then work the same as the
2900 @code{\%} escape, and, thus, no longer appear in the output. Without
2901 an argument it will return the hyphenation character to @code{\%}.
2903 @cindex hyphenation patterns
2904 @cindex pattern for hyphenation
2906 To further customize hyphenation the @code{hpf} request will read in a
2907 file of hyphenation patterns. This file will be searched for in the
2908 same way that @file{tmac.@var{name}} is searched for when the
2909 @samp{-m@var{name}} option is specified.
2911 It should have the same format as the argument to the @code{\patterns}
2912 primitive in @TeX{}; the letters appearing in this file are interpreted
2913 as hyphenation codes. A @samp{%} character in the patterns file
2914 introduces a comment that continues to the end of the line.
2920 The set of hyphenation patterns is associated with the current language
2921 set by the @code{hla} request. The @code{hpf} request is usually
2922 invoked by the @file{troffrc} or @file{troffrc-end} file.
2925 The @code{hcode} request has the following syntax:
2928 .hcode @var{c1 code1 c2 code2...}
2931 It sets the hyphenation code of character @var{c1} to @var{code1} and
2932 that of @var{c2} to @var{code2}. A hyphenation code must be a single
2933 input character (not a special character) other than a digit or a space.
2934 Initially each lower-case letter has a hyphenation code, which is
2935 itself, and each upper-case letter has a hyphenation code which is the
2936 lower-case version of itself.
2938 @cindex hyphenation margin
2939 @cindex margin for hyphenation
2942 The @code{hym} request will set the hyphenation margin to the value
2943 given as its argument: when the current adjustment mode is not@w{
2944 }@samp{b}, the line will not be hyphenated if the line is no more than
2945 that amount short. The default hyphenation margin is@w{ }0. The
2946 default scaling indicator for this request is@w{ }m. The hyphenation
2947 margin is associated with the current environment. The current
2948 hyphenation margin is available in the @code{.hym} register.
2950 @cindex hyphenation space
2953 The @code{hys} request sets the hyphenation space to the value given as
2954 the first argument: when the current adjustment mode is@w{ }@samp{b},
2955 don't hyphenate the line if the line can be justified by adding no more
2956 than that amount of extra space to each word space. The default
2957 hyphenation space is@w{ }0. The default scaling indicator for this
2958 request is@w{ }m. The hyphenation space is associated with the current
2959 environment. The current hyphenation space is available in the
2960 @code{.hys} register.
2962 @cindex soft hyphen character
2963 @cindex character, soft hyphen
2965 The @code{shc} request will set the soft hyphen character to the
2966 character given as an argument. If the argument is omitted, the soft
2967 hyphen character will be set to the default character @code{\(hy}. The
2968 soft hyphen character is the character which will be inserted when a
2969 word is hyphenated at a line break. If the soft hyphen character does
2970 not exist in the font of the character immediately preceding a potential
2971 break point, then the line will not be broken at that point. Neither
2972 definitions (specified with the @code{char} request) nor translations
2973 (specified with the @code{tr} request) are considered when finding the
2974 soft hyphen character.
2982 The @code{hla} request will set the current hyphenation language to that
2983 given by the first argument. Hyphenation exceptions specified with the
2984 @code{hw} request and hyphenation patterns specified with the @code{hpf}
2985 request are both associated with the current hyphenation language. The
2986 @code{hla} request is usually invoked by the @file{troffrc} or the
2987 @file{troffrc-end} files. The current hyphenation language is available
2988 in the number register @code{.hla}.
2991 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
2992 @section Manipulating Spacing
2993 @cindex manipulating spacing
2994 @cindex spacing, manipulating
2997 The @code{sp} request will cause @code{gtroff} to space downwards the
2998 distance specified as the first argument. With no argument it will
2999 advance 1@w{ }line. A negative argument will cause @code{gtroff} to
3000 move up the page the specified distance. If the argument is preceded by
3001 a @samp{|} @code{gtroff} will move that distance from the top of the
3004 @cindex double-spacing
3007 Often you may want your output to be double or triple spaced. The
3008 @code{ls} request will cause @code{troff} to output @var{n}-1 blank
3009 lines after each line of text, where @var{n} is the argument given to
3010 the @code{ls} request. With no argument @code{gtroff} will go back to
3011 single spacing. The number register @code{.L} contains the current line
3016 Sometimes, extra vertical spacing is only needed occasionally, i.e.@: to
3017 allow space for a tall construct (like an equation). The @code{\x}
3018 escape will do this. The escape is given a numerical argument (like
3019 @samp{\x'3p'}). If this number is positive extra vertical space will be
3020 inserted below the current line. A negative number will add space
3021 above. If this escape is used multiple times on the same line, the
3022 maximum of the values is used. The @code{.a} number register contains
3023 the most recent (nonnegative) extra vertical line space.
3027 ... example of inline equation ...
3032 @cindex no-space mode
3033 @cindex mode, no-space
3034 Spacing (either via @code{sp} or via blank lines) can be disabled with
3035 the @code{ns} request. This will enable @dfn{no-space mode}. This mode
3036 will end when actual text is output or the @code{rs} request is
3037 encountered. No-space mode will also prevent requests to advance to the
3038 next page unless they are accompanied by a page number (@pxref{Page
3039 Control}, for more information).
3042 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
3043 @section Tabs and Fields
3044 @cindex tabs and fields
3045 @cindex fields and tabs
3048 Tab stops are much like those on a typewriter: a tab character (or the
3049 @code{\t} escape) on input will cause horizontal motion to the next tab
3053 Tab stops can be changed with the @code{ta} request. This request takes
3054 a series of numbers as arguments which indicate where each tab stop is
3055 to be (overriding any previous settings). These can be specified
3056 absolutely, i.e.@: as the distance from the left margin. For example,
3057 the following will set tab stops every one inch.
3060 .ta 1i 2i 3i 4i 5i 6i
3063 Tab stops can also be specified relatively (using a leading @samp{+})
3064 which means that the specified tab stop will be set that distance from
3065 the previous tab stop. For example, the following is equivalent to the
3069 .ta 1i +1i +1i +1i +1i +1i
3072 After the specified tab stops repeat values may be set for tabs beyond
3073 the last one specified. This is most commonly used to specify tabs set
3074 at equal intervals. The complete syntax for setting tabs is
3077 ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2} @dots{} @var{rn}
3081 This will set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn}
3082 and then set tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{},
3083 @var{nn}+@var{rn} and then at @var{nn}+@var{rn}+@var{r1},
3084 @var{nn}+@var{rn}+@var{r2}, @dots{}, @var{nn}+@var{rn}+@var{rn}, and so
3085 on. For example the following is, yet again, the same as the previous
3092 The material in each tab column may be justified to the right or left
3093 or centered in the column. This is specified by appending an
3094 @samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop.
3095 The default justification is @samp{L}. Example:
3102 The number register @code{.tabs} contains a string representation of the
3103 current tab settings suitable for use as an argument to the @code{ta}
3107 Normally @code{gtroff} will fill the space to the next tab stop with
3108 spaces. In some cases you may wish to change this. The @code{tc}
3109 request will do this. With no argument @code{gtroff} will revert to
3116 Sometimes you may wish to use the @code{tc} request to fill a tab stop
3117 with a given character, but also, you want to use normal tab stops on
3118 the rest of the line. For this @code{gtroff} provides an alternate tab
3119 mechanism, called @dfn{leaders} which will do just that. They are used
3120 exclusively to produce a repeated run of characters to the next tab
3123 You can declare what character will be repeated with the @code{lc}
3124 request. If you do not give it an argument, the leaders will act the
3128 Leader are invoked by using the @code{\a} escape while specifying the
3131 @cindex table of contents
3132 @cindex contents, table of
3133 Thus for a table of contents you may want to have tab stops defined so
3134 that the section number is one tab stop, the title is the second with
3135 the remaining space being filled with a line of dots and then the page
3136 number slightly separated from the dots.
3148 Fields are a more general way of laying out tabular data.
3152 @c XXX add explanation
3154 @node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial
3155 @section Character Translations
3156 @cindex character translations
3157 @cindex translations of characters
3163 The control character (@samp{.}) and the no-break control character
3164 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
3165 respectively. The single argument is the new character to be used.
3166 With no argument the normal control character is restored.
3170 The @code{eo} request will completely disable the escape mechanism. The
3171 @code{ec} request can be used to change the escape character from the
3172 default @samp{\} to what is specified as an argument. It can be also
3173 used to re-enable the escape mechanism after an @code{eo} request.
3176 The @code{tr} request will translate characters.
3182 @code{trnt} is the same as the @code{tr} request except that the
3183 translations do not apply to text that is transparently throughput into
3184 a diversion with @code{\!}. @xref{Diversions}, for more information.
3196 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it will
3200 @node Line Layout, Page Layout, Character Translations, Programming Tutorial
3201 @section Line Layout
3203 @cindex layout, line
3205 @cindex dimensions, line
3206 @cindex line dimensions
3207 The following drawing shows the dimensions which @code{gtroff} uses for
3208 placing a line of output onto the page. They are labeled with the
3209 request which manipulates that dimension.
3214 -->| po |<-----------ll------------>|
3215 +----+----+----------------------+----+
3217 +----+----+----------------------+----+
3222 These dimensions are:
3227 @cindex margin, left
3229 @cindex offset, page
3231 @dfn{Page offset}--This is the leftmost position of text on the final
3232 output, defining the @dfn{left margin}. It can be adjusted with the
3233 @code{po} request, and the current setting can be found in the built-in
3234 number register @code{.o}. Note that this request does not cause a
3235 break, so changing the page offset in the middle of text being filled
3236 may not do what you expect.
3239 @cindex line indentation
3241 @dfn{Indentation}--This is the distance from the left margin where text
3242 will be printed. This can be adjusted with the @code{in} request, and
3243 the current setting can be found in the built-in number register.
3244 @code{.i}. This request causes a break.
3248 There is also the request @code{ti} which will cause one output line to
3249 be indented, after which the indentation returns to@w{ }0. This request
3250 causes a break. The number register @code{.in} is the indent that
3251 applies to the current output line.
3254 @cindex length of line
3257 @dfn{Line length}--This is the distance from the left margin to right
3258 margin. This can be adjusted with the @code{ll} request, and the
3259 current setting can be found in the built-in number register @code{.l}
3260 Note, as the figure implies, line length is not affected by the current
3261 indentation. The number register @code{.ll} is the line length that
3262 applies to the current output line.
3268 A bunch of really boring text which should
3269 be indented from both margins.
3270 Replace me with a better (and more) example!
3276 @node Page Layout, Page Control, Line Layout, Programming Tutorial
3277 @section Page Layout
3279 @cindex layout, page
3281 @code{gtroff} provides some very primitive operations for controlling
3285 @cindex length of page
3288 Troff lets you specify the @dfn{page length} via the @code{pl} request.
3289 This is the length of the physical output page. The current setting can
3290 be found in the built-in number register @code{.p}. Note that this only
3291 specifies the size of the page, not the top and bottom margins. Those
3292 are not done by groff directly. @xref{Traps}, for further information
3298 Troff provides several operations which help in setting up top and
3299 bottom titles (or headers and footers)
3302 @cindex three-part title
3305 The @code{tl} request will print a @dfn{title line}, which consists of
3306 three parts: a left justified portion, a centered portion and a right
3307 justified portion. The argument to @code{tl} is specified as
3308 @code{'@var{left}'@var{center}'@var{right}'}. The @samp{%} character is
3309 replaced with the current page number. You can change this character
3310 with the @code{pc} request (see below).
3312 @cindex length of title line
3313 @cindex title line, length
3316 The title line is printed using its own line length, which is specified
3317 with the @code{lt} request. The current setting of this is available in
3318 the @code{.lt} number register.
3321 @cindex number, page
3323 The @code{pn} request will change the page number of the @emph{next}
3324 page. The only argument is the page number.
3328 The current page number is stored in the number register @code{%}. The
3329 number register @code{.pn} contains the number of the next page: either
3330 the value set by a @code{pn} request, or the number of the current page
3333 @cindex changing the page number character
3334 @cindex page number character, changing
3336 The @code{pc} request will change the page number character (used by the
3337 @code{tl} request) to a different character. With no argument, this
3338 mechanism is disabled.
3343 @node Page Control, Fonts, Page Layout, Programming Tutorial
3344 @section Page Control
3345 @cindex page control
3346 @cindex control, page
3350 To stop processing the current page, and move to the next page, you can
3351 invoke the @code{bp} request. This request will also cause a break. It
3352 can also take an argument of what the next page should be numbered. The
3353 only difference between @code{bp} and @code{pn} is that @code{pn} does
3354 not cause a break or actually eject a page.
3360 .tl 'left top'center top'right top'
3367 Often you may want to make sure that you have a certain amount of space
3368 before a new page occurs. This is most useful to make sure that there
3369 is not a single @dfn{orphan} line left at the bottom of a page. The
3370 @code{ne} request will ensure that there is a certain distance,
3371 specified by the first argument, before the next page is triggered
3372 (@pxref{Traps}, for further information). The default unit for
3373 @code{ne} is @code{v} and the default argument is@w{ }1@dmn{v}.
3375 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
3376 you can do the following before each paragraph:
3387 @code{sv} is similar to the @code{ne} request; it reserves the specified
3388 amount of vertical space. If the desired amount of space exists before
3389 the next trap (bottom page boundary), the space will be output
3390 immediately. If there is not enough space, it is stored for later
3391 output via the @code{os} request. The default argument is@w{ }1@dmn{v}
3392 and the default unit is @code{v}.
3395 @node Fonts, Sizes, Page Control, Programming Tutorial
3401 @code{gtroff} gives you the ability to switch fonts at any point in your
3402 text. There are two ways to do this, via the @code{ft} request and the
3405 Fonts are generally specified as upper-case strings, which are usually
3406 1@w{ }to 4 characters representing an abbreviation or acronym of the font
3409 The basic set of fonts are @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
3410 These are Times Roman, Italic, Bold, and Bold Italic. There is also at
3411 least one symbol font which contains various special symbols (Greek,
3412 mathematics). Such symbols fonts cannot be used directly, but should be
3420 * Artificial Fonts::
3421 * Ligatures and Kerning::
3424 @node Changing Fonts, Font Families, Fonts, Fonts
3425 @subsection Changing Fonts
3426 @cindex changing fonts
3427 @cindex fonts, changing
3430 @cindex previous font
3431 @cindex font, previous
3432 You can change fonts with both the @code{ft} request. With no arguments
3433 it will switch to the previous font (also known as @samp{P}).
3444 The @code{\f} escape is useful for changing fonts in the middle of
3448 eggs, bacon, \fBspam\fP and sausage.
3452 Both of the above examples will produce the same output. Note the usage
3453 of @samp{P} to indicate the previous font---using @code{\f} it is not
3454 possible to omit this parameter.
3456 Sometimes when putting letters of different fonts, you need more or less
3457 space at such boundaries. There are two escapes to help with this.
3460 @cindex italic correction
3461 @cindex correction, italic
3462 The @code{\/} escape increases the width of the preceding character so
3463 that the spacing between that character and the following character will
3464 be correct if the following character is a Roman character. For
3465 example, if an italic@w{ }f is immediately followed by a Roman right
3466 parenthesis, then in many fonts the top right portion of the f will
3467 overlap the top left of the right parenthesis. It is a good idea to use
3468 this escape sequence whenever an italic character is immediately
3469 followed by a Roman character without any intervening space. This small
3470 amount of space is also called @dfn{italic correction}.
3473 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids
3477 @cindex left italic correction
3478 @cindex correction, left italic
3479 The @code{\,} escape modifies the spacing of the following character so
3480 that the spacing between that character and the preceding character will
3481 be correct if the preceding character is a Roman character. It is a
3482 good idea to use this escape sequence whenever a Roman character is
3483 immediately followed by an italic character without any intervening
3484 space. In analogy to above, this space could be called @dfn{left italic
3485 correction}, but this term isn't used widely.
3488 @c For example, inserting \, between the parenthesis and the f changes
3502 The @code{ftr} request will translate fonts; its syntax is
3505 .ftr @var{F} @var{G}
3509 which translates font@w{ }@var{F} to font@w{ }@var{G}. Whenever a font
3510 named @var{F} is referred to in a @code{\f} escape sequence, or in the
3511 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
3512 @code{fspecial}, @code{fp}, or @code{code} requests, font@w{ }@var{G} will
3513 be used. If @var{G} is missing, or equal to @var{F} then font@w{
3514 }@var{F} will not be translated.
3516 @node Font Families, Font Positions, Changing Fonts, Fonts
3517 @subsection Font Families
3518 @cindex font families
3519 @cindex families, font
3521 Due to the variety of fonts available, @code{gtroff} has added the
3522 concept of font families. Each of these families has four styles
3523 (@samp{R}, @samp{I}, @samp{B} and @samp{BI}).
3525 The fonts are specified as the concatenation of the font family and
3526 style. Specifying a font without the family part will cause
3527 @code{gtroff} to use that style of the current family. By default,
3528 @code{gtroff} uses the Times family.
3530 This way, you can just use the basic four fonts and select a different
3531 font family on the command line.
3535 You can also switch font families with the @code{fam} request. The
3536 current font family is available in the number register @code{.fam}.
3537 This is a string-valued register.
3553 @node Font Positions, Using Symbols, Font Families, Fonts
3554 @subsection Font Positions
3555 @cindex font positions
3556 @cindex positions, font
3558 For the sake of old phototypesetters and compatability with old versions
3559 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
3560 on which various fonts are mounted. The last one or two are reserved
3561 for the symbol font(s).
3564 New fonts can be mounted with the @code{fp} request. These numeric
3565 positions can then be referred to with font changing commands. When
3566 @code{gtroff} starts it is using font number one.
3582 Note that after these font changes have taken place the original font
3586 The current font in use, as a font position, is available in number
3587 register @code{.f}. This can be useful to remember the current font,
3592 ... lots 'o text ...
3597 The number of the next free font position is available in the number
3598 register @code{.fp}. This is useful when mounting a new font, like so:
3601 .fp \n[.fp] NEATOFONT
3605 Fonts not listed in the @file{DESC} file are automatically mounted on
3606 the next available font position when they are referenced. If a font is
3607 to be mounted explicitly with the @code{fp} request on an unused font
3608 position, it should be mounted on the first unused font position, which
3609 can be found in the @code{.fp} register. Although @code{gtroff} does
3610 not enforce this strictly, it will not allow a font to be mounted at a
3611 position whose number is much greater than that of any currently used
3615 The @code{fp} request has an optional third argument. This argument
3616 gives the external name of the font, which is used for finding the font
3617 description file. The second argument gives the internal name of the
3618 font which is used to refer to the font in @code{gtroff} after it has
3619 been mounted. If there is no third argument then the internal name will
3620 be used as the external name. This feature allows you to use fonts with
3621 long names in compatibility mode.
3623 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
3624 @subsection Using Symbols
3625 @cindex using symbols
3626 @cindex symbols, using
3630 Symbols can be inserted by using a special escape sequence. This escape
3631 is simply the escape character (usually a backslash) followed by an
3632 identifier. The symbol identifiers have to be two or more characters,
3633 since single characters conflict with all the other escapes. The
3634 identifier can be either preceded by a parenthesis if it is two
3635 characters long, or surrounded by square brackets. So, the symbol for
3636 the mathematical Greek letter `pi' can be produced either by @code{\(*p}
3640 area = \(*p\fIr\fP\u2\d
3644 The escape @code{\C'@var{xxx}'} will typeset the character named
3645 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
3646 But @code{\C} has the advantage that it is compatible with recent
3647 versions of @code{ditroff} and is available in compatibility mode.
3651 The escape @code{\N'@var{n}'} will typeset the character with code@w{
3652 }@var{n} in the current font. @var{n} can be any integer. Most devices
3653 only have characters with codes between 0 and@w{ }255. If the current
3654 font does not contain a character with that code, special fonts will
3655 @emph{not} be searched. The @code{\N} escape sequence can be
3656 conveniently used on conjunction with the @code{char} request:
3659 .char \[phone] \f(ZD\N'37'
3664 @cindex unnamed characters
3665 @cindex characters, unnamed
3666 The code of each character is given in the fourth column in the font
3667 description file after the charset command. It is possible to include
3668 unnamed characters in the font description file by using a name of
3669 @samp{---}; the @code{\N} escape sequence is the only way to use these.
3671 @c XXX should be `glyph', not `character'
3674 @cindex character properties
3675 @cindex properties of characters
3676 Each character has certain properties associated with it. These
3677 properties can be modified with the @code{cflags} request. The first
3678 argument is the the sum of the desired flags and the remaining arguments
3679 are the characters to have those properties.
3683 @cindex end of sentence characters
3684 @cindex characters, end of sentence
3685 the character ends sentences (initially characters @samp{.?!} have this
3688 @cindex hyphenating characters
3689 @cindex characters, hyphenation
3690 lines can be broken before the character (initially no characters have
3693 lines can be broken after the character (initially the characters
3694 @samp{-\(hy\(em} have this property)
3696 @cindex overlapping characters
3697 @cindex characters, overlapping
3698 the character overlaps horizontally (initially the characters
3699 @samp{\(ul\(rn\(ru} have this property)
3701 the character overlaps vertically (initially character @samp{\(br} has
3704 @cindex transparent characters
3705 @cindex characters, transparent
3706 an end of sentence character followed by any number of characters with
3707 this property will be treated as the end of a sentence if followed by a
3708 newline or two spaces; in other words the character is @dfn{transparent}
3709 for the purposes of end of sentence recognition---this is the same as
3710 having a zero space factor in @TeX{} (initially characters
3711 @samp{"')]*\(dg\(rq} have this property).
3715 @cindex defining characters
3716 @cindex characters, defining
3717 You can create new characters with the @code{char} request. It is
3721 .char @var{c} @var{string}
3730 This defines character@w{ }@var{c} to be @var{string}. Every time
3731 character@w{ }@var{c} needs to be printed, @var{string} will be
3732 processed in a temporary environment and the result will be wrapped up
3733 into a single object. Compatibility mode will be turned off and the
3734 escape character will be set to @samp{\} while @var{string} is being
3735 processed. Any emboldening, constant spacing or track kerning will be
3736 applied to this object rather than to individual characters in
3737 @var{string}. A character defined by this request can be used just like
3738 a normal character provided by the output device. In particular other
3739 characters can be translated to it with the @code{tr} request; it can be
3740 made the leader character by the @code{lc} request; repeated patterns
3741 can be drawn with the character using the @code{\l} and @code{\L} escape
3742 sequences; words containing the character can be hyphenated correctly,
3743 if the @code{hcode} request is used to give the character a hyphenation
3744 code. There is a special anti-recursion feature: use of character
3745 within the character's definition will be handled like normal characters
3746 not defined with @code{char}.
3749 @cindex removing character definition
3750 @cindex character, removing definition
3751 A character definition can be removed with the @code{rchar} request.
3752 Its arguments are the characters to be removed. This undoes the effect
3753 of a @code{char} request.
3755 @xref{Special Characters}.
3757 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
3758 @subsection Artificial Fonts
3759 @cindex artificial fonts
3760 @cindex fonts, artificial
3762 There are a number of requests for artificially creating fonts. These
3763 are largely vestigial remains from the days when output devices did not
3764 have a wide variety of fonts, and when @code{nroff} and @code{troff}
3765 were separate programs. These are no longer necessary in GNU
3770 The @code{ul} request will print subsequent lines in italics on a device
3771 capable of it, or underline the text on an character output device. The
3772 single argument is the number of lines to be ``underlined,'' with no
3773 argument, the next line will be underlined.
3776 @cindex continuous underlining
3777 @cindex underlining, continuous
3778 The @code{cu} request is similar to @code{ul} ...
3783 @cindex underline font
3784 @cindex font for underlining
3785 The @code{uf} request will set the underline font used by @code{ul} and
3789 @cindex imitating bold face
3790 @cindex bold face, imitating
3791 The @code{bd} request artificially creates a bold font by printing each
3792 character twice, slightly offset. The first argument specifies the font
3793 to embolden, and the second is the number of basic units, minus one, by
3794 which the two characters will be offset. If the second argument is
3795 missing, emboldening will be turned off.
3797 @node Ligatures and Kerning, , Artificial Fonts, Fonts
3798 @subsection Ligatures and Kerning
3799 @cindex ligatures and kerning
3800 @cindex kerning and ligatures
3808 You can switch the ligature mechanism on or off with the @code{lg}
3809 request; if the parameter is non-zero or missing, ligatures are enabled,
3810 otherwise disabled. Default is on. The current ligature mode can be
3811 found in the number register @code{.lg} (set to@w{ }1 if ligatures are
3812 enabled, 0@w{ }otherwise).
3818 @cindex zero width space character
3819 @cindex character, zero width space
3820 @cindex space character, zero width
3821 If the font description file contains pairwise kerning information,
3822 characters from that font will be kerned. Kerning between two
3823 characters can be inhibited by placing @code{\&} between them.
3827 You can activate kerning with the @code{kern} request. If the parameter
3828 is non-zero or missing, enable pairwise kerning, otherwise disable it.
3829 The number register @code{.kern} is set to@w{ }1 if pairwise kerning is
3830 enabled, 0@w{ }otherwise.
3833 @cindex track kerning
3834 @cindex kerning, track
3835 What is track kerning?
3839 Track kerning must be used with great care since it is usually
3840 considered bad typography if the reader notices the effect. The syntax
3841 of the @code{tkf} request is
3844 .tkf @var{f} @var{s1} @var{n1} @var{s2} @var{n2}
3848 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
3849 }@var{f} the width of every character will be increased by an amount
3850 between @var{n1} and @var{n2}; if the current point size is less than or
3851 equal to @var{s1} the width will be increased by @var{n1}; if it is
3852 greater than or equal to @var{s2} the width will be increased by
3853 @var{n2}; if the point size is greater than or equal to @var{s1} and
3854 less than or equal to @var{s2} the increase in width is a linear
3855 function of the point size.
3858 @node Sizes, Strings, Fonts, Programming Tutorial
3864 @cindex size of type
3865 @cindex vertical spacing
3866 @cindex spacing, vertical
3867 @code{gtroff} uses two dimensions with each line of text, type size and
3868 vertical spacing. The @dfn{type size} is the height from the text
3869 @dfn{baseline} to the top of the tallest character (descenders may drop
3870 below this baseline). @dfn{Vertical spacing} is the amount of space
3871 @code{gtroff} allows for a line of text; normally, this is about 20%@w{
3872 }larger than the current type size. Ratios smaller than this can result
3873 in hard-to-read text; larger that this, it will spread your text out
3874 more vertically (useful for term papers). By default, @code{gtroff}
3875 uses 10@w{ }point type on 12@w{ }point spacing.
3878 The difference between type size and vertical spacing is known, by
3879 typesetters, as @dfn{leading}.
3882 * Changing Type Sizes::
3883 * Fractional Type Sizes::
3886 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
3887 @subsection Changing Type Sizes
3888 @cindex changing type sizes
3889 @cindex type sizes, changing
3896 Using the @code{ps} request and the @code{\s} escape you can change the
3897 type size. The @code{vs} request will change the vertical spacing. The
3898 default unit for the @code{ps} and @code{vs} requests are points. The
3899 number registers @code{.s} and @code{.v} contain the current type size
3900 and vertical spacing.
3902 These requests take parameters in units of points. You can specify
3903 sizes as an absolute size, or as a relative change from the current
3904 size. The size@w{ }0 means go back to the previous size. With no
3905 argument it will also revert to the previous size.
3912 wink, wink, \s+2nudge, nudge,\s+8 say no more!
3916 The @code{\s} escape may be called in a variety of ways. Much like
3917 other escapes there must be a way to determine where the argument ends
3918 and the text begins. Any of the following forms are valid:
3922 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 0
3923 or in the range 4 to@w{ }39.
3926 Increase resp.@: decrease the point size by @var{n}@w{ }points.
3927 @var{n}@w{ }must be exactly one digit.
3929 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly two
3935 Increase resp.@: decrease the point size by @var{nn}@w{ }points.
3936 @var{nn} must be exactly two digits.
3939 @xref{Fractional Type Sizes}, for yet another syntactical form of using
3940 the @code{\s} escape.
3942 Some devices may only have certain permissible sizes, in which case
3943 @code{gtroff} will round to the nearest permissible size.
3948 ... .sz macro example?? ...
3951 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
3952 @subsection Fractional Type Sizes
3953 @cindex fractional type sizes
3954 @cindex type sizes, fractional
3956 @cindex @code{s} unit
3957 @cindex unit, @code{s}
3958 @cindex @code{z} unit
3959 @cindex unit, @code{z}
3965 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
3966 @var{sizescale} is specified in the @file{DESC} file (1@w{ }by default.)
3967 There is a new scale indicator @samp{z} which has the effect of
3968 multiplying by @var{sizescale}. Requests and escape sequences in
3969 @code{gtroff} interpret arguments that represent a point size as being in
3970 units of scaled points, but they evaluate each such argument using a
3971 default scale indicator of @samp{z}. Arguments treated in this way are
3972 the argument to the @code{ps} request, the third argument to the
3973 @code{cs} request, the second and fourth arguments to the @code{tkf}
3974 request, the argument to the @code{\H} escape sequence, and those
3975 variants of the @code{\s} escape sequence that take a numeric expression
3976 as their argument (see below).
3978 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
3979 will be equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
3980 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 10250
3981 scaled points, which is equal to 10.25@w{ }points.
3983 It would make no sense to use the @samp{z} scale indicator in a numeric
3984 expression whose default scale indicator was neither @samp{u} nor
3985 @samp{z}, and so @code{gtroff} disallows this. Similarly it would make
3986 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
3987 numeric expression whose default scale indicator was @samp{z}, and so
3988 @code{gtroff} disallows this as well.
3990 There is also new scale indicator @samp{s} which multiplies by the
3991 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
3992 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
3997 The number register @code{.s} returns the point size in points as decimal
3998 fraction. There is also a new number register @code{.ps} that returns
3999 the point size in scaled points.
4003 The last-requested point size in scaled points is contained in the
4004 @code{.psr} number register. The last requested point size in points as
4005 a decimal fraction can be found in @code{.psr}. This is a string-valued
4011 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
4012 expression with a default scale indicator of @samp{z}.
4021 Increases resp.@: decreases the point size by @var{n} scaled points;
4022 @var{n} is a numeric expression with a default scale indicator of
4029 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
4034 @code{gtroff} has string variables, which are entirely for user
4035 convenience (i.e.@: there are no built-in strings). They are defined
4036 via the @code{ds} request.
4039 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
4043 @cindex string interpolation
4044 @cindex string expansion
4045 @cindex interpolation of strings
4046 @cindex expansion of strings
4047 They are interpolated, or expanded in-place, via the @code{\*} escape:
4050 The \*(UX Operating System
4053 If the string named by the @code{\*} does not exist, the escape will be
4054 replaced by nothing.
4056 @cindex comments, with @code{ds}
4057 @strong{Caution:} Unlike other requests, the second argument to the
4058 @code{ds} request takes up the entire line including trailing spaces.
4059 This means that comments on a line with such a request can introduce
4060 unwanted space into a string.
4063 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
4067 Instead you should either put the comment on another line or have the
4068 comment escape adjacent with the end of the string.
4071 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
4074 @cindex trailing quotes
4075 @cindex quotes, trailing
4076 @cindex leading spaces with @code{ds}
4077 @cindex spaces with @code{ds}
4078 If you need leading space you can start the string with a double quote.
4079 No trailing quote is needed; in fact, any trailing quote is included in
4083 .ds sign " Yours in a white wine sauce,
4087 @cindex appending to strings
4088 @cindex strings, appending
4089 You can also append onto a string with the @code{as} request. It works
4090 similar to the @code{ds} request except that it appends the second
4091 argument onto the string named by the first argument.
4094 .as sign " with shallots, onions and garlic,
4098 @cindex multi-line strings
4099 @cindex strings, multi-line
4100 @cindex newline character, escaping
4101 @cindex escaping newline characters
4102 Strings are not limited to a single line of text. A string can span
4103 several lines by escaping the newlines with a backslash. The resulting
4104 string will be stored @emph{without} the newlines.
4107 .ds foo lots and lots \
4108 of text are on these \
4114 Rudimentary string manipulation routines are given with the
4115 @code{substring} and @code{length} requests. The former has the
4119 .substring @var{xx} @var{n1} [@var{n2}]
4123 It replaces the string in register@w{ }@var{xx} with the substring
4124 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
4125 in the string has index one. If @var{n2} is omitted, it is taken to be
4126 equal to the string's length. If the index value @var{n1} or @var{n2}
4127 is negative or zero, it will be counted from the end of the string,
4128 going backwards: The last character has index@w{ }0, the character
4129 before the last character has index@w{ }-1, etc.
4132 @cindex length of a string
4133 @cindex string, length of
4134 Here the syntax of the @code{length} request:
4137 .length @var{xx} @var{string}
4141 It computes the length of @var{string} and returns it in the number
4142 register@w{ }@var{xx} (which is not necessarily defined before).
4164 @xref{Identifiers}, and @ref{Comments}.
4167 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
4168 @section Conditionals and Loops
4169 @cindex conditionals and loops
4170 @cindex loops and conditionals
4174 In @code{if} and @code{while} requests, there are several more operators
4180 True if the current page is even or odd numbered (respectively).
4183 True if the document is being processed by @code{nroff} (or a character
4184 device) resp.@: @code{troff}.
4185 @item '@var{xxx}'@var{yyy}'
4186 True if the string @var{xxx} is equal to the string @var{yyy}. Other
4187 characters can be used in place of the single quotes.
4189 The strings are `formatted' before being compared.
4192 True if there is a number register named @var{xxx}.
4194 True if there is a string, macro, diversion, or request named @var{xxx}.
4197 True if there is a character @var{ch} available; @var{ch} is either an
4198 @sc{ascii} character or a special character (@code{\(@var{ch}} or
4199 @code{\[@var{ch}]}); the condition will also be true if @var{ch} has
4200 been defined by the @code{char} request.
4208 @node if-else, while, Conditionals and Loops, Conditionals and Loops
4212 Troff has if-then-else constructs like other languages, although the
4213 formatting can be painful.
4216 The @code{if} request has the following syntax:
4219 .if @var{expr} @var{anything}
4223 where @var{expr} is the expression to be evaluated; @var{anything} (the
4224 remainder of the line) will be executed if @var{expr} evaluates to
4225 non-zero (true). @var{anything} will be interpreted as though it was on
4226 a line by itself. @xref{Expressions}, for more info.
4228 Here are some examples:
4231 .if t .ls 2 \" double spacing in troff
4232 .if 0 .ab how'd this happen?
4237 An if-then-else is written using two requests @code{ie} and @code{el}.
4238 The first request is the `if' part and the latter is the `else' part.
4249 In many cases you want more than one request to be executed as a result
4250 of any of these requests. This can be done using the @code{\@{} and
4251 @code{\@}} escapes. The following example shows the possible ways to
4252 use these escapes (note the position of the opening and closing braces).
4268 @node while, , if-else, Conditionals and Loops
4273 @code{gtroff} provides a looping construct using the @code{while}
4274 request, which is used much like the @code{if} (and related) requests.
4275 The first argument is an expression which will be evaluated. The
4276 @code{while} request will interpret the remainder of the line until the
4277 expression evaluates to 0 or false.
4281 .while (\na<9) \&\n+a,
4286 The preceding example produces:
4289 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
4292 @cindex zero width space character
4293 @cindex character, zero width space
4294 @cindex space character, zero width
4297 Note the usage of the @code{\&} escape to avoid a control character at
4298 the beginning of a line.
4302 The @code{break} request will @dfn{break} out of a while loop. Be sure
4303 not to confuse this with the @code{br} request (causing a line break).
4304 The @code{continue} request will finish the current iteration of a while
4305 loop, immediately restarting the next iteration.
4310 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
4311 @section Writing Macros
4312 @cindex writing macros
4313 @cindex macros, writing
4316 A @dfn{macro} is a collection of text and embedded commands which can be
4317 invoked multiple times. Macros are used for defining common operations.
4318 Macros are defined using the @code{de} request. This request takes a
4319 name for the macro as the first argument. Subsequent lines are copied
4320 into an internal buffer until the line @code{..} is encountered. The
4321 optional second argument to @code{de} can change this ending token.
4323 For example, suppose at the beginning of each paragraph, you want cause
4324 a break, move down a partial line and indent the first line. Such a
4325 macro (it is called @code{P}) could be defined as follows:
4335 The @code{am} request works similarly to @code{de} except it appends
4336 onto the macro named by the first argument. So, if we decide we want
4337 our previously defined @code{P} macro to actually do indented instead of
4338 block paragraphs we can add the necessary code to our existing macro:
4347 @cindex aliases, macro
4348 @cindex macro aliases
4349 Macros can be aliased with the @code{als} request.
4358 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
4359 @subsection Copy-in Mode
4360 @cindex copy-in mode
4361 @cindex mode, copy-in
4368 When troff reads in the text for a macro or diversion it copies the text
4369 (including request lines, but excluding escapes) into an internal
4370 buffer. Escapes will be converted into an internal form, except for
4371 @code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which
4372 are evaluated and inserted into the text where the escape was located.
4373 This is known as @dfn{copy-in} mode.
4375 What this means is that you can specify when these escapes are to be
4376 evaluated (either at copy-in time or at the time of use) by insulating
4377 the escapes with an extra backslash. Compare this to the @code{\def}
4378 and @code{\edef} commands in @TeX{}.
4380 For example, the following will result in the numbers 20 and@c{ }10
4393 @node Parameters, , Copy-in Mode, Writing Macros
4394 @subsection Parameters
4399 The arguments to a macro can be examined using a variety of escapes.
4400 The number of arguments is available in the @code{.$} number register.
4401 Any individual argument can be retrieved with one of the following
4404 @cindex copy-in mode
4405 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
4406 @code{\$[@var{nnn}]} will result in the @var{n}th, @var{nn}th or
4407 @var{nnn}th argument. As usual, the first form only accepts a single
4408 number (larger than zero), the second only a two-digit number (larger or
4409 equal to@w{ }10), and the third any positive integer value (larger than
4410 zero). Macros can have an unlimited number of arguments. Note that due
4411 to copy-in mode, you will want to have two backslashes on these in
4412 actual use, since you do not want them interpolated until the macro is
4416 The request @code{shift} will shift the arguments 1@w{ }position, or as
4417 many positions as specified by its argument. After executing this
4418 request, argument@w{ }@var{i} will become argument @var{i}-@var{n};
4419 arguments 1 to@w{ }@var{n} will no longer be available. Shifting by
4420 negative amounts is currently undefined.
4424 In some cases you will want to just use all of the arguments at once.
4425 For example if you pass the arguments along to another macro. The
4426 @code{\$*} escape is the concatenation of all the arguments separated by
4427 spaces. A similar escape is @code{\$@@}, which is the concatenation of
4428 all the arguments with each surrounded by double quotes, and separated
4433 The @code{\$0} escape is the name by which the current macro was
4434 invoked. The @code{als} request can make a macro have more than one
4439 .ie \\n(.$=1 .ds Vl Pre-Release Version
4440 .el .ds Vl Version \\$3, \\$4.
4444 This would be called as
4450 @xref{Request Arguments}.
4453 @node Page Motions, Drawing Requests, Writing Macros, Programming Tutorial
4454 @section Page Motions
4455 @cindex page motions
4456 @cindex motions, page
4459 Motions up and down the page can be done with the @code{sp} request.
4460 However, this causes a break so that the actual effect is to move to the
4461 left margin and then to the specified location.
4465 The request @code{mk} can be used to mark a location on a page, for
4466 movement to later. This request takes a register name as an argument in
4467 which to store the current page location. With no argument it will
4468 store the location in an internal register. The results of this can be
4469 used later by the @code{rt} or the @code{sp} request. The @code{rt}
4470 request will return @emph{upwards} to the location given in the register
4471 name given as an argument, with no argument it will return to the
4472 location marked with the @code{mk} request
4477 ... dual column example ...
4480 The following escapes will give you much finer control of movements
4484 @cindex vertical motion
4485 @cindex motion, vertical
4486 The @code{\v'@var{e}'} will let you do arbitrary vertical motion from
4487 the current location on the page. The argument@w{ }@var{e} specifies
4488 the distance to move; positive is downwards and negative upwards. The
4489 default unit for this escape is vertical spaces, @code{v}'s. Beware,
4490 however, that @code{gtroff} will leave text processing to continue
4491 wherever the motion ends, so if you don't want to interfere with text
4492 processing, make sure your motions are balanced.
4494 There are some special case escapes for vertical motion.
4498 move upwards@w{ }1@dmn{v}.
4500 move upwards@w{ }.5@dmn{v}.
4502 move down@w{ }.5@dmn{v}.
4506 Horizontal motions can be done via the @code{\h'@var{e}'} escape. The
4507 expression@w{ }@var{e} indicates how far to move: positive is rightwards
4508 and negative leftwards.
4510 There are a number of special case escapes for horizontal motion:
4514 an unbreakable and unpaddable (i.e.@: not expanded during filling)
4515 space. (Note: It is a backslash followed by a space.)
4517 an unbreakable space that stretches like a normal inter-word space when a
4524 a space the size of a digit.
4525 @cindex zero width space character
4526 @cindex character, zero width space
4527 @cindex space character, zero width
4531 Like @code{\&} except that it behaves like a character declared with the
4532 @code{cflags} request to be transparent for the purposes of end of
4533 sentence recognition.
4539 ... tex logo example ...
4543 @cindex width escape
4544 @cindex escape, width
4545 Often you will want to do horizontal movement based on the width of some
4546 arbitrary text (e.g.@: given as an argument to a macro). For that,
4547 there is the escape @code{\w'@var{text}'} which will interpolate to the
4548 width of the given @var{text} in basic units.
4553 ... strlen example ...
4556 Font changes may occur in @var{text} which don't affect current
4559 After use, @code{\w} sets several registers:
4566 The highest and lowest point, respectively, in @var{text}.
4571 Like the @code{st} and @code{sb} registers, but takes account of the
4572 heights and depths of characters.
4575 is set according to what kinds of characters occur in @var{text}:
4578 only short characters, no descenders or tall characters.
4584 both a descender and a tall character
4588 The amount of horizontal space (possibly negative) that should be added
4589 to the last character before a subscript.
4592 How far to right of the center of the last character in the @code{\w}
4593 argument, the center of an accent from a Roman font should be placed
4594 over that character.
4603 @c XXX documentation
4606 @node Drawing Requests, Traps, Page Motions, Programming Tutorial
4607 @section Drawing Requests
4608 @cindex drawing requests
4609 @cindex requests for drawing
4611 @code{gtroff} provides a number of ways to draw lines and other figures
4612 on the page. Used in combination with the page motion commands
4613 (@pxref{Page Motions}, for more info) you can draw a wide variety of
4614 figures. However, for complex drawings these operations can be quite
4615 cumbersome, and it may be wise to use graphic preprocessors like
4616 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
4619 All drawing is done via escapes.
4622 @cindex horizontal line
4623 @cindex line, horizontal
4624 The @code{\l} escape will draw a line rightwards from the current
4625 location. The full syntax for this escape is
4632 where @var{l} is the length of the line to be drawn, starting at the
4633 current location; positive numbers will draw to the right, and negative
4634 will draw towards the left. This can also be specified absolutely
4635 (i.e.@: with a leading @samp{|}) which will draw back to the beginning
4638 @cindex underscore character
4639 @cindex character, underscore
4640 @cindex line drawing character
4641 @cindex character for line drawing
4642 The optional second parameter @var{c} is a character to draw the line
4643 with. If this second argument is not specified, troff will use the
4644 underscore character.
4646 @cindex zero width space character
4647 @cindex character, zero width space
4648 @cindex space character, zero width
4650 If you need to separate the two arguments (to prevent troff from
4651 interpreting a drawing character as a scaling indicator), you can
4652 separate them with @code{\&}.
4654 Here a small useful example:
4658 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
4664 Note that this works by outputting a box rule (a vertical line), then
4665 the text given as an argument and then another box rule. Then the line
4666 drawing escapes both draw from the current location to the beginning of
4667 the @emph{input} line.
4670 @cindex vertical line
4671 @cindex line, vertical
4672 @cindex line drawing character
4673 @cindex character for line drawing
4674 @cindex box rule character
4675 @cindex character, box rule
4676 Vertical lines are drawn using the @code{\L} escape. Its parameters are
4677 specified similar to the @code{\l} escape. If the length is positive,
4678 the movement will be downwards, and upwards for negative values. The
4679 default character is the box rule character. As with the vertical
4680 motion escapes, text processing will blindly continue where the line
4690 More flexible drawing functions are available via the @code{\D} escape.
4691 While the previous escapes will work on a character device, these
4695 @item \D'l @var{dx} @var{dy}'
4696 Draw a line from the current location to the relative point specified by
4697 (@var{dx},@var{dy}).
4702 ...revised box macro...
4707 Draw a circle with a diameter of @var{d} with the leftmost point at the
4710 Draw a solid circle with the same parameters as an outlined circle.
4711 @item \D'e @var{dx} @var{dy}'
4713 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
4714 diameter of @var{dy} with the leftmost point at the current position.
4715 @item \D'E @var{dx} @var{dy}'
4716 Draw a solid ellipse with the same parameters as an outlined ellipse.
4717 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
4719 Draw an arc clockwise from the current location through the two
4720 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
4721 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4723 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
4724 then to (@var{dx2},@var{dy2}), and so on.
4726 @cindex gray shading
4728 Set the shade of gray to be used for filling solid objects to@w{
4729 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
4730 corresponds solid white and 1000 to solid black, and values in between
4731 correspond to intermediate shades of gray. This applies only to solid
4732 circles, solid ellipses and solid polygons. By default, a level of@w{
4734 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4736 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
4737 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
4738 are exhausted, a line is drawn back to the starting point.
4743 ... box example (yes, again)...
4746 @itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4747 Draw a solid polygon with the same parameters as an outlined polygon.
4752 ... shaded box example ...
4756 @cindex line thickness
4757 @cindex thickness of lines
4758 Set the current line thickness to @var{n} machine units. A value of
4759 zero selects the smallest available line thickness. A negative value
4760 makes the line thickness proportional to the current point size (this is
4761 the default behaviour of @code{ditroff}).
4765 @cindex pile, character
4766 @cindex character pile
4767 The @code{\b} escape will @dfn{pile} a sequence of characters
4768 vertically, and center it vertically on the current line. This can be
4769 used to build large brackets and braces.
4772 \b'\(lt\(bv\(lk\(bv\(lb'
4775 @xref{Drawing Functions}.
4777 @node Traps, Diversions, Drawing Requests, Programming Tutorial
4781 @dfn{Traps} are locations, which, when reached, will call a specified
4782 macro. These traps can occur at a given location on the page, at a
4783 given location in the current diversion, after a certain number of input
4784 lines or at the end of input.
4787 * Page Location Traps::
4789 * Input Line Traps::
4790 * End-of-input Traps::
4793 @node Page Location Traps, Diversion Traps, Traps, Traps
4794 @subsection Page Location Traps
4795 @cindex page location traps
4796 @cindex traps, page location
4798 @c XXX definition of wh request
4800 @cindex page headers
4801 @cindex page footers
4804 Page location traps are frequently used for page headers and footers.
4805 The following is a simple example of this.
4808 .de hd \" Page header
4813 .de fo \" Page footer
4818 .wh 0 hd \" trap at top of the page
4819 .wh -1i fo \" trap one inch from bottom
4823 @cindex distance to next trap
4824 @cindex trap, distance
4825 The number register @code{.t} is the distance to the next trap.
4828 @cindex changing trap location
4829 @cindex trap, changing location
4830 The location of a trap can be changed later on with the @code{ch}
4831 request. The first argument is the name of the macro to be invoked at
4832 the trap and the second argument is the new location for the trap. This
4833 is useful when you are building up footnotes in a diversion, and you
4834 need to allow more space at the bottom of the page for them.
4839 ... (simplified) footnote example ...
4846 The @code{vpt} request will enable vertical position traps if the
4847 argument is non-zero, disable them otherwise. Vertical position traps
4848 are traps set by the @code{wh} or @code{dt} requests. Traps set by the
4849 @code{it} request are not vertical position traps. The parameter that
4850 controls whether vertical position traps are enabled is global.
4851 Initially vertical position traps are enabled. The current setting of
4852 this is available in the number register @code{.vpt}.
4856 The number register @code{.trunc} contains the amount of vertical space
4857 truncated by the most recently sprung vertical position trap, or, if the
4858 trap was sprung by a @code{ne} request, minus the amount of vertical
4859 motion produced by the @code{ne} request. In other words, at the point
4860 a trap is sprung, it represents the difference of what the vertical
4861 position would have been but for the trap, and what the vertical
4862 position actually is.
4865 The number register @code{.ne} contains the amount of space that was
4866 needed in the last @code{ne} request that caused a trap to be sprung.
4867 Useful in conjunction with the @code{.trunc} register. @xref{Page
4868 Control}, for more information.
4870 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
4871 @subsection Diversion Traps
4872 @cindex diversion traps
4873 @cindex traps, diversion
4877 Traps can also be set @emph{within} a diversion using the @code{dt}
4878 request. Like @code{wh} the first argument is the location of the trap
4879 and the second argument is the name of the macro to be invoked. The
4880 number register @code{.t} will still work within diversions.
4881 @xref{Diversions}, for more information.
4883 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
4884 @subsection Input Line Traps
4885 @cindex input line traps
4886 @cindex traps, input line
4889 The @code{it} request will set an input line trap. The format for
4893 .it @var{n} @var{name}
4897 where @var{n} is the number of lines of input which may be read before
4898 @dfn{springing} the trap, @var{name} is the macro to be invoked.
4899 Request lines are not counted as input lines.
4901 For example, one possible use is to have a macro which will print the
4902 next @var{n}@w{ }lines in a bold font.
4914 @node End-of-input Traps, , Input Line Traps, Traps
4915 @subsection End-of-input Traps
4916 @cindex end-of-input traps
4917 @cindex traps, end-of-input
4920 The @code{em} request will set a trap at the end of input. The macro
4921 specified as an argument will be executed after the last line of the
4922 input file has been processed.
4924 For example, if your document had to have a section at the bottom of the
4925 last page for someone to approve your document, you could set it up with
4943 @node Diversions, Environments, Traps, Programming Tutorial
4947 In @code{gtroff} you can @dfn{divert} text into a named storage area.
4948 Due to the similarity to defining macros it is sometimes said to be
4949 stored in a macro. This is used for saving text for output at a later
4950 time, which is useful for keeping blocks of text on the same page,
4951 footnotes, tables of contents and indices.
4955 A diversion is initiated by the @code{di} request. Like the @code{de}
4956 request, it takes an argument of a macro name to divert subsequent text
4957 into. The @code{da} macro will append to an existing diversion.
4959 @code{di} (resp.@: @code{da}) without an argument ends the diversion.
4964 ... end-note example ...
4971 @cindex nested diversions
4972 @cindex diversion, nested
4973 Diversions may be nested. The number register @code{.z} contains the
4974 name of the current diversion. The number register @code{.d} contains
4975 the current vertical place in the diversion. If not in a diversion it
4976 is the same as the register @code{nl}.
4984 After completing a diversion, the built-in number registers @code{dn}
4985 and @code{dl} contain the vertical and horizontal size of the diversion.
4988 .\" Center text both horizontally & vertically
4997 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
5012 @cindex transparent output
5013 @cindex output, transparent
5014 Requests, macros and escapes are interpreted when read into a diversion.
5015 There are two ways to prevent this; either way will take the given text
5016 and @dfn{transparently} embed it into the diversion. The first method
5017 is to prefix the line with @code{\!}. This will cause the entire line
5018 to be transparently inserted into the diversion. This is useful for
5019 macros you do not want invoked until the diverted text is actually
5022 @c XXX anything is read in copy mode. (what about \! ??)
5025 The other way is to surround the text by the @code{\?} escape, i.e.
5032 @var{anything} may not contain newlines; use @code{\!} if you want to
5033 embed newlines in a diversion. The escape sequence @code{\?} is also
5034 recognized in copy mode and turned into a single internal code; it is
5035 this code that terminates anything. Thus the following example will
5042 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
5057 @cindex unformatting diversions
5058 @cindex diversion, unformatting
5059 The @code{asciify} request only exists in order to make certain gross
5060 hacks work with GNU @code{troff}. It @dfn{unformats} the diversion
5061 specified as an argument in such a way that @sc{ascii} characters that
5062 were formatted and diverted will be treated like ordinary input
5063 characters when the diversion is reread. For example, the following
5064 will set register @code{n} to@w{ }1.
5077 @xref{Copy-in Mode}.
5080 @node Environments, I/O, Diversions, Programming Tutorial
5081 @section Environments
5082 @cindex environments
5084 Often you will need to print some text in a certain format regardless of
5085 what may be in effect at the time, for example, in a trap invoked macro
5086 to print headers and footers. To solve this @code{gtroff} has
5087 @dfn{environments} in which text is processed. An environment contains
5088 most of the parameters that control text processing. You can switch
5089 amongst these environments; by default @code{gtroff} processes text in
5090 environment@w{ }0. The following is the information kept in an
5097 font (family and style)
5105 partially collected lines
5108 These environments may be given arbitrary names (@pxref{Identifiers},
5109 for more info). Old versions of troff only had environments named
5110 @samp{0}, @samp{1} and@w{ }@samp{2}.
5114 The @code{ev} request will switch among environments. The single
5115 argument is the name of the environment to switch to. With no argument
5116 @code{gtroff} will switch back to the previous environment. There is no
5117 limit on the number of named environments; they will be created the
5118 first time that they are referenced. The @code{.ev} register contains
5119 the name or number of the current environment. This is a string-valued
5122 Note that a call to @code{ev} (with argument) will push the previously
5123 active environment onto a stack. If, say, environments @samp{foo},
5124 @samp{bar}, and @samp{zap} are called (in that order), the first
5125 @code{ev} request without parameter will switch back to environment
5126 @samp{bar} (which will be popped off the stack), and a second call will
5127 switch back to environment @samp{foo}.
5132 ... page break macro, revised ...
5135 Here another example:
5146 \(dg Note the large, friendly letters.
5151 To copy an environment into the current one, use the @code{evc} request,
5152 which takes the name of the environment to copy from as an argument.
5155 @node I/O, Postprocessor Access, Environments, Programming Tutorial
5158 @cindex input and output requests
5159 @cindex requests for input and output
5160 @cindex output and input requests
5163 The @code{so} request will read in the file given as an argument and
5164 include it in place of the @code{so} request. This is quite useful for
5165 large documents, i.e.@: keeping each chapter in a separate file.
5166 @xref{gsoelim}, for more information.
5169 The @code{mso} request is the same as the @code{so} request except that
5170 the file is searched for in the same way that @file{tmac.@var{name}} is
5171 searched for when the @samp{-m@var{name}} option is specified.
5174 @cindex transparent output
5175 @cindex output, transparent
5176 The @code{cf} and @code{trf} requests are to include a file. It will
5177 transparently output the contents of file filename. Each line is output
5178 as it were preceded by @code{\!}; however, the lines are not subject to
5179 copy-mode interpretation. If the file does not end with a newline, then
5180 a newline will be added. For example, you can define a macro@w{
5181 }@code{x} containing the contents of file@w{ }@file{f}, using
5189 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
5190 will embed in the diversion an object which, when reread, will cause the
5191 contents of @var{filename} to be transparently copied through to the
5192 output. In @sc{Unix} @code{troff}, the contents of @var{filename} is
5193 immediately copied through to the output regardless of whether there is
5194 a current diversion; this behaviour is so anomalous that it must be
5198 With @code{trf}, unlike @code{cf}, the file cannot contain characters
5199 such as NUL that are not legal troff input characters.
5202 The @code{nx} request will force @code{gtroff} to continue processing of
5203 the file specified as an argument.
5206 The @code{rd} request will read from standard input, and include what is
5207 read as though it were part of the input file. Text is read until a
5208 blank line is encountered.
5210 @cindex form letters
5211 @cindex letters, form
5212 Using these two requests you can set up form letters. The form letter
5213 template is constructed like this:
5231 When this is run, the following file should be redirected in. Note that
5232 requests included in this file are executed as though they were part of
5233 the form letter. The last block of input is the @code{ex} requests
5234 which tells groff to stop processing. If this was not there, groff
5235 would not know when to stop.
5239 708 NW 19th Av., #202
5256 @c XXX documentation
5259 The @code{sy} request will allow arbitrary system commands to be
5260 executed from within a @code{gtroff} document. The output is not saved
5261 anyplace, so it is up to you to do so.
5263 @c XXX add info about safer and unsafe mode
5265 For example, the following example will introduce the current time
5268 @cindex time, current
5269 @cindex current time
5272 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
5273 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
5280 Note that this works by having the @code{perl} script (run by @code{sy})
5281 print out the @code{nr} requests which will set the number registers
5282 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
5283 the @code{so} request.
5286 The @code{systat} number register contains the return value of the
5287 @code{system()} function executed by the last @code{sy} request.
5290 The @code{open} request will open a file (specified as the second
5291 argument) for writing and associate the stream (specified as the first
5295 The @code{opena} is like @code{open}, but if the file exists, append to
5296 it instead of truncating it.
5300 @cindex copy-in mode
5301 @cindex mode, copy-in
5302 The @code{write} request will write to the file associated with the
5303 stream specified by the first argument. The stream must previously have
5304 been the subject of an open request. The remainder of the line is
5305 interpreted as the @code{ds} request reads its second argument: A
5306 leading @samp{"} will be stripped, and it will be read in copy-in mode.
5309 The @code{close} request will close the stream specified by the first
5310 argument; stream will no longer be an acceptable argument to the
5311 @code{write} request.
5316 ... example of open write &c...
5320 The @code{\V} escape will interpolate the contents of the specified
5321 environment variable, as returned by @code{getenv()}. The argument to
5322 @code{\V} is specified as an identifier, i.e.@: @samp{\V@var{x}},
5323 @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} is interpreted in
5327 @node Postprocessor Access, Miscellaneous, I/O, Programming Tutorial
5328 @section Postprocessor Access
5329 @cindex postprocessor access
5330 @cindex access of postprocessor
5332 There are two escapes which will allow you to give information directly
5333 to the postprocessor. This is particularly useful for embedding
5334 @sc{PostScript} into your final document.
5337 The @code{\X} escape will embed its argument into the @code{gtroff}
5338 output preceded with @w{@samp{x X}}.
5341 The @code{\Y} escape is called with an identifier (i.e.@:
5342 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
5343 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
5344 contents of the string or macro @var{xxx} are not interpreted; also it
5345 is permitted for @var{xxx} to have been defined as a macro and thus
5346 contain newlines (it is not permitted for the argument to @code{\X} to
5347 contain newlines). The inclusion of newlines requires an extension to
5348 the @sc{Unix} @code{troff} output format, and will confuse drivers that
5349 do not know about this extension.
5351 @xref{Output Devices}.
5354 @node Miscellaneous, Debugging, Postprocessor Access, Programming Tutorial
5355 @section Miscellaneous
5356 @cindex miscellaneous
5358 This section contains parts of @code{gtroff} which cannot (yet) be
5359 categorized elsewhere in this manual.
5362 @cindex line numbers
5363 @cindex numbers, line
5364 Line numbers can be printed in the left margin using the @code{nm}
5365 request. The first argument is the line number of the @emph{next}
5366 output line; this defaults to@w{ }1. The second argument indicates on
5367 which lines numbers will be printed, i.e.@: 5 means put line numbers on
5368 every 5@w{ }lines; this defaults to@w{ }1. The third argument is the
5369 space to be left between the number and your text; this defaults to@w{
5370 }1. The fourth argument is the indentation of the line numbers.
5371 Without arguments, line numbers are turned off.
5374 The @code{nn} request will temporarily turn off line numbering. The
5375 first argument is the number of lines not to be numbered; this defaults
5378 @c XXX (does this disable incrementing or display?)
5383 ... line numbering example ...
5387 @cindex margin characters
5388 @cindex characters for margins
5389 Margin characters can be automatically printed to the right of your text
5390 with the @code{mc} request. The first argument is the character to be
5391 printed, and the second argument is the distance away from your text.
5392 With no arguments the margin characters are turned off. If this occurs
5393 before a break, no margin character will be printed.
5397 This is quite useful for indicating text that has changed, and, in fact,
5398 there are programs available for doing this (they are called
5399 @code{nrchbar} and @code{changebar} and can be found in any
5400 @samp{comp.sources.unix} archive.
5405 ... margin char example ...
5410 @cindex multi-file documents
5411 @cindex documents, multi-file
5412 The primary reason for the existence of @code{lf} is to make debugging
5413 documents which are split into many files, which are then put together
5414 with @code{soelim} and other preprocessors. The first argument is the
5415 name of the file and the second argument is the input line number in
5416 that file. This way troff can produce error messages which are
5417 intelligible to the user.
5422 ... example of soelim'ed doc ...
5426 @node Debugging, Implementation Differences, Miscellaneous, Programming Tutorial
5430 @code{gtroff} is not easy to debug, but there are some useful features
5431 and strategies for debugging.
5436 The @code{tm} request will send output to stderr; this is very useful
5437 for printing debugging output.
5439 When doing something involved it is useful to leave the debugging
5440 statements in the code and have them turned on by a command line flag.
5443 .if \n(DB .tm debugging output
5447 Then you can activate these statements with:
5456 The @code{ab} request is similar to the @code{tm} request, except that
5457 it will cause @code{gtroff} to stop processing. With no argument it
5458 will print @samp{User Abort}.
5462 The @code{ex} request will also cause @code{gtroff} to stop processing
5463 (if encountered at the topmost level; see also @ref{I/O}.
5465 If you know you are going to get many errors and no useful output, you
5466 can tell @code{gtroff} to suppress formatted output with the @samp{-z}
5470 @cindex dumping symbol table
5471 @cindex symbol table, dumping
5472 The @code{pm} request will dump out the entire symbol table.
5475 @cindex dumping number registers
5476 @cindex number registers, dumping
5477 The @code{pnr} request will print the names and contents of all
5478 currently defined number registers on stderr.
5481 @cindex dumping traps
5482 @cindex traps, dumping
5483 The @code{ptr} request will print the names and positions of all traps
5484 (not including input line traps and diversion traps) on stderr. Empty
5485 slots in the page trap list are printed as well, because they can affect
5486 the priority of subsequently planted traps.
5489 @cindex flush output
5490 @cindex output, flush
5491 @cindex interactive use of @code{gtroff}
5492 @cindex @code{gtroff}, interactive use
5493 The @code{fl} request instructs @code{gtroff} to flush its output
5494 immediately. The intention is that this be used when using
5495 @code{gtroff} interactively. There is little other use for it.
5498 @cindex backtrace of input stack
5499 @cindex input stack, backtrace
5500 The @code{backtrace} request will print a backtrace of the input stack
5504 @code{gtroff} has command line options for printing out more warnings
5505 (@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or an
5506 error occurs. The most verbose level of warnings is @samp{-ww}.
5510 @cindex level of warnings
5511 @cindex warnings, level
5512 The @code{warn} request controls the level of warnings checked for. The
5513 only argument is the sum of the numbers associated with each warning
5514 that is to be enabled; all other warnings will be disabled. The number
5515 associated with each warning is listed below. For example,
5516 @w{@code{.warn 0}} will disable all warnings, and @w{@code{.warn 1}}
5517 will disable all warnings except that about missing characters. If an
5518 argument is not given, all warnings will be enabled. The number
5519 register @code{.warn} contains the current warning level.
5522 @subsection Warnings
5525 The warnings that can be given to @code{gtroff} are divided into the
5526 following categories. The name associated with each warning is used by
5527 the @samp{-w} and @samp{-W} options; the number is used by the
5528 @code{warn} request and by the @code{.warn} register.
5533 Non-existent characters. This is enabled by default.
5536 Invalid numeric expressions. This is enabled by default.
5540 In fill mode, lines which could not be broken so that their length was
5541 less than the line length. This is enabled by default.
5544 Missing or mismatched closing delimiters.
5549 Use of the @code{el} request with no matching @code{ie} request.
5553 Meaningless scaling indicators.
5556 Out of range arguments.
5559 Dubious syntax in numeric expressions.
5564 Use of @code{di} or @code{da} without an argument when there is no
5569 @c XXX more findex entries
5570 Use of undefined strings, macros and diversions. When an undefined
5571 string, macro or diversion is used, that string is automatically defined
5572 as empty. So, in most cases, at most one warning will be given for each
5577 @c XXX more findex entries
5578 Use of undefined number registers. When an undefined number register is
5579 used, that register is automatically defined to have a value of@w{ }0.
5580 A definition is automatically made with a value of@w{ }0. So, in most
5581 cases, at most one warning will be given for use of a particular name.
5584 Use of a tab character where a number was expected.
5588 Use of @code{\@}} where a number was expected.
5591 Requests that are missing non-optional arguments.
5594 Illegal input characters.
5597 Unrecognized escape sequences. When an unrecognized escape sequence is
5598 encountered, the escape character is ignored.
5601 @cindex compatibility mode
5602 Missing space between a request or macro and its argument. This warning
5603 will be given when an undefined name longer than two characters is
5604 encountered, and the first two characters of the name make a defined
5605 name. The request or macro will not be invoked. When this warning is
5606 given, no macro is automatically defined. This is enabled by default.
5607 This warning will never occur in compatibility mode.
5610 Non-existent fonts. This is enabled by default.
5612 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
5613 intended that this covers all warnings that are useful with traditional
5620 @node Implementation Differences, Summary, Debugging, Programming Tutorial
5621 @section Implementation Differences
5622 @cindex implementation differences
5623 @cindex differences in implementation
5624 @cindex compatibility mode
5625 @cindex mode, compatibility
5627 GNU @code{troff} has a number of features which cause incompatibilities
5628 with documents written with old versions of @code{troff}.
5632 Long names cause some incompatibilities. @sc{Unix} @code{troff} will
5644 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
5645 @code{troff} will interpret this as a call of a macro named
5646 @code{dsabcd}. Also @sc{Unix} @code{troff} will interpret @code{\*[} or
5647 @code{\n[} as references to a string or number register called @samp{[}.
5648 In GNU @code{troff}, however, this will normally be interpreted as the
5649 start of a long name. In compatibility mode GNU @code{troff} will
5650 interpret these things in the traditional way. In compatibility mode,
5651 however, long names are not recognized. Compatibility mode can be
5652 turned on with the @samp{-C} command line option, and turned on or off
5653 with the @code{cp} request. The number register @code{.C} is@w{ }1 if
5654 compatibility mode is on, 0@w{ }otherwise.
5670 GNU @code{troff} does not allow the use of the escape sequences
5671 @code{\|}, @code{\^}, @code{\&}, @code{\@}}, @code{\@{},
5672 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5673 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
5674 registers, fonts or environments; @sc{Unix} @code{troff} does. The
5675 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
5676 avoiding use of these escape sequences in names.
5678 @cindex fractional point sizes
5679 @cindex point sizes, fractional
5681 Fractional point sizes cause one noteworthy incompatibility. In
5682 @sc{Unix} @code{troff} the @code{ps} request ignores scale indicators
5690 will set the point size to 10@w{ }points, whereas in GNU @code{troff} it
5691 will set the point size to 10@w{ }scaled points. @xref{Fractional Type
5692 Sizes}, for more information.
5699 @cindex input and output characters
5700 @cindex output characters
5701 @cindex characters, input and output
5702 In GNU @code{troff} there is a fundamental difference between
5703 unformatted, input characters, and formatted, output characters.
5704 Everything that affects how an output character will be output is stored
5705 with the character; once an output character has been constructed it is
5706 unaffected by any subsequent requests that are executed, including
5707 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
5708 Normally output characters are constructed from input characters at the
5709 moment immediately before the character is added to the current output
5710 line. Macros, diversions and strings are all, in fact, the same type of
5711 object; they contain lists of input characters and output characters in
5712 any combination. An output character does not behave like an input
5713 character for the purposes of macro processing; it does not inherit any
5714 of the special properties that the input character from which it was
5715 constructed might have had. For example,
5728 @cindex transparent output
5729 @cindex output, transparent
5731 will print @samp{\\} in GNU @code{troff}; each pair of input backslashes
5732 is turned into one output backslash and the resulting output backslashes
5733 are not interpreted as escape characters when they are reread.
5734 @sc{Unix} @code{troff} would interpret them as escape characters when
5735 they were reread and would end up printing one @samp{\}. The correct
5736 way to obtain a printable backslash is to use the @code{\e} escape
5737 sequence: This will always print a single instance of the current escape
5738 character, regardless of whether or not it is used in a diversion; it
5739 will also work in both GNU @code{troff} and @sc{Unix} @code{troff}. If
5740 you wish for some reason to store in a diversion an escape sequence that
5741 will be interpreted when the diversion is reread, you can either use the
5742 traditional @code{\!} transparent output facility, or, if this is
5743 unsuitable, the new @code{\?} escape sequence.
5745 @xref{Diversions}, for more information.
5748 @node Summary, , Implementation Differences, Programming Tutorial
5752 @c XXX documentation
5756 @node Preprocessors, Output Devices, Programming Tutorial, Top
5757 @chapter Preprocessors
5758 @cindex preprocessors
5760 This chapter describes all preprocessors that come with @code{groff} or
5761 which are freely available.
5774 @node geqn, gtbl, Preprocessors, Preprocessors
5775 @section @code{geqn}
5785 @node Invoking geqn, , geqn, geqn
5786 @subsection Invoking @code{geqn}
5787 @cindex invoking @code{geqn}
5788 @cindex @code{geqn}, invoking
5793 @node gtbl, gpic, geqn, Preprocessors
5794 @section @code{gtbl}
5804 @node Invoking gtbl, , gtbl, gtbl
5805 @subsection Invoking @code{gtbl}
5806 @cindex invoking @code{gtbl}
5807 @cindex @code{gtbl}, invoking
5812 @node gpic, ggrn, gtbl, Preprocessors
5813 @section @code{gpic}
5823 @node Invoking gpic, , gpic, gpic
5824 @subsection Invoking @code{gpic}
5825 @cindex invoking @code{gpic}
5826 @cindex @code{gpic}, invoking
5831 @node ggrn, grap, gpic, Preprocessors
5832 @section @code{ggrn}
5842 @node Invoking ggrn, , ggrn, ggrn
5843 @subsection Invoking @code{ggrn}
5844 @cindex invoking @code{ggrn}
5845 @cindex @code{ggrn}, invoking
5850 @node grap, grefer, ggrn, Preprocessors
5851 @section @code{grap}
5854 A freely available implementation of @code{grap}, written by Ted Faber,
5855 is available as an extra package from the following address:
5858 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
5862 @node grefer, gsoelim, grap, Preprocessors
5863 @section @code{grefer}
5864 @cindex @code{refer}
5865 @cindex @code{grefer}
5873 @node Invoking grefer, , grefer, grefer
5874 @subsection Invoking @code{grefer}
5875 @cindex invoking @code{grefer}
5876 @cindex @code{grefer}, invoking
5881 @node gsoelim, , grefer, Preprocessors
5882 @section @code{gsoelim}
5883 @cindex @code{soelim}
5884 @cindex @code{gsoelim}
5889 * Invoking gsoelim::
5892 @node Invoking gsoelim, , gsoelim, gsoelim
5893 @subsection Invoking @code{gsoelim}
5894 @cindex invoking @code{gsoelim}
5895 @cindex @code{gsoelim}, invoking
5901 @node Output Devices, File formats, Preprocessors, Top
5902 @chapter Output Devices
5903 @cindex output devices
5904 @cindex devices for output
5909 * Special Characters::
5920 @node Special Characters, grotty, Output Devices, Output Devices
5921 @section Special Characters
5922 @cindex special characters
5923 @cindex characters, special
5930 @node grotty, grops, Special Characters, Output Devices
5931 @section @code{grotty}
5932 @cindex @code{grotty}
5940 @node Invoking grotty, , grotty, grotty
5941 @subsection Invoking @code{grotty}
5942 @cindex invoking @code{grotty}
5943 @cindex @code{grotty}, invoking
5948 @node grops, grodvi, grotty, Output Devices
5949 @section @code{grops}
5950 @cindex @code{grops}
5956 * Embedding PostScript::
5959 @node Invoking grops, Embedding PostScript, grops, grops
5960 @subsection Invoking @code{grops}
5961 @cindex invoking @code{grops}
5962 @cindex @code{grops}, invoking
5966 @node Embedding PostScript, , Invoking grops, grops
5967 @subsection Embedding PostScript
5968 @cindex embedding postscript
5969 @cindex postscript, embedding
5974 @node grodvi, grolj4, grops, Output Devices
5975 @section @code{grodvi}
5976 @cindex @code{grodvi}
5984 @node Invoking grodvi, , grodvi, grodvi
5985 @subsection Invoking @code{grodvi}
5986 @cindex invoking @code{grodvi}
5987 @cindex @code{grodvi}, invoking
5992 @node grolj4, grolbp, grodvi, Output Devices
5993 @section @code{grolj4}
5994 @cindex @code{grolj4}
6002 @node Invoking grolj4, , grolj4, grolj4
6003 @subsection Invoking @code{grolj4}
6004 @cindex invoking @code{grolj4}
6005 @cindex @code{grolj4}, invoking
6010 @node grolbp, grohtml, grolj4, Output Devices
6011 @section @code{grolbp}
6012 @cindex @code{grolbp}
6020 @node Invoking grolbp, , grolbp, grolbp
6021 @subsection Invoking @code{grolbp}
6022 @cindex invoking @code{grolbp}
6023 @cindex @code{grolbp}, invoking
6028 @node grohtml, gxditview, grolbp, Output Devices
6029 @section @code{grohtml}
6030 @cindex @code{grohtml}
6035 * Invoking grohtml::
6038 @node Invoking grohtml, , grohtml, grohtml
6039 @subsection Invoking @code{grohtml}
6040 @cindex invoking @code{grohtml}
6041 @cindex @code{grohtml}, invoking
6046 @node gxditview, , grohtml, Output Devices
6047 @section @code{gxditview}
6048 @cindex @code{gxditview}
6053 * Invoking gxditview::
6056 @node Invoking gxditview, , gxditview, gxditview
6057 @subsection Invoking @code{gxditview}
6058 @cindex invoking @code{gxditview}
6059 @cindex @code{gxditview}, invoking
6066 @node File formats, Installation, Output Devices, Top
6067 @chapter File formats
6068 @cindex file formats
6069 @cindex formats, file
6079 @node gtroff Output, Font Files, File formats, File formats
6080 @section @code{gtroff} Output
6081 @cindex @code{gtroff} output
6082 @cindex output, @code{gtroff}
6084 This section describes the format output of GNU @code{troff}. The
6085 output format used by GNU @code{troff} is very similar to that used by
6086 @sc{Unix} device-independent @code{troff} (@code{ditroff}).
6091 * Drawing Functions::
6092 * Line Continuation::
6095 @node Output Format, Device Control, gtroff Output, gtroff Output
6096 @subsection Output Format
6097 @cindex output format
6098 @cindex format of output
6101 @cindex input, 8-bit
6102 The output format is text based, as opposed to a binary format (like
6103 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
6104 characters can have the eighth bit set, as can the names of fonts and
6107 The output format consists of single command characters with attached
6108 parameters which are separated from subsequent text by whitespace or a
6111 The names of characters and fonts can be of arbitrary length; drivers
6112 should not assume that they will be only two characters long (as
6113 @code{ditroff} does).
6115 When a character is to be printed, that character will always be in the
6116 current font. Unlike @code{ditroff}, it is not necessary for drivers to
6117 search special fonts to find a character.
6132 @item @var{nn}@var{c}
6135 @var{xxx} is any sequence of characters terminated by a space or a
6136 newline; the first character should be printed at the current position,
6137 the the current horizontal position should be increased by the width of
6138 the first character, and so on for each character. The width of the
6139 character is that given in the font file, appropriately scaled for the
6140 current point size, and rounded so that it is a multiple of the
6141 horizontal resolution. Special characters cannot be printed using this
6146 This command is only allowed if the @samp{tcommand} line is present in
6147 the @file{DESC} file.
6148 @item u@var{n} @var{xxx}
6149 This is same as the @samp{t} command except that after printing each
6150 character, the current horizontal position is increased by the sum of
6151 the width of that character and@w{ }@var{n}.
6153 This command is only allowed if the @samp{tcommand} line is present in
6154 the @file{DESC} file.
6155 @item n@var{a}@var{b}
6162 The argument to the @samp{s} command is in scaled points (units of
6163 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
6164 command in the @file{DESC} file).
6169 @item D@var{c} @var{x}@dots{}\n
6173 @node Device Control, Drawing Functions, Output Format, gtroff Output
6174 @subsection Device Control
6175 @cindex device control
6176 @cindex control of devices
6178 The @samp{x} command is normally followed by a letter or word indicating
6179 the function to perform, followed by white space separated arguments.
6181 The first argument can be abbreviated to the first letter.
6188 @item x res @var{n} @var{h} @var{v}
6192 The argument to the @w{@samp{x Height}} command is also in scaled
6196 The first three output commands are guaranteed to be:
6205 For example, the input
6208 crunchy \fH\s+2frog\s0\fP!?
6217 ... sample output here ...
6220 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
6221 @subsection Drawing Functions
6222 @cindex drawing functions
6223 @cindex functions for drawing
6226 The @samp{D} drawing command has been extended. These extensions will
6227 only be used by GNU @code{pic} if the @samp{-x} option is given.
6229 @xref{Drawing Requests}.
6234 Set the shade of gray to be used for filling solid objects to@w{
6235 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
6236 corresponds solid white and 1000 to solid black, and values in between
6237 correspond to intermediate shades of gray. This applies only to solid
6238 circles, solid ellipses and solid polygons. By default, a level of@w{
6239 }1000 will be used. Whatever color a solid object has, it should
6240 completely obscure everything beneath it. A value greater than@w{ }1000
6241 or less than@w{ }0 can also be used: this means fill with the shade of
6242 gray that is currently being used for lines and text. Normally this
6243 will be black, but some drivers may provide a way of changing this.
6245 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
6246 point at the current position.
6247 @item DE @var{dx} @var{dy}
6248 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
6249 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
6251 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
6252 Draw a polygon with. The first vertex is at the current position, the
6253 second vertex at an offset (@var{dx1},@var{dy1}) from the current
6254 position, the second vertex at an offset (@var{dx2},@var{dy2}) from the
6255 first vertex, and so on up to the @var{n}-th vertex. At the moment, GNU
6256 @code{pic} only uses this command to generate triangles and rectangles.
6257 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
6258 Like @code{Dp} but draw a solid rather than outlined polygon.
6260 @cindex line thickness
6261 @cindex thickness of lines
6262 Set the current line thickness to @var{n}@w{ }machine units.
6263 Traditionally, @sc{Unix} @code{troff} drivers use a line thickness
6264 proportional to the current point size; drivers should continue to do
6265 this if no @code{Dt} command has been given, or if a @code{Dt} command
6266 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
6267 }@var{n} selects the smallest available line thickness.
6271 A difficulty arises in how the current position should be changed after
6272 the execution of these commands. This is not of great importance since
6273 the code generated by GNU @code{pic} does not depend on this. Given a
6274 drawing command of the form
6277 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
6284 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
6285 @samp{~}, @sc{Unix} @code{troff} will treat each of the x@w{ }value as a
6286 horizontal quantity, and each of the y@w{ }values as a vertical quantity
6287 and will assume that the width of the drawn object is sum if all x@w{
6288 }values, and that the height is the sum of all y@w{ }values. (The
6289 assumption about the height can be seen by examining the @code{st} and
6290 @code{sb} registers after using such a @code{D}@w{ }command in a
6291 @code{\w} escape sequence.) This rule also holds for all the original
6292 drawing commands with the exception of @code{De}. For the sake of
6293 compatibility GNU @code{troff} also follows this rule, even though it
6294 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
6295 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
6296 @code{D}@w{ }command of the form
6299 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
6303 the current position should be increased horizontally by the sum of all
6304 x@w{ }values and vertically by the sum of all y@w{ }values.
6306 @node Line Continuation, , Drawing Functions, gtroff Output
6307 @subsection Line Continuation
6308 @cindex line continuation in output commands
6309 @cindex output commands, line continuation
6311 There is a continuation convention which permits the argument to the
6312 @w{@samp{x X}} command to contain newlines: When outputting the argument
6313 to the @w{@samp{x X}} command, GNU @code{troff} will follow each newline
6314 in the argument with a @samp{+} character (as usual, it will terminate
6315 the entire argument with a newline); thus if the line after the line
6316 containing the @w{@samp{x X}} command starts with @samp{+}, then the
6317 newline ending the line containing the @w{@samp{x X}} command should be
6318 treated as part of the argument to the @w{@samp{x X}} command, the
6319 @samp{+} should be ignored, and the part of the line following the
6320 @samp{+} should be treated like the part of the line following the
6321 @w{@samp{x X}} command.
6324 @node Font Files, , gtroff Output, File formats
6329 The @code{gtroff} font format is roughly a superset of the
6330 @code{ditroff} font format. Unlike the @code{ditroff} font format,
6331 there is no associated binary format; all files are text files. The
6332 font files for device @var{name} are stored in a directory
6333 @file{dev@var{name}}. There are two types of file: a device description
6334 file called @file{DESC} and for each font@w{ }@samp{F} a font file
6335 called@w{ }@file{F}.
6338 * DESC file format::
6339 * Font file format::
6342 @node DESC file format, Font file format, Font Files, Font Files
6343 @subsection @file{DESC} file format
6344 @cindex @file{DESC} file format
6345 @cindex font description file format
6346 @cindex format of font description file
6349 The @file{DESC} file can contain the following types of line:
6354 There are @var{n} machine units per inch.
6357 The horizontal resolution is @var{n} machine units.
6360 The vertical resolution is @var{n} machine units.
6362 @item sizescale @var{n}
6363 The scale factor for point sizes. By default this has a value of@w{ }1.
6364 One scaled point is equal to one point/@var{n}. The arguments to the
6365 @code{unitwidth} and @code{sizes} commands are given in scaled points.
6366 @xref{Fractional Type Sizes}, for more information.
6368 @item unitwidth @var{n}
6369 Quantities in the font files are given in machine units for fonts whose
6370 point size is @var{n}@w{ }scaled points.
6373 This means that the postprocessor can handle the @samp{t} and @samp{u}
6376 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
6377 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
6378 @var{sn} scaled points. The list of sizes must be terminated by a@w{
6379 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
6380 list can extend over more than one line.
6382 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
6383 The first @var{m}@w{ }font positions will be associated with styles
6384 @var{S1} @dots{} @var{Sm}.
6386 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
6387 Fonts @var{F1} @dots{} @var{Fn} will be mounted in the font positions
6388 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
6389 styles. This command may extend over more than one line. A font name
6390 of@var{ }0 will cause no font to be mounted on the corresponding font
6393 @item family @var{fam}
6394 The default font family is @var{fam}.
6397 This line and everything following in the file are ignored. It is
6398 allowed for the sake of backwards compatibility.
6401 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
6402 are compulsory. Other commands are ignored by @code{gtroff} but may be
6403 used by postprocessors to store arbitrary information about the device
6404 in the @file{DESC} file.
6406 @c XXX add other commands resp. xrefs to output devices
6407 @c XXX add obsolete commands
6409 @node Font file format, , DESC file format, Font Files
6410 @subsection Font file format
6411 @cindex font file format
6412 @cindex format of font files
6414 A font file has two sections. The first section is a sequence of lines
6415 each containing a sequence of blank delimited words; the first word in
6416 the line is a key, and subsequent words give a value for that key.
6421 The name of the font is@w{ }@var{F}.
6423 @item spacewidth @var{n}
6424 The normal width of a space is@w{ }@var{n}.
6427 The characters of the font have a slant of @var{n}@w{ }degrees.
6428 (Positive means forward.)
6430 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
6431 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
6432 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
6433 @samp{ffl}. For backwards compatibility, the list of ligatures may be
6434 terminated with a@w{ }0. The list of ligatures may not extend over more
6438 The font is special; this means that when a character is requested that
6439 is not present in the current font, it will be searched for in any
6440 special fonts that are mounted.
6443 Other commands are ignored by @code{gtroff} but may be used by
6444 postprocessors to store arbitrary information about the font in the font
6447 @cindex comments in font files
6448 @cindex font files, comments
6450 The first section can contain comments which start with the @samp{#}
6451 character and extend to the end of a line.
6453 The second section contains one or two subsections. It must contain a
6454 @code{charset} subsection and it may also contain a @code{kernpairs}
6455 subsection. These subsections can appear in any order. Each
6456 subsection starts with a word on a line by itself.
6459 The word @code{charset} starts the character set subsection. The
6460 @code{charset} line is followed by a sequence of lines. Each line gives
6461 information for one character. A line comprises a number of fields
6462 separated by blanks or tabs. The format is
6464 @c XXX fix it for new HTML additions
6467 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
6471 @cindex input, 8-bit
6475 @var{name} identifies the character: If @var{name} is a single
6476 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
6477 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
6478 a single character, then it corresponds to the @code{gtroff} input
6479 character@w{ }\@var{c}; otherwise it corresponds to the groff input
6480 character @samp{\[@var{name}]}. (If it is exactly two characters
6481 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
6482 supports 8-bit characters; however some utilities have difficulties with
6483 eight-bit characters. For this reason, there is a convention that the
6484 name @samp{char@var{n}} is equivalent to the single character whose code
6485 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
6486 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
6487 Latin-1} character set. The name @samp{---} is special and indicates
6488 that the character is unnamed; such characters can only be used by means
6489 of the @code{\N} escape sequence in troff.
6491 @c XXX input encodings vs. output encodings
6493 The @var{type} field gives the character type:
6497 the character has an descender, for example, `p';
6499 the character has an ascender, for example, `b';
6501 the character has both an ascender and a descender, for example, `('.
6504 The @var{code} field gives the code which the postprocessor uses to
6505 print the character. The character can also be input to @code{gtroff}
6506 using this code by means of the @code{\N} escape sequence. The code can
6507 be any integer. If it starts with @samp{0} it will be interpreted as
6508 octal; if it starts with @samp{0x} or @samp{0X} it will be interpreted as
6511 Anything on the line after the @var{code} field will be ignored.
6513 The @var{metrics} field has the form:
6516 @var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]}
6519 There must not be any spaces between these subfields. Missing subfields
6520 are assumed to be@w{ }0. The subfields are all decimal integers. Since
6521 there is no associated binary format, these values are not required to
6522 fit into a variable of type @samp{char} as they are in @code{ditroff}.
6523 The @var{width} subfield gives the width of the character. The
6524 @var{height} subfield gives the height of the character (upwards is
6525 positive); if a character does not extend above the baseline, it should
6526 be given a zero height, rather than a negative height. The @var{depth}
6527 subfield gives the depth of the character, that is, the distance below
6528 the lowest point below the baseline to which the character extends
6529 (downwards is positive); if a character does not extend below above the
6530 baseline, it should be given a zero depth, rather than a negative depth.
6531 The @var{italic_correction} subfield gives the amount of space that
6532 should be added after the character when it is immediately to be
6533 followed by a character from a Roman font. The
6534 @var{left_italic_correction} subfield gives the amount of space that
6535 should be added before the character when it is immediately to be
6536 preceded by a character from a Roman font. The
6537 @var{subscript_correction} gives the amount of space that should be
6538 added after a character before adding a subscript. This should be less
6539 than the italic correction.
6541 A line in the @code{charset} section can also have the format
6548 This indicates that @var{name} is just another name for the character
6549 mentioned in the preceding line.
6552 The word @code{kernpairs} starts the kernpairs section. This contains a
6553 sequence of lines of the form:
6556 @var{c1} @var{c2} @var{n}
6559 This means that when character @var{c1} appears next to character
6560 @var{c2} the space between them should be increased by@w{ }@var{n}.
6561 Most entries in kernpairs section will have a negative value for@w{
6566 @node Installation, Request and Operator Index, File formats, Top
6567 @chapter Installation
6568 @cindex installation
6574 @node Request and Operator Index, Register Index, Installation, Top
6575 @chapter Request and Operator Index
6581 @node Register Index, Font File Keyword Index, Request and Operator Index, Top
6582 @chapter Register Index
6588 @node Font File Keyword Index, Program and File Index, Register Index, Top
6589 @chapter Font File Keyword Index
6595 @node Program and File Index, Concept Index, Font File Keyword Index, Top
6596 @chapter Program and File Index
6602 @node Concept Index, , Program and File Index, Top
6603 @chapter Concept Index