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 graphics display to do any operations on a
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, it
736 is possible to perform a wide range of formatting tasks, such as
737 footnotes, table 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 to specify how certain routine operations (e.g.@w{
788 }starting paragraphs, printing headers and footers, etc.)@: should be
789 done. These macros can be collected together into a @dfn{macro
790 package}. There are a number of macro packages available; the most
791 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 can be
913 seen, 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 @code{gtroff} numeric
1059 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1060 name of the device) for the @file{DESC} file and font files before the
1063 Search directory @var{dir} for macro files before the normal directory.
1065 This option is as described in @ref{gsoelim}. It implies the @samp{-s}
1070 @node Environment, Invocation Examples, Options, Invoking groff
1071 @section Environment
1072 @cindex environment variables
1073 @cindex variables in environment
1075 There are also several environment variables which can modify the
1076 behavior of @code{groff}.
1079 @item GROFF_COMMAND_PREFIX
1080 @tindex GROFF_COMMAND_PREFIX
1081 If this is set to @var{X}, then @code{groff} will run
1082 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1083 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1084 @code{soelim}. It does not apply to @code{grops}, @code{grodvi},
1085 @code{grotty}, @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1086 @item GROFF_TMAC_PATH
1087 @tindex GROFF_TMAC_PATH
1088 A colon separated list of directories in which to search for macro
1090 @item GROFF_TYPESETTER
1091 @tindex GROFF_TYPESETTER
1092 The default output device.
1093 @item GROFF_FONT_PATH
1094 @tindex GROFF_FONT_PATH
1095 A colon separated list of directories in which to search for the
1096 @code{dev}@var{name} directory.
1099 The search path for commands executed by @code{groff}.
1101 @tindex GROFF_TMPDIR
1103 The directory in which temporary files will be created. If this is not
1104 set and @code{TMPDIR} is set, temporary files will be created in that
1105 directory. Otherwise temporary files will be created in @code{/tmp}.
1106 The @code{grops} and @code{grefer} commands can create temporary files.
1110 @node Invocation Examples, , Environment, Invoking groff
1111 @section Invocation Examples
1112 @cindex invocation examples
1113 @cindex examples of invocation
1115 This section will list several common uses of @code{groff} and the
1116 command line which will accomplish it.
1123 This command processes @var{file} without a macro package or a
1124 preprocessor. The output device is the default, @var{ps}, and the
1125 output is sent to stdout.
1128 groff -t -mandoc -Tascii file | less
1132 This is basically what a call to @code{man} does. The manual page
1133 @var{file} is processed with the @code{-mandoc} macros (which in turn
1134 either call the @code{-man} or the @code{-mdoc} macro package), using
1135 the @code{tbl} preprocessor and the @sc{ascii} output device. Finally,
1136 the result is displayed with the @code{less} pager.
1143 Preview @var{file} with @code{gxditview}, using the @code{-me} macro
1147 groff -man -rD1 -z file
1151 Check @var{file} with the @code{-man} macro package, forcing
1152 double-sided printing---don't produce any output.
1154 @subsection @code{grog}
1156 @code{grog} reads files and guesses which of the @code{groff}
1157 preprocessors and/or macro packages are are required for formatting
1158 them, and prints the @code{groff} command including those options on the
1159 standard output. The options generated are one of @samp{-e},
1160 @samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-R},
1161 @samp{-g}, @samp{-s}, and @samp{-t}.
1163 A filename of @samp{-} is taken to refer to the standard input. If no
1164 files are specified the standard input will be read. Any specified
1165 options will be included in the printed command. No space is allowed
1166 between options and their arguments. For example,
1173 will guess the appropriate command to print @file{paper.ms} and then
1174 print it to the command line after adding the @samp{-Tdvi} option. For
1175 direct execution, enclose the call to @code{grog} in backquotes on the
1176 @sc{Unix} shell prompt:
1179 `grog -Tdvi paper.ms` > paper.dvi
1183 As seen in the example, it is still necessary to redirect the output to
1184 something meaningful (i.e.@: either a file or a pager program like
1189 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1190 @chapter Tutorial for Macro Users
1191 @cindex tutorial for macro users
1192 @cindex macro tutorial for users
1193 @cindex user's tutorial for macros
1194 @cindex user's macro tutorial
1196 Most users tend to use a macro package to format their papers. This
1197 means that the whole breadth of @code{groff} is not necessary for most
1198 people. This chapter covers the material needed to efficiently use a
1207 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1211 This section covers some of the basic concepts necessary to understand
1212 how to use a macro package.@footnote{This section is derived from
1213 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1214 References are made throughout to more detailed information, if desired.
1216 @code{gtroff} reads an input file prepared by the user and outputs a
1217 formatted paper suitable for publication or framing. The input consists
1218 of text, or words to be printed, and embedded commands (@dfn{requests}
1219 and @dfn{escapes}), which tell @code{gtroff} how to format the printed
1220 copy. For more detail on this @pxref{Embedded Commands}.
1222 The word @dfn{argument} is used in this manual to mean a word or number
1223 which appears on the same line as a request which modifies the meaning
1224 of that request. For example, the request
1231 spaces one line, but
1238 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1239 request which says to space four lines instead of one. Arguments are
1240 separated from the request and from each other by spaces. More details
1241 on this can be found in @ref{Request Arguments}.
1243 The primary function of @code{gtroff} is to collect words from input
1244 lines, fill output lines with those words, justify the right hand margin
1245 by inserting extra spaces in the line, and output the result. For
1253 Four score and seven
1258 will be read, packed onto output lines, and justified to produce:
1261 Now is the time for all good men to come to the aid of their party.
1262 Four score and seven years ago,...
1267 Sometimes a new output line should be started even though the current
1268 line is not yet full; for example, at the end of a paragraph. To do
1269 this it is possible to cause a @dfn{break}, which starts a new output
1270 line. Some requests cause a break automatically, as do blank input
1271 lines and input lines beginning with a space.
1273 Not all input lines are text to be formatted. Some of the input lines
1274 are requests which describe how to format the text. Requests always
1275 have a period or an apostrophe (@samp{'}) as the first character of the
1278 The text formatter also does more complex things, such as automatically
1279 numbering pages, skipping over page boundaries putting footnotes in the
1280 correct place, and so forth.
1282 Here a few hints for preparing text for input to @code{gtroff}. First,
1283 keep the input lines short. Short input lines are easier to edit, and
1284 @code{gtroff} will pack words onto longer lines anyhow. In keeping with
1285 this, it is helpful to begin a new line after every period, comma, or
1286 phrase, since common corrections are to add or delete sentences or
1287 phrases. Secondly, do not hyphenate words at the end of
1288 lines---@code{gtroff} is smart enough to hyphenate words for the user as
1289 needed, but is not smart enough to take hyphens out and join a word back
1290 together. Also, words such as ``mother-in-law'' should not be broken
1291 over a line, since then a space can occur where not wanted, such as
1292 ``@w{mother- in}-law''.
1295 @cindex double spacing
1297 @code{gtroff} will double space output text automatically if using the
1298 request @w{@samp{.ls 2}}. Single spaced mode can be reactivated by
1299 typing @w{@samp{.ls 1}}.
1301 A number of requests allow to change the way the printed copy looks,
1302 sometimes called the @dfn{layout} of the output page. Most of these
1303 requests adjust the placing of @dfn{white space} (blank lines or
1308 The @samp{.bp} request starts a new page.
1313 @cindex lines, empty
1314 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1315 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1316 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1317 @var{N}@w{ }centimeters). For example, the input:
1321 My thoughts on the subject
1326 leaves one and a half inches of space, followed by the line ``My
1327 thoughts on the subject'', followed by a single blank line.
1330 @cindex centering lines
1331 @cindex lines, centering
1332 Text lines can be centered by using the @code{ce} request. The line
1333 after @code{ce} is centered (horizontally) on the page. To center more
1334 than one line, use @w{@code{.ce @var{N}}} (where @var{N} is the number
1335 of lines to center), followed by the @var{N}@w{ }lines. To center many
1336 lines without counting them, type:
1345 The @w{@samp{ce 0}} request tells @code{groff} to center zero more
1346 lines, in other words, stop centering.
1351 All of these requests cause a break; that is, they always start a new
1352 line. To start a new line without performing any other action, use
1356 @node Common Features, , Basics, Tutorial for Macro Users
1357 @section Common Features
1358 @cindex common features
1359 @cindex features, common
1361 @code{gtroff} provides very low level operations for formatting a
1362 document. There are many common routine operations which are done in
1363 all documents. These common operations are written into @dfn{macros}
1364 and collected into a @dfn{macro package}.
1366 All macro packages provide certain common capabilities which fall into
1367 the following categories.
1369 @subsection Paragraphs
1372 One of the most common and most used capability is starting a paragraph.
1373 There are a number of different types of paragraphs, any of which can be
1374 initiated with macros supplied by the macro package. Normally,
1375 paragraphs start with a blank line and the first line indented, like the
1376 text in this manual. There are also block style paragraphs, which omit
1380 Some men look at constitutions with sanctimonious
1381 reverence, and deem them like the ark of the covenant, too
1382 sacred to be touched.
1386 And there are also indented paragraphs which begin with a tag or label
1387 at the margin and the remaining text indented.
1390 one This is the first paragraph. Notice how the first
1391 line of the resulting paragraph lines up with the
1392 other lines in the paragraph.
1394 This paragraph had a long label. The first
1395 character of text on the first line will not line up
1396 with the text on second and subsequent lines,
1397 although they will line up with each other.
1400 A variation of this is a bulleted list.
1403 @subsection Sections and Chapters
1405 Most macro packages supply some form of section headers. The simplest
1406 kind is simply the heading on a line by itself in bold type. Others
1407 supply automatically numbered section heading or different heading
1408 styles at different levels. Some, more sophisticated, macro packages
1409 supply macros for starting chapters and appendices.
1411 @subsection Headers and Footers
1413 Every macro packages gives some way to manipulate the headers and
1414 footers (or @dfn{titles}) on each page. Some packages will allow for
1415 different ones on the even and odd pages (for material printed in a book
1418 The titles are called three-part titles, that is, there is a
1419 left-justified part, a centered part, and a right-justified part. An
1420 automatically generated page number may be put in any of these fields
1421 with the @samp{%} character (@pxref{Page Layout} for more details).
1423 @subsection Page Layout
1425 Most macro packages let thte user specify top and bottom margins and
1426 other details about the appearance of the printed pages.
1428 @subsection Displays
1431 Displays are sections of text to be set off from the body of the paper.
1432 Major quotes, tables, and figures are types of displays, as are all the
1433 examples used in this document.
1435 @cindex quotes, major
1436 @cindex major quotes
1437 @dfn{Major quotes} are quotes which are several lines long, and hence
1438 are set in from the rest of the text without quote marks around them.
1441 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1442 should be used when the material to be printed should not be filled and
1443 justified like normal text, such as columns of figures or the examples
1447 A @dfn{keep} is a display of lines which are kept on a single page if
1448 possible. An example for a keep might be a diagram. Keeps differ from
1449 lists in that lists may be broken over a page boundary whereas keeps
1452 @cindex keep, floating
1453 @cindex floating keep
1454 Floating keeps move relative to the text. Hence, they are good for
1455 things which will be referred to by name, such as ``See figure@w{ }3''.
1456 A floating keep will appear at the bottom of the current page if it will
1457 fit; otherwise, it will appear at the top of the next page. Meanwhile,
1458 the surrounding text will `flow' around the keep, thus leaving now blank
1461 @subsection Footnotes and annotations
1465 There are a number of requests to save text for later printing.
1466 @dfn{Footnotes} are printed at the bottom of the current page. Delayed
1467 text is intended to be a variant form of footnote; the text is printed
1468 only when explicitly called for, such as at the end of each chapter.
1470 @cindex delayed text
1471 @dfn{Delayed text} is very similar to a footnote except that it is
1472 printed when called for explicitly. This allows a list of references to
1473 appear (for example) at the end of each chapter, as is the convention in
1476 Most macro packages which supply this functionality also supply a means
1477 of automatically numbering either type of annotation.
1479 @subsection Table of Contents
1480 @cindex table of contents
1481 @cindex contents, table of
1483 @dfn{Tables of contents} are a type of delayed text having a tag
1484 (usually the page number) attached to each entry after a row of dots.
1485 The table accumulates throughout the paper until printed, usually after
1486 the paper has ended. Many macro packages will provide the ability to
1487 have several tables of contents (i.e.@: one standard one, one for
1493 While some macro packages will use the term @dfn{index}, none actually
1494 provide that functionality. The facilities they call indices are
1495 actually more appropriate for tables of contents.
1497 @subsection Paper formats
1498 @cindex paper formats
1500 Some macro packages provide stock formats for various kinds of
1501 documents. Many of them provide a common format for the title and
1502 opening pages of a technical paper. The @code{-mm} macros in particular
1503 provide formats for letters and memoranda.
1505 @subsection Multiple Columns
1507 Some macro packages (except @code{-man}) provide the ability to have two
1508 or more columns on a page.
1510 @subsection Font and Size changes
1512 The built-in font and size functions are not always intuitive, so all
1513 macro packages provide macros to make these operations simpler.
1515 @subsection Predefined Strings
1517 Most macro packages provide various predefined strings for a variety of
1518 uses, examples are sub- and superscripts, printable dates, quotes and
1519 various special characters.
1521 @subsection Preprocessor Support
1523 All macro packages provide support for the various preprocessors.
1525 @subsection Configuration and Customization
1527 Some macro packages provide means of customizing many of details of how
1528 the package behaves. This ranges from setting the default type size to
1529 changing the appearance of section headers.
1533 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1534 @chapter Macro Packages
1535 @cindex macro packages
1536 @cindex packages, macros
1538 This chapter documents the main macro packages that come with
1550 @node -man, -mdoc, Macro Packages, Macro Packages
1554 @c XXX documentation
1557 @node -mdoc, -ms, -man, Macro Packages
1559 @cindex @code{-mdoc}
1561 @c XXX documentation
1564 @node -ms, -me, -mdoc, Macro Packages
1568 @c XXX documentation
1571 @node -me, -mm, -ms, Macro Packages
1575 @c XXX documentation
1578 @node -mm, , -me, Macro Packages
1582 @c XXX documentation
1586 @node Programming Tutorial, Preprocessors, Macro Packages, Top
1587 @chapter Programming Tutorial
1588 @cindex programming tutorial
1589 @cindex tutorial for programming
1591 This chapter covers @strong{all} of the facilities of @code{gtroff}.
1592 Users of macro packages may skip it.
1597 * Input Conventions::
1601 * Embedded Commands::
1603 * Manipulating Filling and Adjusting::
1604 * Manipulating Hyphenation::
1605 * Manipulating Spacing::
1607 * Character Translations::
1614 * Conditionals and Loops::
1617 * Drawing Requests::
1622 * Postprocessor Access::
1625 * Implementation Differences::
1630 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
1634 @code{gtroff} input files contain text with control commands
1635 interspersed throughout. But, even without control codes, @code{gtroff}
1636 will still do several things the input text: filling and adjusting,
1637 adding additional space after sentences, hyphenating and inserting
1638 implicit line breaks.
1641 * Filling and Adjusting::
1645 * Implicit Line Breaks::
1648 @node Filling and Adjusting, Hyphenation, Text, Text
1649 @subsection Filling and Adjusting
1650 @cindex filling and adjusting
1651 @cindex adjusting and filling
1653 When @code{gtroff} reads in text it collects words from input and fits
1654 as many of them together on one output line as it can. This is known as
1657 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
1658 it. Which means it will widen the spacing between words until the text
1659 reaches the right margin (in the default adjustment mode). Extra spaces
1660 between words are preserved, but spaces at the end of lines are ignored.
1661 Spaces at the front of a line will cause a @dfn{break} (breaks will be
1662 explained in @ref{Implicit Line Breaks})
1664 @xref{Manipulating Filling and Adjusting}.
1666 @node Hyphenation, Sentences, Filling and Adjusting, Text
1667 @subsection Hyphenation
1670 Since the odds of finding a set of words, for every output line, which
1671 will fit nicely on a line without inserting excessive amounts of space
1672 between words is not great, @code{gtroff} will hyphenate words so that
1673 lines can be justified without there being too much space between words.
1674 It uses an internal hyphenation algorithm, to indicate which words can
1675 be hyphenated and how to do so. When a word is hyphenated the first
1676 part of the word will be added to the current filled line being output
1677 (with an attached hyphen), and the other portion will be added to the
1678 next line to be filled.
1680 @xref{Manipulating Hyphenation}.
1682 @node Sentences, Tab Stops, Hyphenation, Text
1683 @subsection Sentences
1686 Although it is often debated, some typesetting rules say there should be
1687 different amounts of space after various punctuation marks. For example,
1688 a period at the end of a sentence should have twice as much space
1689 following it as would a comma or a period as part of an abbreviation.
1691 @cindex sentence spaces
1692 @cindex spaces between sentences
1693 @cindex french-spacing
1694 @code{gtroff} does this by flagging certain characters (normally
1695 @samp{!}, @samp{?} and @samp{.}) as @dfn{end of sentence} characters.
1696 When @code{gtroff} encounters one of these characters at the end of a
1697 line it will append two @dfn{sentence spaces} in the formatted output.
1698 (Thus, one of the conventions mentioned in @ref{Input Conventions}).
1700 @c XXX also describe how characters like ) are treated here -jjc
1701 @c gotta do some research on this -trent
1703 @node Tab Stops, Implicit Line Breaks, Sentences, Text
1704 @subsection Tab Stops
1706 @cindex stops, tabulator
1708 @code{gtroff} translates @dfn{tabulator stops}, also called @dfn{tabs},
1709 in the input into movements to the next tab stop. These tab stops are
1710 initially located every half inch across the page. Using this simple
1711 tables can easily be made. However, this can often be deceptive as the
1712 appearance (and width) of the text on a terminal and the results from
1713 @code{gtroff} can vary greatly.
1715 Also, a possible sticking point is that lines beginning with tab
1716 characters will still be filled, again producing unexpected results.
1717 For example, the following input
1719 @multitable {12345678} {12345678} {12345678} {12345678}
1721 @tab 1 @tab 2 @tab 3
1729 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
1731 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
1734 @xref{Tabs and Fields}.
1736 @node Implicit Line Breaks, , Tab Stops, Text
1737 @subsection Implicit Line Breaks
1738 @cindex implicit line breaks
1739 @cindex implicit breaks of lines
1740 @cindex line, implicit breaks
1742 @cindex break, implicit
1745 An important concept in @code{gtroff} is the @dfn{break}. When a break
1746 occurs, @code{gtroff} will output the partially filled line
1747 (unadjusted), and resume collecting and filling text on the next output
1753 There are several ways to cause a break in @code{gtroff}. A blank line
1754 will not only cause a break, but it will also cause a one line vertical
1755 space (effectively a blank line) to be output.
1757 A line which begins with a space will cause a break and the space will
1758 be output at the beginning of the next line. Note that this space isn't
1759 adjusted, even in fill mode.
1761 The end of file will also cause a break (otherwise the last line of the
1762 document may vanish!)
1764 Certain requests also cause breaks, implicitly or explicity. This will
1767 @xref{Manipulating Filling and Adjusting}.
1770 @node Input Conventions, Measurements, Text, Programming Tutorial
1771 @section Input Conventions
1772 @cindex input conventions
1773 @cindex conventions for input
1775 Since @code{gtroff} does filling automatically, it is traditional in
1776 @code{groff} not to try and type things in as nicely formatted
1777 paragraphs. These are some conventions commonly used when typing
1782 Break lines after punctuation, particularly at the end of sentences,
1783 and in other logical places. Keep separate phrases on lines by
1784 themselves, as entire phrases are often added or deleted when editing.
1786 Try to keep lines less than 40-60@w{ }characters, to allow space for
1787 inserting more text.
1789 Do not try to do any formatting in a WYSIWYG manner (i.e.@: don't try
1790 and use spaces to get proper indentation).
1794 @node Measurements, Expressions, Input Conventions, Programming Tutorial
1795 @section Measurements
1796 @cindex measurements
1798 @cindex units of measurement
1800 @cindex machine units
1801 @cindex measurement units
1802 @code{gtroff} (like any other programs) requires numeric parameters to
1803 specify various measurements. Most numeric parameters@footnote{those
1804 that specify vertical or horizontal motion or a type size} may have a
1805 @dfn{measurement unit} attached. These units are specified as a single
1806 character which immediately follows the number or expression. Each of
1807 these units are understood, by @code{gtroff}, to be a multiple of its
1808 @dfn{basic unit}. So, whenever a different measurement unit is
1809 specified @code{gtroff} converts this into its @dfn{basic units}. This
1810 basic unit, represented by a @samp{u}, is a device dependent measurement
1811 which is quite small, ranging from 1/75th to 1/72000th of an inch; all
1812 other units are converted eventually to basic units. The values may be
1813 given as fractional numbers---nevertheless, fractional basic units are
1814 always rounded to integers.
1816 Some of the measurement units are completely independent of any of the
1817 current settings (e.g.@: type size) of @code{gtroff}.
1822 @cindex @code{i} unit
1823 @cindex unit, @code{i}
1824 Inches. An antiquated measurement unit still in use in certain
1825 backwards countries. One inch is equal to 2.54@dmn{cm}.
1828 @cindex @code{c} unit
1829 @cindex unit, @code{c}
1830 Centimeters. One centimeter is equal to 0.3937@dmn{in}.
1833 @cindex @code{p} unit
1834 @cindex unit, @code{p}
1835 Points. This is a typesetter's measurement used for measure type size.
1836 It is 72@w{ }points to an inch.
1839 @cindex @code{P} unit
1840 @cindex unit, @code{P}
1841 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
1842 12@w{ }points to a pica).
1845 @cindex @code{s} unit
1846 @cindex unit, @code{s}
1847 @cindex @code{z} unit
1848 @cindex unit, @code{z}
1849 @xref{Fractional Type Sizes}, for a discussion of these units.
1852 The other measurements understood by @code{gtroff} are dependent on
1853 settings currently in effect in @code{gtroff}. These are very useful
1854 for specifying measurements which should look proper with any size of
1860 @cindex @code{m} unit
1861 @cindex unit, @code{m}
1862 Ems. This unit is equal to the current font size in points. So called
1863 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
1864 in the current font.
1867 @cindex @code{n} unit
1868 @cindex unit, @code{n}
1869 Ens. This is half of an em.
1871 @cindex vertical space
1872 @cindex space, vertical
1873 @cindex @code{v} unit
1874 @cindex unit, @code{v}
1875 Vertical space. This is equivalent to the current line spacing.
1876 @xref{Sizes}, for more information about this.
1878 @cindex @code{M} unit
1879 @cindex unit, @code{M}
1883 @xref{Fractional Type Sizes}.
1889 @node Default Units, , Measurements, Measurements
1890 @subsection Default Units
1891 @cindex default units
1892 @cindex units, default
1894 Many requests take a default unit. While this can be helpful at times,
1895 it can cause strange errors in some expressions. For example, the line
1896 length request expects em's. Here are several attempts to get a line
1897 length of 3.5@w{ }inches and the results:
1904 7i/2u @result{} 3.5i
1908 As shown in the example, the safest way to specify measurements is to
1909 always attach a scaling indicator.
1912 @node Expressions, Identifiers, Measurements, Programming Tutorial
1913 @section Expressions
1916 @code{gtroff} has most of operators common to other languages:
1918 @c XXX more details; examples
1922 @cindex arithmetic operators
1923 @cindex operators, arithmetic
1929 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
1930 (division), @samp{*} (multiplication), @samp{%} (modulo).
1932 @cindex comparison operators
1933 @cindex operators, comparison
1940 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
1941 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
1942 (equal), @samp{==} (the same as @samp{=}).
1944 @cindex logical operators
1945 @cindex operators, logical
1948 Logical: @samp{&} (logical and), @samp{:} (logical or).
1950 @cindex unary operators
1951 @cindex operators, unary
1955 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
1956 (just for completeness; does nothing in expressions), @samp{!} (logical
1957 not). See below for the use of unary operators in motion requests.
1958 @c XXX (if/while only??)
1960 @cindex extremum operators
1961 @cindex operators, extremum
1964 Extremum: @samp{>?} (maximum), @samp{<?} (minimum). For example,
1965 @samp{5>?3} yields@w{ }@samp{5}.
1968 @cindex scaling operator
1969 @cindex operator, scaling
1970 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
1971 the default scaling indicator. If @var{c} is missing, ignore scaling
1972 indicators in the evaluation of @var{e}.
1978 Parentheses may be used as in any other language. However, in
1979 @code{gtroff} they are necessary to ensure order of evaluation.
1980 @code{gtroff} has no operator precedence; expressions are evaluated left
1981 to right. This means that @samp{3+5*4} is evaluated as if it were
1982 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as expected.
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
2011 Like any other language, @code{gtroff} has rules for properly formed
2012 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
2013 almost any printable character. The exception are the following
2017 @cindex whitespace characters
2018 @cindex newline character
2019 @cindex character, whitespace
2021 Whitespace characters (space, tabs, and newlines).
2022 @cindex character, backspace
2023 @cindex backspace character
2025 Backspace (@code{0x08}) and character code @code{0x01}.
2026 @cindex illegal input characters
2027 @cindex input characters, illegal
2028 @cindex characters, illegal input
2031 The following input characters are illegal and will be ignored, causing
2032 a warning message: @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
2033 @code{0x80}-@code{0x9F}. Currently, some of these reserved codepoints
2034 are used internally, thus making it non-trivial to extend @code{gtroff}
2035 to cover Unicode or other character sets resp.@: encodings which use
2036 characters of these ranges.
2038 Note that illegal characters will be removed before parsing; an
2039 identifier `foo', followed by an illegal character, followed by `bar'
2040 will be treated as `foobar'.
2043 For example, any of the following is valid.
2054 Note that identifiers longer than two characters with a closing bracket
2055 (@samp{]}) in its name can't be accessed with escape sequences which
2056 expect an identifier as a parameter.
2060 @deffn Escape \A ident
2061 Whether an identifier @var{ident} is valid in @code{gtroff} can be
2062 tested with the @code{\A} escape. It expands to the character@w{ }1
2063 or@w{ }0 according to whether its argument (given in quotes) is or is
2064 not acceptable as the name of a string, macro, diversion, number
2065 register, environment, or font. It will return@w{ }0 if no argument is
2066 given. This is useful for looking up user input in some sort of
2075 @c XXX add xrefs above
2077 Identifiers in @code{gtroff} can be any length, but, in some contexts,
2078 @code{gtroff} needs to be told where identifiers end and text begins
2079 (and in different ways depending on their length).
2088 Two characters. Must be prefixed with @samp{(} in some situations.
2090 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
2091 and@w{ }@samp{]} in some situations. Any length identifier can be put
2095 @cindex undefined identifiers
2096 @cindex indentifiers, undefined
2097 Unlike many other programming languages, undefined identifiers are
2098 silently ignored or expanded to nothing.
2100 @c XXX add info about -ww command line option.
2102 @xref{Interpolating Registers}, and @ref{Strings}.
2105 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
2106 @section Embedded Commands
2107 @cindex embedded commands
2108 @cindex commands, embedded
2110 Most documents need more functionality beyond filling, adjusting and
2111 implicit line breaking. In order to gain further functionality,
2112 @code{gtroff} allows commands to be embedded into the text, in two ways.
2114 The first is a @dfn{request} which takes up an entire line, and does
2115 some large scale operation (e.g.@: break lines, start new pages).
2117 The other is an @dfn{escape} which can be embedded anywhere in the text,
2118 or even as an argument to a request.
2119 @c XXX (Not always?)
2120 Escapes generally do more minor operations like sub- and superscripts,
2121 print a symbol, etc.
2129 @node Requests, Macros, Embedded Commands, Embedded Commands
2130 @subsection Requests
2133 @cindex control character
2134 @cindex character, control
2137 A request line begins with a control character, which is either a single
2138 quote (@samp{'}) or a period (@samp{.}). These can be changed;
2139 @xref{Character Translations}, for details. After this there may be
2140 optional tabs or spaces followed by an identifier which is the name of
2141 the request. This may be followed by any number of space-separated
2144 @cindex zero width space character
2145 @cindex character, zero width space
2146 @cindex space character, zero width
2148 To begin a line with a control character without it being interpreted,
2149 precede it with @code{\&}. This represents a zero width space, which
2150 means it will not affect the output.
2152 In most cases the period is used as a control character. Several
2153 requests will cause a break; using the single quote control character
2157 * Request Arguments::
2160 @node Request Arguments, , Requests, Requests
2161 @subsubsection Request Arguments
2162 @cindex request arguments
2163 @cindex arguments to requests
2165 Arguments to requests (and macros) are processed much like the shell:
2166 The line is split into arguments according to spaces. An argument which
2167 is intended to contain spaces can either be enclosed in quotes (single
2168 or double), or have the spaces @dfn{escaped} with backslashes.
2171 .uh The Mouse Problem
2172 .uh "The Mouse Problem"
2173 .uh The\ Mouse\ Problem
2179 The first line is the @code{uh} macro being called with 3 arguments,
2180 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
2181 same effect or calling the @code{uh} macro with one argument @samp{The
2182 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
2183 is `classical' in the sense that it can be found in most @code{troff}
2184 documents. Nevertheless, it is not optimal in all situations since
2185 @samp{\ } inserts a fixed-width space character which can't stretch.
2186 @code{gtroff} provides a different command @code{\~} to insert a
2190 Note, however, that the @code{ds} request works differently.
2191 @xref{Strings}, for more details.
2193 @node Macros, Escapes, Requests, Embedded Commands
2197 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
2198 which can be invoked by name. They are called in the same manner as
2199 requests---arguments also may be passed in the same manner.
2201 @xref{Writing Macros}, and @ref{Request Arguments}.
2203 @node Escapes, , Macros, Embedded Commands
2207 Escapes may occur anywhere in the input to @code{gtroff}. They begin
2208 with a backslash usually and are followed by a single character which
2209 indicates the function to be performed. The escape character can be
2210 changed; @xref{Character Translations}.
2215 Escape sequences which require an identifier as a parameter accept three
2216 possible syntax forms.
2220 The next single character is the identifier.
2222 If this single character is an opening parenthesis, take the following
2223 two characters as the identifier. Note that there is no closing
2224 parenthesis after the identifier.
2226 If this single character is an opening bracket, take all characters
2227 until a closing bracket as the identifier.
2240 @cindex argument delimiting characters
2241 @cindex characters, argument delimiting
2242 @cindex delimiting characters for arguments
2243 Other escapes may require several arguments and/or some special format.
2244 In such cases the argument is traditionally enclosed in single quotes
2245 (and quotes are always used in this manual for the definitions of the
2246 escape sequences). The enclosed text is then processed according to
2247 what that escape expects. Example:
2256 Note that the quote character can be replaced with any other character
2257 which does not occur in the argument (even a newline or a space
2258 character) in the following escapes: @code{\o}, @code{\b}, and
2259 @code{\X}. This makes e.g.
2268 @result{} A caf@'e in Paris
2272 possible, but it is better not to use this feature to avoid confusion.
2302 The following escapes sequences (which are handled similar to characters
2303 since they don't take a parameter) are also allowed as delimiters:
2304 @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, @code{\@}},
2305 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\?},
2306 @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, @code{\~},
2307 @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e}, @code{\E},
2308 @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't use these
2315 No newline characters as delimiters are allowed in the following
2316 escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}.
2329 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
2330 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
2331 @code{\x} can't use the following characters as delimiters:
2337 The digits @code{0}-@code{9}.
2353 The (single character) operators @samp{+-/*%<>=&:().}.
2355 @cindex space character
2356 @cindex character, space
2357 @cindex tab character
2358 @cindex character, tab
2359 @cindex newline character
2360 @cindex character, newline
2361 The space, tab, and newline characters.
2376 All escape sequences except @code{\%}, @code{\@{}, @code{\@}},
2377 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
2378 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
2384 To have a backslash appear in the output several escapes are defined:
2385 @code{\\}, @code{\e} or @code{\E}. These are very similar, and only
2386 differ with respect to being used in macros or diversions.
2387 @xref{Copy-in Mode}, and @ref{Diversions}, for more information.
2395 @node Comments, , Escapes, Escapes
2396 @subsubsection Comments
2399 Probably one of the most@footnote{Unfortunately, this is a lie. But
2400 hopefully future @code{gtroff} hackers will believe it :-)} common forms
2401 of escapes is the comment.
2404 Start a comment. Everything to the end of the input line is ignored.
2406 This may sound simple, but it can be tricky to keep the comments from
2407 interfering with the appearance of the final output.
2410 If the escape is to the right of some text or a request, that portion of
2411 the line will be ignored, but the space leading up to it will be noticed
2412 by @code{gtroff}. This only affects the @code{.ds} request.
2413 @c XXX (any others?)
2415 One possibly irritating idiosyncracy is that tabs must not be used to
2416 line up comments. Tabs are not treated as white space between the
2417 request and macro arguments.
2419 @cindex undefined request
2420 @cindex request, undefined
2421 A comment on a line by itself will be treated as a blank line, because
2422 after eliminating the comment, that is all that remains:
2439 As a consequence, it is common to start the line with @code{.\"} which
2440 will cause the line to be treated as an undefined request and thus
2443 Another commenting scheme seen sometimes is three consecutive single
2444 quotes (@code{'''}) at the beginning of a line. This works, but
2445 @code{gtroff} will give a warning about an undefined macro, which is
2446 harmless, but irritating.
2450 Now to avoid all this @code{gtroff} has a new comment mechanism using
2451 the @code{\#} escape. This escape works the same as @code{\"} except
2452 that the newline is also ignored:
2472 For large blocks of text, the @code{ig} request may be useful.
2475 @c XXX definition of .ig
2477 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
2481 Numeric variables in @code{gtroff} are called @dfn{registers}. There
2482 are a number of built-in registers, supplying anything from the date to
2483 details of formatting parameters.
2485 @xref{Identifiers}, for details on register identifiers.
2488 * Setting Registers::
2489 * Interpolating Registers::
2491 * Assigning Formats::
2492 * Built-in Registers::
2495 @node Setting Registers, Interpolating Registers, Registers, Registers
2496 @subsection Setting Registers
2497 @cindex setting registers
2498 @cindex registers, setting
2500 Registers are defined resp.@: set via the @code{nr} request or the
2503 @deffn Request nr ident value
2504 @deffnx Escape \R ident value
2505 Set number register @var{ident} to @var{value}. If @var{ident} doesn't
2506 exist, it will be created.
2509 For example, the following two lines are equivalent:
2516 Both @code{nr} and @code{\N} have two additional special forms to
2517 increment resp.@: decrement a register.
2519 @deffn Request nr ident +value
2520 @deffnx Request nr ident -value
2521 @deffnx Escape \N ident +value
2522 @deffnx Escape \N ident -value
2523 Increment (decrement) register @var{ident} by @var{value}.
2532 To assign the negated value of a register to another register, some care
2533 must be taken to get the desired result:
2547 The surrounding parentheses prevent the interpretation of the minus sign
2548 as a decrementing operator.
2551 @deffn Request rr ident
2552 Remove number register @var{ident}.
2555 @deffn Request rnn ident1 ident2
2556 Rename number register @var{ident1} to @var{ident2}.
2559 @deffn Request aln ident1 ident2
2560 This request creates an alias @var{ident1} for a number register
2561 @var{ident2}. The new name and the old name will be exactly equivalent.
2562 If @var{ident1} is undefined, a warning of type @samp{reg} will be
2563 generated, and the request will be ignored. @xref{Debugging}, for
2564 information about warnings.
2567 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
2568 @subsection Interpolating Registers
2569 @cindex interpolating registers
2570 @cindex registers, interpolating
2572 Numeric registers can be accessed via the @code{\n} escape.
2574 @deffn Escape \n ident
2575 @c XXX is the following correct?
2576 Interpolate number register @var{ident}. This means that the value of
2577 the register is expanded in-place while @code{gtroff} is parsing the
2588 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
2589 @subsection Auto-increment
2590 @cindex auto-increment
2591 @cindex increment, automatic
2593 Number registers can also be auto-incremented and auto-decremented. The
2594 increment resp.@: decrement factor can be specified with a third
2595 argument to the @code{nr} request or @code{\N} escape.
2597 @deffn Request nr ident value incr
2598 @deffnx Escape \N ident value incr
2599 Set number register @var{ident} to @var{value}; the increment for
2600 auto-incrementing is set to @var{incr}.
2603 To activate auto-incrementing, the escape @code{\n} has a special syntax
2606 @deffn Escape \n +ident
2607 @deffnx Escape \n -ident
2608 Before interpolating, increment resp.@: decrement @var{ident} by the
2609 auto-increment value as specified with the @code{nr} request (or the
2610 @code{\N} escape). If no auto-increment value has been specified, both
2611 syntax forms are identical to @code{\n}.
2620 \n+a, \n+a, \n+a, \n+a, \n+a
2622 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
2624 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
2632 -5, -10, -15, -20, -25
2636 To change the increment value without changing the value of a register,
2637 the following can be used.
2643 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
2644 @subsection Assigning Formats
2645 @cindex assigning formats
2646 @cindex formats, assigning
2649 When a register is used in the text of an input file (as opposed to part
2650 of an expression) it is textually replaced (or interpolated) with a
2651 representation of that number. This output format can be changed to a
2652 variety of formats (numbers, Roman numerals, etc). This is done using
2653 the @code{af} request. The first argument to @code{af} is the name of
2654 the number register to be changed, and the second argument is the output
2655 format. The following output formats are available:
2659 This is the default format, decimal numbers: 1, 2, 3,@w{ }@dots{}
2661 Decimal numbers with as many leading zeros as specified. So, @samp{01}
2662 would result in 01, 02, 03,@w{ }@dots{}
2664 @cindex roman numerals
2665 @cindex numerals, Roman
2666 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@dots{}
2668 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@dots{}
2670 Upper-case letters: A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@dots{}
2672 Lower-case letters: a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@dots{}
2675 The following example will produce @samp{10, X, j, 010}:
2679 .af a 1 \" the default format
2690 The @code{\g} escape returns the current format of the specified
2691 register. For example, @samp{\ga} after the previous example would
2692 produce the string @samp{001}. If the register hasn't been defined yet,
2693 nothing is returned.
2695 @node Built-in Registers, , Assigning Formats, Registers
2696 @subsection Built-in Registers
2697 @cindex built-in registers
2698 @cindex registers, built-in
2700 The following lists some built-in registers which are not described
2701 elsewhere in this manual. Any register which begin with a @samp{.} is
2702 read-only. A complete listing of all built-in registers can be found in
2703 @ref{Register Index}.
2708 Horizontal resolution in basic units.
2711 Vertical resolution in basic units.
2714 Day of the week (1-7).
2717 Day of the year (1-31).
2720 Current month (1-12).
2726 The year minus@w{ }1900. Unfortunately, the @sc{Unix} Version@w{ }7
2727 @code{troff} documentation had a year@w{ }2000 bug: It incorrectly
2728 claimed that @samp{\n(yr} was the last two digits of the year. That
2729 claim has never been true of either traditional @code{troff} or GNU
2730 @code{troff}. Old @code{troff} input that looks like this:
2733 '\" The following line stopped working after 1999
2734 This document was formatted in 19\n(yr.
2738 can be corrected as follows:
2741 This document was formatted in \n[year].
2745 or, to be portable to older @code{troff} versions, as follows:
2749 This document was formatted in \n(y4.
2756 The current @emph{input} line number.
2759 The current @emph{output} line number.
2762 The major version number. For example, if the version number is@w{
2763 }1.03 then @code{.x} will contain@w{ }@samp{1}.
2766 The minor version number. For example, if the version number is@w{
2767 }1.03 then @code{.y} will contain@w{ }@samp{03}.
2770 The revision number of @code{groff}.
2773 Always@w{ }1. Macros should use this to determine whether they are
2774 running under GNU @code{troff}.
2777 If the current output device is @sc{ascii}, this is set to@w{ }1, zero
2781 This register indicates whether the current page is actually being
2782 printed, i.e., whether the @samp{-o} option is being used to only print
2783 selected pages. @xref{Options}, for more information.
2787 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
2788 @section Manipulating Filling and Adjusting
2789 @cindex manipulating filling and adjusting
2790 @cindex filling and adjusting, manipulating
2791 @cindex adjusting and filling, manipulating
2792 @cindex justifying text
2793 @cindex text, justifying
2798 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
2799 Breaks}. The @code{br} request will likewise cause a break. Several
2800 other requests will also cause breaks, but implicitly. They are
2801 @code{bp}, @code{ce}, @code{fi}, @code{fl}, @code{in}, @code{nf},
2802 @code{sp}, and @code{ti}.
2807 Initially, @code{gtroff} will fill and adjust text to both margins.
2808 Filling can be disabled via the @code{nf} request and re-enabled with
2809 the @code{fi} request. These implicitly disable and re-enable
2810 adjusting. Both of these will cause a break in the text currently being
2811 filled. The number register @code{.u} is equal to@w{ }1 in fill mode
2812 and@w{ }0 in no-fill mode.
2816 Adjusting can be disabled with the @code{ad} request and re-enabled with
2817 the @code{na} request. The @code{ad} request takes a single argument to
2818 indicate how to adjust text.
2822 @cindex ragged-right
2823 Adjust text to the left margin. This produces what is traditionally
2824 called ragged-right text.
2827 Adjust text to the right margin, producing ragged-left text.
2829 @cindex centered text
2831 @c XXX difference to .ce?
2834 Justify to both margins. This is default of @code{gtroff}.
2837 With no argument to @code{ad}, @code{gtroff} will adjust lines the same
2838 way it was the last time it was filling. For example:
2848 .ad \" back to centering
2853 The current adjustment mode is available in the number register
2857 The escape @code{\p} will cause a break and the remaining text to be
2860 @cindex word space size
2861 @cindex size of word space
2862 @cindex space between words
2863 @cindex sentence space size
2864 @cindex size of sentence space
2865 @cindex space between sentences
2867 The @code{ss} request changes the minimum size of a space between filled
2868 words. It takes its units as one twelfth of the space width parameter
2869 for the current font. Initially both the word space size and the
2870 sentence space size are@w{ }12.
2872 If two arguments are given to the @code{ss} request, the second argument
2873 gives the sentence space size. If the second argument is not given, the
2874 sentence space size will be the same as the word space size. The
2875 sentence space size is used in two circumstances: If the end of a
2876 sentence occurs at the end of a line in fill mode, then both an
2877 inter-word space and a sentence space will be added; if two spaces
2878 follow the end of a sentence in the middle of a line, then the second
2879 space will be a sentence space. Note that the behaviour of @sc{Unix}
2880 @code{troff} will be exactly that exhibited by GNU @code{troff} if a
2881 second argument is never given to the @code{ss} request. In GNU
2882 @code{troff}, as in @sc{Unix} @code{troff}, a sentence should always be
2883 followed with either a newline or two spaces.
2887 The number registers @code{.ss} and @code{.sss} are the values of the
2888 parameters set by the first and second arguments of the @code{ss}
2892 @cindex centering lines
2893 @cindex lines, centering
2894 The @code{ce} request will center text. While the @w{@samp{ad c}}
2895 request will also center text, it has the side effect of filling the
2896 text. The @code{.ce} request will not fill the text it affects. This
2897 request causes a break.
2899 With no arguments, @code{ce} will fill the next line of text. The
2900 single argument @code{ce} takes is a number indicating the number of
2901 lines to be centered. If the argument is zero, centering is disabled.
2903 A common idiom is to turn on centering for a large number of lines, and
2904 to turn off centering after text to be centered. This is useful for any
2905 request which takes a number of lines as an argument.
2918 The @code{.ce} number register contains the number of lines remaining to
2919 be centered, as set by the @code{ce} request.
2921 @cindex justifying text
2922 @cindex text, justifying
2923 @cindex right-justifying
2926 A similar request is @code{rj} request which will justify unfilled text
2927 to the right margin. Its arguments are identical to the @code{ce}
2928 request. The @code{.rj} number register is the number of lines to be
2929 right-justified as set by the @code{rj} request.
2932 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
2933 @section Manipulating Hyphenation
2934 @cindex manipulating hyphenation
2935 @cindex hyphenation, manipulating
2937 As discussed in @ref{Hyphenation}, @code{gtroff} will hyphenate words.
2938 There are a number of ways to influence how hyphenation is done.
2943 Hyphenation can be turned off with the @code{nh} request, and turned
2944 back on with the @code{hy} request. However, the hyphenation facilities
2945 of @code{gtroff} are far more flexible than this. The @code{hy} request
2946 can be used to tell @code{gtroff} to restrict hyphenation to certain
2947 cases. The request takes a single numeric argument. The current
2948 hyphenation restrictions can be found in the number register @code{.hy}.
2952 The default argument, which indicates to hyphenate without restrictions.
2954 Do not hyphenate the last word on a page or column.
2956 Do not hyphenate the last two characters of a word.
2958 Do not hyphenate the first two characters of a word.
2961 The values in the previous table are additive. For example, the
2962 value@w{ }12 causes @code{gtroff} to neither hyphenate the last two nor
2963 the first two characters of a word.
2969 @cindex explicit hyphens
2970 @cindex hyphen, explicit
2971 The @code{hlm} request will set the maximum number of consecutive
2972 hyphenated lines to the value given as the first argument. If this
2973 number is negative, there is no maximum. The default value is@w{ }-1.
2974 This value is associated with the current environment. Only lines
2975 output from an environment count towards the maximum associated with
2976 that environment. Hyphens resulting from @code{\%} are counted;
2977 explicit hyphens are not. The current setting of this is available in
2978 the @code{.hlm} register. Also the number of immediately preceding
2979 consecutive hyphenated lines are available in the number register
2983 The @code{hw} request specifies how a specific word is to be hyphenated.
2984 It takes only one argument which is the word with hyphens at the
2985 hyphenation points. For example:
2992 This request can be used more than once.
2995 @c In old versions of troff there was a
2996 @c limited amount of space to store such information, fortunately,
2997 @c with groff, this is no longer a restriction.
3000 @cindex hyphenation character
3001 @cindex character, hyphenation
3002 @cindex disabling hyphenation
3003 @cindex hyphenation, disabling
3004 To tell @code{gtroff} how to hyphenate words on the fly, the @code{\%}
3005 escape, also known as the @dfn{hyphenation character}, can be used.
3006 Preceding a word with this character will prevent it from being
3007 hyphenated, putting it in a word will indicate to @code{gtroff} that the
3008 word may be hyphenated at that point. Note that this mechanism will
3009 only affect one word; to change the hyphenation of a word for the entire
3010 document, use the @code{hw} request.
3013 The @code{hc} request changes the hyphenation character. The character
3014 specified as an argument will then work the same as the @code{\%}
3015 escape, and, thus, no longer appear in the output. Without an argument
3016 it will return the hyphenation character to @code{\%}.
3018 @cindex hyphenation patterns
3019 @cindex pattern for hyphenation
3021 To further customize hyphenation the @code{hpf} request will read in a
3022 file of hyphenation patterns. This file will be searched for in the
3023 same way that @file{tmac.@var{name}} is searched for when the
3024 @samp{-m@var{name}} option is specified.
3026 It should have the same format as the argument to the @code{\patterns}
3027 primitive in @TeX{}; the letters appearing in this file are interpreted
3028 as hyphenation codes. A @samp{%} character in the patterns file
3029 introduces a comment that continues to the end of the line.
3035 The set of hyphenation patterns is associated with the current language
3036 set by the @code{hla} request. The @code{hpf} request is usually
3037 invoked by the @file{troffrc} or @file{troffrc-end} file.
3040 The @code{hcode} request has the following syntax:
3043 .hcode @var{c1 code1 c2 code2...}
3046 It sets the hyphenation code of character @var{c1} to @var{code1} and
3047 that of @var{c2} to @var{code2}. A hyphenation code must be a single
3048 input character (not a special character) other than a digit or a space.
3049 Initially each lower-case letter has a hyphenation code, which is
3050 itself, and each upper-case letter has a hyphenation code which is the
3051 lower-case version of itself.
3053 @cindex hyphenation margin
3054 @cindex margin for hyphenation
3057 The @code{hym} request will set the hyphenation margin to the value
3058 given as its argument: when the current adjustment mode is not@w{
3059 }@samp{b}, the line will not be hyphenated if the line is no more than
3060 that amount short. The default hyphenation margin is@w{ }0. The
3061 default scaling indicator for this request is@w{ }m. The hyphenation
3062 margin is associated with the current environment. The current
3063 hyphenation margin is available in the @code{.hym} register.
3065 @cindex hyphenation space
3068 The @code{hys} request sets the hyphenation space to the value given as
3069 the first argument: when the current adjustment mode is@w{ }@samp{b},
3070 don't hyphenate the line if the line can be justified by adding no more
3071 than that amount of extra space to each word space. The default
3072 hyphenation space is@w{ }0. The default scaling indicator for this
3073 request is@w{ }m. The hyphenation space is associated with the current
3074 environment. The current hyphenation space is available in the
3075 @code{.hys} register.
3077 @cindex soft hyphen character
3078 @cindex character, soft hyphen
3080 The @code{shc} request will set the soft hyphen character to the
3081 character given as an argument. If the argument is omitted, the soft
3082 hyphen character will be set to the default character @code{\(hy}. The
3083 soft hyphen character is the character which will be inserted when a
3084 word is hyphenated at a line break. If the soft hyphen character does
3085 not exist in the font of the character immediately preceding a potential
3086 break point, then the line will not be broken at that point. Neither
3087 definitions (specified with the @code{char} request) nor translations
3088 (specified with the @code{tr} request) are considered when finding the
3089 soft hyphen character.
3097 The @code{hla} request will set the current hyphenation language to that
3098 given by the first argument. Hyphenation exceptions specified with the
3099 @code{hw} request and hyphenation patterns specified with the @code{hpf}
3100 request are both associated with the current hyphenation language. The
3101 @code{hla} request is usually invoked by the @file{troffrc} or the
3102 @file{troffrc-end} files. The current hyphenation language is available
3103 in the number register @code{.hla}.
3106 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
3107 @section Manipulating Spacing
3108 @cindex manipulating spacing
3109 @cindex spacing, manipulating
3112 The @code{sp} request will cause @code{gtroff} to space downwards the
3113 distance specified as the first argument. With no argument it will
3114 advance 1@w{ }line. A negative argument will cause @code{gtroff} to
3115 move up the page the specified distance. If the argument is preceded by
3116 a @samp{|} @code{gtroff} will move that distance from the top of the
3119 @cindex double-spacing
3122 For double or triple spaced output use @code{ls}. This request causes
3123 @code{troff} to output @var{n}-1 blank lines after each line of text,
3124 where @var{n} is the argument given to the @code{ls} request. With no
3125 argument @code{gtroff} will go back to single spacing. The number
3126 register @code{.L} contains the current line spacing setting.
3130 Sometimes, extra vertical spacing is only needed occasionally, i.e.@: to
3131 allow space for a tall construct (like an equation). The @code{\x}
3132 escape will do this. The escape is given a numerical argument (like
3133 @samp{\x'3p'}). If this number is positive extra vertical space will be
3134 inserted below the current line. A negative number will add space
3135 above. If this escape is used multiple times on the same line, the
3136 maximum of the values is used. The @code{.a} number register contains
3137 the most recent (nonnegative) extra vertical line space.
3141 ... example of inline equation ...
3146 @cindex no-space mode
3147 @cindex mode, no-space
3148 Spacing (either via @code{sp} or via blank lines) can be disabled with
3149 the @code{ns} request. This will enable @dfn{no-space mode}. This mode
3150 will end when actual text is output or the @code{rs} request is
3151 encountered. No-space mode will also prevent requests to advance to the
3152 next page unless they are accompanied by a page number (@pxref{Page
3153 Control}, for more information).
3156 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
3157 @section Tabs and Fields
3158 @cindex tabs and fields
3159 @cindex fields and tabs
3162 Tab stops are much like those on a typewriter: a tab character (or the
3163 @code{\t} escape) on input will cause horizontal motion to the next tab
3167 Tab stops can be changed with the @code{ta} request. This request takes
3168 a series of numbers as arguments which indicate where each tab stop is
3169 to be (overriding any previous settings). These can be specified
3170 absolutely, i.e.@: as the distance from the left margin. For example,
3171 the following will set tab stops every one inch.
3174 .ta 1i 2i 3i 4i 5i 6i
3177 Tab stops can also be specified relatively (using a leading @samp{+})
3178 which means that the specified tab stop will be set that distance from
3179 the previous tab stop. For example, the following is equivalent to the
3183 .ta 1i +1i +1i +1i +1i +1i
3186 After the specified tab stops repeat values may be set for tabs beyond
3187 the last one specified. This is most commonly used to specify tabs set
3188 at equal intervals. The complete syntax for setting tabs is
3191 ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2} @dots{} @var{rn}
3195 This will set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn}
3196 and then set tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{},
3197 @var{nn}+@var{rn} and then at @var{nn}+@var{rn}+@var{r1},
3198 @var{nn}+@var{rn}+@var{r2}, @dots{}, @var{nn}+@var{rn}+@var{rn}, and so
3199 on. For example the following is, yet again, the same as the previous
3206 The material in each tab column may be justified to the right or left
3207 or centered in the column. This is specified by appending an
3208 @samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop.
3209 The default justification is @samp{L}. Example:
3216 The number register @code{.tabs} contains a string representation of the
3217 current tab settings suitable for use as an argument to the @code{ta}
3221 Normally @code{gtroff} will fill the space to the next tab stop with
3222 spaces. This can be change with the @code{tc} request. With no
3223 argument @code{gtroff} will revert to using spaces.
3229 Sometimes it may may be desirable to use the @code{tc} request to fill a
3230 particular tab stop with a given character, but also normal tab stops on
3231 the rest of the line. For this @code{gtroff} provides an alternate tab
3232 mechanism, called @dfn{leaders} which will do just that. They are used
3233 exclusively to produce a repeated run of characters to the next tab
3236 The character that will be repeated can be declared with the @code{lc}
3237 request. Without an argument, the leaders will act the same as tabs.
3240 Leader are invoked by using the @code{\a} escape while specifying the
3243 @cindex table of contents
3244 @cindex contents, table of
3245 For a table of contents, to name an example, tab stops may be defined so
3246 that the section number is one tab stop, the title is the second with
3247 the remaining space being filled with a line of dots, and then the page
3248 number slightly separated from the dots.
3260 Fields are a more general way of laying out tabular data.
3264 @c XXX add explanation
3266 @node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial
3267 @section Character Translations
3268 @cindex character translations
3269 @cindex translations of characters
3275 The control character (@samp{.}) and the no-break control character
3276 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
3277 respectively. The single argument is the new character to be used.
3278 With no argument the normal control character is restored.
3282 The @code{eo} request will completely disable the escape mechanism. The
3283 @code{ec} request can be used to change the escape character from the
3284 default @samp{\} to what is specified as an argument. It can be also
3285 used to re-enable the escape mechanism after an @code{eo} request.
3288 The @code{tr} request will translate characters.
3294 @code{trnt} is the same as the @code{tr} request except that the
3295 translations do not apply to text that is transparently throughput into
3296 a diversion with @code{\!}. @xref{Diversions}, for more information.
3308 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it will
3312 @node Line Layout, Page Layout, Character Translations, Programming Tutorial
3313 @section Line Layout
3315 @cindex layout, line
3317 @cindex dimensions, line
3318 @cindex line dimensions
3319 The following drawing shows the dimensions which @code{gtroff} uses for
3320 placing a line of output onto the page. They are labeled with the
3321 request which manipulates that dimension.
3326 -->| po |<-----------ll------------>|
3327 +----+----+----------------------+----+
3329 +----+----+----------------------+----+
3334 These dimensions are:
3339 @cindex margin, left
3341 @cindex offset, page
3343 @dfn{Page offset}--This is the leftmost position of text on the final
3344 output, defining the @dfn{left margin}. It can be adjusted with the
3345 @code{po} request, and the current setting can be found in the built-in
3346 number register @code{.o}. Note that this request does not cause a
3347 break, so changing the page offset in the middle of text being filled
3348 may not yield the expected result.
3351 @cindex line indentation
3353 @dfn{Indentation}--This is the distance from the left margin where text
3354 will be printed. This can be adjusted with the @code{in} request, and
3355 the current setting can be found in the built-in number register.
3356 @code{.i}. This request causes a break.
3360 There is also the request @code{ti} which will cause one output line to
3361 be indented, after which the indentation returns to@w{ }0. This request
3362 causes a break. The number register @code{.in} is the indent that
3363 applies to the current output line.
3366 @cindex length of line
3369 @dfn{Line length}--This is the distance from the left margin to right
3370 margin. This can be adjusted with the @code{ll} request, and the
3371 current setting can be found in the built-in number register @code{.l}
3372 Note, as the figure implies, line length is not affected by the current
3373 indentation. The number register @code{.ll} is the line length that
3374 applies to the current output line.
3380 A bunch of really boring text which should
3381 be indented from both margins.
3382 Replace me with a better (and more) example!
3388 @node Page Layout, Page Control, Line Layout, Programming Tutorial
3389 @section Page Layout
3391 @cindex layout, page
3393 @code{gtroff} provides some very primitive operations for controlling
3397 @cindex length of page
3400 The @dfn{page length} can be specified via the @code{pl} request. This
3401 is the length of the physical output page. The current setting can be
3402 found in the built-in number register @code{.p}. Note that this only
3403 specifies the size of the page, not the top and bottom margins. Those
3404 are not done by groff directly. @xref{Traps}, for further information
3410 @code{gtroff} provides several operations which help in setting up top
3411 and bottom titles (or headers and footers)
3414 @cindex three-part title
3417 The @code{tl} request will print a @dfn{title line}, which consists of
3418 three parts: a left justified portion, a centered portion and a right
3419 justified portion. The argument to @code{tl} is specified as
3420 @code{'@var{left}'@var{center}'@var{right}'}. The @samp{%} character is
3421 replaced with the current page number. This character can be changed
3422 with the @code{pc} request (see below).
3424 @cindex length of title line
3425 @cindex title line, length
3428 The title line is printed using its own line length, which is specified
3429 with the @code{lt} request. The current setting of this is available in
3430 the @code{.lt} number register.
3433 @cindex number, page
3435 The @code{pn} request will change the page number of the @emph{next}
3436 page. The only argument is the page number.
3440 The current page number is stored in the number register @code{%}. The
3441 number register @code{.pn} contains the number of the next page: either
3442 the value set by a @code{pn} request, or the number of the current page
3445 @cindex changing the page number character
3446 @cindex page number character, changing
3448 The @code{pc} request will change the page number character (used by the
3449 @code{tl} request) to a different character. With no argument, this
3450 mechanism is disabled.
3455 @node Page Control, Fonts, Page Layout, Programming Tutorial
3456 @section Page Control
3457 @cindex page control
3458 @cindex control, page
3462 To stop processing the current page, and move to the next page, invoke
3463 the @code{bp} request. This request will also cause a break. It can
3464 also take an argument of what the next page should be numbered. The
3465 only difference between @code{bp} and @code{pn} is that @code{pn} does
3466 not cause a break or actually eject a page.
3472 .tl 'left top'center top'right top'
3479 It is often necessary to force a certain amount of space before a new
3480 page occurs. This is most useful to make sure that there is not a
3481 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
3482 request will ensure that there is a certain distance, specified by the
3483 first argument, before the next page is triggered (@pxref{Traps}, for
3484 further information). The default unit for @code{ne} is @code{v} and
3485 the default argument is@w{ }1@dmn{v}.
3487 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
3488 do the following before each paragraph:
3499 @code{sv} is similar to the @code{ne} request; it reserves the specified
3500 amount of vertical space. If the desired amount of space exists before
3501 the next trap (bottom page boundary), the space will be output
3502 immediately. If there is not enough space, it is stored for later
3503 output via the @code{os} request. The default argument is@w{ }1@dmn{v}
3504 and the default unit is @code{v}.
3507 @node Fonts, Sizes, Page Control, Programming Tutorial
3513 @code{gtroff} has the ability to switch fonts at any point in the text.
3514 There are two ways to do this, via the @code{ft} request and the
3517 Fonts are generally specified as upper-case strings, which are usually
3518 1@w{ }to 4 characters representing an abbreviation or acronym of the font
3521 The basic set of fonts are @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
3522 These are Times Roman, Italic, Bold, and Bold Italic. There is also at
3523 least one symbol font which contains various special symbols (Greek,
3524 mathematics). Such symbols fonts cannot be used directly, but should be
3532 * Artificial Fonts::
3533 * Ligatures and Kerning::
3536 @node Changing Fonts, Font Families, Fonts, Fonts
3537 @subsection Changing Fonts
3538 @cindex changing fonts
3539 @cindex fonts, changing
3542 @cindex previous font
3543 @cindex font, previous
3544 Font changes can be done either with the @code{ft} request or the
3545 @code{\f} request. With no arguments it will switch to the previous
3546 font (also known as @samp{P}).
3557 The @code{\f} escape is useful for changing fonts in the middle of
3561 eggs, bacon, \fBspam\fP and sausage.
3565 Both of the above examples will produce the same output. Note the usage
3566 of @samp{P} to indicate the previous font---using @code{\f} it is not
3567 possible to omit this parameter.
3569 Sometimes when putting letters of different fonts, more or less space at
3570 such boundaries are needed. There are two escapes to help with this.
3573 @cindex italic correction
3574 @cindex correction, italic
3575 The @code{\/} escape increases the width of the preceding character so
3576 that the spacing between that character and the following character will
3577 be correct if the following character is a Roman character. For
3578 example, if an italic@w{ }f is immediately followed by a Roman right
3579 parenthesis, then in many fonts the top right portion of the f will
3580 overlap the top left of the right parenthesis. It is a good idea to use
3581 this escape sequence whenever an italic character is immediately
3582 followed by a Roman character without any intervening space. This small
3583 amount of space is also called @dfn{italic correction}.
3586 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids
3590 @cindex left italic correction
3591 @cindex correction, left italic
3592 The @code{\,} escape modifies the spacing of the following character so
3593 that the spacing between that character and the preceding character will
3594 be correct if the preceding character is a Roman character. It is a
3595 good idea to use this escape sequence whenever a Roman character is
3596 immediately followed by an italic character without any intervening
3597 space. In analogy to above, this space could be called @dfn{left italic
3598 correction}, but this term isn't used widely.
3601 @c For example, inserting \, between the parenthesis and the f changes
3615 The @code{ftr} request will translate fonts; its syntax is
3618 .ftr @var{F} @var{G}
3622 which translates font@w{ }@var{F} to font@w{ }@var{G}. Whenever a font
3623 named @var{F} is referred to in a @code{\f} escape sequence, or in the
3624 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
3625 @code{fspecial}, @code{fp}, or @code{code} requests, font@w{ }@var{G} will
3626 be used. If @var{G} is missing, or equal to @var{F} then font@w{
3627 }@var{F} will not be translated.
3629 @node Font Families, Font Positions, Changing Fonts, Fonts
3630 @subsection Font Families
3631 @cindex font families
3632 @cindex families, font
3634 Due to the variety of fonts available, @code{gtroff} has added the
3635 concept of font families. Each of these families has four styles
3636 (@samp{R}, @samp{I}, @samp{B} and @samp{BI}).
3638 The fonts are specified as the concatenation of the font family and
3639 style. Specifying a font without the family part will cause
3640 @code{gtroff} to use that style of the current family. By default,
3641 @code{gtroff} uses the Times family.
3643 This way, it is possible to use the basic four fonts and to select a
3644 different font family on the command line.
3648 Font families can be switched with the @code{fam} request. The current
3649 font family is available in the number register @code{.fam}. This is a
3650 string-valued register.
3666 @node Font Positions, Using Symbols, Font Families, Fonts
3667 @subsection Font Positions
3668 @cindex font positions
3669 @cindex positions, font
3671 For the sake of old phototypesetters and compatability with old versions
3672 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
3673 on which various fonts are mounted. The last one or two are reserved
3674 for the symbol font(s).
3677 New fonts can be mounted with the @code{fp} request. These numeric
3678 positions can then be referred to with font changing commands. When
3679 @code{gtroff} starts it is using font number one.
3695 Note that after these font changes have taken place the original font
3699 The current font in use, as a font position, is available in number
3700 register @code{.f}. This can be useful to remember the current font,
3705 ... lots 'o text ...
3710 The number of the next free font position is available in the number
3711 register @code{.fp}. This is useful when mounting a new font, like so:
3714 .fp \n[.fp] NEATOFONT
3718 Fonts not listed in the @file{DESC} file are automatically mounted on
3719 the next available font position when they are referenced. If a font is
3720 to be mounted explicitly with the @code{fp} request on an unused font
3721 position, it should be mounted on the first unused font position, which
3722 can be found in the @code{.fp} register. Although @code{gtroff} does
3723 not enforce this strictly, it will not allow a font to be mounted at a
3724 position whose number is much greater than that of any currently used
3728 The @code{fp} request has an optional third argument. This argument
3729 gives the external name of the font, which is used for finding the font
3730 description file. The second argument gives the internal name of the
3731 font which is used to refer to the font in @code{gtroff} after it has
3732 been mounted. If there is no third argument then the internal name will
3733 be used as the external name. This feature make it possible to use
3734 fonts with long names in compatibility mode.
3736 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
3737 @subsection Using Symbols
3738 @cindex using symbols
3739 @cindex symbols, using
3743 Symbols can be inserted by using a special escape sequence. This escape
3744 is simply the escape character (usually a backslash) followed by an
3745 identifier. The symbol identifiers have to be two or more characters,
3746 since single characters conflict with all the other escapes. The
3747 identifier can be either preceded by a parenthesis if it is two
3748 characters long, or surrounded by square brackets. So, the symbol for
3749 the mathematical Greek letter `pi' can be produced either by @code{\(*p}
3753 area = \(*p\fIr\fP\u2\d
3757 The escape @code{\C'@var{xxx}'} will typeset the character named
3758 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
3759 But @code{\C} has the advantage that it is compatible with recent
3760 versions of @code{ditroff} and is available in compatibility mode.
3764 The escape @code{\N'@var{n}'} will typeset the character with code@w{
3765 }@var{n} in the current font. @var{n} can be any integer. Most devices
3766 only have characters with codes between 0 and@w{ }255. If the current
3767 font does not contain a character with that code, special fonts will
3768 @emph{not} be searched. The @code{\N} escape sequence can be
3769 conveniently used on conjunction with the @code{char} request:
3772 .char \[phone] \f(ZD\N'37'
3777 @cindex unnamed characters
3778 @cindex characters, unnamed
3779 The code of each character is given in the fourth column in the font
3780 description file after the charset command. It is possible to include
3781 unnamed characters in the font description file by using a name of
3782 @samp{---}; the @code{\N} escape sequence is the only way to use these.
3784 @c XXX should be `glyph', not `character'
3787 @cindex character properties
3788 @cindex properties of characters
3789 Each character has certain properties associated with it. These
3790 properties can be modified with the @code{cflags} request. The first
3791 argument is the the sum of the desired flags and the remaining arguments
3792 are the characters to have those properties.
3796 @cindex end of sentence characters
3797 @cindex characters, end of sentence
3798 the character ends sentences (initially characters @samp{.?!} have this
3801 @cindex hyphenating characters
3802 @cindex characters, hyphenation
3803 lines can be broken before the character (initially no characters have
3806 lines can be broken after the character (initially the characters
3807 @samp{-\(hy\(em} have this property)
3809 @cindex overlapping characters
3810 @cindex characters, overlapping
3811 the character overlaps horizontally (initially the characters
3812 @samp{\(ul\(rn\(ru} have this property)
3814 the character overlaps vertically (initially character @samp{\(br} has
3817 @cindex transparent characters
3818 @cindex characters, transparent
3819 an end of sentence character followed by any number of characters with
3820 this property will be treated as the end of a sentence if followed by a
3821 newline or two spaces; in other words the character is @dfn{transparent}
3822 for the purposes of end of sentence recognition---this is the same as
3823 having a zero space factor in @TeX{} (initially characters
3824 @samp{"')]*\(dg\(rq} have this property).
3828 @cindex defining characters
3829 @cindex characters, defining
3830 New characters can be created with the @code{char} request. It is
3834 .char @var{c} @var{string}
3843 This defines character@w{ }@var{c} to be @var{string}. Every time
3844 character@w{ }@var{c} needs to be printed, @var{string} will be
3845 processed in a temporary environment and the result will be wrapped up
3846 into a single object. Compatibility mode will be turned off and the
3847 escape character will be set to @samp{\} while @var{string} is being
3848 processed. Any emboldening, constant spacing or track kerning will be
3849 applied to this object rather than to individual characters in
3850 @var{string}. A character defined by this request can be used just like
3851 a normal character provided by the output device. In particular other
3852 characters can be translated to it with the @code{tr} request; it can be
3853 made the leader character by the @code{lc} request; repeated patterns
3854 can be drawn with the character using the @code{\l} and @code{\L} escape
3855 sequences; words containing the character can be hyphenated correctly,
3856 if the @code{hcode} request is used to give the character a hyphenation
3857 code. There is a special anti-recursion feature: use of character
3858 within the character's definition will be handled like normal characters
3859 not defined with @code{char}.
3862 @cindex removing character definition
3863 @cindex character, removing definition
3864 A character definition can be removed with the @code{rchar} request.
3865 Its arguments are the characters to be removed. This undoes the effect
3866 of a @code{char} request.
3868 @xref{Special Characters}.
3870 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
3871 @subsection Artificial Fonts
3872 @cindex artificial fonts
3873 @cindex fonts, artificial
3875 There are a number of requests for artificially creating fonts. These
3876 are largely vestigial remains from the days when output devices did not
3877 have a wide variety of fonts, and when @code{nroff} and @code{troff}
3878 were separate programs. These are no longer necessary in GNU
3883 The @code{ul} request will print subsequent lines in italics on a device
3884 capable of it, or underline the text on an character output device. The
3885 single argument is the number of lines to be ``underlined,'' with no
3886 argument, the next line will be underlined.
3889 @cindex continuous underlining
3890 @cindex underlining, continuous
3891 The @code{cu} request is similar to @code{ul} ...
3896 @cindex underline font
3897 @cindex font for underlining
3898 The @code{uf} request will set the underline font used by @code{ul} and
3902 @cindex imitating bold face
3903 @cindex bold face, imitating
3904 The @code{bd} request artificially creates a bold font by printing each
3905 character twice, slightly offset. The first argument specifies the font
3906 to embolden, and the second is the number of basic units, minus one, by
3907 which the two characters will be offset. If the second argument is
3908 missing, emboldening will be turned off.
3910 @node Ligatures and Kerning, , Artificial Fonts, Fonts
3911 @subsection Ligatures and Kerning
3912 @cindex ligatures and kerning
3913 @cindex kerning and ligatures
3921 The ligature mechanism can be switched on or off with the @code{lg}
3922 request; if the parameter is non-zero or missing, ligatures are enabled,
3923 otherwise disabled. Default is on. The current ligature mode can be
3924 found in the number register @code{.lg} (set to@w{ }1 if ligatures are
3925 enabled, 0@w{ }otherwise).
3931 @cindex zero width space character
3932 @cindex character, zero width space
3933 @cindex space character, zero width
3934 If the font description file contains pairwise kerning information,
3935 characters from that font will be kerned. Kerning between two
3936 characters can be inhibited by placing @code{\&} between them.
3940 Kerning can be activated with the @code{kern} request. If the parameter
3941 is non-zero or missing, enable pairwise kerning, otherwise disable it.
3942 The number register @code{.kern} is set to@w{ }1 if pairwise kerning is
3943 enabled, 0@w{ }otherwise.
3946 @cindex track kerning
3947 @cindex kerning, track
3948 What is track kerning?
3952 Track kerning must be used with great care since it is usually
3953 considered bad typography if the reader notices the effect. The syntax
3954 of the @code{tkf} request is
3957 .tkf @var{f} @var{s1} @var{n1} @var{s2} @var{n2}
3961 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
3962 }@var{f} the width of every character will be increased by an amount
3963 between @var{n1} and @var{n2}; if the current point size is less than or
3964 equal to @var{s1} the width will be increased by @var{n1}; if it is
3965 greater than or equal to @var{s2} the width will be increased by
3966 @var{n2}; if the point size is greater than or equal to @var{s1} and
3967 less than or equal to @var{s2} the increase in width is a linear
3968 function of the point size.
3971 @node Sizes, Strings, Fonts, Programming Tutorial
3977 @cindex size of type
3978 @cindex vertical spacing
3979 @cindex spacing, vertical
3980 @code{gtroff} uses two dimensions with each line of text, type size and
3981 vertical spacing. The @dfn{type size} is the height from the text
3982 @dfn{baseline} to the top of the tallest character (descenders may drop
3983 below this baseline). @dfn{Vertical spacing} is the amount of space
3984 @code{gtroff} allows for a line of text; normally, this is about 20%@w{
3985 }larger than the current type size. Ratios smaller than this can result
3986 in hard-to-read text; larger that this, it will spread the text out more
3987 vertically (useful for term papers). By default, @code{gtroff} uses
3988 10@w{ }point type on 12@w{ }point spacing.
3991 The difference between type size and vertical spacing is known, by
3992 typesetters, as @dfn{leading}.
3995 * Changing Type Sizes::
3996 * Fractional Type Sizes::
3999 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
4000 @subsection Changing Type Sizes
4001 @cindex changing type sizes
4002 @cindex type sizes, changing
4009 Using the @code{ps} request and the @code{\s} escape the type size can
4010 be changed. The @code{vs} request will change the vertical spacing.
4011 The default unit for the @code{ps} and @code{vs} requests are points.
4012 The number registers @code{.s} and @code{.v} contain the current type
4013 size and vertical spacing.
4015 These requests take parameters in units of points. It is possible to
4016 specify sizes as an absolute size, or as a relative change from the
4017 current size. The size@w{ }0 means go back to the previous size. With
4018 no argument it will also revert to the previous size.
4025 wink, wink, \s+2nudge, nudge,\s+8 say no more!
4029 The @code{\s} escape may be called in a variety of ways. Much like
4030 other escapes there must be a way to determine where the argument ends
4031 and the text begins. Any of the following forms are valid:
4035 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 0
4036 or in the range 4 to@w{ }39.
4039 Increase resp.@: decrease the point size by @var{n}@w{ }points.
4040 @var{n}@w{ }must be exactly one digit.
4042 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly two
4048 Increase resp.@: decrease the point size by @var{nn}@w{ }points.
4049 @var{nn} must be exactly two digits.
4052 @xref{Fractional Type Sizes}, for yet another syntactical form of using
4053 the @code{\s} escape.
4055 Some devices may only have certain permissible sizes, in which case
4056 @code{gtroff} will round to the nearest permissible size.
4061 ... .sz macro example?? ...
4064 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
4065 @subsection Fractional Type Sizes
4066 @cindex fractional type sizes
4067 @cindex type sizes, fractional
4069 @cindex @code{s} unit
4070 @cindex unit, @code{s}
4071 @cindex @code{z} unit
4072 @cindex unit, @code{z}
4078 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
4079 @var{sizescale} is specified in the @file{DESC} file (1@w{ }by default.)
4080 There is a new scale indicator @samp{z} which has the effect of
4081 multiplying by @var{sizescale}. Requests and escape sequences in
4082 @code{gtroff} interpret arguments that represent a point size as being in
4083 units of scaled points, but they evaluate each such argument using a
4084 default scale indicator of @samp{z}. Arguments treated in this way are
4085 the argument to the @code{ps} request, the third argument to the
4086 @code{cs} request, the second and fourth arguments to the @code{tkf}
4087 request, the argument to the @code{\H} escape sequence, and those
4088 variants of the @code{\s} escape sequence that take a numeric expression
4089 as their argument (see below).
4091 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
4092 will be equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
4093 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 10250
4094 scaled points, which is equal to 10.25@w{ }points.
4096 It would make no sense to use the @samp{z} scale indicator in a numeric
4097 expression whose default scale indicator was neither @samp{u} nor
4098 @samp{z}, and so @code{gtroff} disallows this. Similarly it would make
4099 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
4100 numeric expression whose default scale indicator was @samp{z}, and so
4101 @code{gtroff} disallows this as well.
4103 There is also new scale indicator @samp{s} which multiplies by the
4104 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
4105 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
4110 The number register @code{.s} returns the point size in points as decimal
4111 fraction. There is also a new number register @code{.ps} that returns
4112 the point size in scaled points.
4116 The last-requested point size in scaled points is contained in the
4117 @code{.psr} number register. The last requested point size in points as
4118 a decimal fraction can be found in @code{.psr}. This is a string-valued
4124 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
4125 expression with a default scale indicator of @samp{z}.
4134 Increases resp.@: decreases the point size by @var{n} scaled points;
4135 @var{n} is a numeric expression with a default scale indicator of
4142 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
4147 @code{gtroff} has string variables, which are entirely for user
4148 convenience (i.e.@: there are no built-in strings). They are defined
4149 via the @code{ds} request.
4152 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
4156 @cindex string interpolation
4157 @cindex string expansion
4158 @cindex interpolation of strings
4159 @cindex expansion of strings
4160 They are interpolated, or expanded in-place, via the @code{\*} escape:
4163 The \*(UX Operating System
4166 If the string named by the @code{\*} does not exist, the escape will be
4167 replaced by nothing.
4169 @cindex comments, with @code{ds}
4170 @strong{Caution:} Unlike other requests, the second argument to the
4171 @code{ds} request takes up the entire line including trailing spaces.
4172 This means that comments on a line with such a request can introduce
4173 unwanted space into a string.
4176 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
4180 Instead the comment should be put on another line or have the comment
4181 escape adjacent with the end of the string.
4184 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
4187 @cindex trailing quotes
4188 @cindex quotes, trailing
4189 @cindex leading spaces with @code{ds}
4190 @cindex spaces with @code{ds}
4191 To produce leading space the string can be started with a double quote.
4192 No trailing quote is needed; in fact, any trailing quote is included in
4196 .ds sign " Yours in a white wine sauce,
4200 @cindex appending to strings
4201 @cindex strings, appending
4202 The @code{as} request will append a string to another string. It works
4203 similar to the @code{ds} request except that it appends the second
4204 argument onto the string named by the first argument.
4207 .as sign " with shallots, onions and garlic,
4211 @cindex multi-line strings
4212 @cindex strings, multi-line
4213 @cindex newline character, escaping
4214 @cindex escaping newline characters
4215 Strings are not limited to a single line of text. A string can span
4216 several lines by escaping the newlines with a backslash. The resulting
4217 string will be stored @emph{without} the newlines.
4220 .ds foo lots and lots \
4221 of text are on these \
4227 Rudimentary string manipulation routines are given with the
4228 @code{substring} and @code{length} requests. The former has the
4232 .substring @var{xx} @var{n1} [@var{n2}]
4236 It replaces the string in register@w{ }@var{xx} with the substring
4237 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
4238 in the string has index one. If @var{n2} is omitted, it is taken to be
4239 equal to the string's length. If the index value @var{n1} or @var{n2}
4240 is negative or zero, it will be counted from the end of the string,
4241 going backwards: The last character has index@w{ }0, the character
4242 before the last character has index@w{ }-1, etc.
4245 @cindex length of a string
4246 @cindex string, length of
4247 Here the syntax of the @code{length} request:
4250 .length @var{xx} @var{string}
4254 It computes the length of @var{string} and returns it in the number
4255 register@w{ }@var{xx} (which is not necessarily defined before).
4277 @xref{Identifiers}, and @ref{Comments}.
4280 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
4281 @section Conditionals and Loops
4282 @cindex conditionals and loops
4283 @cindex loops and conditionals
4287 In @code{if} and @code{while} requests, there are several more operators
4293 True if the current page is even or odd numbered (respectively).
4296 True if the document is being processed by @code{nroff} (or a character
4297 device) resp.@: @code{troff}.
4298 @item '@var{xxx}'@var{yyy}'
4299 True if the string @var{xxx} is equal to the string @var{yyy}. Other
4300 characters can be used in place of the single quotes.
4302 The strings are `formatted' before being compared.
4305 True if there is a number register named @var{xxx}.
4307 True if there is a string, macro, diversion, or request named @var{xxx}.
4310 True if there is a character @var{ch} available; @var{ch} is either an
4311 @sc{ascii} character or a special character (@code{\(@var{ch}} or
4312 @code{\[@var{ch}]}); the condition will also be true if @var{ch} has
4313 been defined by the @code{char} request.
4321 @node if-else, while, Conditionals and Loops, Conditionals and Loops
4325 @code{gtroff} has if-then-else constructs like other languages, although
4326 the formatting can be painful.
4329 The @code{if} request has the following syntax:
4332 .if @var{expr} @var{anything}
4336 where @var{expr} is the expression to be evaluated; @var{anything} (the
4337 remainder of the line) will be executed if @var{expr} evaluates to
4338 non-zero (true). @var{anything} will be interpreted as though it was on
4339 a line by itself. @xref{Expressions}, for more info.
4341 Here are some examples:
4344 .if t .ls 2 \" double spacing in troff
4345 .if 0 .ab how'd this happen?
4350 An if-then-else is written using two requests @code{ie} and @code{el}.
4351 The first request is the `if' part and the latter is the `else' part.
4362 In many cases more than one request is to be executed as a result of any
4363 of these requests. This can be done using the @code{\@{} and @code{\@}}
4364 escapes. The following example shows the possible ways to use these
4365 escapes (note the position of the opening and closing braces).
4381 @node while, , if-else, Conditionals and Loops
4386 @code{gtroff} provides a looping construct using the @code{while}
4387 request, which is used much like the @code{if} (and related) requests.
4388 The first argument is an expression which will be evaluated. The
4389 @code{while} request will interpret the remainder of the line until the
4390 expression evaluates to 0 or false.
4394 .while (\na<9) \&\n+a,
4399 The preceding example produces:
4402 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
4405 @cindex zero width space character
4406 @cindex character, zero width space
4407 @cindex space character, zero width
4410 Note the usage of the @code{\&} escape to avoid a control character at
4411 the beginning of a line.
4415 The @code{break} request will @dfn{break} out of a while loop. Be sure
4416 not to confuse this with the @code{br} request (causing a line break).
4417 The @code{continue} request will finish the current iteration of a while
4418 loop, immediately restarting the next iteration.
4423 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
4424 @section Writing Macros
4425 @cindex writing macros
4426 @cindex macros, writing
4429 A @dfn{macro} is a collection of text and embedded commands which can be
4430 invoked multiple times. Macros are used for defining common operations.
4431 Macros are defined using the @code{de} request. This request takes a
4432 name for the macro as the first argument. Subsequent lines are copied
4433 into an internal buffer until the line @code{..} is encountered. The
4434 optional second argument to @code{de} can change this ending token.
4436 Here a small example macro called @samp{P} which will cause a break and
4437 the insertion of some vertical space. It could be used to separate
4448 The @code{am} request works similarly to @code{de} except it appends
4449 onto the macro named by the first argument. So, to make the previously
4450 defined @samp{P} macro actually do indented instead of block paragraphs,
4451 is is possible to add the necessary code to the existing macro like
4461 @cindex aliases, macro
4462 @cindex macro aliases
4463 Macros can be aliased with the @code{als} request.
4472 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
4473 @subsection Copy-in Mode
4474 @cindex copy-in mode
4475 @cindex mode, copy-in
4482 When @code{gtroff} reads in the text for a macro or diversion it copies
4483 the text (including request lines, but excluding escapes) into an
4484 internal buffer. Escapes will be converted into an internal form,
4485 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
4486 @code{\@key{RET}} which are evaluated and inserted into the text where
4487 the escape was located. This is known as @dfn{copy-in} mode.
4489 What this means is that you can specify when these escapes are to be
4490 evaluated (either at copy-in time or at the time of use) by insulating
4491 the escapes with an extra backslash. Compare this to the @code{\def}
4492 and @code{\edef} commands in @TeX{}.
4494 For example, the following will result in the numbers 20 and@c{ }10
4507 @node Parameters, , Copy-in Mode, Writing Macros
4508 @subsection Parameters
4513 The arguments to a macro can be examined using a variety of escapes.
4514 The number of arguments is available in the @code{.$} number register.
4515 Any individual argument can be retrieved with one of the following
4518 @cindex copy-in mode
4519 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
4520 @code{\$[@var{nnn}]} will result in the @var{n}th, @var{nn}th or
4521 @var{nnn}th argument. As usual, the first form only accepts a single
4522 number (larger than zero), the second only a two-digit number (larger or
4523 equal to@w{ }10), and the third any positive integer value (larger than
4524 zero). Macros can have an unlimited number of arguments. Note that due
4525 to copy-in mode, two backslashes should be used on these in actual use
4526 to prevent interpolation until the macro is actually invoked.
4529 The request @code{shift} will shift the arguments 1@w{ }position, or as
4530 many positions as specified by its argument. After executing this
4531 request, argument@w{ }@var{i} will become argument @var{i}-@var{n};
4532 arguments 1 to@w{ }@var{n} will no longer be available. Shifting by
4533 negative amounts is currently undefined.
4537 In some cases it is convenient to use all of the arguments at once (for
4538 example, to pass the arguments along to another macro). The @code{\$*}
4539 escape is the concatenation of all the arguments separated by spaces. A
4540 similar escape is @code{\$@@}, which is the concatenation of all the
4541 arguments with each surrounded by double quotes, and separated by
4546 The @code{\$0} escape is the name by which the current macro was
4547 invoked. The @code{als} request can make a macro have more than one
4552 .ie \\n(.$=1 .ds Vl Pre-Release Version
4553 .el .ds Vl Version \\$3, \\$4.
4557 This would be called as
4563 @xref{Request Arguments}.
4566 @node Page Motions, Drawing Requests, Writing Macros, Programming Tutorial
4567 @section Page Motions
4568 @cindex page motions
4569 @cindex motions, page
4572 Motions up and down the page can be done with the @code{sp} request.
4573 However, this causes a break so that the actual effect is to move to the
4574 left margin and then to the specified location.
4578 The request @code{mk} can be used to mark a location on a page, for
4579 movement to later. This request takes a register name as an argument in
4580 which to store the current page location. With no argument it will
4581 store the location in an internal register. The results of this can be
4582 used later by the @code{rt} or the @code{sp} request. The @code{rt}
4583 request will return @emph{upwards} to the location given in the register
4584 name given as an argument, with no argument it will return to the
4585 location marked with the @code{mk} request
4590 ... dual column example ...
4593 The following escapes give fine control of movements about the page.
4596 @cindex vertical motion
4597 @cindex motion, vertical
4598 The @code{\v'@var{e}'} enables arbitrary vertical motion from the
4599 current location on the page. The argument@w{ }@var{e} specifies the
4600 distance to move; positive is downwards and negative upwards. The
4601 default unit for this escape is vertical spaces, @code{v}'s. Beware,
4602 however, that @code{gtroff} will leave text processing to continue
4603 wherever the motion ends, so to avoid interference with text processing,
4604 motions should be balanced.
4606 There are some special case escapes for vertical motion.
4610 move upwards@w{ }1@dmn{v}.
4612 move upwards@w{ }.5@dmn{v}.
4614 move down@w{ }.5@dmn{v}.
4618 Horizontal motions can be done via the @code{\h'@var{e}'} escape. The
4619 expression@w{ }@var{e} indicates how far to move: positive is rightwards
4620 and negative leftwards.
4622 There are a number of special case escapes for horizontal motion:
4626 an unbreakable and unpaddable (i.e.@: not expanded during filling)
4627 space. (Note: It is a backslash followed by a space.)
4629 an unbreakable space that stretches like a normal inter-word space when a
4636 a space the size of a digit.
4637 @cindex zero width space character
4638 @cindex character, zero width space
4639 @cindex space character, zero width
4643 Like @code{\&} except that it behaves like a character declared with the
4644 @code{cflags} request to be transparent for the purposes of end of
4645 sentence recognition.
4651 ... tex logo example ...
4655 @cindex width escape
4656 @cindex escape, width
4657 A frequent need is to do horizontal movement based on the width of some
4658 arbitrary text (e.g.@: given as an argument to a macro). For that,
4659 there is the escape @code{\w'@var{text}'} which will interpolate to the
4660 width of the given @var{text} in basic units.
4665 ... strlen example ...
4668 Font changes may occur in @var{text} which don't affect current
4671 After use, @code{\w} sets several registers:
4678 The highest and lowest point, respectively, in @var{text}.
4683 Like the @code{st} and @code{sb} registers, but takes account of the
4684 heights and depths of characters.
4687 is set according to what kinds of characters occur in @var{text}:
4690 only short characters, no descenders or tall characters.
4696 both a descender and a tall character
4700 The amount of horizontal space (possibly negative) that should be added
4701 to the last character before a subscript.
4704 How far to right of the center of the last character in the @code{\w}
4705 argument, the center of an accent from a Roman font should be placed
4706 over that character.
4715 @c XXX documentation
4718 @node Drawing Requests, Traps, Page Motions, Programming Tutorial
4719 @section Drawing Requests
4720 @cindex drawing requests
4721 @cindex requests for drawing
4723 @code{gtroff} provides a number of ways to draw lines and other figures
4724 on the page. Used in combination with the page motion commands
4725 (@pxref{Page Motions}, for more info), a wide variety of figures can be
4726 drawn. However, for complex drawings these operations can be quite
4727 cumbersome, and it may be wise to use graphic preprocessors like
4728 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
4731 All drawing is done via escapes.
4734 @cindex horizontal line
4735 @cindex line, horizontal
4736 The @code{\l} escape will draw a line rightwards from the current
4737 location. The full syntax for this escape is
4744 where @var{l} is the length of the line to be drawn, starting at the
4745 current location; positive numbers will draw to the right, and negative
4746 will draw towards the left. This can also be specified absolutely
4747 (i.e.@: with a leading @samp{|}) which will draw back to the beginning
4750 @cindex underscore character
4751 @cindex character, underscore
4752 @cindex line drawing character
4753 @cindex character for line drawing
4754 The optional second parameter @var{c} is a character to draw the line
4755 with. If this second argument is not specified, @code{gtroff} will use
4756 the underscore character.
4758 @cindex zero width space character
4759 @cindex character, zero width space
4760 @cindex space character, zero width
4762 To separate the two arguments (to prevent @code{gtroff} from
4763 interpreting a drawing character as a scaling indicator) use @code{\&}.
4765 Here a small useful example:
4769 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
4775 Note that this works by outputting a box rule (a vertical line), then
4776 the text given as an argument and then another box rule. Then the line
4777 drawing escapes both draw from the current location to the beginning of
4778 the @emph{input} line.
4781 @cindex vertical line
4782 @cindex line, vertical
4783 @cindex line drawing character
4784 @cindex character for line drawing
4785 @cindex box rule character
4786 @cindex character, box rule
4787 Vertical lines are drawn using the @code{\L} escape. Its parameters are
4788 specified similar to the @code{\l} escape. If the length is positive,
4789 the movement will be downwards, and upwards for negative values. The
4790 default character is the box rule character. As with the vertical
4791 motion escapes, text processing will blindly continue where the line
4801 More flexible drawing functions are available via the @code{\D} escape.
4802 While the previous escapes will work on a character device, these
4806 @item \D'l @var{dx} @var{dy}'
4807 Draw a line from the current location to the relative point specified by
4808 (@var{dx},@var{dy}).
4813 ...revised box macro...
4818 Draw a circle with a diameter of @var{d} with the leftmost point at the
4821 Draw a solid circle with the same parameters as an outlined circle.
4822 @item \D'e @var{dx} @var{dy}'
4824 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
4825 diameter of @var{dy} with the leftmost point at the current position.
4826 @item \D'E @var{dx} @var{dy}'
4827 Draw a solid ellipse with the same parameters as an outlined ellipse.
4828 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
4830 Draw an arc clockwise from the current location through the two
4831 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
4832 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4834 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
4835 then to (@var{dx2},@var{dy2}), and so on.
4837 @cindex gray shading
4839 Set the shade of gray to be used for filling solid objects to@w{
4840 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
4841 corresponds solid white and 1000 to solid black, and values in between
4842 correspond to intermediate shades of gray. This applies only to solid
4843 circles, solid ellipses and solid polygons. By default, a level of@w{
4845 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4847 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
4848 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
4849 are exhausted, a line is drawn back to the starting point.
4854 ... box example (yes, again)...
4857 @itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4858 Draw a solid polygon with the same parameters as an outlined polygon.
4863 ... shaded box example ...
4867 @cindex line thickness
4868 @cindex thickness of lines
4869 Set the current line thickness to @var{n} machine units. A value of
4870 zero selects the smallest available line thickness. A negative value
4871 makes the line thickness proportional to the current point size (this is
4872 the default behaviour of @code{ditroff}).
4876 @cindex pile, character
4877 @cindex character pile
4878 The @code{\b} escape will @dfn{pile} a sequence of characters
4879 vertically, and center it vertically on the current line. This can be
4880 used to build large brackets and braces.
4883 \b'\(lt\(bv\(lk\(bv\(lb'
4886 @xref{Drawing Functions}.
4888 @node Traps, Diversions, Drawing Requests, Programming Tutorial
4892 @dfn{Traps} are locations, which, when reached, will call a specified
4893 macro. These traps can occur at a given location on the page, at a
4894 given location in the current diversion, after a certain number of input
4895 lines or at the end of input.
4898 * Page Location Traps::
4900 * Input Line Traps::
4901 * End-of-input Traps::
4904 @node Page Location Traps, Diversion Traps, Traps, Traps
4905 @subsection Page Location Traps
4906 @cindex page location traps
4907 @cindex traps, page location
4909 @c XXX definition of wh request
4911 @cindex page headers
4912 @cindex page footers
4915 Page location traps are frequently used for page headers and footers.
4916 The following is a simple example of this.
4919 .de hd \" Page header
4924 .de fo \" Page footer
4929 .wh 0 hd \" trap at top of the page
4930 .wh -1i fo \" trap one inch from bottom
4934 @cindex distance to next trap
4935 @cindex trap, distance
4936 The number register @code{.t} is the distance to the next trap.
4939 @cindex changing trap location
4940 @cindex trap, changing location
4941 The location of a trap can be changed later on with the @code{ch}
4942 request. The first argument is the name of the macro to be invoked at
4943 the trap, and the second argument is the new location for the trap.
4944 This is useful for building up footnotes in a diversion to allow more
4945 space at the bottom of the page for them.
4950 ... (simplified) footnote example ...
4957 The @code{vpt} request will enable vertical position traps if the
4958 argument is non-zero, disable them otherwise. Vertical position traps
4959 are traps set by the @code{wh} or @code{dt} requests. Traps set by the
4960 @code{it} request are not vertical position traps. The parameter that
4961 controls whether vertical position traps are enabled is global.
4962 Initially vertical position traps are enabled. The current setting of
4963 this is available in the number register @code{.vpt}.
4967 The number register @code{.trunc} contains the amount of vertical space
4968 truncated by the most recently sprung vertical position trap, or, if the
4969 trap was sprung by a @code{ne} request, minus the amount of vertical
4970 motion produced by the @code{ne} request. In other words, at the point
4971 a trap is sprung, it represents the difference of what the vertical
4972 position would have been but for the trap, and what the vertical
4973 position actually is.
4976 The number register @code{.ne} contains the amount of space that was
4977 needed in the last @code{ne} request that caused a trap to be sprung.
4978 Useful in conjunction with the @code{.trunc} register. @xref{Page
4979 Control}, for more information.
4981 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
4982 @subsection Diversion Traps
4983 @cindex diversion traps
4984 @cindex traps, diversion
4988 Traps can also be set @emph{within} a diversion using the @code{dt}
4989 request. Like @code{wh} the first argument is the location of the trap
4990 and the second argument is the name of the macro to be invoked. The
4991 number register @code{.t} will still work within diversions.
4992 @xref{Diversions}, for more information.
4994 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
4995 @subsection Input Line Traps
4996 @cindex input line traps
4997 @cindex traps, input line
5000 The @code{it} request will set an input line trap. The format for
5004 .it @var{n} @var{name}
5008 where @var{n} is the number of lines of input which may be read before
5009 @dfn{springing} the trap, @var{name} is the macro to be invoked.
5010 Request lines are not counted as input lines.
5012 For example, one possible use is to have a macro which will print the
5013 next @var{n}@w{ }lines in a bold font.
5025 @node End-of-input Traps, , Input Line Traps, Traps
5026 @subsection End-of-input Traps
5027 @cindex end-of-input traps
5028 @cindex traps, end-of-input
5031 The @code{em} request will set a trap at the end of input. The macro
5032 specified as an argument will be executed after the last line of the
5033 input file has been processed.
5035 For example, if the document had to have a section at the bottom of the
5036 last page for someone to approve it, the @code{em} request could be
5054 @node Diversions, Environments, Traps, Programming Tutorial
5058 In @code{gtroff} it is possible to @dfn{divert} text into a named
5059 storage area. Due to the similarity to defining macros it is sometimes
5060 said to be stored in a macro. This is used for saving text for output
5061 at a later time, which is useful for keeping blocks of text on the same
5062 page, footnotes, tables of contents and indices.
5066 A diversion is initiated by the @code{di} request. Like the @code{de}
5067 request, it takes an argument of a macro name to divert subsequent text
5068 into. The @code{da} macro will append to an existing diversion.
5070 @code{di} (resp.@: @code{da}) without an argument ends the diversion.
5075 ... end-note example ...
5082 @cindex nested diversions
5083 @cindex diversion, nested
5084 Diversions may be nested. The number register @code{.z} contains the
5085 name of the current diversion. The number register @code{.d} contains
5086 the current vertical place in the diversion. If not in a diversion it
5087 is the same as the register @code{nl}.
5095 After completing a diversion, the built-in number registers @code{dn}
5096 and @code{dl} contain the vertical and horizontal size of the diversion.
5099 .\" Center text both horizontally & vertically
5108 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
5123 @cindex transparent output
5124 @cindex output, transparent
5125 Requests, macros and escapes are interpreted when read into a diversion.
5126 There are two ways to prevent this; either way will take the given text
5127 and @dfn{transparently} embed it into the diversion. The first method
5128 is to prefix the line with @code{\!}. This will cause the entire line
5129 to be transparently inserted into the diversion. This is useful for
5130 macros which shouldn't be invoked until the diverted text is actually
5133 @c XXX anything is read in copy mode. (what about \! ??)
5136 The other way is to surround the text by the @code{\?} escape, i.e.
5143 @var{anything} may not contain newlines; use @code{\!} to embed
5144 newlines in a diversion. The escape sequence @code{\?} is also
5145 recognized in copy mode and turned into a single internal code; it is
5146 this code that terminates anything. Thus the following example will
5153 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
5168 @cindex unformatting diversions
5169 @cindex diversion, unformatting
5170 The @code{asciify} request only exists in order to make certain gross
5171 hacks work with GNU @code{troff}. It @dfn{unformats} the diversion
5172 specified as an argument in such a way that @sc{ascii} characters that
5173 were formatted and diverted will be treated like ordinary input
5174 characters when the diversion is reread. For example, the following
5175 will set register @code{n} to@w{ }1.
5188 @xref{Copy-in Mode}.
5191 @node Environments, I/O, Diversions, Programming Tutorial
5192 @section Environments
5193 @cindex environments
5195 It happens frequently that some text should be printed in a certain
5196 format regardless of what may be in effect at the time, for example, in
5197 a trap invoked macro to print headers and footers. To solve this
5198 @code{gtroff} has @dfn{environments} in which text is processed. An
5199 environment contains most of the parameters that control text
5200 processing. It is possible to switch amongst these environments; by
5201 default @code{gtroff} processes text in environment@w{ }0. The
5202 following is the information kept in an environment.
5208 font (family and style)
5216 partially collected lines
5219 These environments may be given arbitrary names (@pxref{Identifiers},
5220 for more info). Old versions of @code{troff} only had environments
5221 named @samp{0}, @samp{1} and@w{ }@samp{2}.
5225 The @code{ev} request will switch among environments. The single
5226 argument is the name of the environment to switch to. With no argument
5227 @code{gtroff} will switch back to the previous environment. There is no
5228 limit on the number of named environments; they will be created the
5229 first time that they are referenced. The @code{.ev} register contains
5230 the name or number of the current environment. This is a string-valued
5233 Note that a call to @code{ev} (with argument) will push the previously
5234 active environment onto a stack. If, say, environments @samp{foo},
5235 @samp{bar}, and @samp{zap} are called (in that order), the first
5236 @code{ev} request without parameter will switch back to environment
5237 @samp{bar} (which will be popped off the stack), and a second call will
5238 switch back to environment @samp{foo}.
5243 ... page break macro, revised ...
5246 Here another example:
5257 \(dg Note the large, friendly letters.
5262 To copy an environment into the current one, use the @code{evc} request,
5263 which takes the name of the environment to copy from as an argument.
5266 @node I/O, Postprocessor Access, Environments, Programming Tutorial
5269 @cindex input and output requests
5270 @cindex requests for input and output
5271 @cindex output and input requests
5274 The @code{so} request will read in the file given as an argument and
5275 include it in place of the @code{so} request. This is quite useful for
5276 large documents, i.e.@: keeping each chapter in a separate file.
5277 @xref{gsoelim}, for more information.
5280 The @code{mso} request is the same as the @code{so} request except that
5281 the file is searched for in the same way that @file{tmac.@var{name}} is
5282 searched for when the @samp{-m@var{name}} option is specified.
5285 @cindex transparent output
5286 @cindex output, transparent
5287 The @code{cf} and @code{trf} requests are to include a file. It will
5288 transparently output the contents of file filename. Each line is output
5289 as it were preceded by @code{\!}; however, the lines are not subject to
5290 copy-mode interpretation. If the file does not end with a newline, then
5291 a newline will be added. For example, to define a macro@w{ }@code{x}
5292 containing the contents of file@w{ }@file{f}, use
5300 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
5301 will embed in the diversion an object which, when reread, will cause the
5302 contents of @var{filename} to be transparently copied through to the
5303 output. In @sc{Unix} @code{troff}, the contents of @var{filename} is
5304 immediately copied through to the output regardless of whether there is
5305 a current diversion; this behaviour is so anomalous that it must be
5309 With @code{trf}, unlike @code{cf}, the file cannot contain characters
5310 such as NUL that are not legal @code{gtroff} input characters.
5312 @c XXX xref to illegal input characters
5315 The @code{nx} request will force @code{gtroff} to continue processing of
5316 the file specified as an argument.
5319 The @code{rd} request will read from standard input, and include what is
5320 read as though it were part of the input file. Text is read until a
5321 blank line is encountered.
5323 @cindex form letters
5324 @cindex letters, form
5325 Using these two requests it is easy to set up form letters. The form
5326 letter template is constructed like this:
5344 When this is run, the following file should be redirected in. Note that
5345 requests included in this file are executed as though they were part of
5346 the form letter. The last block of input is the @code{ex} requests
5347 which tells groff to stop processing. If this was not there, groff
5348 would not know when to stop.
5352 708 NW 19th Av., #202
5369 @c XXX documentation
5372 The @code{sy} request will allow arbitrary system commands to be
5373 executed from within a @code{gtroff} document. The output is not saved
5374 anyplace, so it is up to the user to do so.
5376 @c XXX add info about safer and unsafe mode
5378 For example, the following example will introduce the current time
5381 @cindex time, current
5382 @cindex current time
5385 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
5386 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
5393 Note that this works by having the @code{perl} script (run by @code{sy})
5394 print out the @code{nr} requests which will set the number registers
5395 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
5396 the @code{so} request.
5399 The @code{systat} number register contains the return value of the
5400 @code{system()} function executed by the last @code{sy} request.
5403 The @code{open} request will open a file (specified as the second
5404 argument) for writing and associate the stream (specified as the first
5408 The @code{opena} is like @code{open}, but if the file exists, append to
5409 it instead of truncating it.
5413 @cindex copy-in mode
5414 @cindex mode, copy-in
5415 The @code{write} request will write to the file associated with the
5416 stream specified by the first argument. The stream must previously have
5417 been the subject of an open request. The remainder of the line is
5418 interpreted as the @code{ds} request reads its second argument: A
5419 leading @samp{"} will be stripped, and it will be read in copy-in mode.
5422 The @code{close} request will close the stream specified by the first
5423 argument; stream will no longer be an acceptable argument to the
5424 @code{write} request.
5429 ... example of open write &c...
5433 The @code{\V} escape will interpolate the contents of the specified
5434 environment variable, as returned by @code{getenv()}. The argument to
5435 @code{\V} is specified as an identifier, i.e.@: @samp{\V@var{x}},
5436 @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} is interpreted in
5440 @node Postprocessor Access, Miscellaneous, I/O, Programming Tutorial
5441 @section Postprocessor Access
5442 @cindex postprocessor access
5443 @cindex access of postprocessor
5445 There are two escapes which will allow information to be directly given
5446 to the postprocessor. This is particularly useful for embedding
5447 @sc{PostScript} into the final document.
5450 The @code{\X} escape will embed its argument into the @code{gtroff}
5451 output preceded with @w{@samp{x X}}.
5454 The @code{\Y} escape is called with an identifier (i.e.@:
5455 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
5456 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
5457 contents of the string or macro @var{xxx} are not interpreted; also it
5458 is permitted for @var{xxx} to have been defined as a macro and thus
5459 contain newlines (it is not permitted for the argument to @code{\X} to
5460 contain newlines). The inclusion of newlines requires an extension to
5461 the @sc{Unix} @code{troff} output format, and will confuse drivers that
5462 do not know about this extension.
5464 @xref{Output Devices}.
5467 @node Miscellaneous, Debugging, Postprocessor Access, Programming Tutorial
5468 @section Miscellaneous
5469 @cindex miscellaneous
5471 This section contains parts of @code{gtroff} which cannot (yet) be
5472 categorized elsewhere in this manual.
5475 @cindex line numbers
5476 @cindex numbers, line
5477 Line numbers can be printed in the left margin using the @code{nm}
5478 request. The first argument is the line number of the @emph{next}
5479 output line; this defaults to@w{ }1. The second argument indicates on
5480 which lines numbers will be printed, i.e.@: 5 means put line numbers on
5481 every 5@w{ }lines; this defaults to@w{ }1. The third argument is the
5482 space to be left between the number and the text; this defaults to@w{
5483 }1. The fourth argument is the indentation of the line numbers.
5484 Without arguments, line numbers are turned off.
5487 The @code{nn} request will temporarily turn off line numbering. The
5488 first argument is the number of lines not to be numbered; this defaults
5491 @c XXX (does this disable incrementing or display?)
5496 ... line numbering example ...
5500 @cindex margin characters
5501 @cindex characters for margins
5502 Margin characters can be automatically printed to the right of the text
5503 with the @code{mc} request. The first argument is the character to be
5504 printed, and the second argument is the distance away from the main body
5505 text. With no arguments the margin characters are turned off. If this
5506 occurs before a break, no margin character will be printed.
5510 This is quite useful for indicating text that has changed, and, in fact,
5511 there are programs available for doing this (they are called
5512 @code{nrchbar} and @code{changebar} and can be found in any
5513 @samp{comp.sources.unix} archive.
5518 ... margin char example ...
5523 @cindex multi-file documents
5524 @cindex documents, multi-file
5525 The primary reason for the existence of @code{lf} is to make debugging
5526 documents which are split into many files, which are then put together
5527 with @code{soelim} and other preprocessors. The first argument is the
5528 name of the file and the second argument is the input line number in
5529 that file. This way @code{gtroff} can produce error messages which are
5530 intelligible to the user.
5535 ... example of soelim'ed doc ...
5539 @node Debugging, Implementation Differences, Miscellaneous, Programming Tutorial
5543 @code{gtroff} is not easy to debug, but there are some useful features
5544 and strategies for debugging.
5549 The @code{tm} request will send output to stderr; this is very useful
5550 for printing debugging output.
5552 When doing something involved it is useful to leave the debugging
5553 statements in the code and have them turned on by a command line flag.
5556 .if \n(DB .tm debugging output
5560 To activate these statements say
5569 The @code{ab} request is similar to the @code{tm} request, except that
5570 it will cause @code{gtroff} to stop processing. With no argument it
5571 will print @samp{User Abort}.
5575 The @code{ex} request will also cause @code{gtroff} to stop processing
5576 (if encountered at the topmost level; see also @ref{I/O}.
5578 If it is known in advance that there will be many errors and no useful
5579 output, @code{gtroff} can be forced to suppress formatted output with
5583 @cindex dumping symbol table
5584 @cindex symbol table, dumping
5585 The @code{pm} request will dump out the entire symbol table.
5588 @cindex dumping number registers
5589 @cindex number registers, dumping
5590 The @code{pnr} request will print the names and contents of all
5591 currently defined number registers on stderr.
5594 @cindex dumping traps
5595 @cindex traps, dumping
5596 The @code{ptr} request will print the names and positions of all traps
5597 (not including input line traps and diversion traps) on stderr. Empty
5598 slots in the page trap list are printed as well, because they can affect
5599 the priority of subsequently planted traps.
5602 @cindex flush output
5603 @cindex output, flush
5604 @cindex interactive use of @code{gtroff}
5605 @cindex @code{gtroff}, interactive use
5606 The @code{fl} request instructs @code{gtroff} to flush its output
5607 immediately. The intention is that this be used when using
5608 @code{gtroff} interactively. There is little other use for it.
5611 @cindex backtrace of input stack
5612 @cindex input stack, backtrace
5613 The @code{backtrace} request will print a backtrace of the input stack
5617 @code{gtroff} has command line options for printing out more warnings
5618 (@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or an
5619 error occurs. The most verbose level of warnings is @samp{-ww}.
5623 @cindex level of warnings
5624 @cindex warnings, level
5625 The @code{warn} request controls the level of warnings checked for. The
5626 only argument is the sum of the numbers associated with each warning
5627 that is to be enabled; all other warnings will be disabled. The number
5628 associated with each warning is listed below. For example,
5629 @w{@code{.warn 0}} will disable all warnings, and @w{@code{.warn 1}}
5630 will disable all warnings except that about missing characters. If an
5631 argument is not given, all warnings will be enabled. The number
5632 register @code{.warn} contains the current warning level.
5635 @subsection Warnings
5638 The warnings that can be given to @code{gtroff} are divided into the
5639 following categories. The name associated with each warning is used by
5640 the @samp{-w} and @samp{-W} options; the number is used by the
5641 @code{warn} request and by the @code{.warn} register.
5646 Non-existent characters. This is enabled by default.
5649 Invalid numeric expressions. This is enabled by default.
5653 In fill mode, lines which could not be broken so that their length was
5654 less than the line length. This is enabled by default.
5657 Missing or mismatched closing delimiters.
5662 Use of the @code{el} request with no matching @code{ie} request.
5666 Meaningless scaling indicators.
5669 Out of range arguments.
5672 Dubious syntax in numeric expressions.
5677 Use of @code{di} or @code{da} without an argument when there is no
5682 @c XXX more findex entries
5683 Use of undefined strings, macros and diversions. When an undefined
5684 string, macro or diversion is used, that string is automatically defined
5685 as empty. So, in most cases, at most one warning will be given for each
5690 @c XXX more findex entries
5691 Use of undefined number registers. When an undefined number register is
5692 used, that register is automatically defined to have a value of@w{ }0.
5693 A definition is automatically made with a value of@w{ }0. So, in most
5694 cases, at most one warning will be given for use of a particular name.
5697 Use of a tab character where a number was expected.
5701 Use of @code{\@}} where a number was expected.
5704 Requests that are missing non-optional arguments.
5707 Illegal input characters.
5710 Unrecognized escape sequences. When an unrecognized escape sequence is
5711 encountered, the escape character is ignored.
5714 @cindex compatibility mode
5715 Missing space between a request or macro and its argument. This warning
5716 will be given when an undefined name longer than two characters is
5717 encountered, and the first two characters of the name make a defined
5718 name. The request or macro will not be invoked. When this warning is
5719 given, no macro is automatically defined. This is enabled by default.
5720 This warning will never occur in compatibility mode.
5723 Non-existent fonts. This is enabled by default.
5725 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
5726 intended that this covers all warnings that are useful with traditional
5733 @node Implementation Differences, Summary, Debugging, Programming Tutorial
5734 @section Implementation Differences
5735 @cindex implementation differences
5736 @cindex differences in implementation
5737 @cindex compatibility mode
5738 @cindex mode, compatibility
5740 GNU @code{troff} has a number of features which cause incompatibilities
5741 with documents written with old versions of @code{troff}.
5745 Long names cause some incompatibilities. @sc{Unix} @code{troff} will
5757 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
5758 @code{troff} will interpret this as a call of a macro named
5759 @code{dsabcd}. Also @sc{Unix} @code{troff} will interpret @code{\*[} or
5760 @code{\n[} as references to a string or number register called @samp{[}.
5761 In GNU @code{troff}, however, this will normally be interpreted as the
5762 start of a long name. In compatibility mode GNU @code{troff} will
5763 interpret these things in the traditional way. In compatibility mode,
5764 however, long names are not recognized. Compatibility mode can be
5765 turned on with the @samp{-C} command line option, and turned on or off
5766 with the @code{cp} request. The number register @code{.C} is@w{ }1 if
5767 compatibility mode is on, 0@w{ }otherwise.
5783 GNU @code{troff} does not allow the use of the escape sequences
5784 @code{\|}, @code{\^}, @code{\&}, @code{\@}}, @code{\@{},
5785 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
5786 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
5787 registers, fonts or environments; @sc{Unix} @code{troff} does. The
5788 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
5789 avoiding use of these escape sequences in names.
5791 @cindex fractional point sizes
5792 @cindex point sizes, fractional
5794 Fractional point sizes cause one noteworthy incompatibility. In
5795 @sc{Unix} @code{troff} the @code{ps} request ignores scale indicators
5803 will set the point size to 10@w{ }points, whereas in GNU @code{troff} it
5804 will set the point size to 10@w{ }scaled points. @xref{Fractional Type
5805 Sizes}, for more information.
5812 @cindex input and output characters
5813 @cindex output characters
5814 @cindex characters, input and output
5815 In GNU @code{troff} there is a fundamental difference between
5816 unformatted, input characters, and formatted, output characters.
5817 Everything that affects how an output character will be output is stored
5818 with the character; once an output character has been constructed it is
5819 unaffected by any subsequent requests that are executed, including
5820 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
5821 Normally output characters are constructed from input characters at the
5822 moment immediately before the character is added to the current output
5823 line. Macros, diversions and strings are all, in fact, the same type of
5824 object; they contain lists of input characters and output characters in
5825 any combination. An output character does not behave like an input
5826 character for the purposes of macro processing; it does not inherit any
5827 of the special properties that the input character from which it was
5828 constructed might have had. For example,
5841 @cindex transparent output
5842 @cindex output, transparent
5844 will print @samp{\\} in GNU @code{troff}; each pair of input backslashes
5845 is turned into one output backslash and the resulting output backslashes
5846 are not interpreted as escape characters when they are reread.
5847 @sc{Unix} @code{troff} would interpret them as escape characters when
5848 they were reread and would end up printing one @samp{\}. The correct
5849 way to obtain a printable backslash is to use the @code{\e} escape
5850 sequence: This will always print a single instance of the current escape
5851 character, regardless of whether or not it is used in a diversion; it
5852 will also work in both GNU @code{troff} and @sc{Unix} @code{troff}. To
5853 store, for some reason, an escape sequence in a diversion that will be
5854 interpreted when the diversion is reread, either use the traditional
5855 @code{\!} transparent output facility, or, if this is unsuitable, the
5856 new @code{\?} escape sequence.
5858 @xref{Diversions}, for more information.
5861 @node Summary, , Implementation Differences, Programming Tutorial
5865 @c XXX documentation
5869 @node Preprocessors, Output Devices, Programming Tutorial, Top
5870 @chapter Preprocessors
5871 @cindex preprocessors
5873 This chapter describes all preprocessors that come with @code{groff} or
5874 which are freely available.
5887 @node geqn, gtbl, Preprocessors, Preprocessors
5888 @section @code{geqn}
5898 @node Invoking geqn, , geqn, geqn
5899 @subsection Invoking @code{geqn}
5900 @cindex invoking @code{geqn}
5901 @cindex @code{geqn}, invoking
5906 @node gtbl, gpic, geqn, Preprocessors
5907 @section @code{gtbl}
5917 @node Invoking gtbl, , gtbl, gtbl
5918 @subsection Invoking @code{gtbl}
5919 @cindex invoking @code{gtbl}
5920 @cindex @code{gtbl}, invoking
5925 @node gpic, ggrn, gtbl, Preprocessors
5926 @section @code{gpic}
5936 @node Invoking gpic, , gpic, gpic
5937 @subsection Invoking @code{gpic}
5938 @cindex invoking @code{gpic}
5939 @cindex @code{gpic}, invoking
5944 @node ggrn, grap, gpic, Preprocessors
5945 @section @code{ggrn}
5955 @node Invoking ggrn, , ggrn, ggrn
5956 @subsection Invoking @code{ggrn}
5957 @cindex invoking @code{ggrn}
5958 @cindex @code{ggrn}, invoking
5963 @node grap, grefer, ggrn, Preprocessors
5964 @section @code{grap}
5967 A freely available implementation of @code{grap}, written by Ted Faber,
5968 is available as an extra package from the following address:
5971 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
5975 @node grefer, gsoelim, grap, Preprocessors
5976 @section @code{grefer}
5977 @cindex @code{refer}
5978 @cindex @code{grefer}
5986 @node Invoking grefer, , grefer, grefer
5987 @subsection Invoking @code{grefer}
5988 @cindex invoking @code{grefer}
5989 @cindex @code{grefer}, invoking
5994 @node gsoelim, , grefer, Preprocessors
5995 @section @code{gsoelim}
5996 @cindex @code{soelim}
5997 @cindex @code{gsoelim}
6002 * Invoking gsoelim::
6005 @node Invoking gsoelim, , gsoelim, gsoelim
6006 @subsection Invoking @code{gsoelim}
6007 @cindex invoking @code{gsoelim}
6008 @cindex @code{gsoelim}, invoking
6014 @node Output Devices, File formats, Preprocessors, Top
6015 @chapter Output Devices
6016 @cindex output devices
6017 @cindex devices for output
6022 * Special Characters::
6033 @node Special Characters, grotty, Output Devices, Output Devices
6034 @section Special Characters
6035 @cindex special characters
6036 @cindex characters, special
6043 @node grotty, grops, Special Characters, Output Devices
6044 @section @code{grotty}
6045 @cindex @code{grotty}
6053 @node Invoking grotty, , grotty, grotty
6054 @subsection Invoking @code{grotty}
6055 @cindex invoking @code{grotty}
6056 @cindex @code{grotty}, invoking
6061 @node grops, grodvi, grotty, Output Devices
6062 @section @code{grops}
6063 @cindex @code{grops}
6069 * Embedding PostScript::
6072 @node Invoking grops, Embedding PostScript, grops, grops
6073 @subsection Invoking @code{grops}
6074 @cindex invoking @code{grops}
6075 @cindex @code{grops}, invoking
6079 @node Embedding PostScript, , Invoking grops, grops
6080 @subsection Embedding PostScript
6081 @cindex embedding postscript
6082 @cindex postscript, embedding
6087 @node grodvi, grolj4, grops, Output Devices
6088 @section @code{grodvi}
6089 @cindex @code{grodvi}
6097 @node Invoking grodvi, , grodvi, grodvi
6098 @subsection Invoking @code{grodvi}
6099 @cindex invoking @code{grodvi}
6100 @cindex @code{grodvi}, invoking
6105 @node grolj4, grolbp, grodvi, Output Devices
6106 @section @code{grolj4}
6107 @cindex @code{grolj4}
6115 @node Invoking grolj4, , grolj4, grolj4
6116 @subsection Invoking @code{grolj4}
6117 @cindex invoking @code{grolj4}
6118 @cindex @code{grolj4}, invoking
6123 @node grolbp, grohtml, grolj4, Output Devices
6124 @section @code{grolbp}
6125 @cindex @code{grolbp}
6133 @node Invoking grolbp, , grolbp, grolbp
6134 @subsection Invoking @code{grolbp}
6135 @cindex invoking @code{grolbp}
6136 @cindex @code{grolbp}, invoking
6141 @node grohtml, gxditview, grolbp, Output Devices
6142 @section @code{grohtml}
6143 @cindex @code{grohtml}
6148 * Invoking grohtml::
6151 @node Invoking grohtml, , grohtml, grohtml
6152 @subsection Invoking @code{grohtml}
6153 @cindex invoking @code{grohtml}
6154 @cindex @code{grohtml}, invoking
6159 @node gxditview, , grohtml, Output Devices
6160 @section @code{gxditview}
6161 @cindex @code{gxditview}
6166 * Invoking gxditview::
6169 @node Invoking gxditview, , gxditview, gxditview
6170 @subsection Invoking @code{gxditview}
6171 @cindex invoking @code{gxditview}
6172 @cindex @code{gxditview}, invoking
6179 @node File formats, Installation, Output Devices, Top
6180 @chapter File formats
6181 @cindex file formats
6182 @cindex formats, file
6192 @node gtroff Output, Font Files, File formats, File formats
6193 @section @code{gtroff} Output
6194 @cindex @code{gtroff} output
6195 @cindex output, @code{gtroff}
6197 This section describes the format output of GNU @code{troff}. The
6198 output format used by GNU @code{troff} is very similar to that used by
6199 @sc{Unix} device-independent @code{troff} (@code{ditroff}).
6204 * Drawing Functions::
6205 * Line Continuation::
6208 @node Output Format, Device Control, gtroff Output, gtroff Output
6209 @subsection Output Format
6210 @cindex output format
6211 @cindex format of output
6214 @cindex input, 8-bit
6215 The output format is text based, as opposed to a binary format (like
6216 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
6217 characters can have the eighth bit set, as can the names of fonts and
6220 The output format consists of single command characters with attached
6221 parameters which are separated from subsequent text by whitespace or a
6224 The names of characters and fonts can be of arbitrary length; drivers
6225 should not assume that they will be only two characters long (as
6226 @code{ditroff} does).
6228 When a character is to be printed, that character will always be in the
6229 current font. Unlike @code{ditroff}, it is not necessary for drivers to
6230 search special fonts to find a character.
6245 @item @var{nn}@var{c}
6248 @var{xxx} is any sequence of characters terminated by a space or a
6249 newline; the first character should be printed at the current position,
6250 the the current horizontal position should be increased by the width of
6251 the first character, and so on for each character. The width of the
6252 character is that given in the font file, appropriately scaled for the
6253 current point size, and rounded so that it is a multiple of the
6254 horizontal resolution. Special characters cannot be printed using this
6259 This command is only allowed if the @samp{tcommand} line is present in
6260 the @file{DESC} file.
6261 @item u@var{n} @var{xxx}
6262 This is same as the @samp{t} command except that after printing each
6263 character, the current horizontal position is increased by the sum of
6264 the width of that character and@w{ }@var{n}.
6266 This command is only allowed if the @samp{tcommand} line is present in
6267 the @file{DESC} file.
6268 @item n@var{a}@var{b}
6275 The argument to the @samp{s} command is in scaled points (units of
6276 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
6277 command in the @file{DESC} file).
6282 @item D@var{c} @var{x}@dots{}\n
6286 @node Device Control, Drawing Functions, Output Format, gtroff Output
6287 @subsection Device Control
6288 @cindex device control
6289 @cindex control of devices
6291 The @samp{x} command is normally followed by a letter or word indicating
6292 the function to perform, followed by white space separated arguments.
6294 The first argument can be abbreviated to the first letter.
6301 @item x res @var{n} @var{h} @var{v}
6305 The argument to the @w{@samp{x Height}} command is also in scaled
6309 The first three output commands are guaranteed to be:
6318 For example, the input
6321 crunchy \fH\s+2frog\s0\fP!?
6330 ... sample output here ...
6333 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
6334 @subsection Drawing Functions
6335 @cindex drawing functions
6336 @cindex functions for drawing
6339 The @samp{D} drawing command has been extended. These extensions will
6340 only be used by GNU @code{pic} if the @samp{-x} option is given.
6342 @xref{Drawing Requests}.
6347 Set the shade of gray to be used for filling solid objects to@w{
6348 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
6349 corresponds solid white and 1000 to solid black, and values in between
6350 correspond to intermediate shades of gray. This applies only to solid
6351 circles, solid ellipses and solid polygons. By default, a level of@w{
6352 }1000 will be used. Whatever color a solid object has, it should
6353 completely obscure everything beneath it. A value greater than@w{ }1000
6354 or less than@w{ }0 can also be used: this means fill with the shade of
6355 gray that is currently being used for lines and text. Normally this
6356 will be black, but some drivers may provide a way of changing this.
6358 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
6359 point at the current position.
6360 @item DE @var{dx} @var{dy}
6361 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
6362 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
6364 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
6365 Draw a polygon with. The first vertex is at the current position, the
6366 second vertex at an offset (@var{dx1},@var{dy1}) from the current
6367 position, the second vertex at an offset (@var{dx2},@var{dy2}) from the
6368 first vertex, and so on up to the @var{n}-th vertex. At the moment, GNU
6369 @code{pic} only uses this command to generate triangles and rectangles.
6370 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
6371 Like @code{Dp} but draw a solid rather than outlined polygon.
6373 @cindex line thickness
6374 @cindex thickness of lines
6375 Set the current line thickness to @var{n}@w{ }machine units.
6376 Traditionally, @sc{Unix} @code{troff} drivers use a line thickness
6377 proportional to the current point size; drivers should continue to do
6378 this if no @code{Dt} command has been given, or if a @code{Dt} command
6379 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
6380 }@var{n} selects the smallest available line thickness.
6384 A difficulty arises in how the current position should be changed after
6385 the execution of these commands. This is not of great importance since
6386 the code generated by GNU @code{pic} does not depend on this. Given a
6387 drawing command of the form
6390 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
6397 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
6398 @samp{~}, @sc{Unix} @code{troff} will treat each of the x@w{ }value as a
6399 horizontal quantity, and each of the y@w{ }values as a vertical quantity
6400 and will assume that the width of the drawn object is sum if all x@w{
6401 }values, and that the height is the sum of all y@w{ }values. (The
6402 assumption about the height can be seen by examining the @code{st} and
6403 @code{sb} registers after using such a @code{D}@w{ }command in a
6404 @code{\w} escape sequence.) This rule also holds for all the original
6405 drawing commands with the exception of @code{De}. For the sake of
6406 compatibility GNU @code{troff} also follows this rule, even though it
6407 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
6408 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
6409 @code{D}@w{ }command of the form
6412 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
6416 the current position should be increased horizontally by the sum of all
6417 x@w{ }values and vertically by the sum of all y@w{ }values.
6419 @node Line Continuation, , Drawing Functions, gtroff Output
6420 @subsection Line Continuation
6421 @cindex line continuation in output commands
6422 @cindex output commands, line continuation
6424 There is a continuation convention which permits the argument to the
6425 @w{@samp{x X}} command to contain newlines: When outputting the argument
6426 to the @w{@samp{x X}} command, GNU @code{troff} will follow each newline
6427 in the argument with a @samp{+} character (as usual, it will terminate
6428 the entire argument with a newline); thus if the line after the line
6429 containing the @w{@samp{x X}} command starts with @samp{+}, then the
6430 newline ending the line containing the @w{@samp{x X}} command should be
6431 treated as part of the argument to the @w{@samp{x X}} command, the
6432 @samp{+} should be ignored, and the part of the line following the
6433 @samp{+} should be treated like the part of the line following the
6434 @w{@samp{x X}} command.
6437 @node Font Files, , gtroff Output, File formats
6442 The @code{gtroff} font format is roughly a superset of the
6443 @code{ditroff} font format. Unlike the @code{ditroff} font format,
6444 there is no associated binary format; all files are text files. The
6445 font files for device @var{name} are stored in a directory
6446 @file{dev@var{name}}. There are two types of file: a device description
6447 file called @file{DESC} and for each font@w{ }@samp{F} a font file
6448 called@w{ }@file{F}.
6451 * DESC file format::
6452 * Font file format::
6455 @node DESC file format, Font file format, Font Files, Font Files
6456 @subsection @file{DESC} file format
6457 @cindex @file{DESC} file format
6458 @cindex font description file format
6459 @cindex format of font description file
6462 The @file{DESC} file can contain the following types of line:
6467 There are @var{n} machine units per inch.
6470 The horizontal resolution is @var{n} machine units.
6473 The vertical resolution is @var{n} machine units.
6475 @item sizescale @var{n}
6476 The scale factor for point sizes. By default this has a value of@w{ }1.
6477 One scaled point is equal to one point/@var{n}. The arguments to the
6478 @code{unitwidth} and @code{sizes} commands are given in scaled points.
6479 @xref{Fractional Type Sizes}, for more information.
6481 @item unitwidth @var{n}
6482 Quantities in the font files are given in machine units for fonts whose
6483 point size is @var{n}@w{ }scaled points.
6486 This means that the postprocessor can handle the @samp{t} and @samp{u}
6489 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
6490 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
6491 @var{sn} scaled points. The list of sizes must be terminated by a@w{
6492 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
6493 list can extend over more than one line.
6495 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
6496 The first @var{m}@w{ }font positions will be associated with styles
6497 @var{S1} @dots{} @var{Sm}.
6499 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
6500 Fonts @var{F1} @dots{} @var{Fn} will be mounted in the font positions
6501 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
6502 styles. This command may extend over more than one line. A font name
6503 of@var{ }0 will cause no font to be mounted on the corresponding font
6506 @item family @var{fam}
6507 The default font family is @var{fam}.
6510 This line and everything following in the file are ignored. It is
6511 allowed for the sake of backwards compatibility.
6514 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
6515 are compulsory. Other commands are ignored by @code{gtroff} but may be
6516 used by postprocessors to store arbitrary information about the device
6517 in the @file{DESC} file.
6519 @c XXX add other commands resp. xrefs to output devices
6520 @c XXX add obsolete commands
6522 @node Font file format, , DESC file format, Font Files
6523 @subsection Font file format
6524 @cindex font file format
6525 @cindex format of font files
6527 A font file has two sections. The first section is a sequence of lines
6528 each containing a sequence of blank delimited words; the first word in
6529 the line is a key, and subsequent words give a value for that key.
6534 The name of the font is@w{ }@var{F}.
6536 @item spacewidth @var{n}
6537 The normal width of a space is@w{ }@var{n}.
6540 The characters of the font have a slant of @var{n}@w{ }degrees.
6541 (Positive means forward.)
6543 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
6544 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
6545 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
6546 @samp{ffl}. For backwards compatibility, the list of ligatures may be
6547 terminated with a@w{ }0. The list of ligatures may not extend over more
6551 The font is special; this means that when a character is requested that
6552 is not present in the current font, it will be searched for in any
6553 special fonts that are mounted.
6556 Other commands are ignored by @code{gtroff} but may be used by
6557 postprocessors to store arbitrary information about the font in the font
6560 @cindex comments in font files
6561 @cindex font files, comments
6563 The first section can contain comments which start with the @samp{#}
6564 character and extend to the end of a line.
6566 The second section contains one or two subsections. It must contain a
6567 @code{charset} subsection and it may also contain a @code{kernpairs}
6568 subsection. These subsections can appear in any order. Each
6569 subsection starts with a word on a line by itself.
6572 The word @code{charset} starts the character set subsection. The
6573 @code{charset} line is followed by a sequence of lines. Each line gives
6574 information for one character. A line comprises a number of fields
6575 separated by blanks or tabs. The format is
6577 @c XXX fix it for new HTML additions
6580 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
6584 @cindex input, 8-bit
6588 @var{name} identifies the character: If @var{name} is a single
6589 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
6590 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
6591 a single character, then it corresponds to the @code{gtroff} input
6592 character@w{ }\@var{c}; otherwise it corresponds to the groff input
6593 character @samp{\[@var{name}]}. (If it is exactly two characters
6594 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
6595 supports 8-bit characters; however some utilities have difficulties with
6596 eight-bit characters. For this reason, there is a convention that the
6597 name @samp{char@var{n}} is equivalent to the single character whose code
6598 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
6599 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
6600 Latin-1} character set. The name @samp{---} is special and indicates
6601 that the character is unnamed; such characters can only be used by means
6602 of the @code{\N} escape sequence in @code{gtroff}.
6604 @c XXX input encodings vs. output encodings
6606 The @var{type} field gives the character type:
6610 the character has an descender, for example, `p';
6612 the character has an ascender, for example, `b';
6614 the character has both an ascender and a descender, for example, `('.
6617 The @var{code} field gives the code which the postprocessor uses to
6618 print the character. The character can also be input to @code{gtroff}
6619 using this code by means of the @code{\N} escape sequence. The code can
6620 be any integer. If it starts with @samp{0} it will be interpreted as
6621 octal; if it starts with @samp{0x} or @samp{0X} it will be interpreted as
6624 Anything on the line after the @var{code} field will be ignored.
6626 The @var{metrics} field has the form:
6629 @var{width}[,@var{height}[,@var{depth}[,@var{italic_correction}
6630 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]]
6634 There must not be any spaces between these subfields (it has been split
6635 here into two lines for better legibility only). Missing subfields are
6636 assumed to be@w{ }0. The subfields are all decimal integers. Since
6637 there is no associated binary format, these values are not required to
6638 fit into a variable of type @samp{char} as they are in @code{ditroff}.
6639 The @var{width} subfield gives the width of the character. The
6640 @var{height} subfield gives the height of the character (upwards is
6641 positive); if a character does not extend above the baseline, it should
6642 be given a zero height, rather than a negative height. The @var{depth}
6643 subfield gives the depth of the character, that is, the distance below
6644 the lowest point below the baseline to which the character extends
6645 (downwards is positive); if a character does not extend below above the
6646 baseline, it should be given a zero depth, rather than a negative depth.
6647 The @var{italic_correction} subfield gives the amount of space that
6648 should be added after the character when it is immediately to be
6649 followed by a character from a Roman font. The
6650 @var{left_italic_correction} subfield gives the amount of space that
6651 should be added before the character when it is immediately to be
6652 preceded by a character from a Roman font. The
6653 @var{subscript_correction} gives the amount of space that should be
6654 added after a character before adding a subscript. This should be less
6655 than the italic correction.
6657 A line in the @code{charset} section can also have the format
6664 This indicates that @var{name} is just another name for the character
6665 mentioned in the preceding line.
6668 The word @code{kernpairs} starts the kernpairs section. This contains a
6669 sequence of lines of the form:
6672 @var{c1} @var{c2} @var{n}
6675 This means that when character @var{c1} appears next to character
6676 @var{c2} the space between them should be increased by@w{ }@var{n}.
6677 Most entries in kernpairs section will have a negative value for@w{
6682 @node Installation, Request and Operator Index, File formats, Top
6683 @chapter Installation
6684 @cindex installation
6690 @node Request and Operator Index, Register Index, Installation, Top
6691 @chapter Request and Operator Index
6697 @node Register Index, Font File Keyword Index, Request and Operator Index, Top
6698 @chapter Register Index
6704 @node Font File Keyword Index, Program and File Index, Register Index, Top
6705 @chapter Font File Keyword Index
6711 @node Program and File Index, Concept Index, Font File Keyword Index, Top
6712 @chapter Program and File Index
6718 @node Concept Index, , Program and File Index, Top
6719 @chapter Concept Index