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
16 @c tindex: environment variables
18 @c tindex and cindex are merged.
23 @dircategory Miscellaneous
25 * Groff: (groff). The GNU troff document formatting system.
38 This Info file documents GNU troff version 1.16.
40 Published by the Free Software Foundation
41 59 Temple Place, Suite 330
42 Boston, MA 02111-1307 USA
44 Copyright (C) 1994-2000 Free Software Foundation, Inc.
46 Permission is granted to make and distribute verbatim copies of this
47 manual provided the copyright notice and this permission notice are
48 preserved on all copies.
51 Permission is granted to process this file through TeX and print the
52 results, provided the printed document carries copying permission notice
53 identical to this one except for the removal of this paragraph (this
54 paragraph not being relevant to the printed manual).
57 Permission is granted to copy and distribute modified versions of this
58 manual under the conditions for verbatim copying, provided that the
59 entire resulting derived work is distributed under the terms of a
60 permission notice identical to this one.
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions,
64 except that this permission notice may be stated in a translation
65 approved by the Foundation.
67 Permission is granted to copy and distribute modified versions of this
68 manual under the conditions for verbatim copying, provided also that the
69 section entitled ``GNU General Public License'' is included exactly as
70 in the original, and provided that the entire resulting derived work is
71 distributed under the terms of a permission notice identical to this
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions,
76 except that the section entitled ``GNU General Public License'' may be
77 included in a translation approved by the Free Software Foundation
78 instead of in the original English.
84 @subtitle The GNU implementation of @code{groff}
85 @subtitle Edition 1.16
87 @author by Trent A.@w{ }Fisher
88 @author and the maintainer of groff
90 @c Include the Distribution inside the titlepage environment so
91 @c that headings are turned off. Headings on and off do not work.
94 @vskip 0pt plus 1filll
95 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
97 Version 1.16 of @code{groff}, @*
100 Published by the Free Software Foundation @*
101 59 Temple Place, Suite 330 @*
102 Boston, MA 02111-1307 USA
105 Permission is granted to make and distribute verbatim copies of this
106 manual provided the copyright notice and this permission notice are
107 preserved on all copies.
109 Permission is granted to copy and distribute modified versions of this
110 manual under the conditions for verbatim copying, provided also that the
111 section entitled ``GNU General Public License'' is included exactly as
112 in the original, and provided that the entire resulting derived work is
113 distributed under the terms of a permission notice identical to this
116 Permission is granted to copy and distribute translations of this manual
117 into another language, under the above conditions for modified versions,
118 except that the section entitled ``GNU General Public License'' may be
119 included in a translation approved by the Free Software Foundation
120 instead of in the original English.
122 Cover art by Etienne Suvasa.
128 @node Top, Copying, (dir), (dir)
131 This Info file documents groff version 1.16, the GNU implementation of
132 the troff typesetting system.
134 This is an in-progress document; contributions, comments, or
135 contributions are welcome. Send them to bug-groff@@gnu.org.
142 * Tutorial for Macro Users::
144 * Programming Tutorial::
159 @node Copying, Introduction, Top, Top
161 @unnumbered GNU GENERAL PUBLIC LICENSE
162 @center Version 2, June 1991
165 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
166 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
168 Everyone is permitted to copy and distribute verbatim copies of this
169 license document, but changing it is not allowed.
172 @unnumberedsec Preamble
174 The licenses for most software are designed to take away your freedom to
175 share and change it. By contrast, the GNU General Public License is
176 intended to guarantee your freedom to share and change free software --
177 to make sure the software is free for all its users. This General
178 Public License applies to most of the Free Software Foundation's
179 software and to any other program whose authors commit to using it.
180 (Some other Free Software Foundation software is covered by the GNU
181 Library General Public License instead.) You can apply it to your
184 When we speak of free software, we are referring to freedom, not price.
185 Our General Public Licenses are designed to make sure that you have the
186 freedom to distribute copies of free software (and charge for this
187 service if you wish), that you receive source code or can get it if you
188 want it, that you can change the software or use pieces of it in new
189 free programs; and that you know you can do these things.
191 To protect your rights, we need to make restrictions that forbid anyone
192 to deny you these rights or to ask you to surrender the rights. These
193 restrictions translate to certain responsibilities for you if you
194 distribute copies of the software, or if you modify it.
196 For example, if you distribute copies of such a program, whether gratis
197 or for a fee, you must give the recipients all the rights that you have.
198 You must make sure that they, too, receive or can get the source code.
199 And you must show them these terms so they know their rights.
201 We protect your rights with two steps: (1)@w{ }copyright the software,
202 and (2)@w{ }offer you this license which gives you legal permission to
203 copy, distribute and/or modify the software.
205 Also, for each author's protection and ours, we want to make certain
206 that everyone understands that there is no warranty for this free
207 software. If the software is modified by someone else and passed on, we
208 want its recipients to know that what they have is not the original, so
209 that any problems introduced by others will not reflect on the original
210 authors' reputations.
212 Finally, any free program is threatened constantly by software patents.
213 We wish to avoid the danger that redistributors of a free program will
214 individually obtain patent licenses, in effect making the program
215 proprietary. To prevent this, we have made it clear that any patent
216 must be licensed for everyone's free use or not licensed at all.
218 The precise terms and conditions for copying, distribution and
222 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
225 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
230 This License applies to any program or other work which contains a
231 notice placed by the copyright holder saying it may be distributed under
232 the terms of this General Public License. The ``Program'', below,
233 refers to any such program or work, and a ``work based on the Program''
234 means either the Program or any derivative work under copyright law:
235 that is to say, a work containing the Program or a portion of it, either
236 verbatim or with modifications and/or translated into another language.
237 (Hereinafter, translation is included without limitation in the term
238 ``modification''.) Each licensee is addressed as ``you''.
240 Activities other than copying, distribution and modification are not
241 covered by this License; they are outside its scope. The act of running
242 the Program is not restricted, and the output from the Program is
243 covered only if its contents constitute a work based on the Program
244 (independent of having been made by running the Program). Whether that
245 is true depends on what the Program does.
248 You may copy and distribute verbatim copies of the Program's source code
249 as you receive it, in any medium, provided that you conspicuously and
250 appropriately publish on each copy an appropriate copyright notice and
251 disclaimer of warranty; keep intact all the notices that refer to this
252 License and to the absence of any warranty; and give any other
253 recipients of the Program a copy of this License along with the Program.
255 You may charge a fee for the physical act of transferring a copy, and
256 you may at your option offer warranty protection in exchange for a fee.
259 You may modify your copy or copies of the Program or any portion of it,
260 thus forming a work based on the Program, and copy and distribute such
261 modifications or work under the terms of Section@w{ }1 above, provided
262 that you also meet all of these conditions:
266 You must cause the modified files to carry prominent notices stating
267 that you changed the files and the date of any change.
270 You must cause any work that you distribute or publish, that in whole or
271 in part contains or is derived from the Program or any part thereof, to
272 be licensed as a whole at no charge to all third parties under the terms
276 If the modified program normally reads commands interactively when run,
277 you must cause it, when started running for such interactive use in the
278 most ordinary way, to print or display an announcement including an
279 appropriate copyright notice and a notice that there is no warranty (or
280 else, saying that you provide a warranty) and that users may
281 redistribute the program under these conditions, and telling the user
282 how to view a copy of this License. (Exception: if the Program itself
283 is interactive but does not normally print such an announcement, your
284 work based on the Program is not required to print an announcement.)
287 These requirements apply to the modified work as a whole. If
288 identifiable sections of that work are not derived from the Program, and
289 can be reasonably considered independent and separate works in
290 themselves, then this License, and its terms, do not apply to those
291 sections when you distribute them as separate works. But when you
292 distribute the same sections as part of a whole which is a work based on
293 the Program, the distribution of the whole must be on the terms of this
294 License, whose permissions for other licensees extend to the entire
295 whole, and thus to each and every part regardless of who wrote it.
297 Thus, it is not the intent of this section to claim rights or contest
298 your rights to work written entirely by you; rather, the intent is to
299 exercise the right to control the distribution of derivative or
300 collective works based on the Program.
302 In addition, mere aggregation of another work not based on the Program
303 with the Program (or with a work based on the Program) on a volume of a
304 storage or distribution medium does not bring the other work under the
305 scope of this License.
308 You may copy and distribute the Program (or a work based on it, under
309 Section@w{ }2) in object code or executable form under the terms of
310 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
315 Accompany it with the complete corresponding machine-readable source
316 code, which must be distributed under the terms of Sections@w{ }1 and@w{
317 }2 above on a medium customarily used for software interchange; or,
320 Accompany it with a written offer, valid for at least three years, to
321 give any third party, for a charge no more than your cost of physically
322 performing source distribution, a complete machine-readable copy of the
323 corresponding source code, to be distributed under the terms of
324 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
328 Accompany it with the information you received as to the offer to
329 distribute corresponding source code. (This alternative is allowed only
330 for noncommercial distribution and only if you received the program in
331 object code or executable form with such an offer, in accord with
332 Subsection@w{ }b above.)
335 The source code for a work means the preferred form of the work for
336 making modifications to it. For an executable work, complete source
337 code means all the source code for all modules it contains, plus any
338 associated interface definition files, plus the scripts used to control
339 compilation and installation of the executable. However, as a special
340 exception, the source code distributed need not include anything that is
341 normally distributed (in either source or binary form) with the major
342 components (compiler, kernel, and so on) of the operating system on
343 which the executable runs, unless that component itself accompanies the
346 If distribution of executable or object code is made by offering access
347 to copy from a designated place, then offering equivalent access to copy
348 the source code from the same place counts as distribution of the source
349 code, even though third parties are not compelled to copy the source
350 along with the object code.
353 You may not copy, modify, sublicense, or distribute the Program except
354 as expressly provided under this License. Any attempt otherwise to
355 copy, modify, sublicense or distribute the Program is void, and will
356 automatically terminate your rights under this License. However,
357 parties who have received copies, or rights, from you under this License
358 will not have their licenses terminated so long as such parties remain
362 You are not required to accept this License, since you have not signed
363 it. However, nothing else grants you permission to modify or distribute
364 the Program or its derivative works. These actions are prohibited by
365 law if you do not accept this License. Therefore, by modifying or
366 distributing the Program (or any work based on the Program), you
367 indicate your acceptance of this License to do so, and all its terms and
368 conditions for copying, distributing or modifying the Program or works
372 Each time you redistribute the Program (or any work based on the
373 Program), the recipient automatically receives a license from the
374 original licensor to copy, distribute or modify the Program subject to
375 these terms and conditions. You may not impose any further restrictions
376 on the recipients' exercise of the rights granted herein. You are not
377 responsible for enforcing compliance by third parties to this License.
380 If, as a consequence of a court judgment or allegation of patent
381 infringement or for any other reason (not limited to patent issues),
382 conditions are imposed on you (whether by court order, agreement or
383 otherwise) that contradict the conditions of this License, they do not
384 excuse you from the conditions of this License. If you cannot
385 distribute so as to satisfy simultaneously your obligations under this
386 License and any other pertinent obligations, then as a consequence you
387 may not distribute the Program at all. For example, if a patent license
388 would not permit royalty-free redistribution of the Program by all those
389 who receive copies directly or indirectly through you, then the only way
390 you could satisfy both it and this License would be to refrain entirely
391 from distribution of the Program.
393 If any portion of this section is held invalid or unenforceable under
394 any particular circumstance, the balance of the section is intended to
395 apply and the section as a whole is intended to apply in other
398 It is not the purpose of this section to induce you to infringe any
399 patents or other property right claims or to contest validity of any
400 such claims; this section has the sole purpose of protecting the
401 integrity of the free software distribution system, which is implemented
402 by public license practices. Many people have made generous
403 contributions to the wide range of software distributed through that
404 system in reliance on consistent application of that system; it is up to
405 the author/donor to decide if he or she is willing to distribute
406 software through any other system and a licensee cannot impose that
409 This section is intended to make thoroughly clear what is believed to be
410 a consequence of the rest of this License.
413 If the distribution and/or use of the Program is restricted in certain
414 countries either by patents or by copyrighted interfaces, the original
415 copyright holder who places the Program under this License may add an
416 explicit geographical distribution limitation excluding those countries,
417 so that distribution is permitted only in or among countries not thus
418 excluded. In such case, this License incorporates the limitation as if
419 written in the body of this License.
422 The Free Software Foundation may publish revised and/or new versions of
423 the General Public License from time to time. Such new versions will be
424 similar in spirit to the present version, but may differ in detail to
425 address new problems or concerns.
427 Each version is given a distinguishing version number. If the Program
428 specifies a version number of this License which applies to it and ``any
429 later version'', you have the option of following the terms and
430 conditions either of that version or of any later version published by
431 the Free Software Foundation. If the Program does not specify a version
432 number of this License, you may choose any version ever published by the
433 Free Software Foundation.
436 If you wish to incorporate parts of the Program into other free programs
437 whose distribution conditions are different, write to the author to ask
438 for permission. For software which is copyrighted by the Free Software
439 Foundation, write to the Free Software Foundation; we sometimes make
440 exceptions for this. Our decision will be guided by the two goals of
441 preserving the free status of all derivatives of our free software and
442 of promoting the sharing and reuse of software generally.
452 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
453 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
454 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
455 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
456 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
457 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
458 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
459 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
460 NECESSARY SERVICING, REPAIR OR CORRECTION.
463 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
464 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
465 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
466 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
467 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
468 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
469 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
470 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
471 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
475 @heading END OF TERMS AND CONDITIONS
478 @center END OF TERMS AND CONDITIONS
483 @unnumberedsec How to Apply These Terms to Your New Programs
485 If you develop a new program, and you want it to be of the greatest
486 possible use to the public, the best way to achieve this is to make it
487 free software which everyone can redistribute and change under these
490 To do so, attach the following notices to the program. It is safest to
491 attach them to the start of each source file to most effectively convey
492 the exclusion of warranty; and each file should have at least the
493 ``copyright'' line and a pointer to where the full notice is found.
496 @var{one line to give the program's name and an idea of what it does.}
497 Copyright (C) 19@var{yy} @var{name of author}
499 This program is free software; you can redistribute it and/or modify
500 it under the terms of the GNU General Public License as published by
501 the Free Software Foundation; either version 2 of the License, or (at
502 your option) any later version.
504 This program is distributed in the hope that it will be useful, but
505 WITHOUT ANY WARRANTY; without even the implied warranty of
506 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
507 General Public License for more details.
509 You should have received a copy of the GNU General Public License
510 along with this program; if not, write to the Free Software
511 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
514 Also add information on how to contact you by electronic and paper mail.
516 If the program is interactive, make it output a short notice like this
517 when it starts in an interactive mode:
520 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
521 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
522 `show w'. This is free software, and you are welcome to redistribute
523 it under certain conditions; type `show c' for details.
526 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
527 show the appropriate parts of the General Public License. Of course,
528 the commands you use may be called something other than @samp{show@w{
529 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu
530 items---whatever suits your program.
532 You should also get your employer (if you work as a programmer) or your
533 school, if any, to sign a ``copyright disclaimer'' for the program, if
534 necessary. Here is a sample; alter the names:
538 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
539 `Gnomovision' (which makes passes at compilers) written by James
542 @var{signature of Ty Coon}, 1 April 1989 Ty Coon, President of Vice
546 This General Public License does not permit incorporating your program
547 into proprietary programs. If your program is a subroutine library, you
548 may consider it more useful to permit linking proprietary applications
549 with the library. If this is what you want to do, use the GNU Library
550 General Public License instead of this License.
554 @node Introduction, Invoking groff, Copying, Top
555 @chapter Introduction
558 GNU @code{troff} (or @code{groff}) is a system for typesetting
559 documents. @code{troff} is very flexible and has been in existence (and
560 use) for about 3@w{ }decades. It is quite widespread and firmly
561 entrenched in the @sc{Unix} community.
566 * groff Capabilities::
567 * Macro Package Intro::
568 * Preprocessor Intro::
569 * Output device intro::
574 @node What Is groff?, History, Introduction, Introduction
575 @section What Is @code{groff}?
576 @cindex what is @code{groff}?
577 @cindex @code{groff} -- what is it?
579 @code{groff} is of an older generation of document preparation systems,
580 which operate more like compilers than the more recent interactive
581 WYSIWYG@footnote{What You See Is What You Get} systems. @code{groff}
582 and its contemporary counterpart, @TeX{}, both work using a @dfn{batch}
583 paradigm: The input (or @dfn{source}) files are normal text files with
584 embedded formatting commands. These files can then be processed by
585 @code{groff} to produce a typeset document on a variety of devices.
587 Likewise, @code{groff} should not be confused with a @dfn{word
588 processor}, since that term connotes an integrated system which includes
589 an editor and a text formatter. Also, many word processors follow the
590 WYSIWYG paradigm which was discussed earlier.
592 Although WYSIWYG systems may be easier to use, they have a number of
593 disadvantages compared to @code{troff}:
597 They must be used on a bitmapped display to do any operations on your
600 Most of the WYSIWYG systems are either non-free or are not very
603 @code{troff} is firmly entrenched in all @sc{Unix} systems.
605 It is difficult to have a wide range of capabilities available within
606 the confines of a GUI/window system.
608 It is more difficult to make global changes to a document.
612 ``GUIs normally make it simple to accomplish simple actions and
613 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
614 @code{comp.unix.wizards})
618 @node History, groff Capabilities, What Is groff?, Introduction
622 @cindex @code{runoff}
623 @code{troff} can trace its origins back to a formatting program called
624 @code{runoff} which ran on MIT's CTSS system. This name came from the
625 common phrase of the time ``I'll run off a document.''
628 The first version of @sc{Unix} was developed on a PDP-7 which was
629 sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11
630 for further work on the operating system. In order to justify the cost
631 for this system, they proposed that they would implement a document
632 formatting system for the AT&T patents division. This first formatting
633 program was a reimplementation of @code{runoff}. In accordance with
634 @sc{Unix}'s penchant for abreviations, it was named @code{roff} (an
635 abreviation of @code{runoff}).
638 When they needed a more flexible language, a new version of @code{roff}
639 called @code{nroff} (Newer @code{roff}) was written. It had a much more
640 complicated syntax, but provided the basis for all future versions.
641 When they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{
642 }Ossanna wrote a version of @code{nroff} which would drive it. It was
643 dubbed @code{troff} for typesetter @code{roff}, although many people
644 have speculated that it actually means Times @code{roff} because of
645 @code{troff}'s use of the Times font family by default. As such, the
646 name @code{troff} is pronounced t-roff rather than trough.
648 With @code{troff} came @code{nroff} (they were actually the same program
649 except for some @samp{#ifdefs}), which was for producing output for line
650 printers and character terminals. It understood everything @code{troff}
651 did, and ignored the commands which were not aplicable (i.e.@: font
654 Since there are several things which cannot be done easily in
655 @code{troff}, work on several preprocessors began. These programs would
656 transform certain parts of a document into @code{troff}, which made a
657 very natural use of pipes in @sc{Unix}.
659 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
660 specified in a much simpler and more intuitive manner. @code{tbl} is a
661 preprocessor for formatting tables. The @code{refer} preprocessor (and
662 the similar program, @code{bib}) processes citations in a document
663 according to a bibliographic database.
665 Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
666 language and produced output specifically for the CAT phototypesetter.
667 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
668 code and still dependent on the CAT. As the CAT became less common, and
669 was no longer supported by the manufacturer, the need to make it support
670 other devices became a priority. However, before this could be done, he
671 was killed in an auto accident.
674 @cindex @code{ditroff}
675 So, Brian Kernighan took on the task of rewriting @code{troff}. The
676 newly rewritten version produced a device independent code which was
677 very easy for postprocessors to read and translate to the appropriate
678 printer codes. Also, this new version of @code{troff} (called
679 @code{ditroff}) had several extentions, which included drawing
682 Due to the additional abilities of the new version of @code{troff},
683 several new preprocessors appeared. The @code{pic} preprocessor
684 provides a wide range of drawing functions. Likewise the @code{ideal}
685 preprocessor did the same, although via a much different paradigm. The
686 @code{grap} preprocessor took specifications for graphs, but, unlike
687 other preprocessors, produced @code{pic} code.
689 James Clark began work on a GNU implementation of @code{ditroff} in
690 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
691 June@w{ }1990. @code{groff} included
695 A replacement for @code{ditroff} with many extentions.
697 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
699 Postprocessors for character devices, PostScript, @TeX{} DVI, and X@w{
700 }windows. GNU @code{troff} also eliminated the need for a separate
701 @code{nroff} program with a postprocessor which would produce @sc{ascii}
704 A version of the @code{-me} macros and an implementation of the
708 Also, a front-end was included which could construct the, sometimes
709 painfully long, pipelines required for all the post- and preprocessors.
711 Development of GNU @code{troff} progressed rapidly, and saw the
712 additions of a replacement for @code{refer}, an implementation of the
713 @code{-ms} and @code{-mm} macros, and a program to deduce how to format
714 a document (@code{grog}).
716 It was declared a stable (i.e.@: non beta) package with the release of
717 version@w{ }1.04 around November@w{ }1991.
719 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
720 an orphan for a few years). As a result, new features and programs like
721 @code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an
722 output device to produce HTML output, have been added.
725 @node groff Capabilities, Macro Package Intro, History, Introduction
726 @section @code{groff} Capabilities
727 @cindex @code{groff} capabilities
728 @cindex capabilities of @code{groff}
730 So what exactly is @code{groff} capable of doing? @code{groff} provides
731 a wide range of low-level text formatting operations. Using these, you
732 can perform a wide range of formatting tasks, such as footnotes, table
733 of contents, multiple columns, etc.
737 Text filling, adjusting, and centering
743 Font and character size control
745 Vertical spacing (i.e.@: double spacing)
747 Line length and indenting
749 Macros, strings, diversions, and traps
753 Tabs, leaders, and fields
755 Input and output conventions and character translation
757 Overstrike, bracket, line drawing, and zero-width functions
759 Local horizontal and vertical motions and the width function
763 Output line numbering
765 Conditional acceptance of input
767 Environment switching
769 Insertions from the standard input
771 Input/output file switching
773 Output and error messages
777 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
778 @section Macro Packages
779 @cindex macro packages
781 Since @code{groff} provides such low level facilities, it can be quite
782 difficult to use by itself. However, @code{groff} provides a
783 @dfn{macro} facility which allows you to specify how certain routine
784 operations (e.g.@w{ }starting paragraphs, printing headers and footers,
785 etc.)@: should be done. These macros can be collected together into a
786 @dfn{macro package}. There are a number of macro packages available;
787 the most common (and the ones described in this manual) are @code{-man},
788 @code{-mdoc}, @code{-me}, @code{-ms}, and @code{-mm}.
791 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
792 @section Preprocessors
793 @cindex preprocessors
795 Although @code{groff} provides most functions needed to format a
796 document, some operations would be unwieldy (i.e.@: drawing pictures).
797 Therefore, programs called preprocessors were written which understand
798 their own language and produce the necessary @code{groff} operations.
799 These preprocessors are able to differentiate their own input from the
800 rest of the document via markers.
802 To use a preprocessor, @sc{Unix} pipes are used to feed the output from
803 the preprocessor into @code{groff}. Any number of preprocessors may be
804 used on a given document; in this case, the preprocessors are linked
805 together into one pipeline. However, in @code{groff}, the user does not
806 need to construct the pipe, but only tell @code{groff} what
807 preprocessors to use.
809 @code{groff} currently has preprocessors for producing tables
810 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
811 (@code{pic} and @code{grn}), and for processing bibliographies
812 (@code{refer}). An associated program which is useful when dealing with
813 preprocessors is @code{soelim}.
815 There are other preprocessors in existence, but there are,
816 unfortunately, no free implementations available. They are for drawing
817 pictures (@code{ideal}) and chemical structures (@code{chem}).
819 A free implementation of @code{grap}, a preprocessor for drawing graphs,
820 can be obtained as an extra package.
823 @node Output device intro, Credits, Preprocessor Intro, Introduction
824 @section Output Devices
825 @cindex postprocessors
826 @cindex output devices
827 @cindex devices for output
829 @code{groff} actually produces device independent code which may be fed
830 into a postprocessor which will produce output for a particular device.
831 Currently, @code{groff} has postprocessors for PostScript, character
832 terminals, X@w{ }Windows (for previewing), @TeX{} DVI format, HP
833 LaserJet@w{ }4 printers, and HTML.
836 @node Credits, , Output device intro, Introduction
840 Large portions of this manual were taken from existing documents, most
841 notably, the manual pages for the @code{groff} package by James Clark,
842 and Eric Allman's papers on the @code{-me} macro package.
846 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
847 @chapter Invoking @code{groff}
848 @cindex invoking @code{groff}
849 @cindex @code{groff} invocation
853 This section focuses on how to invoke the @code{groff} front end. This
854 front end takes care of the details of constructing the pipeline among
855 the preprocessors, @code{gtroff} and the postprocessor.
857 It has become a tradition that GNU programs get the prefix @dfn{g} to
858 distinguish it from its original counterparts provided by the host
859 (@pxref{Environment}, for more details). Thus, for example, @code{geqn}
860 is GNU @code{eqn}. On operating systems like Linux or the Hurd, which
861 don't contain proprietary software, this prefix is omitted since GNU
862 @code{troff} is the only used incarnation of @code{troff}. Exception:
863 @code{groff} is never replaced by `@code{roff}'.
868 * Invocation Examples::
872 @node Options, Environment, Invoking groff, Invoking groff
884 @code{groff} is a front-end to the groff document formatting system.
885 Normally it runs the @code{gtroff} program and a postprocessor
886 appropriate for the selected device. The default device is @samp{ps}.
887 It can optionally preprocess with any of @code{gpic}, @code{geqn},
888 @code{gtbl}, @code{ggrn}, @code{grefer}, or @code{gsoelim}.
890 This section only documents options to the @code{groff} front end. Many
891 of the arguments to @code{groff} are passed on to @code{gtroff},
892 therefore those are also included. Arguments to pre- or postprocessors
893 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
894 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
895 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
896 grohtml}, @ref{Invoking grodvi}, and @ref{Invoking gxditview}.
898 The command line format for @code{groff} is:
901 groff [ -abeghilpstvzCENRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
902 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
903 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
904 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
905 [ @var{files}@dots{} ]
908 The command line format for @code{gtroff} is as follows. As you can
909 see, many of the options to @code{groff} are actually passed on to
913 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
914 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
915 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
916 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
919 Options without an argument can be grouped behind a single @samp{-}. A
920 filename of @samp{-} denotes the standard input.
923 The @code{grog} command can be used to guess the correct @code{groff}
924 command to use to format a file.
928 Print a help message.
930 Preprocess with @code{geqn}.
932 Preprocess with @code{gtbl}.
934 Preprocess with @code{ggrn}.
936 Preprocess with @code{gpic}.
938 Preprocess with @code{gsoelim}.
940 Preprocess with @code{grefer}. No mechanism is provided for passing
941 arguments to @code{grefer} because most @code{grefer} options have
942 equivalent commands which can be included in the file. @xref{grefer},
946 Note that @code{gtroff} also accepts a @samp{-R} option, which is not
947 accessible via @code{groff}. This option prevents the loading of the
950 Make programs run by @code{groff} print out their version number.
952 Print the pipeline on stdout instead of executing it.
954 Suppress output from @code{gtroff}. Only error messages will be
957 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
958 will automatically run the appropriate postprocessor.
960 Pass @var{arg} to the postprocessor. Each argument should be passed
961 with a separate @samp{-P} option. Note that @code{groff} does not
962 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
964 Send the output to a printer. The command used for this is specified by
965 the print command in the device description file.
967 Pass @var{arg} to the spooler. Each argument should be passed with a
968 separate @samp{-L} option. Note that @code{groff} does not prepend a
969 @samp{-} to @var{arg} before passing it to the postprocessor.
971 Prepare output for device @var{dev}. The default device is @samp{ps}.
972 The following are the output devices currently available:
975 For PostScript printers and previewers.
977 For @TeX{} dvi format.
979 For a 75dpi X11 previewer.
981 For a 100dpi X11 previewer.
983 For typewriter-like devices.
985 For typewriter-like devices using the ISO@w{ }Latin@w{-}1 (ISO@w{
986 }8859@w{-}1) character set.
988 For typewriter-like devices using the Unicode (ISO@w{ }10646) character
989 set with UTF@w{-}8 encoding.
991 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
993 To produce HTML output.
996 The postprocessor to be used for a device is specified by the
997 @code{postpro} command in the device description file. (@xref{Font
998 Files}, for more info.) This can be overridden with the @samp{-X}
1001 Preview with @code{gxditview} instead of using the usual postprocessor.
1002 This is unlikely to produce good results except with @samp{-Tps}.
1004 Don't allow newlines with @code{eqn} delimiters. This is the same as
1005 the @samp{-N} option in @code{geqn}.
1007 Safer mode. Pass the @samp{-S} option to @code{gpic} and use the
1008 @samp{-msafer} macros with @code{gtroff} (enabled by default).
1010 Unsafe mode. Reverts to the old unsafe behaviour.
1012 Generate an @sc{ascii} approximation of the typeset output.
1014 Print a backtrace with each warning or error message. This backtrace
1015 should help track down the cause of the error. The line numbers given
1016 in the backtrace may not always be correct: @code{gtroff}'s idea of line
1017 numbers gets confused by @code{as} or @code{am} requests.
1019 Read the standard input after all the named input files have been
1022 Enable warning @var{name}. Available warnings are described in
1023 @ref{Debugging}. Multiple @samp{-w} options are allowed.
1025 Inhibit warning @var{name}. Multiple @samp{-W} options are allowed.
1027 Inhibit all error messages.
1029 Enable compatibility mode.
1031 @itemx -d@var{name}=s
1032 Define @var{c} or @var{name} to be a string @var{s}; @var{c} must be a
1033 one-letter @var{name}.
1035 Use @var{fam} as the default font family.
1037 Read in the file @file{tmac.@var{name}}. Normally this will be searched
1038 for in @code{groff}'s lib directory.
1040 Number the first page @var{num}.
1042 Output only pages in @var{list}, which is a comma-separated list of page
1043 ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
1044 print every page between @var{m} and @var{n}, @samp{-@var{n}} means
1045 print every page up to @var{n}, @samp{@var{n}-} means print every page
1046 from @var{n}. @code{gtroff} will exit after printing the last page in
1049 @itemx -r@var{name}=@var{n}
1050 Set number register @var{c} or @var{name} to @var{n}; @var{c} must be a
1051 one-letter @var{name}; @var{n} can be any troff numeric expression.
1053 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1054 name of the device) for the @file{DESC} file and font files before the
1057 Search directory @var{dir} for macro files before the normal directory.
1059 This option is as described in @ref{gsoelim}. It implies the @samp{-s}
1064 @node Environment, Invocation Examples, Options, Invoking groff
1065 @section Environment
1066 @cindex environment variables
1067 @cindex variables in environment
1069 There are also several environment variables which can modify
1070 @code{groff}'s behavior.
1073 @item GROFF_COMMAND_PREFIX
1074 @tindex GROFF_COMMAND_PREFIX
1075 If this is set to @var{X}, then @code{groff} will run
1076 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1077 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1078 @code{soelim}. It does not apply to @code{grops}, @code{grodvi},
1079 @code{grotty}, @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1080 @item GROFF_TMAC_PATH
1081 @tindex GROFF_TMAC_PATH
1082 A colon separated list of directories in which to search for macro
1084 @item GROFF_TYPESETTER
1085 @tindex GROFF_TYPESETTER
1086 The default output device.
1087 @item GROFF_FONT_PATH
1088 @tindex GROFF_FONT_PATH
1089 A colon separated list of directories in which to search for the
1090 @code{dev}@var{name} directory.
1093 The search path for commands executed by @code{groff}.
1095 @tindex GROFF_TMPDIR
1097 The directory in which temporary files will be created. If this is not
1098 set and @code{TMPDIR} is set, temporary files will be created in that
1099 directory. Otherwise temporary files will be created in @code{/tmp}.
1100 The @code{grops} and @code{grefer} commands can create temporary files.
1104 @node Invocation Examples, , Environment, Invoking groff
1105 @section Invocation Examples
1106 @cindex invocation examples
1107 @cindex examples of invocation
1109 This section will list several common uses of @code{groff} and the
1110 command line which will accomplish it.
1117 This command processes @var{file} without a macro package or a
1118 preprocessor. The output device is the default, @var{ps}, and the
1119 output is sent to stdout.
1122 groff -t -mandoc -Tascii file | less
1126 This is basically what a call to @code{man} does. The manual page
1127 @var{file} is processed with the @code{-mandoc} macros (which in turn
1128 either call the @code{-man} or the @code{-mdoc} macro package), using
1129 the @code{tbl} preprocessor and the @sc{ascii} output device. Finally,
1130 the result is displayed with the @code{less} pager.
1137 Preview @var{file} with @code{gxditview}, using the @code{-me} macro
1141 groff -man -rD1 -z file
1145 Check @var{file} with the @code{-man} macro package, forcing
1146 double-sided printing---don't produce any output.
1148 @subsection @code{grog}
1150 @code{grog} reads files and guesses which of the @code{groff}
1151 preprocessors and/or macro packages are are required for formatting
1152 them, and prints the @code{groff} command including those options on the
1153 standard output. The options generated are one of @samp{-e},
1154 @samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-R},
1155 @samp{-g}, @samp{-s}, and @samp{-t}.
1157 A filename of @samp{-} is taken to refer to the standard input. If no
1158 files are specified the standard input will be read. Any specified
1159 options will be included in the printed command. No space is allowed
1160 between options and their arguments. For example,
1167 will guess the appropriate command to print @file{paper.ms} and then
1168 print it to the command line after adding the @samp{-Tdvi} option. If
1169 you want to directly execute it, enclose the call to @code{grog} in
1170 backquotes on the @sc{Unix} shell prompt:
1173 `grog -Tdvi paper.ms` > paper.dvi
1177 As you can see, it is still necessary to redirect the output to
1178 something meaningful (i.e.@: either a file or a pager program like
1183 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1184 @chapter Tutorial for Macro Users
1185 @cindex tutorial for macro users
1186 @cindex macro tutorial for users
1187 @cindex user's tutorial for macros
1188 @cindex user's macro tutorial
1190 Most users tend to use a macro package to format their papers. This
1191 means that the whole breadth of @code{groff} is not neccessary for most
1192 people. This chapter covers the material needed to efficiently use a
1201 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1205 This section covers some of the basic concepts you will need to
1206 understand to use a macro package.@footnote{This section is derived from
1207 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1208 References are made throughout to more detailed information, if desired.
1210 @code{gtroff} reads an input file prepared by the user and outputs a
1211 formatted paper suitable for publication or framing. The input consists
1212 of text, or words to be printed, and embedded commands (@dfn{requests}
1213 and @dfn{escapes}), which tell @code{gtroff} how to format the printed
1214 copy. For more detail on this @pxref{Embedded Commands}.
1216 The word @dfn{argument} is used in this manual to mean a word or number
1217 which appears on the same line as a request which modifies the meaning
1218 of that request. For example, the request
1225 spaces one line, but
1232 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1233 request which says to space four lines instead of one. Arguments are
1234 separated from the request and from each other by spaces. More details
1235 on this can be found in @ref{Request Arguments}.
1237 The primary function of @code{gtroff} is to collect words from input
1238 lines, fill output lines with those words, justify the right hand margin
1239 by inserting extra spaces in the line, and output the result. For
1247 Four score and seven
1252 will be read, packed onto output lines, and justified to produce:
1255 Now is the time for all good men to come to the aid of their party.
1256 Four score and seven years ago,...
1261 Sometimes you may want to start a new output line even though the line
1262 you are on is not yet full; for example, at the end of a paragraph. To
1263 do this you can cause a @dfn{break}, which starts a new output line.
1264 Some requests cause a break automatically, as do blank input lines and
1265 input lines beginning with a space.
1267 Not all input lines are text to be formatted. Some of the input lines
1268 are requests which describe how to format the text. Requests always
1269 have a period or an apostrophe (@samp{'}) as the first character of the
1272 The text formatter also does more complex things, such as automatically
1273 numbering pages, skipping over page boundaries putting footnotes in the
1274 correct place, and so forth.
1276 Here a few hints for preparing text for input to @code{gtroff}. First,
1277 keep the input lines short. Short input lines are easier to edit, and
1278 @code{gtroff} will pack words onto longer lines for you anyhow. In
1279 keeping with this, it is helpful to begin a new line after every period,
1280 comma, or phrase, since common corrections are to add or delete
1281 sentences or phrases. Secondly, do not hyphenate words at the end of
1282 lines---@code{gtroff} is smart enough to hyphenate words for you as
1283 needed, but is not smart enough to take hyphens out and join a word back
1284 together. Also, words such as ``mother-in-law'' should not be broken
1285 over a line, since then you will get a space where not wanted, such as
1286 ``@w{mother- in}-law''.
1289 @cindex double spacing
1291 @code{gtroff} will double space output text automatically if you use the
1292 request @w{@samp{.ls 2}}. You can revert to single spaced mode by
1293 typing @w{@samp{.ls 1}}.
1295 A number of requests allow you to change the way the printed copy looks,
1296 sometimes called the @dfn{layout} of the output page. Most of these
1297 requests adjust the placing of @dfn{white space} (blank lines or
1302 The @samp{.bp} request starts a new page.
1307 @cindex lines, empty
1308 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1309 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1310 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1311 @var{N}@w{ }centimeters). For example, the input:
1315 My thoughts on the subject
1320 leaves one and a half inches of space, followed by the line ``My
1321 thoughts on the subject'', followed by a single blank line.
1324 @cindex centering lines
1325 @cindex lines, centering
1326 Text lines can be centered by using the @samp{.ce} request. The line
1327 after @samp{.ce} is centered (horizontally) on the page. To center more
1328 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1329 of lines to center), followed by the @var{N}@w{ }lines. If you want to
1330 center many lines but don't want to count them, type:
1339 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1340 lines, in other words, stop centering.
1345 All of these requests cause a break; that is, they always start a new
1346 line. If you want to start a new line without performing any other
1347 action, use @samp{.br}.
1350 @node Common Features, , Basics, Tutorial for Macro Users
1351 @section Common Features
1352 @cindex common features
1353 @cindex features, common
1355 @code{gtroff} provides very low level operations for formatting a
1356 document. There are many common routine operations which are done in
1357 all documents. These common operations are written into @dfn{macros}
1358 and collected into a @dfn{macro package}.
1360 All macro packages provide certain common capabilities which fall into
1361 the following categories.
1363 @subsection Paragraphs
1366 One of the most common and most used capability is starting a paragraph.
1367 There are a number of different types of paragraphs, any of which can be
1368 initiated with macros supplied by the macro package. Normally,
1369 paragraphs start with a blank line and the first line indented, like the
1370 text in this manual. There are also block style paragraphs, which omit
1374 Some men look at constitutions with sanctimonious
1375 reverence, and deem them like the ark of the covenant, too
1376 sacred to be touched.
1380 And there are also indented paragraphs which begin with a tag or label
1381 at the margin and the remaining text indented.
1384 one This is the first paragraph. Notice how the first
1385 line of the resulting paragraph lines up with the
1386 other lines in the paragraph.
1388 This paragraph had a long label. The first
1389 character of text on the first line will not line up
1390 with the text on second and subsequent lines,
1391 although they will line up with each other.
1394 A variation of this is a bulleted list.
1397 @subsection Sections and Chapters
1399 Most macro packages supply some form of section headers. The simplest
1400 kind is simply the heading on a line by itself in bold type. Others
1401 supply automatically numbered section heading or different heading
1402 styles at different levels. Some, more sophisticated, macro packages
1403 supply macros for starting chapters and appendicies.
1405 @subsection Headers and Footers
1407 Every macro packages gives you some way to manipulate the headers and
1408 footers (or @dfn{titles}) on each page. Some packages will allow you to
1409 have different ones on the even and odd pages (for material printed in a
1412 The titles are called three-part titles, that is, there is a
1413 left-justified part, a centered part, and a right-justified part. An
1414 automatically generated page number may be put in any of these fields
1415 with the @samp{%} character (@pxref{Page Layout} for more details).
1417 @subsection Page Layout
1419 Most macro packages let you specify top and bottom margins and other
1420 details about the appearance of the printed pages.
1422 @subsection Displays
1425 Displays are sections of text to be set off from the body of the paper.
1426 Major quotes, tables, and figures are types of displays, as are all the
1427 examples used in this document.
1429 @cindex quotes, major
1430 @cindex major quotes
1431 @dfn{Major quotes} are quotes which are several lines long, and hence
1432 are set in from the rest of the text without quote marks around them.
1435 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1436 should be used when the material to be printed should not be filled and
1437 justified like normal text, such as columns of figures or the examples
1441 A @dfn{keep} is a display of lines which are kept on a single page if
1442 possible. An example of where you would use a keep might be a diagram.
1443 Keeps differ from lists in that lists may be broken over a page boundary
1444 whereas keeps will not.
1446 @cindex keep, floating
1447 @cindex floating keep
1448 Floating keeps move relative to the text. Hence, they are good for
1449 things which will be referred to by name, such as ``See figure@w{ }3''.
1450 A floating keep will appear at the bottom of the current page if it will
1451 fit; otherwise, it will appear at the top of the next page. Meanwhile,
1452 the surrounding text will `flow' around the keep, thus leaving now blank
1455 @subsection Footnotes and annotations
1459 There are a number of requests to save text for later printing.
1460 @dfn{Footnotes} are printed at the bottom of the current page. Delayed
1461 text is intended to be a variant form of footnote; the text is printed
1462 only when explicitly called for, such as at the end of each chapter.
1464 @cindex delayed text
1465 @dfn{Delayed text} is very similar to a footnote except that it is
1466 printed when called for explicitly. This allows a list of references to
1467 appear (for example) at the end of each chapter, as is the convention in
1470 Most macro packages which supply this functionality also supply a means
1471 of automatically numbering either type of annotation.
1473 @subsection Table of Contents
1474 @cindex table of contents
1475 @cindex contents, table of
1477 @dfn{Tables of contents} are a type of delayed text having a tag
1478 (usually the page number) attached to each entry after a row of dots.
1479 The table accumulates throughout the paper until printed, usually after
1480 the paper has ended. Many macro packages will provide the ability to
1481 have several tables of contents (i.e.@: one standard one, one for
1487 While some macro packages will use the term @dfn{index}, none actually
1488 provide that functionality. The facilities they call indices are
1489 actually more appropriate for tables of contents.
1491 @subsection Paper formats
1492 @cindex paper formats
1494 Some macro packages provide stock formats for various kinds of
1495 documents. Many of them provide a common format for the title and
1496 opening pages of a technical paper. The @code{-mm} macros in particular
1497 provide formats for letters and memoranda.
1499 @subsection Multiple Columns
1501 Some macro packages (except @code{-man}) provide the ability to have two
1502 or more columns on a page.
1504 @subsection Font and Size changes
1506 The built-in font and size functions are not always intuitive, so all
1507 macro packages provide macros to make these operations simpler.
1509 @subsection Predefined Strings
1511 Most macro packages provide various predefined strings for a variety of
1512 uses, examples are sub- and superscripts, printable dates, quotes and
1513 various special characters.
1515 @subsection Preprocessor Support
1517 All macro packages provide support for the various preprocessors.
1519 @subsection Configuration and Customization
1521 Some macro packages provide means of customizing many of details of how
1522 the package behaves. This ranges from setting the default type size to
1523 changing the appearance of section headers.
1527 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1528 @chapter Macro Packages
1529 @cindex macro packages
1530 @cindex packages, macros
1532 This chapter documents the main macro packages that come with
1544 @node -man, -mdoc, Macro Packages, Macro Packages
1548 @c XXX documentation
1551 @node -mdoc, -ms, -man, Macro Packages
1553 @cindex @code{-mdoc}
1555 @c XXX documentation
1558 @node -ms, -me, -mdoc, Macro Packages
1562 @c XXX documentation
1565 @node -me, -mm, -ms, Macro Packages
1569 @c XXX documentation
1572 @node -mm, , -me, Macro Packages
1576 @c XXX documentation
1580 @node Programming Tutorial, Preprocessors, Macro Packages, Top
1581 @chapter Programming Tutorial
1582 @cindex programming tutorial
1583 @cindex tutorial for programming
1585 This chapter covers @strong{all} of the facilities of @code{gtroff}. If
1586 you are intending to use a macro package, you probably do not want to
1591 * Input Conventions::
1595 * Embedded Commands::
1597 * Manipulating Filling and Adjusting::
1598 * Manipulating Hyphenation::
1599 * Manipulating Spacing::
1601 * Character Translations::
1608 * Conditionals and Loops::
1611 * Drawing Functions::
1616 * Postprocessor Access::
1619 * Implementation Differences::
1624 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
1628 @code{gtroff} input files contain text with control commands
1629 interspersed throughout. But, even without control codes, @code{gtroff}
1630 will still do several things with your text: filling and adjusting,
1631 adding additional space after sentences, hyphenating and inserting
1632 implicit line breaks.
1635 * Filling and Adjusting::
1639 * Implicit Line Breaks::
1642 @node Filling and Adjusting, Hyphenation, Text, Text
1643 @subsection Filling and Adjusting
1644 @cindex filling and adjusting
1645 @cindex adjusting and filling
1647 When @code{gtroff} reads in text it collects words from input and fits
1648 as many of them together on one output line as it can. This is known as
1651 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
1652 it. which means it will widen the spacing between words until the text
1653 reaches the right margin (in the default adjustment mode). Extra spaces
1654 between words are preserved, but spaces at the end of lines are ignored.
1655 Spaces at the front of a line will cause a @dfn{break} (breaks will be
1656 explained in @ref{Implicit Line Breaks})
1658 @xref{Manipulating Filling and Adjusting}.
1660 @node Hyphenation, Sentences, Filling and Adjusting, Text
1661 @subsection Hyphenation
1664 Since the odds of finding a set of words, for every output line, which
1665 will fit nicely on a line without inserting excessive amounts of space
1666 between words is not great, @code{gtroff} will hyphenate words so that
1667 lines can be justified without there being too much space between words.
1668 It uses an internal hyphenation algorithm, to indicate which words can
1669 be hyphenated and how to do so. When a word is hyphenated the first
1670 part of the word will be added to the current filled line being output
1671 (with an attached hyphen), and the other portion will be added to the
1672 next line to be filled.
1674 @xref{Manipulating Hyphenation}.
1676 @node Sentences, Tab Stops, Hyphenation, Text
1677 @subsection Sentences
1680 Although it is often debated, some typesetting rules say there should be
1681 different amounts of space after various puctuation marks. For example,
1682 a period at the end of a sentence should have twice as much space
1683 following it as would a comma or a period as part of an abbreviation.
1685 @cindex sentence spaces
1686 @cindex spaces between sentences
1687 @cindex french-spacing
1688 @code{gtroff} does this by flagging certain characters (normally
1689 @samp{!}, @samp{?} and @samp{.}) as @dfn{end of sentence} characters.
1690 When @code{gtroff} encounters one of these characters at the end of a
1691 line it will append two @dfn{sentence spaces} in the formatted output.
1692 (Thus, one of the conventions mentioned in @ref{Input Conventions}).
1694 @c XXX also describe how characters like ) are treated here -jjc
1695 @c gotta do some research on this -trent
1697 @node Tab Stops, Implicit Line Breaks, Sentences, Text
1698 @subsection Tab Stops
1700 @cindex stops, tabulator
1702 @code{gtroff} translates @dfn{tabulator stops}, also called @dfn{tabs},
1703 in the input into movements to the next tab stop. These tab stops are
1704 initially located every half inch across the page. Using this you can
1705 make simple tables. However, this can often be deceptive as the
1706 appearance (and width) of your text on a terminal and the results from
1707 @code{gtroff} can vary greatly.
1709 Also, a possible sticking point is that lines beginning with tab
1710 characters will still be filled, again producing unexpected results.
1711 For example, the following input
1713 @multitable {12345678} {12345678} {12345678} {12345678}
1715 @tab 1 @tab 2 @tab 3
1723 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
1725 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
1728 @xref{Tabs and Fields}.
1730 @node Implicit Line Breaks, , Tab Stops, Text
1731 @subsection Implicit Line Breaks
1732 @cindex implicit line breaks
1733 @cindex implicit breaks of lines
1734 @cindex line, implicit breaks
1736 @cindex break, implicit
1739 An important concept in @code{gtroff} is the @dfn{break}. When a break
1740 occurs, @code{gtroff} will output the partially filled line
1741 (unadjusted), and resume collecting and filling text on the next output
1747 There are several ways to cause a break in @code{gtroff}. A blank line
1748 will not only cause a break, but it will also cause a one line vertical
1749 space (effectively a blank line) to be output.
1751 A line which begins with a space will cause a break and the space will
1752 be output at the beginning of the next line. Note that this space isn't
1753 adjusted, even in fill mode.
1755 The end of file will also cause a break (otherwise the last line of your
1756 document may vanish!)
1758 Certain requests also cause breaks, implicitly or explicity. This will
1761 @xref{Manipulating Filling and Adjusting}.
1764 @node Input Conventions, Measurements, Text, Programming Tutorial
1765 @section Input Conventions
1766 @cindex input conventions
1767 @cindex conventions for input
1769 Since @code{gtroff} does filling automatically, it is traditional in
1770 @code{groff} not to try and type things in as nicely formatted
1771 paragraphs. These are some conventions commonly used when typing
1776 Break lines after punctuation, particularily at the end of sentences,
1777 and in other logical places. Keep separate phrases on lines by
1778 themselves, as entire phrases are often added or deleted when editing.
1780 Try to keep lines less than 40-60@w{ }characters, to allow space for
1781 inserting more text.
1783 Do not try to do any formatting in a WYSIWYG manner (i.e.@: don't try
1784 and use spaces to get proper indentation).
1788 @node Measurements, Expressions, Input Conventions, Programming Tutorial
1789 @section Measurements
1790 @cindex measurements
1792 @cindex units of measurement
1794 @cindex machine units
1795 @cindex measurement units
1796 @code{gtroff} (like any other programs) requires numeric parameters to
1797 specify various measurements. Most numeric parameters@footnote{those
1798 that specify vertical or horizontal motion or a type size} may have a
1799 @dfn{measurement unit} attached. These units are specified as a single
1800 character which immediately follows the number or expression. Each of
1801 these units are understood, by @code{gtroff}, to be a multiple of its
1802 @dfn{basic unit}. So, whenever a different measurement unit is
1803 specified @code{gtroff} converts this into its @dfn{basic units}. This
1804 basic unit, represented by a @samp{u}, is a device dependent measurement
1805 which is quite small, ranging from 1/75th to 1/72000th of an inch; all
1806 other units are converted eventually to basic units. The values may be
1807 given as fractional numbers---nevertheless, fractional basic units are
1808 always rounded to integers.
1810 Some of the measurement units are completely independent of any of the
1811 current settings (e.g.@: type size) of @code{gtroff}.
1816 @cindex @code{i} unit
1817 @cindex unit, @code{i}
1818 Inches. An antiquated measurement unit still in use in certain
1819 backwards countries. One inch is equal to 2.54@dmn{cm}.
1822 @cindex @code{c} unit
1823 @cindex unit, @code{c}
1824 Centimeters. One centimeter is equal to 0.3937@dmn{in}.
1827 @cindex @code{p} unit
1828 @cindex unit, @code{p}
1829 Points. This is a typesetter's measurement used for measure type size.
1830 It is 72@w{ }points to an inch.
1833 @cindex @code{P} unit
1834 @cindex unit, @code{P}
1835 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
1836 12@w{ }points to a pica).
1839 @cindex @code{s} unit
1840 @cindex unit, @code{s}
1841 @cindex @code{z} unit
1842 @cindex unit, @code{z}
1843 @xref{Fractional Type Sizes}, for a discussion of these units.
1846 The other measurements understood by @code{gtroff} are dependent on
1847 settings currently in effect in @code{gtroff}. These are very useful
1848 for specifying measurements which should look proper with any size of
1854 @cindex @code{m} unit
1855 @cindex unit, @code{m}
1856 Ems. This unit is equal to the current font size in points. So called
1857 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
1858 in the current font.
1861 @cindex @code{n} unit
1862 @cindex unit, @code{n}
1863 Ens. This is half of an em.
1865 @cindex vertical space
1866 @cindex space, vertical
1867 @cindex @code{v} unit
1868 @cindex unit, @code{v}
1869 Vertical space. This is equivalent to the current line spacing.
1870 @xref{Sizes}, for more information about this.
1872 @cindex @code{M} unit
1873 @cindex unit, @code{M}
1877 @xref{Fractional Type Sizes}.
1883 @node Default Units, , Measurements, Measurements
1884 @subsection Default Units
1885 @cindex default units
1886 @cindex units, default
1888 Many requests take a default unit. While this can be helpful at times,
1889 it can cause strange errors in some expressions. For example, the line
1890 length request expects em's. Here are several attempts to get a line
1891 length of 3.5@w{ }inches and the results:
1898 7i/2u @result{} 3.5i
1902 As you can see, the safest way to specify measurements is to always
1903 attach a scaling indicator.
1906 @node Expressions, Identifiers, Measurements, Programming Tutorial
1907 @section Expressions
1910 @code{gtroff} has most of operators common to other languages:
1912 @c XXX more details; examples
1916 @cindex arithmetic operators
1917 @cindex operators, arithmetic
1923 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
1924 (division), @samp{*} (multiplication), @samp{%} (modulo).
1926 @cindex comparison operators
1927 @cindex operators, comparison
1934 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
1935 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
1936 (equal), @samp{==} (the same as @samp{=}).
1938 @cindex logical operators
1939 @cindex operators, logical
1942 Logical: @samp{&} (logical and), @samp{:} (logical or).
1944 @cindex unary operators
1945 @cindex operators, unary
1949 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
1950 (just for completeness; does nothing in expressions), @samp{!} (logical
1951 not). See below for the use of unary operators in motion requests.
1952 @c XXX (if/while only??)
1954 @cindex extremum operators
1955 @cindex operators, extremum
1958 Extremum: @samp{>?} (maximum), @samp{<?} (minimum). For example,
1959 @samp{5>?3} yields@w{ }@samp{5}.
1962 @cindex scaling operator
1963 @cindex operator, scaling
1964 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
1965 the default scaling indicator. If @var{c} is missing, ignore scaling
1966 indicators in the evaluation of @var{e}.
1972 Parentheses may be used as in any other language. However, in
1973 @code{gtroff} they are necessary to ensure order of evaluation.
1974 @code{gtroff} has no operator precedence; expressions are evaluated left
1975 to right. This means that @samp{3+5*4} is evaluated as if it were
1976 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may
1982 @cindex motion operators
1983 @cindex operators, motion
1984 For many requests which cause a motion on the page, the unary operators
1985 work differently. The @samp{+} and @samp{-} operators indicate a motion
1986 relative to the current position (down or up, respectively). The
1987 @samp{|} operator indicates an absolute position on the page or input
1990 @samp{+} and @samp{-} are also treated differently by the @code{nr}
1992 @c XXX (?), add xref
1994 @cindex space characters in expressions
1995 @cindex expressions and space characters
1996 Due to the way arguments are parsed, spaces are not allowed in
1997 expressions, unless the entire expression is surrounded by parentheses.
1999 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2002 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
2003 @section Identifiers
2010 Like any other language, @code{gtroff} has rules for properly formed
2011 @dfn{identifiers}. In @code{gtroff} an identifier can be made up of
2012 almost any printable character. The only exception are characters which
2013 are interpreted by @code{gtroff} (backslash, square brackets, and
2014 @samp{?}). So, for example, any of the following is valid.
2025 You can test whether an identifier is valid in @code{gtroff} with the
2026 @code{\A} escape. It expands to@w{ }1 or@w{ }0 according to whether its
2027 argument (given in quotes) is or is not acceptable as the name of a
2028 string, macro, diversion, number register, environment, or font. It
2029 will return@w{ }0 if no argument is given. This is useful if you want
2030 to look up user input in some sort of associative table.
2032 @c XXX add xrefs above
2034 Identifiers in @code{gtroff} can be any length, but, in some contexts,
2035 @code{gtroff} needs to be told where identifiers end and text begins
2036 (and in different ways depending on their length).
2045 Two characters. Must be prefixed with @samp{(} in some situations.
2047 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
2048 and@w{ }@samp{]} in some situations. Any length identifier can be put
2052 Unlike many other programming languages, undefined identifiers are
2053 silently ignored or expanded to nothing.
2055 @c XXX add info about -ww command line option.
2057 @xref{Interpolating Registers}, and @ref{Strings}.
2060 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
2061 @section Embedded Commands
2062 @cindex embedded commands
2063 @cindex commands, embedded
2065 With most documents you need more funtionality beyond filling, adjusting
2066 and implicit line breaking. In order to gain further functionality,
2067 @code{gtroff} allows commands to be embedded into your text, in two
2070 The first is a @dfn{request} which takes up an entire line, and does
2071 some large scale operation (e.g.@: break lines, start new pages).
2073 The other is an @dfn{escape} which can be embedded anywhere in your
2074 text, or even as an argument to a request.
2075 @c XXX (Not always?)
2076 Escapes generally do more minor operations like sub- and superscripts,
2077 print a symbol, etc.
2085 @node Requests, Macros, Embedded Commands, Embedded Commands
2086 @subsection Requests
2089 @cindex control character
2090 @cindex character, control
2093 A request line begins with a control character, which is either a single
2094 quote (@samp{'}) or a period (@samp{.}). These can be changed;
2095 @xref{Character Translations}, for details. After this there may be
2096 optional tabs or spaces followed by an identifier which is the name of
2097 the request. This may be followed by any number of space separated
2101 If you want to begin a line with a control character without it being
2102 interpreted, precede it with @code{\&}. This represents a zero width
2103 space, which means it will not affect your output.
2105 In most cases you will use the period as a control character. Several
2106 requests will cause a break; using the single quote control character
2110 * Request Arguments::
2113 @node Request Arguments, , Requests, Requests
2114 @subsubsection Request Arguments
2115 @cindex request arguments
2116 @cindex arguments to requests
2118 Arguments to requests (and macros) are processed much like the shell:
2119 The line is split into arguments according to spaces. An argument which
2120 is intended to contain spaces can either be enclosed in quotes (single
2121 or double), or have the spaces @dfn{escaped} with backslashes.
2126 .uh The Mouse Problem
2127 .uh "The Mouse Problem"
2128 .uh The\ Mouse\ Problem
2132 The first line is the @code{uh} macro being called with 3 arguments,
2133 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
2134 same effect or calling the @code{uh} macro with one argument @samp{The
2137 Note, however, that the @code{ds} request works differently.
2141 @node Macros, Escapes, Requests, Embedded Commands
2145 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
2146 which can be invoked by name. They are called in the same manner as
2147 requests---arguments also may be passed in the same manner.
2149 @xref{Writing Macros}, and @ref{Request Arguments}.
2151 @node Escapes, , Macros, Embedded Commands
2157 Escapes may occur anywhere in the input to @code{gtroff}. They begin
2158 with a backslash and are followed by a single character which indicates
2159 the function to be performed. If you want to have a backslash appear in
2160 your document, you should use the escape sequence @code{\e}. Merely
2161 escaping the backslash with another backslash will work in @emph{some}
2164 Many escapes have no parameters; those that do, do so in one of two
2165 ways. For escapes which require an identifier there must be a way for
2166 @code{gtroff} to tell where the identifier ends and the text begins. It
2167 assumes that the next single character is the identifier, but if that
2168 character is an opening parenthesis, it takes the next two characters as
2169 the identifier; and if the next character is an opening bracket, all
2170 characters until a closing bracket are taken as the identifier. Note
2171 that in the second case there is no closing parenthesis. For example:
2180 Other escapes may require several arguments and/or some special format.
2181 In these cases the @dfn{argument} is enclosed in single quotes
2182 @c XXX (not required??)
2183 and the enclosing text is decoded according to what that escape expects.
2192 If you want to have a backslash appear in your output, you can use
2193 several escapes: @code{\\}, @code{\e} or @code{\E}. These are very
2194 similar, and only differ with respect to being used in macros or
2195 diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for more
2204 @node Comments, , Escapes, Escapes
2205 @subsubsection Comments
2209 Probably one of the most@footnote{Unfortunately, this is a lie. But
2210 hopefully future @code{gtroff} hackers will believe it :-)} common forms
2211 of escapes is the comment. They begin with the @code{\"} escape and end
2212 at the end of the input line.
2214 This may sound simple, but it can be tricky to keep the comments from
2215 interfering with the apperarance of your final outupt.
2218 If the escape is to the right of some text or a request, that portion of
2219 the line will be ignored, but the space leading up to it will be noticed
2220 by @code{gtroff}. This only affects the @code{.ds} request.
2221 @c XXX (any others?)
2223 One possibly irritating idiosyncracy is that you must not use tabs to
2224 line up your comments. Tabs are not treated as white space between the
2225 request and macro arguments.
2227 @cindex undefined request
2228 @cindex request, undefined
2229 If you have a comment on a line by itself, it will be treated as a blank
2230 line, because after eliminating the comment, that is all that remains.
2231 So, it is common to start the line with @code{.\"} which will cause the
2232 line to be treated as an undefined request.
2234 Another commenting scheme seen sometimes is three consecutive single
2235 quotes (@code{'''}) at the begining of a line. This works, but
2236 @code{gtroff} will give a warning about an undefined macro, which is
2237 harmless, but irritating.
2240 Now to avoid all this @code{gtroff} has a new comment mechanism using
2241 the @code{\#} escape. This escape works the same as @code{\"} except
2242 that the newline is also ignored.
2245 For large blocks of text, the @code{ig} request may be useful.
2249 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
2253 Registers are @code{gtroff}'s numeric variables. @code{gtroff} has a
2254 number of built-in registers, supplying anything from the date to
2255 details of formatting parameters.
2260 * Setting Registers::
2261 * Interpolating Registers::
2263 * Assigning Formats::
2264 * Built-in Registers::
2267 @node Setting Registers, Interpolating Registers, Registers, Registers
2268 @subsection Setting Registers
2269 @cindex setting registers
2270 @cindex registers, setting
2274 Registers are defined resp.@: set via the @code{nr} request or the
2275 @code{\R} escape. For example, the following two lines are equivalent:
2283 The @code{rr} request will remove the register specified by the
2287 The @code{rnn} request will rename a number register. The format is
2288 @w{@samp{.rnn @var{x} @var{y}}}, which will rename number register
2292 Aliases can be created for a number register. The format is
2293 @w{@samp{.aln @var{xx} @var{yy}}}, which will create an alias @var{xx}
2294 for number register object named @var{yy}. The new name and the old
2295 name will be exactly equivalent. If @var{yy} is undefined, a warning of
2296 type @samp{reg} will be generated, and the request will be ignored.
2297 @xref{Debugging}, for information about warnings.
2299 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
2300 @subsection Interpolating Registers
2301 @cindex interpolating registers
2302 @cindex registers, interpolating
2305 Numeric registers are @dfn{interpolated} via the @code{\n} escape.
2307 @c XXX the following is wrong. Should I say any more than the above??
2308 @c This means that the value of the number register is expanded in-place
2309 @c on the input line before any other actions, i.e. before requests and
2310 @c escapes are interpreted.
2317 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
2318 @subsection Auto-increment
2319 @cindex auto-increment
2320 @cindex increment, automatic
2323 Number registers can also be auto-incremented and auto-decremented. You
2324 can specify the increment resp.@: decrement factor with a third argument
2325 to the @code{nr} request. The default value is@w{ }0. For example,
2330 \n+a, \n+a, \n+a, \n+a, \n+a
2332 \n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx
2343 If you want to change the increment factor without changing the value of
2344 a register, the following can be used.
2350 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
2351 @subsection Assigning Formats
2352 @cindex assigning formats
2353 @cindex formats, assigning
2356 When a register is used in the text of an input file (as opposed to part
2357 of an expression) it is textually replaced (or interpolated) with a
2358 representation of that number. This output format can be changed to a
2359 variety of formats (numbers, roman numerals, etc). This is done using
2360 the @code{af} request. The first argument to @code{af} is the name of
2361 the number register to be changed, and the second argument is the output
2362 format. The following output formats are available:
2366 This is the default format, decimal numbers: 1, 2, 3,@w{ }@dots{}
2368 Decimal numbers with as many leading zeros as specified. So, @samp{001}
2369 would result in 001, 002, 003,@w{ }@dots{}
2371 @cindex roman numerals
2372 @cindex numerals, roman
2373 Upper-case roman numerals: 0, I, II, III, IV,@w{ }@dots{}
2375 Lower-case roman numerals: 0, i, ii, iii, iv,@w{ }@dots{}
2377 Upper-case letters: A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@dots{}
2379 Lower-case letters: a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@dots{}
2382 The following example will produce @samp{10, X, j, 010}:
2386 .af a 1 \" the default format
2397 The @code{\g} escape returns the current format of the specified
2398 register. For example, @samp{\ga} after the previous example would
2401 @node Built-in Registers, , Assigning Formats, Registers
2402 @subsection Built-in Registers
2403 @cindex built-in registers
2404 @cindex registers, built-in
2406 The following lists some built-in registers which are not described
2407 elsewhere in this manual. Any register which begin with a @samp{.} is
2408 read-only. A complete listing of all built-in registers can be found in
2409 @ref{Register Index}.
2414 Horizontal resolution in basic units.
2417 Vertical resolution in basic units.
2420 Day of the week (1-7).
2423 Day of the year (1-31).
2426 Current month (1-12).
2432 The year minus@w{ }1900. Unfortunately, the @sc{Unix} Version@w{ }7
2433 troff documentation had a year@w{ }2000 bug: It incorrectly claimed that
2434 @samp{\n(yr} was the last two digits of the year. That claim has never
2435 been true of either traditional @code{troff} or GNU @code{troff}. If
2436 you see old @code{troff} input that looks like this:
2439 '\" The following line stopped working after 1999
2440 This document was formatted in 19\n(yr.
2444 you can correct it as follows:
2447 This document was formatted in \n[year].
2451 or, if you want to be portable to older @code{troff} versions, as
2456 This document was formatted in \n(y4.
2463 The current @emph{input} line number.
2466 The current @emph{output} line number.
2469 The major version number. For example, if the version number is@w{
2470 }1.03 then @code{.x} will contain@w{ }@samp{1}.
2473 The minor version number. For example, if the version number is@w{
2474 }1.03 then @code{.y} will contain@w{ }@samp{03}.
2477 The revision number of @code{groff}.
2480 Always@w{ }1. Macros should use this to determine whether they are
2481 running under GNU @code{troff}.
2484 If the current output device is @sc{ascii}, this is set to@w{ }1, zero
2488 This register indicates whether the current page is actually being
2489 printed, i.e., whether the @samp{-o} option is being used to only print
2490 selected pages. @xref{Options}, for more information.
2494 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
2495 @section Manipulating Filling and Adjusting
2496 @cindex manipulating filling and adjusting
2497 @cindex filling and adjusting, manipulating
2498 @cindex adjusting and filling, manipulating
2503 Several ways of causing @dfn{breaks} were given in
2504 @ref{Implicit Line Breaks}.
2505 The @code{br} request will likewise cause a break.
2506 Several other requests will also cause breaks, implicitly.
2520 Initially, groff will fill and ajust text to both margins.
2521 Filling can be disabled via the @code{nf} request
2522 and re-enabled with the @code{fi} request.
2523 These implicitly disable and re-enable adjusting.
2524 Both of these will cause break in text currently being filled.
2525 The number register @code{.u} is equal to 1 in fill mode and 0 in
2531 Adjusting can be disabled with the @code{ad} request and re-enabled
2532 with the @code{na} request.
2533 The @code{ad} request takes a single argument to indicate how to
2535 The current adjustment mode is available in the number register
2540 @cindex ragged-right
2541 Adjust text to the left margin. This produces what is traditionally
2542 called ragged-right text.
2544 Adjust text to the right margin.
2549 Justify to both margins. This is groff's default.
2552 With no argument to @code{ad}, troff will adjust lines the same way
2553 it was the last time it was filling. For example:
2563 .ad \" back to centering
2568 The escape @code{\p} will cause a break and cause the remaining text
2572 The @code{ss} request allows you to change the minimum size of a
2573 space between filled words.
2574 This request takes it's units as one twelfth of the
2575 spacewidth parameter for the current font. Initially both the word
2576 space size and the sentence space size are 12.
2578 When two arguments are given to the @code{ss} request, the second argument
2579 gives the sentence space size. If the second argument is not given, the
2580 sentence space size will be the same as the word space size.
2581 The sentence space size
2582 is used in two circumstances: if the end of a sentence occurs at the end
2583 of a line in fill mode, then both an inter-word space and a sentence
2584 space will be added; if two spaces follow the end of a sentence in the
2585 middle of a line, then the second space will be a sentence space. Note
2586 that the behaviour of @sc{Unix} troff will be exactly that exhibited by GNU
2587 troff if a second argument is never given to the @code{ss} request. In GNU
2588 troff, as in @sc{Unix} troff, you should always follow a sentence with either
2589 a newline or two spaces.
2593 The number registers @code{.ss} and @code{.sss} are
2594 the values of the parameters set by the first and second
2595 arguments of the @code{ss} request.
2598 The @code{ce} request will center text.
2599 While the @samp{ad c} request will also center text, it has the side
2600 effect of filling the text. The @code{.ce} request will not fill the
2602 This request causes a break.
2604 With no arguments, @code{ce} will fill the next line of text.
2605 The single argument @code{ce} takes is a number indicating the
2606 number of lines to be centered. With no argument centering is
2609 A common idiom is to turn on centering for a large number of lines,
2610 and then turn off centering when you are done with the centered text.
2611 This is useful for any request which takes a number of lines as an
2625 The @code{.ce} number register contains the number of lines remaining
2626 to be centered, as set by the @code{ce} request.
2631 A similar request is @code{rj} request which will justify unfilled
2632 text to the right margin. Its arguments are identical to the
2634 The @code{.rj} number register is
2635 the number of lines to be right-justified as set by the @code{rj}
2639 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
2640 @section Manipulating Hyphenation
2641 @cindex manipulating hyphenation
2642 @cindex hyphenation, manipulating
2644 As discussed in @ref{Hyphenation}, groff will hyphenate words.
2645 There are a number of ways to modify the how hyphenation is done.
2650 This hyphenation can be turned off with the @code{nh} request, and
2651 turned back on with the @code{hy} request. However, troff's
2652 hyphenation facilities are far more flexible than this. The @code{hy}
2653 request can be used to tell troff to restrict hypenation to certain
2654 cases. The request takes a single numeric argument.
2655 The current hyphenation restrictions can be found in the number
2660 The default argument, which
2661 indicates to hyphenate without restrictions.
2663 Do not hyphenate the last word on a page or column.
2665 Do not hyphenate the last two characters of a word.
2667 Do not hyphenate the first two characters of a word.
2673 The @code{hlm} request will
2674 set the maximum number of consecutive hyphenated lines to the value
2675 given as the first argument.
2677 negative, there is no maximum. The default value is -1.
2679 associated with the current environment. Only lines output from an
2680 environment count towards the maximum associated with that environment.
2681 Hyphens resulting from @code{\%} are counted; explicit hyphens are not.
2682 The current setting of this is available in the @code{.hlm} request.
2683 Also the number of immediately preceding consecutive hyphenated lines
2684 are available in the number register @code{.hlc}.
2687 The @code{hw} request allows you to specify how a specific word is
2688 to be hyphenated. It takes only one argument which is the word with
2689 hyphens at the hyphenation points. For example:
2690 @samp{.hw in-sa-lub-rious}.
2691 @c In old versions of troff there was a
2692 @c limited amount of space to store such information, fortunately,
2693 @c with groff, this is no longer a restriction.
2696 @cindex hyphenation character
2697 @cindex character, hyphenation
2698 You can also tell troff how to hyphenate words on the fly with the
2699 use of the @code{\%} escape, also known as the @dfn{hyphenation
2700 character}. Preceding a word with this character will prevent it
2701 from being hyphenated, putting it in a word will indicate to troff
2702 that the word may be hyphenated at that point. Note that this
2703 mechanism will only affect one word, if you want to change the
2704 hyphenation of a word for the entire document, use the @code{hw}
2708 The @code{hc} request allows you to change the hyphenation character.
2709 The character specified as an argument will then work the same as the
2710 @code{\%} escape, and, thus, no longer appear in the output. Without
2711 an argument it will return the hyphenation character to @code{\%}.
2714 To further customize hyphenation the @code{hpf} request will read in
2715 a file of hyphenation patterns.
2716 This file will be searched for in the
2717 same way that @file{tmac.@var{name}} is searched for when the
2718 @samp{-m@var{name}} option is specified.
2720 It should have the same format as the argument to the
2721 \patterns primitive in @TeX{}; the letters appearing in this file are
2722 interpreted as hyphenation codes.
2723 A @samp{%} character in the patterns file
2724 introduces a comment that continues to the end of the line.
2730 hyphenation patterns is associated with the current language set by the
2731 @code{hla} request. The @code{hpf} request is usually invoked by the
2732 @file{troffrc} file.
2735 @code{.hcode @var{c1 code1 c2 code2...}}
2736 Set the hyphenation code of character @var{c1} to code1 and that of
2737 @var{c2} to @var{code2}.
2738 A hyphenation code must be a single input character (not a
2739 special character) other than a digit or a space. Initially each
2740 lower-case letter has a hyphenation code, which is itself, and each
2741 upper-case letter has a hyphenation code which is the lower case
2746 The @code{hym} request will set the hyphenation margin to the value
2747 given as the first argument: when the current adjustment mode is not
2748 @samp{b}, the line will not be hyphenated if the line is no more than
2750 The default hyphenation margin is 0. The default scaling
2751 indicator for this request is m. The hyphenation margin is associated
2752 with the current environment. The current hyphenation margin is
2753 available in the @code{.hym} register.
2757 The @code{hys} request set the hyphenation space to the value given as
2758 the first argument: when the current adjustment mode is b, don't
2759 hyphenate the line if the line can be justified by adding no more than
2760 that amount of extra space to each word space. The default
2761 hyphenation space is 0. The default scaling indicator for this
2762 request is m. The hyphenation space is associated with the current
2763 environment. The current hyphenation space is available in the
2764 @code{.hys} register.
2767 The @code{shc} request will set the soft hyphen character to the
2768 argument given as an argument. If the argument is omitted, the soft
2769 hyphen character will be set to the default @code{\(hy}. The soft
2770 hyphen character is the character which will be inserted when a word
2771 is hyphenated at a line break. If the soft hyphen character does not
2772 exist in the font of the character immediately preceding a potential
2773 break point, then the line will not be broken at that point. Neither
2774 definitions (specified with the @code{char} request) nor translations
2775 (specified with the @code{tr} request) are considered when finding the soft
2781 The @code{hla} request will set the current hyphenation language to
2782 that given by the first argument. Hyphenation exceptions specified
2783 with the @code{hw} request and hyphenation patterns specified with the
2784 @code{hpf} request are both associated with the current hyphenation
2785 language. The @code{hla} request is usually invoked by the
2786 @file{troffrc} file. The current hyphenation language is available
2787 in the number register @code{.hla}.
2790 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
2791 @section Manipulating Spacing
2792 @cindex manipulating spacing
2793 @cindex spacing, manipulating
2796 The @code{sp} request will cause troff to space downwards the
2797 distance specified as the first argument. With no argument it will
2799 A negative argument will cause troff to move up the page the
2801 If the argument is preceded by a @samp{|} troff will move that
2802 distance from the top of the page.
2806 Often you may want your output to be double or triple spaced.
2807 The @code{ls} request will cause troff to output @var{n}-1 blank
2808 lines after each line of text, where @var{n} is the argument given to
2809 the @code{ls} request. With no argument troff will go back to single
2810 spacing. The number register @code{.L} contains the current line
2815 Sometimes, extra vertical spacing is only needed occasionaly,
2816 i.e. to allow space for a tall construct (like an equation).
2817 The @code{\x} escape will do this.
2818 The escape is given a numerical argument (like @samp{\x'3p'}).
2819 If this number is positive extra vertical space will be inserted
2820 below the current line. A negative number will add space above.
2821 If this escape is used multiple times on the same line, the maximum
2823 The @code{.a} number register contains the most recent
2824 extra vertical @strong{emph} line space.
2827 ... example of inline equation ...
2832 @cindex no-space mode
2833 @cindex mode, no-space
2834 Spacing (via either @code{sp} or via blank lines) can be disabled
2835 with the @code{ns} request. This will enable @dfn{no-space mode}.
2836 This mode will end when actual text is output or the @code{rs}
2837 request is encountered. No-space mode will also prevent requests to
2838 advance to the next page unless they are accompanied by a page number
2839 (@pxref{Page Control}, for more information.)
2842 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
2843 @section Tabs and Fields
2844 @cindex tabs and fields
2845 @cindex fields and tabs
2848 Tab stops are much like those on a typewriter: a tab character (or the
2849 @code{\t} escape) on input will cause horizontal motion to the next
2853 Tab stops can be changed with the @code{ta} request.
2854 This request takes a series of numbers as arguments which indicate
2855 where each tab stop is to be (overriding any previous settings).
2856 These can be specified absolutely,
2857 i.e. as the distance from the left margin.
2858 For example, the following wil set tab stops every one inch.
2861 .ta 1i 2i 3i 4i 5i 6i
2864 Tab stops can also be specified relatively (using a leading @samp{+})
2865 which means that the specified tab stop will be set that distance
2866 from the previous tab stop. For example the following is equivalent
2867 to the previous example.
2870 .ta 1i +1i +1i +1i +1i +1i
2873 After the specified tab stops repeat values may be set for tabs beyond
2874 the last one specified. This is most commonly used to specify tabs
2875 set at equal intervals. The compleat syntax for setting tabs is
2876 @code{ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2}
2877 @dots{} @var{rn}} This will set tabs at positions @var{n1}, @var{n2},
2878 @dots{}, @var{nn} and then set tabs at @var{nn}+@var{r1},
2879 @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} and then at
2880 @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, @dots{},
2881 @var{nn}+@var{rn}+@var{rn}, and so on. For example the following is,
2882 yet again, the same as the previous examples.
2888 The material in each tab column may be justified to the right or left
2889 or centered in the column. This is specified by appending an
2890 @samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop.
2891 The default justification is @samp{L}.
2898 The number register @code{.tabs} contains
2899 a string representation of the current tab settings suitable for use as
2900 an argument to the @code{ta} request.
2903 Normally troff will fill the space to the next tab stop with spaces.
2904 In some cases you may wish to change this. The @code{tc} request
2905 will do this. With no argument troff will revert to using spaces.
2911 Sometimes you may wish to use the @code{tc} request to fill a tab
2912 stop with a given character, but also, you want to use normal tab
2913 stops on the rest of the line. For this groff provides an alternate
2914 tab mechanism, called @dfn{leaders} which will do just that.
2915 They are used exclusively to produce a repeated run of characters to
2918 You can declare what character will be repeated with the @code{lc}
2919 request. If you do not give it an argument, the leaders will act the
2923 The difference is that a leader is invoked by using the @code{\a}
2926 @cindex table of contents
2927 @cindex contents, table of
2928 So for a table of contents you may want to have tab stops defined so
2929 that the section number is one tab stop, the title is the second with
2930 the remaining space being filled with a line of dots and then the
2931 page number slightly separated from the dots.
2943 Fields are a more general way of laying out tabular data.
2946 @node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial
2947 @section Character Translations
2948 @cindex character translations
2949 @cindex translations of characters
2953 The control character (@samp{.}) and the no-break control character
2954 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
2956 The single argument is the new character to be used, with no argument
2957 the normal control character is restored.
2961 The @code{eo} request will compleatly disable the escape mechanism.
2962 The @code{ec} request can be used to change the escape character from
2963 the default @samp{\} to what is specified as an argument.
2966 The @code{tr} request will translate characters.
2971 This is the same as the @code{tr} request except that the
2973 apply to text that is transparently throughput into a diversion with
2974 @code{\!}. @xref{Diversions}, for more information.
2985 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it
2986 will print @samp{a}.
2989 @node Line Layout, Page Layout, Character Translations, Programming Tutorial
2990 @section Line Layout
2992 @cindex layout, line
2994 @cindex dimensions, line
2995 @cindex line dimensions
2996 The following drawing shows the dimensions which troff uses for
2997 placing a line of output onto the page. They are labeled with the
2998 request which manipulates that dimension.
3003 -->| po |<-----------ll------------>|
3004 +----+----+----------------------+----+
3006 +----+----+----------------------+----+
3010 These dimensions are:
3015 @dfn{Page offset}--This is the leftmost postition of text on the final
3016 output. This can be adjusted with the @code{po} request, and the
3017 current setting can be found in the built-in number register @code{.o}
3018 Note, that this request does not cause a break, so changing the page
3019 offset in the middle of text being filled may not do what you expect.
3022 @dfn{Indentation}--This is the distance from the left margin where text
3023 will be printed. This can be adjusted with the @code{in} request, and
3024 the current setting can be found in the built-in number register.
3026 This request causes a break.
3030 There is also the request @code{ti} which will cause one output line
3031 to be indented, after which the indentation returns to 0.
3032 This request causes a break.
3033 The number register @code{.in} is the indent that applies to the
3034 current output line.
3038 @dfn{Line length}--This is the distance from the left margin to right
3039 margin. This can be adjusted with the @code{.ll} request, and the
3040 current setting can be found in the built-in number register @code{.l}
3041 Note, as the figure implies, line length is not affected by the current
3043 The number register @code{.ll} is
3044 the line length that applies to the current output line.
3050 A bunch of really boring text which should
3051 be indented from both margins.
3052 replace me with a better (and more) example!
3058 @node Page Layout, Page Control, Line Layout, Programming Tutorial
3059 @section Page Layout
3061 @cindex layout, page
3063 Troff provides some very primitive operations for controlling page
3068 Troff lets you specify the @dfn{page length} via the @code{pl} request.
3069 This is the length of the physical output page.
3070 The current setting can
3071 be found in the built-in number register @code{.p}. Note that this only
3072 specifies the size of the page, not the not the top and bottom margins.
3073 Those are not done by groff directly, @xref{Traps}, for further
3074 information on how to do this.
3079 Troff provides several operations which help in setting up top and
3080 bottom titles (or headers and footers)
3083 The @code{tl} request will print a @dfn{title line}, which consists
3084 of three parts: a left justified portion, a centered portion and a
3085 right justified portion. The argument to @code{tl} is specified as
3086 @code{'@var{left}'@var{center}'@var{right}'}
3087 The @samp{%} character is replaced with the current page number.
3091 The title line is printed using its own line length, which is
3092 specified with the @code{lt} request. The current setting of this is
3093 available in the @code{.lt} number register.
3096 The @code{pn} request will change the page number of the @emph{next}
3097 page. The only argument is the page number.
3101 The current page number is stored in the number register @code{%}.
3102 The number register @code{.pn} contains the
3103 number of the next page:
3104 either the value set by a @code{pn} request, or
3105 the number of the current page plus 1.
3108 The @code{pc} request will change the page number character (used by
3109 the @code{tl} request) to a different character. With no argument,
3110 this mechanism is disabled.
3113 @c distribute these through the text
3117 @node Page Control, Fonts, Page Layout, Programming Tutorial
3118 @section Page Control
3119 @cindex page control
3120 @cindex control, page
3123 To stop processing the current page, and move to the next page, you
3124 can invoke the @code{bp} request. This request will also cause a
3125 break. This request can also take an argument of what the next page
3128 between @code{bp} and @code{pn} is that @code{pn} does not cause a
3129 break or actually eject a page.
3135 .tl 'left top'center top'right top'
3142 Often you may want to make sure that you have a certain amount of
3143 space before a new page occurs. This is most useful to make sure
3144 that there is not a single @dfn{orphan} line left at the bottom of a
3145 page. The @code{ne} request will ensure that there is a certain
3146 distance, specified by the first argument, before the next page is
3147 triggered (@pxref{Traps}, for further information).
3148 The default unit for @code{ne} is v's and the default argument
3151 For example, to make sure that no fewer than 2 lines get orphaned,
3152 you can do the following before each paragraph.
3162 The @code{sv} is similar to the @code{ne} request, it reserves the
3163 specified amount of vertical space. If the desired amount of space
3164 exists before the next trap (bottom page boundary), the space will be
3165 output immediately. If there is not enough space, it is stored for
3166 later output via the @code{os} request.
3167 The default argument is 1v and the default units are v's.
3170 @node Fonts, Sizes, Page Control, Programming Tutorial
3176 Groff gives you the ability to switch fonts at any point in your
3177 text. There are two ways to do this, via the @code{ft} request and
3178 the @code{\f} escape.
3180 Fonts are generaly specified as uppercase strings, which are usually
3181 1 to 4 characters representing an abreviation of acronym of the font
3184 The basic set of fonts are R, I, B, and BI. These are Times Roman,
3185 Italic, Bold, and Bold Italic. There is also at least one symbol
3186 font which contains various special symbols (greek, mathematics).
3187 These latter fonts cannot be used directly, but should be used via an
3195 * Artificial Fonts::
3196 * Ligatures and Kerning::
3199 @node Changing Fonts, Font Families, Fonts, Fonts
3200 @subsection Changing Fonts
3201 @cindex changing fonts
3202 @cindex fonts, changing
3205 You can change fonts with both the @code{ft} request.
3206 With no arguments it
3207 will switch to the previous font (also known as P).
3218 The @code{\f} escape is useful for changing fonts in the middle of words
3221 eggs, bacon, \fBspam\fP and sausage.
3224 Both of the above examples will produce the same output.
3226 Sometimes when putting letters of different fonts, you need more or
3227 less space at such boundaries. There are two escapes to help with
3231 The @code{\/} escape
3232 increases the width of the preceding character so that the spacing
3233 between that character and the following character will be correct if
3234 the following character is a roman character. For example, if an italic
3235 f is immediately followed by a roman right parenthesis, then in many
3236 fonts the top right portion of the f will overlap the top left of the
3238 It is a good idea to use this escape sequence
3239 whenever an italic character is immediately followed by a roman
3240 character without any intervening space.
3242 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids this problem.
3245 The @code{\,} escape
3246 modifies the spacing of the following character so that the spacing
3247 between that character and the preceding character will correct if the
3248 preceding character is a roman character.
3250 to use this escape sequence whenever a roman character is immediately
3251 followed by an italic character without any intervening space.
3253 @c For example, inserting \, between the parenthesis and the f changes (f to (f.
3256 The @code{ftr} request will translate fonts, it is called as
3257 @samp{.ftr @var{F G}}, which
3258 Translate font @var{F} to @var{G}.
3259 Whenever a font named @var{F} is referred to in @code{\f}
3261 or in the @code{ft}, @var{ul}, @var{bd}, @var{cs}, @var{tkf},
3262 @var{special}, @var{fspecial}, @var{fp},
3263 or @var{sty} requests, font @var{G} will be used. If @var{G} is
3264 missing, or equal to @var{F} then font @var{F} will not be translated.
3267 @node Font Families, Font Positions, Changing Fonts, Fonts
3268 @subsection Font Families
3269 @cindex font families
3270 @cindex families, font
3272 Due to the variety of fonts available, groff has added the concept of
3273 font families. Each of these families has four styles (R, I, B and BI),
3275 The fonts are specified as the concatenation of the font family and
3276 style. Specifying a font without the family part will cause groff to
3277 use that style of the current family.
3278 By default, groff uses the Times family.
3280 This way, you can just use the basic four fonts and select a
3281 different font family on the command line.
3285 You can also switch font families with the @code{fam} request
3286 The current font family is available in the number register
3288 This is a string-valued register.
3304 @node Font Positions, Using Symbols, Font Families, Fonts
3305 @subsection Font Positions
3306 @cindex font positions
3307 @cindex positions, font
3309 For the sake of old phototypesetters and compatability with old
3310 versions of troff, groff has the concept of font
3311 @dfn{positions}, on which various fonts are mounted.
3312 The last one or two are reserved for the symbol font(s).
3315 New fonts can be mounted with the @code{fp} request.
3316 These numeric positions can then be referred to with font changing commands.
3317 When groff starts it is using font number one.
3332 (note that after these font changes have taken place the original
3336 The current font in use, as a font position.
3337 This can be useful to remember the current font, for later recall.
3341 ... lots 'o text ...
3346 The number of the next free font position is available in the number
3347 register @code{.fp}. This is useful when mounting a new font, like so:
3350 .fp \n[.fp] NEATOFONT
3354 Fonts not listed in the @file{DESC} file are automatically mounted on
3355 the next available font position when they are referenced.
3357 mountfed explicitly with the @code{fp} request on an unused font position, it
3358 should be mounted on the first unused font position, which can be found
3359 in the @code{.fp} register; although troff does not enforce this strictly,
3360 it will not allow a font to be mounted at a position whose number is
3361 much greater than that of any currently used position.
3363 The @code{fp} request has an optional third argument.
3364 This argument gives the
3365 external name of the font, which is used for finding the font
3366 description file. The second argument gives the internal name of the
3367 font which is used to refer to the font in troff after it has been
3368 mounted. If there is no third argument then the internal name will be
3369 used as the external name. This feature allows you to use fonts with
3370 long names in compatibility mode.
3372 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
3373 @subsection Using Symbols
3374 @cindex using symbols
3375 @cindex symbols, using
3379 Symbols can be inserted by using a special escape sequence.
3380 This escape is simply the escape character (a backslash) followed by
3381 an identifier. The symbol identifiers have to be two or more
3382 characters, since single characters conflict with all the other
3383 escapes. The identifier can be either preceded by a parenthesis if
3384 it is two character, or surrounded by square brackets.
3385 So, the symbol for pi can be produced either by @code{\(*p} or
3389 area = \(*p\fIr\fP\u2\d
3393 The escape @code{\C'@var{xxx}'} will typeset character named
3394 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
3395 But @code{\C} has the advantage that it is compatible with recent
3396 versions of ditroff and is available in compatibility mode.
3399 The escape @code{\N'@var{n}'} will typeset the character with code
3400 @var{n} in the current font. @var{n} can be any integer. Most devices only
3401 have characters with codes between 0 and 255. If the current font
3402 does not contain a character with that code, special fonts will not be
3403 searched. The @code{\N} escape sequence can be conveniently used on
3404 conjunction with the @code{char} request:
3407 .char \[phone] \f(ZD\N'37'
3410 The code of each character is given in the fourth column in the font
3411 description file after the charset command. It is possible to include
3412 unnamed characters in the font description file by using a name of
3413 @samp{---}; the @code{\N} escape sequence is the only way to use these.
3416 Each character has certain properties associated with it.
3417 These properties can be modified with the @code{cflags} request.
3418 The first argument is the the sum of the desired flags and the
3419 remaining arguments are the characters to have those properties.
3422 the character ends sentences (initially characters @samp{.?!} have this
3425 lines can be broken before the character (initially no characters have
3428 lines can be broken after the character (initially characters
3429 @samp{-\(hy\(em} have this property);
3431 the character overlaps horizontally (initially characters
3432 @samp{\(ul\(rn\(ru} have this property);
3434 the character overlaps vertically (initially character @samp{\(br} has
3437 an end of sentence character followed by any number of characters with
3438 this property will be treated as the end of a sentence if followed by a
3439 newline or two spaces; in other words the character is transparent for
3440 the purposes of end of sentence recognition; this is the same as having
3441 a zero space factor in @TeX{} (initially characters
3442 @samp{"')]*\(dg\(rq} have this property).
3446 You can create new characters with the @code{char} request. It is
3447 called as @samp{.char @var{c} @var{string}} Define character @var{c}
3448 to be @var{string}. Every time character @var{c} needs to be printed,
3449 @var{string} will be processed in a temporary environment and the
3450 result will be wrapped up into a single object. Compatibility mode
3451 will be turned off and the escape character will be set to \ while
3452 @var{string} is being processed. Any emboldening, constant spacing or
3453 track kerning will be applied to this object rather than to individual
3454 characters in @var{string}. A character defined by this request can
3455 be used just like a normal character provided by the output device.
3456 In particular other characters can be translated to it with the
3457 @code{tr} request; it can be made the leader character by the
3458 @code{lc} request; repeated patterns can be drawn with the character
3459 using the @code{\l} and @code{\L} escape sequences; words containing
3460 the character can be hyphenated correctly, if the @code{hcode} request
3461 is used to give the character a hyphenation code. There is a special
3462 anti-recursion feature: use of character within the character's
3463 definition will be handled like normal characters not defined with
3467 A character definition can be removed with the @code{rchar} request. Its
3468 arguments are the characters to be removed. This undoes the effect of
3469 a @code{char} request.
3471 @c distribute these through the text
3472 @xref{Special Characters}
3474 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
3475 @subsection Artificial Fonts
3476 @cindex artificial fonts
3477 @cindex fonts, artificial
3479 There are a number of requests for artificially creating fonts.
3480 These are largely vestigal remains from the days when output devices
3481 did not have a wide variety of fonts, and when nroff and troff were
3483 These are no longer necessary in GNU Troff.
3486 The @code{ul} request will print subsequent lines in italics on a device
3487 capable of it, or underline the text on an character output device. The
3488 single argument is the number of lines to be ``underlined,'' with no
3489 argument, the next line will be underlined.
3492 The @code{cu} request is similar to @code{ul} ...
3495 The @code{uf} request will set the underline font used by @code{ul}
3499 The @code{bd} request artificially creates a bold font by printing
3500 each character twice, slightly offset.
3501 The first argument specifies the font to embolden, and the second is
3502 the number of basic units, minus one, by which the two characters
3503 will be offset. If the second argument is missing, emboldening will
3506 @node Ligatures and Kerning, , Artificial Fonts, Fonts
3507 @subsection Ligatures and Kerning
3508 @cindex ligatures and kerning
3509 @cindex kerning and ligatures
3515 The current ligature mode.
3519 If the font description file contains pairwise kerning information,
3520 characters from that font will be kerned. Kerning between two
3521 characters can be inhibited by placing a @code{\&} between them.
3526 If n is non-zero or missing, enable pairwise kerning, otherwise disable
3529 1 if pairwise kerning is enabled, 0 otherwise.
3533 Enable track kerning for font f. When the current font is f the width
3534 of every character will be increased by an amount between n1 and n2;
3535 when the current point size is less than or equal to s1 the width will
3536 be increased by n1; when it is greater than or equal to s2 the width
3537 will be increased by n2; when the point size is greater than or equal to
3538 s1 and less than or equal to s2 the increase in width is a linear
3539 function of the point size.
3542 @node Sizes, Strings, Fonts, Programming Tutorial
3547 Groff uses two dimensions with each line of text, type size and
3548 vertical spacing. The type size is the height from the text
3549 @dfn{baseline} to the top of the tallest character (decenders may drop
3550 below this baseline). Vertical spacing is the amount of space groff
3551 allows for a line of text, normally, this is about 20% larger than the
3552 current type size. Ratios smaller than this can result in
3553 hard-to-read text, larger that this, it will spread your text out more
3554 vertically (useful for term papers). By default, troff uses 10 point
3555 type on 12 point spacing.
3558 The difference between type size and vertical spacing is known, by
3559 typesetters, as @dfn{leading}.
3562 * Changing Type Sizes::
3563 * Fractional Type Sizes::
3566 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
3567 @subsection Changing Type Sizes
3568 @cindex changing type sizes
3569 @cindex type sizes, changing
3576 Using the @code{ps} request and the @code{\s} escape you can change
3577 the type size. The @code{vs} request will change the vertical
3578 spacing. The default unit for the @code{ps} and @code{vs} requests are
3580 The number registers @code{.s} and @code{.v} contain the current
3581 type size and vertical spacing.
3583 These requests take parameters in units of points. You can specify
3584 sizes as an absolute size, or as a relative change from the current
3585 size. The size 0 means go back to the previous size. With no
3586 argument it will revert to the previous size.
3593 wink, wink, \s+2nudge, nudge,\s+8 say no more!
3597 The @code{\s} escape may be called in a variety of ways.
3598 Much like other escapes there must be a way to determine where the
3599 argument ends and the text begins.
3600 Any of the following forms are valid:
3605 @code{\s+(@var{nn}},
3606 @code{\s-(@var{nn}},
3607 @code{\s[+@var{nnn}]},
3608 @code{\s[-@var{nnn}]},
3609 @code{\s+[@var{nnn}]},
3610 @code{\s-[@var{nnn}]}.
3612 Some devices may only have certain permissible sizes, in which case
3613 groff will round to the nearest permissible size.
3616 ... .sz macro example?? ...
3619 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
3620 @subsection Fractional Type Sizes
3621 @cindex fractional type sizes
3622 @cindex type sizes, fractional
3624 @cindex @code{s} unit
3625 @cindex unit, @code{s}
3626 @cindex @code{z} unit
3627 @cindex unit, @code{z}
3628 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
3629 @var{sizescale} is specified in the @file{DESC} file (1 by default.)
3630 There is a new scale indicator @samp{z} which has the effect of
3631 multiplying by @var{sizescale}. Requests and escape sequences in
3632 troff interpret arguments that represent a pointsize as being in units
3633 of scaled points, but they evaluate each such argument using a default
3634 scale indicator of @samp{z}. Arguments treated in this way are the
3635 argument to the @code{ps} request, the third argument to the @code{cs}
3636 request, the second and fourth arguments to the @code{tkf} request,
3637 the argument to the @code{\H} escape sequence, and those variants of
3638 the @code{\s} escape sequence that take a numeric expression as their
3641 For example, suppose @var{sizescale} is 1000; then a scaled point will be
3642 equivalent to a millipoint; the request @samp{.ps 10.25} is equivalent to
3643 @samp{.ps 10.25z} and so sets the pointsize to 10250 scaled points, which is
3644 equal to 10.25 points.
3646 The number register @code{\n(.s} returns the pointsize in points as
3647 decimal fraction. There is also a new number register @code{\n[.ps]}
3648 that returns the pointsize in scaled points.
3650 It would make no sense to use the @samp{z} scale indicator in a
3651 numeric expression whose default scale indicator was neither @samp{u}
3652 nor @samp{z}, and so troff disallows this. Similarily it would make
3653 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
3654 numeric expression whose default scale indicator was @samp{z}, and so
3655 troff disallows this as well.
3657 There is also new scale indicator @samp{s} which multiplies by the
3658 number of units in a scaled point. So, for example, @samp{\n[.ps]s}
3659 is equal to 1m. Be sure not to confuse the @samp{s} and @samp{z}
3666 Set the point size to @var{n} scaled points; @var{n} is a numeric
3667 expression with a default scale indicator of @samp{z}.
3670 The current pointsize in scaled points.
3673 The last-requested pointsize in scaled points.
3676 The last requested pointsize in points as a decimal fraction. This is a
3677 string-valued register.
3680 @c distribute these through the text
3684 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
3689 Groff has string variables, which are entirely for user convenience
3690 (i.e. there are no built-in strings). They are defined via the
3694 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
3698 They are interpolated, or expanded in-place, via the @code{\*} escape:
3701 The \*(UX Operating System
3707 The UNIXtm Operating System
3710 If the string named by the @code{\*} does not exist, the escape will
3711 be replaced by nothing.
3713 @cindex comments, with @code{ds}
3714 NOTE: Unlike other requests the third argument takes up the entire
3715 line including trailing spaces. This means that comments on a line
3716 with such a request can introduce unwanted space into a string.
3719 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" trademark of you-know-who
3722 Instead you should either put the comment on another line or
3723 have the comment escape adjacent with the end of the string.
3726 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" trademark of you-know-who
3729 If you need leading space you can start the string with a double
3730 quote. No trailing quote is needed, in fact any trailing quote is
3731 included in your string.
3735 .ds sign " Yours in a white wine sauce,
3739 @cindex appending to strings
3740 @cindex strings, appending
3741 You can also append onto a string with the @code{as} request.
3742 It works the same as the @code{ds} request except that it appends the
3743 second argument onto the string named by the first argument.
3746 .as sign " with shallots, onions and garlic,
3750 Strings are not limited to a sigle line of text. A string can span
3751 several lines by escaping the newlines with a backslash. The
3752 resulting string will be stored @emph{without} the newlines.
3755 .ds foo lots and lots \
3756 of text are on these \
3762 @code{.substring xx n1 [n2]}
3763 Replace the string in register@w{ }xx with the substring defined by the
3764 indices n1 and@w{ }n2. The first character in the string has index one.
3765 If n2 is omitted, it is taken to be equal to the string's length. If
3766 the index value n1 or n2 is negative or zero, it will be counted from
3767 the end of the string, going backwards: The last character has index@w{
3768 }0, the character before the last character has index@w{ }-1, etc.
3771 @cindex length of a string
3772 @cindex string, length of
3773 @code{.length xx string}
3774 Compute the length of string and return it in the number register@w{ }xx
3775 (which is not necessarily defined before).
3789 @c distribute these through the text
3791 @c distribute these through the text
3795 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
3796 @section Conditionals and Loops
3797 @cindex conditionals and loops
3798 @cindex loops and conditionals
3802 In @code{if} and @code{while} requests, there are several more operators
3808 True if the current page is even or odd numbered (respectively)
3811 True if the document is being processed by
3812 nroff (or a character device) or troff.
3813 @item '@var{xxx}'@var{yyy}'
3814 True if the string @var{xxx} is equal to the string @var{yyy}.
3815 Other characters can be used in place of the single quotes.
3817 The strings are `formatted' before being compared. (?)
3819 True if there is a number register named @var{xxx}.
3821 True if there is a string, macro, diversion, or request named @var{xxx}.
3823 True if there is a character @var{ch} available; @var{ch} is
3824 either an @sc{ascii} character or a special character @code{\(@var{ch}} or
3825 @code{\[@var{ch}]}; the condition will also be true if @var{ch} has been
3826 defined by the @code{char} request.
3834 @node if-else, while, Conditionals and Loops, Conditionals and Loops
3838 Troff has if-then-else constructs like other languages, although
3839 the formatting can be painful.
3842 The @code{if} request is troff's if statement, it is called as
3843 @samp{.if @var{expr} @var{anything}}, where @var{expr} is the
3844 expression to be evaluated,
3845 and @var{anything} (the remainder of the line)
3846 which will be executed if
3847 the @var{expr} evaluates to non-zero (true).
3848 @var{anything} will be interpreted as though it was on a line by
3850 @xref{Expressions}, for more info.
3852 Here are some examples:
3855 .if t .ls 2 \" double spacing in troff
3856 .if 0 .ab how'd this happen??
3861 An if-then-else is written using two requests @code{ie} and @code{el}
3862 the first request is the if part and the latter is the else part.
3871 In many cases you will want more than one request to be executed as a
3872 result of any of these requests, this can be done using the \@{ and
3874 The following example shows the possible ways to use these escapes.
3889 @c distribute these through the text
3892 @node while, , if-else, Conditionals and Loops
3897 Groff provides a looping construct using the @code{while} request,
3898 which is used much like the @code{if} (and related) requests.
3899 The first argument is an expression which will be evaluated.
3900 The @code{while} request will interpret the remainder of the line
3901 until the expression evaluates to 0 or false.
3905 .while (\na<9) \&\n+a,
3909 The preceding example produces:
3912 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
3917 The @code{break} request will
3918 @dfn{break} out of a while loop.
3919 Be sure not to confuse this with the @code{.br} request.
3920 The @code{continue} request will
3921 finish the current iteration of a while loop.
3923 @c distribute these through the text
3927 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
3928 @section Writing Macros
3929 @cindex writing macros
3930 @cindex macros, writing
3933 A macro is a collection of text and embedded commands which can be
3934 invoked multiple times. Macros are used for defining common operations.
3935 Macros are defined using the @code{de} request. This request takes
3936 a name for the macro as the first argument. Subsequent lines are
3937 copied into an internal buffer until the line @code{..} is
3938 encountered. The optional second argument to @code{de} can change
3941 For example, suppose at the beginning of each paragraph, you want
3942 cause a break, move down a partial line and indent the first line.
3943 Such a macro could be defined as follows:
3953 The @code{am} request works similarily to @code{de} except it appends
3954 onto the macro named by the first argument. So, if we decide we want
3955 our previously @code{P} macro to actually do indented instead of
3956 block paragraphs we can add the necessary code to our existing macro.
3965 @cindex aliases, macro
3966 @cindex macro aliases
3967 Macros can be aliased with the @code{als} request.
3983 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
3984 @subsection Copy-in Mode
3985 @cindex copy-in mode
3986 @cindex mode, copy-in
3993 When troff reads in the test for a macro or diversion it copies the
3994 text (including request lines) into an internal buffer, except for
3995 escapes. Escapes will be converted into an internal form, except for
3996 @code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which
3997 are evaluated and inserted into the text where the escape was located.
3998 This is known as @dfn{copy-in} mode.
4000 What this means is that you can specify when these escapes are to be
4001 evaluated (copy-in time or time of use) by insulating the escapes
4002 with an extra backslash.
4004 For example, the following will result in the numbers 20 and 10 being
4017 @node Parameters, , Copy-in Mode, Writing Macros
4018 @subsection Parameters
4023 The arguments to a macro can be examined using a variety of escapes.
4024 The number of arguments is available in the @code{.$} number register.
4025 Any individual argument can be retrieved with one of the following
4028 The escapes @code{\$@var{n}}, @code{\$(@var{nn}}
4029 and @code{\$[@var{nnn}]}
4030 will result in the @var{n}th, @var{nn}th or @var{nnn}th
4031 argument. Macros can have a unlimited number of arguments.
4032 Note that due to copy-in mode, you will want to have two backslashes
4033 on these in actual use, since you do not want them interpolated until
4034 the macro is actually invoked.
4037 The request @code{shift} will shift the arguments 1 position, or as
4038 many positions as specified by the first argument.
4039 After executing this request, argument
4040 @var{i} will become argument @var{i}-@var{n}; arguments 1 to @var{n}
4041 will no longer be available.
4042 Shifting by negative amounts is currently undefined.
4046 In some cases you will want to just use all of the arguments at once.
4047 For example if you pass the arguments along to another macro.
4048 The @code{\$*} escape is
4049 the concatenation of all the arguments separated by spaces.
4050 A similar escape is @code{\$@@},
4052 the concatenation of all the arguments with each surrounded
4053 by double quotes, and separated by spaces.
4057 The @code{\$0} escape is
4058 the name by which the current macro was invoked. The @code{als}
4059 request can make a macro have more than one name.
4063 .ie \\n(.$=1 .ds Vl Pre-Release Version
4064 .el .ds Vl Version \\$3, \\$4.
4068 This would be called as
4075 @c distribute these through the text
4076 @xref{Request Arguments}
4079 @node Page Motions, Drawing Functions, Writing Macros, Programming Tutorial
4080 @section Page Motions
4081 @cindex page motions
4082 @cindex motions, page
4085 Motions up and down the page can be done with the @code{sp} request.
4086 However, this causes a break so that the actual effect is to move to
4087 the left margin and then to the specified location.
4091 The request @code{mk} can be used to mark a location on a page, for
4092 movement to later. This request takes a register name as an
4093 argument in which to store the current page location, with no
4094 argument it will store the location in an internal register.
4095 The results of this can be used later by the @code{rt} or the
4096 @code{sp} request. The @code{rt} request will return
4097 @strong{upwards} to the location given in the register name given as
4098 an argument, with no argument it will return to the location marked
4099 with the @code{mk} request
4102 ... dual column example ...
4105 There are escapes which will give you much finer control of movements
4109 The @code{\v'@var{e}'} will let you do arbitrary vertical motion from
4110 the current location on the page. The argument @var{e} specifies the
4111 distance to move, positive is downwards and negative upwards. The
4112 default unit for this escape is vertical spaces, @code{v}'s. Beware,
4113 however, that troff will leave text processing to continue wherever
4114 the motion ends, so if you don't want to interfere with text
4115 processing, make sure your motions are balanced.
4117 There are some special case escapes for vertical motion.
4129 Horizontal motions can be done via the @code{\h'@var{e}'} escape.
4130 The expression @var{e} indicates how far to move: positive is
4131 rightwards and negative leftwards.
4133 There are a number of special case escapes for horizontal motion:
4137 An unbreakable and unpadable (i.e. not expanded during filling) space.
4138 (Note: it is a backslash followed by a space.)
4140 This produces an unbreakable space that stretches like a normal
4141 interword space when a line is adjusted.
4147 a space the size of a digit.
4151 Like @code{\&} except that it behaves like a character declared with
4152 the @code{cflags} request to be transparent for the purposes of end
4153 of sentence recognition.
4157 ... tex logo example ...
4161 @cindex width escape
4162 @cindex escape, width
4163 Often you will want to do horizontal movement based on the width of
4164 some arbitrary text (e.g. given as an argument to a macro).
4165 For that, there is the escape @code{\w'@var{text}'} which will
4166 interpolate to the width of the given @var{text} in basic units.
4169 ... strlen example ...
4172 Font changes may occur in @var{text} and not affect current settings.
4174 Also after use, @code{\w} sets several registers:
4181 The highest and lowest point, respectively, in @var{text}.
4186 Like the @code{st} and @code{sb} registers, but takes account of the
4187 heights and depths of characters.
4190 is set according to what kinds of characters occur in @var{text}.
4193 all short characters, no decenders or tall characters.
4199 both a decender and a tall character
4203 The amount of horizontal space (possibly negative) that should be
4204 added to the last character before a subscript.
4207 How far to right of the center of the last character in the @code{\w}
4208 argument, the center of an accent from a roman font should be
4209 placed over that character.
4218 @node Drawing Functions, Traps, Page Motions, Programming Tutorial
4219 @section Drawing Functions
4220 @cindex drawing functions
4221 @cindex functions for drawing
4223 Groff provides a number of ways to draw lines, and other figures on
4224 the page. Used in combination with the page motion commands
4225 (@pxref{Page Motions}, for more info) you can draw a wide variety of
4226 figures. However, for complex drawings these operations can be quite
4227 cumbersome, and it may be wise to use the pic preprocessor.
4228 @xref{gpic}, for more information.
4230 All drawing is done via escapes.
4233 The @code{\l} will draw a line rightwards from the current location.
4234 The full syntax for this escape is @samp{\l'@var{l}@var{c}'}, where
4235 @var{l} is the length of the line to be drawn, starting at the
4236 current location, positive numbers will draw to the right, and
4237 negative will draw towards the left. This can also be specified
4238 absolutely (i.e. with a leading |) which will draw back to the
4239 begining of the line.
4241 The optional second parameter @var{c} is a character to draw the line
4242 with. If this second argument is not specified, troff will use the
4243 underscore character.
4245 If you need to separate the two arguments (to prevent troff from
4246 interpreting a drawing character as a scaling indicator), you can
4247 separate them with @code{\&}.
4249 And now, for a useful example:
4253 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
4257 Note that this works by outputing a box rule (a vertical line), then
4258 the text given as an argument and then another box rule.
4259 Then the line drawing escapes both draw from the current location to
4260 the beginning of the @emph{input} line.
4263 Vertical lines are drawn using the @code{\L} escape. It's parameters
4264 are specified the same as the @code{\l} escape. If the length is
4265 positive, the movement will be downwards, and upwards for negative.
4266 The default character is the box rule character.
4267 As with the vertical motion escapes, text processing will blindly
4268 continue where the line ends.
4275 More flexible drawing functions are available via the @code{\D}
4276 escape. While the previous escapes will work on a character device,
4277 these escapes will not.
4280 @item \D'l @var{x} @var{y}'
4281 Draw a line from the current location to the relative point specified
4282 by @var{x}, @var{y}.
4285 ...revised box macro...
4289 Draw a circle with a diameter of @var{d} with the leftmost point at
4290 the current position.
4292 Draw a solid circle with the same parameters as an outlined circle.
4293 @item \D'e @var{dx} @var{dy}'
4294 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
4295 diameter of @var{dy} with the leftmost point at the current position.
4296 @item \D'E @var{dx} @var{dy}'
4297 Draw a solid elipse with the same parameters as an outlined elipse.
4298 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
4299 Draw an arc clockwise from the current location through the two
4300 specified locations.
4301 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4302 Draw a spline from the current location to
4303 @var{dx1}, @var{dy1} and then to @var{dx2}, @var{dy2}, and so on.
4305 Set the shade of gray to be used for filling solid objects to @var{n};
4306 @var{n} must be an integer between 0 and 1000, where 0 corresponds
4307 solid white and 1000 to solid black, and values in between correspond
4308 to intermediate shades of gray. This applies only to solid circles,
4309 solid ellipses and solid polygons. By default, a level of 1000 will
4311 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4312 Draw a polygon from the current location to @var{dx1}, @var{dy1}
4313 and then to @var{dx2}, @var{dy2} and so on. When the specified data
4314 points are exhausted, a line is drawn back to the starting point.
4317 ... box example (yes, again)...
4320 @itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4321 Draw a solid polygon with the same parameters as an outlined polygon.
4324 ... shaded box example ...
4328 Set the current line thickness to @var{n} machine units.
4329 A value of zero selects the smallest available line thickness.
4336 @cindex pile, character
4337 @cindex character pile
4338 The @code{\b} escape will @dfn{pile} a sequence of characters
4339 vertically, and center it vertically on the current line.
4340 This can be used to build large brackets and braces.
4343 \b'\(lt\(bv\(lk\(bv\(lb'
4347 @node Traps, Diversions, Drawing Functions, Programming Tutorial
4351 Traps are locations, which, when reached, will call a specified macro.
4352 These traps can occur at a given location on the page, at a given
4353 location in the current diversion, after a certain number of input
4354 lines or at the end of input.
4357 Any of these traps can be changed after they have been set with the
4358 @code{ch} request. The first arguemnt is the name of the trap or
4359 macro, and the second is the new value for that trap.
4362 * Page Location Traps::
4364 * Input Line Traps::
4365 * End-of-input Traps::
4368 @node Page Location Traps, Diversion Traps, Traps, Traps
4369 @subsection Page Location Traps
4370 @cindex page location traps
4371 @cindex traps, page location
4373 Page location traps are frequently used for page headers and
4374 footers. The following is a simple example of this.
4377 .de hd \" Page header
4382 .de fo \" Page footer
4387 .wh 0 hd \" top of the page
4388 .wh -1i fo \" one inch from bottom
4392 The number register @code{.t} is the distance to the next trap.
4395 The location of a trap can be changed later on with the @code{ch}
4397 The first argument is the name of the macro to be invoked at the trap
4398 and the second argument is the new location for the trap.
4399 This is useful when you are building up footnotes in a diversion, and
4400 you need to allow more space at the bottom of the page for them.
4403 ... (simplified) footnote example ...
4410 The @code{vpt} request will enable vertical position traps if the argment is
4411 non-zero, disable them otherwise. Vertical position traps are traps
4412 set by the @code{wh} or @code{dt} requests. Traps set by the
4413 @code{it} request are not vertical position traps. The parameter that
4414 controls whether vertical position traps are enabled is global.
4415 Initially vertical position traps are enabled. The current setting of
4416 this is available in the number register @code{.vpt}.
4420 The number register @code{.trunc} contains
4421 the amount of vertical space truncated by the most recently
4422 sprung vertical position trap, or, if the trap was sprung by a
4423 @code{ne} request, minus the amount of vertical motion produced by
4424 the @code{ne} request. In other words, at the point a trap is
4425 sprung, it represents the difference of what the vertical position
4426 would have been but for the trap, and what the vertical position
4430 The number register @code{.ne} contains
4431 the amount of space that was needed in the last @code{ne} request that caused
4432 a trap to be sprung. Useful in conjunction with the @code{.trunc}
4433 register. @xref{Page Control}, for more information.
4435 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
4436 @subsection Diversion Traps
4437 @cindex diversion traps
4438 @cindex traps, diversion
4442 Traps can also be set @emph{within} a diversion using the @code{dt}
4443 request. Like @code{wh} the first argument is the location of the
4444 trap and the second argument is the name of the macro to be invoked.
4445 The number register @code{.t} will still work within diversions.
4446 @xref{Diversions}, for more information.
4448 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
4449 @subsection Input Line Traps
4450 @cindex input line traps
4451 @cindex traps, input line
4454 The @code{it} request will set an input line trap. The format for
4455 calling this is @samp{.it @var{n} @var{name}}, where @var{n} is the
4456 number of lines of input which may be read before @dfn{springing} the
4457 trap, @var{name} is the macro to be invoked. Request lines are not
4458 counted as input lines.
4460 For example, one possible use is to have a macro which will print the
4461 next @var{n} lines in a bold font.
4473 @node End-of-input Traps, , Input Line Traps, Traps
4474 @subsection End-of-input Traps
4475 @cindex end-of-input traps
4476 @cindex traps, end-of-input
4479 The @code{em} request will set a trap at the end of input.
4480 The macro specified as an arguement will be executed after the last
4481 line of the input file has been processed.
4483 For example, if your document had to have a section at the bottom of
4484 the last page for someone to approve you document, you could set it
4502 @node Diversions, Environments, Traps, Programming Tutorial
4506 In Troff you can divert text into a named storage area, due to the
4507 similarity to defining macros it is sometimes said to be stored in a
4508 macro. This is used for saving text for output at a later time,
4509 which is useful for keeping blocks of text on the same page,
4510 footnotes, tables of contents and indexes.
4514 Diversion is initiated by the @code{di} request, like the @code{de}
4515 request it takes an argument of a macro name to divert subsequent
4516 text to into. The @code{da} macro will append to an existing diversion.
4519 ... end-note example ...
4526 Diversions may be nested.
4527 The number register @code{.z} contains the name of the current diversion.
4528 The number register @code{.d} contains the current vertical place in
4529 the diversion. If not in a diversion it is the same as the register
4535 After compleating a diversion, the built-in number registers @code{dn}
4536 and @code{dl} contain the vertical and horizontal size of the diversion.
4539 .\" Center text both horizontally & vertically
4548 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
4563 Requests, macros and escapes are interpreted when read into a
4565 There are two ways to prevent this, either way will take the given
4566 text and @dfn{transparently} embed it into the diversion.
4567 The first method is to prefix the line with @code{\!}. This will
4568 cause the entire line to be transparently inserted into the diversion.
4569 This is useful for macros you do not want invoked until the diverted
4570 text is actually output.
4572 @c anything is read in copy mode. (what about \! ??)
4575 The other way is to surround the text by the @code{\?} escape, i.e.
4576 @samp{\?@var{anything}\?}.
4577 @var{anything} may not contain
4578 newlines; use @code{\!} if you want to embed newlines in a diversion. The
4579 escape sequence @code{\?} is also recognised in copy mode and turned into a
4580 single internal code; it is this code that terminates anything. Thus
4581 the followin example will print 4.
4587 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
4615 This request only exists in order to make it possible to make certain
4616 gross hacks work with GNU troff. It @dfn{unformats} the diversion
4617 specified as an argument in
4618 such a way that @sc{ascii} characters that were formatted and diverted
4619 will be treated like ordinary input characters when the diversion is
4620 reread. For example, the following will set register @code{n} to 1.
4634 @c distribute these through the text
4638 @node Environments, I/O, Diversions, Programming Tutorial
4639 @section Environments
4640 @cindex environments
4642 Often you will need to print some text in a certain format regardless
4643 of what may be in effect at the time, for example, in a trap invoked
4644 macro to print headers and footers.
4645 To solve this groff has @dfn{environments} in which text is processed.
4646 An environment contains most of the parameters that control
4647 text processing. You can switch amongst these environments, by
4648 default groff processes text in environment 0.
4649 The following is the information kept in an environment.
4655 Font (family and style)
4663 Partially collected lines
4666 These environments may be given arbitrary names
4667 (@pxref{Identifiers}, for more info.)
4668 Old versions of troff only had environments named 0, 1 and 2.
4672 The @code{ev} request will switch among these environments.
4673 The single argument is the name of the environment to switch to, with
4674 no argument groff will switch back to the previous enviroment.
4675 There is no limit on the number of named environments;
4676 they will be created the first time that they are referenced.
4677 The @code{.ev} number register contains
4678 the name or number of the current environment. This is a string-valued
4682 ... page break macro, revised ...
4694 \(dg Note the large, friendly letters.
4699 @node I/O, Postprocessor Access, Environments, Programming Tutorial
4704 The @code{so} request will read in the file given as an argument and
4705 include it in place of the @code{so} request. This is quite useful
4706 for large documents, i.e. keeping each chapter in a separate file.
4707 @xref{gsoelim}, for more information.
4710 The @code{mso} request is
4711 the same as the @code{so} request except that file is searched for in
4712 the same way that @file{tmac.@var{name}} is searched for when the
4713 @samp{-m@var{name}} option is specified.
4717 The @code{cf} and @code{trf} requests are to include a file.
4718 It will transparently output the contents of file filename. Each
4720 as it would be were it preceded by @code{\!}; however, the lines are not
4721 subject to copy-mode interpretation. If the file does not end with a
4722 newline, then a newline will be added. For example, you can define a
4723 macro @code{x} containing the contents of file @file{f}, using
4732 When used in a diversion, this will embed in the diversion an object
4733 which, when reread, will cause the contents of filename to be
4734 transparently copied through to the output. In @sc{Unix} troff, the contents
4735 of filename is immediately copied through to the output regardless of
4736 whether there is a current diversion; this behaviour is so anomalous
4737 that it must be considered a bug.
4740 With @code{trf}, unlike @code{cf}, the file cannot contain characters
4741 such as NUL that are not legal troff input characters.
4744 The @code{nx} request will force groff to continue processing of the
4745 file specified as an argument.
4748 The @code{rd} request will read from standard input, and include what
4749 is read as though it were part of the input file. Text is read until
4750 a blank line is encountered.
4752 @cindex form letters
4753 @cindex letters, form
4754 Using these two requests you can set up form letters.
4755 The form letter template is constructed like this:
4772 When this is run, the following file should be redirected in.
4773 Note that requests included in this file are executed as though they
4774 were part of the form letter. The last block of input is the
4775 @code{ex} requests which tells groff to stop processing. If this was
4776 not there, groff would not know when to stop.
4778 @cindex Beagle Brothers
4781 708 NW 19th Av., #202
4799 The @code{sy} request will allow arbitrary system commands to be
4800 executed from within a groff document. The output is not saved
4801 anyplace, so it is up to you to do so.
4803 For example, the following example will introduce the current time
4809 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
4810 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
4816 Note that this works by having the perl script (run by @code{sy})
4817 print out the @code{nr} requests which will set the number registers
4818 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in
4819 with the @code{so} request.
4822 The @code{systat} number register contains
4823 The return value of the @code{system()} function executed by the last
4827 The @code{open} request will open
4828 a file (specified as the second argument) for writing and associate
4829 the stream (specified as the first argument) with it.
4833 like open, but if filename exists, append to it instead of truncating
4838 @cindex copy-in mode
4839 @cindex mode, copy-in
4840 The @code{write} request will write to the file associated with the
4841 stream specified by the first argument. The stream must previously
4842 have been the subject of an open request. The remainder of the line
4843 in interpreted as the @code{ds} request reads its second argument: a
4844 leading @code{"} will be stripped, and it will be read in copy-in mode.
4847 The @code{close} request will
4848 close the stream specified by the first argument; stream will no
4849 longer be an acceptable argument to the @code{write} request.
4852 ... example of open write &c...
4856 The @code{\V} escape will
4857 interpolate the contents of the specified environment variable, as returned
4859 The argument to @code{\V} is specified as an identifier, i.e.
4860 @samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}.
4861 @code{\V} is interpreted in copy-in mode.
4864 @node Postprocessor Access, Miscellany, I/O, Programming Tutorial
4865 @section Postprocessor Access
4866 @cindex postprocessor access
4867 @cindex access of postprocessor
4869 There are two escapes which will allow you to give information
4870 directly to the postprocessor. This is particularly useful for
4871 embedding PostScript into your final document.
4874 The @code{\X} escape will embed its argument into the gtroff output
4875 preceded with @samp{x X}.
4878 The @code{\Y} escape is called with an identifier (i.e.
4880 @code{\Y(@var{xx}} or
4881 @code{\Y[@var{xxx}]}).
4882 This is approximately equivalent to @samp{\X'\*[@var{xxx}]'}.
4883 However the contents
4884 of the string or macro @var{xxx} are not interpreted; also it is
4886 @var{xxx} to have been defined as a macro and thus contain newlines
4887 (it is not permitted for the argument to @code{\X} to contain newlines).
4889 newlines requires an extension to the @sc{Unix} troff output format, and will
4890 confuse drivers that do not know about this extension.
4893 @c distribute these through the text
4894 @xref{Output Devices}
4897 @node Miscellany, Debugging, Postprocessor Access, Programming Tutorial
4901 This section contains parts of troff which cannot (yet) be
4902 categorized elsewhere in this manual.
4905 Line numbers can be printed in the left margin
4906 using the @code{nm} request.
4907 The first argument is the line number of the @emph{next} output line,
4909 The second argument indicates on which lines numbers will be printed,
4910 i.e. 5 means put line numbers on every 5 lines, this defaults to 1.
4911 The third argument is the space to be left between the number and
4912 your text, this defaults to 1.
4913 The fourth argument is the indentation of the line numbers.
4914 Without arguments, line numbers are turned off.
4917 The @code{nn} request will temporarily turn off line numbering.
4918 The first argument is the number of lines not to be numbered,
4919 this defaults to 1. (does this disable incrementing or display?)
4922 ... line numbering example ...
4926 margin characters can be automatically printed to the right of your
4927 text with the @code{mc} request.
4928 The first argument is the character to be printed and the second
4929 argument is the distance away from your text.
4930 With no arguments the margin characters are turned off.
4931 If this occurs before a break, no margin character will be printed.
4933 This is quite useful for indicating text that has changed, and, in
4934 fact, there are programs available for doing this (they are called
4935 @code{nrchbar} and @code{changebar} and can be found in any
4936 @samp{comp.sources.unix} archive.
4939 ... margin char example ...
4944 The @code{lf} primary reason for existence is to make debugging
4945 documents which are split into many files, which are then put
4946 together with @code{soelim} and other preprocessors.
4947 The first argument is the name of the file and the second argument is
4948 the input line number in that file.
4949 This way troff can produce error messages which are intelligible to
4953 ... example of soelim'ed doc ...
4957 @node Debugging, Implementation Differences, Miscellany, Programming Tutorial
4961 Troff is not easy to debug, but there are some useful features and
4962 strategies for debugging.
4967 The @code{tm} request will send output to stderr, this is very useful for
4968 printing debugging output.
4970 When doing something involved it is useful to leave the debugging
4971 statements in the code and have them turned on by a command line
4975 .if \n(DB .tm debugging output
4978 Then you can activate these statements with:
4986 The @code{ab} request is similar to the @code{tm} request,
4987 except that it will cause groff to stop processing.
4988 With no argument it will print @samp{User Abort}.
4991 The @code{ex} request will also cause groff to stop processing.
4993 If you know you are going to get many errors and no useful output,
4994 you can tell groff to suppress formatted output with the @samp{-z}
4998 The @code{pm} request will dump out the entire symbol table.
5001 The @code{pnr} request will print the names and contents of all
5002 currently defined number registers on stderr.
5005 The @code{ptr} request will
5006 print the names and positions of all traps (not including input line
5007 traps and diversion traps) on stderr. Empty slots in the page trap list
5008 are printed as well, because they can affect the priority of
5009 subsequently planted traps.
5012 The @code{fl} request instructs groff to flush its output immediately.
5013 The intention is that this be used when using troff interactively.
5014 There is little other use for it.
5017 The @code{backtrace} request will
5018 print a backtrace of the input stack on stderr.
5020 Groff has command line options for printing out more warnings
5021 (@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or
5022 an error occurs. The most verbose level of warnings is @samp{-ww}.
5026 The @code{warn} request controls the level of warnings checked for.
5027 The one argument is the sum of the numbers associated with each
5028 warning that is to be enabled; all other warnings will be disabled.
5029 The number associated with each warning is listed below.
5030 For example, @code{.warn 0} will disable all warnings, and
5031 @code{.warn 1} will disable
5032 all warnings except that about missing characters. If an argument
5033 is not given, all warnings will be enabled.
5034 The number register @code{.warn} contains the current warning level.
5037 @subsection Warnings
5040 The warnings that can be given by troff are divided into the
5041 following categories. The name associated with each warning is used
5042 by the @samp{-w} and @samp{-W} options; the number is used by the
5043 @code{warn} request, and by the @code{.warn} register.
5048 Non-existent characters. This is enabled by default.
5051 Invalid numeric expressions. This is enabled by default.
5054 In fill mode, lines which could not be broken so that
5055 their length was less than the line length. This is
5059 Missing or mismatched closing delimiters.
5062 Use of the @code{el} request with no matching @code{ie} request.
5063 @xref{if-else}, for more information.
5066 Meaningless scaling indicators.
5069 Out of range arguments.
5072 Dubious syntax in numeric expressions.
5077 Use of @code{di} or @code{da} without an argument when there is no
5081 Use of undefined strings, macros and diversions.
5082 When an undefined string, macro or diversion is used,
5083 that string is automatically defined as empty. So,
5084 in most cases, at most one warning will be given for
5088 Use of undefined number registers. When an undefined
5089 number register is used, that register is
5090 automatically defined to have a value of 0. a
5091 definition is automatically made with a value of 0.
5092 So, in most cases, at most one warning will be given
5093 for use of a particular name.
5096 Use of a tab character where a number was expected.
5100 Use of @code{\@}} where a number was expected.
5103 Requests that are missing non-optional arguments.
5106 Illegal input characters.
5109 Unrecognized escape sequences. When an unrecognized
5110 escape sequence is encountered, the escape character
5114 Missing space between a request or macro and its
5115 argument. This warning will be given when an
5116 undefined name longer than two characters is
5117 encountered, and the first two characters of the name
5118 make a defined name. The request or macro will not
5119 be invoked. When this warning is given, no macro is
5120 automatically defined. This is enabled by default.
5121 This warning will never occur in compatibility mode.
5124 Non-existent fonts. This is enabled by default.
5126 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
5127 intended that this covers
5128 all warnings that are useful with traditional macro packages.
5134 @node Implementation Differences, Summary, Debugging, Programming Tutorial
5135 @section Implementation Differences
5136 @cindex implementation differences
5137 @cindex differences in implementation
5139 GNU troff has a number of features which cause incompatibilites with
5140 documents written with old versions of troff.
5142 Long names cause some incompatibilities. @sc{Unix} troff will interpret
5152 as defining a string @samp{ab} with contents @samp{cd}.
5153 Normally, GNU troff will interpret this as a call of a macro named
5154 @code{dsabcd}. Also @sc{Unix} troff will interpret @code{\*[} or
5155 @code{\n[} as references to a string or number register called
5156 @samp{[}. In GNU troff, however, this will normally be interpreted as the
5157 start of a long name. In compatibility mode GNU troff will interpret
5158 these things in the traditional way. In compatibility mode, however,
5159 long names are not recognised. Compatibility mode can be turned on with
5160 the @samp{-C} command line option, and turned on or off with the
5162 The number register @code{.C} is 1 if compatibility mode is on, 0 otherwise.
5165 GNU troff does not allow the use of the escape sequences
5166 @samp{\| \^ \& \@} \@{ \@key{SP} \' \` \- \_ \! \% \c} in names of
5168 diversions, number registers, fonts or environments; @sc{Unix} troff does.
5169 The @code{\A} escape sequence may be helpful in avoiding use of these escape
5172 @cindex fractional point sizes
5173 @cindex point sizes, fractional
5175 Fractional pointsizes cause one noteworthy incompatibility. In @sc{Unix}
5176 troff the @code{ps} request ignores scale indicators and so
5182 will set the pointsize to 10 points, whereas in GNU troff it will set
5183 the pointsize to 10 scaled points.
5184 @xref{Fractional Type Sizes}, for more information.
5191 In GNU troff there is a fundamental difference between unformatted,
5192 input characters, and formatted, output characters. Everything that
5193 affects how an output character will be output is stored with the
5194 character; once an output character has been constructed it is
5195 unaffected by any subsequent requests that are executed, including
5196 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp}
5197 requests. Normally output characters are constructed
5198 from input characters at the moment immediately before the character is
5199 added to the current output line. Macros, diversions and strings are
5200 all, in fact, the same type of object; they contain lists of input
5201 characters and output characters in any combination. An output
5202 character does not behave like an input character for the purposes of
5203 macro processing; it does not inherit any of the special properties that
5204 the input character from which it was constructed might have had. For
5218 will print @samp{\\} in GNU troff; each pair of input backslashes is
5220 output backslash and the resulting output backslashes are not
5221 interpreted as escape
5222 characters when they are reread. @sc{Unix} troff would interpret them as
5223 escape characters when they were reread and would end up printing one
5225 The correct way to obtain a printable backslash is to use the
5227 sequence: this will always print a single instance of the current escape
5228 character, regardless of whether or not it is used in a diversion; it
5229 will also work in both GNU troff and @sc{Unix} troff. If you wish for some
5230 reason to store in a diversion an escape sequence that will be
5231 interpreted when the diversion is reread, you can either use the
5232 traditional @code{\!} transparent output facility, or, if this is unsuitable,
5233 the new @code{\?} escape sequence. @xref{Diversions}, for more information.
5236 @node Summary, , Implementation Differences, Programming Tutorial
5242 @node Preprocessors, Output Devices, Programming Tutorial, Top
5243 @chapter Preprocessors
5244 @cindex preprocessors
5246 This chapter covers describes all preprocessors that come with
5247 @code{groff} or which are freely available.
5260 @node geqn, gtbl, Preprocessors, Preprocessors
5261 @section @code{geqn}
5269 @node Invoking geqn, , geqn, geqn
5270 @subsection Invoking @code{geqn}
5271 @cindex invoking @code{geqn}
5272 @cindex @code{geqn}, invoking
5275 @node gtbl, gpic, geqn, Preprocessors
5276 @section @code{gtbl}
5284 @node Invoking gtbl, , gtbl, gtbl
5285 @subsection Invoking @code{gtbl}
5286 @cindex invoking @code{gtbl}
5287 @cindex @code{gtbl}, invoking
5290 @node gpic, ggrn, gtbl, Preprocessors
5291 @section @code{gpic}
5299 @node Invoking gpic, , gpic, gpic
5300 @subsection Invoking @code{gpic}
5301 @cindex invoking @code{gpic}
5302 @cindex @code{gpic}, invoking
5305 @node ggrn, grap, gpic, Preprocessors
5306 @section @code{ggrn}
5314 @node Invoking ggrn, , ggrn, ggrn
5315 @subsection Invoking @code{ggrn}
5316 @cindex invoking @code{ggrn}
5317 @cindex @code{ggrn}, invoking
5320 @node grap, grefer, ggrn, Preprocessors
5321 @section @code{grap}
5324 @code{grap} is available as an extra package, written by Ted Faber.
5327 @node grefer, gsoelim, grap, Preprocessors
5328 @section @code{grefer}
5329 @cindex @code{refer}
5330 @cindex @code{grefer}
5336 @node Invoking grefer, , grefer, grefer
5337 @subsection Invoking @code{grefer}
5338 @cindex invoking @code{grefer}
5339 @cindex @code{grefer}, invoking
5342 @node gsoelim, , grefer, Preprocessors
5343 @section @code{gsoelim}
5344 @cindex @code{soelim}
5345 @cindex @code{gsoelim}
5348 * Invoking gsoelim::
5351 @node Invoking gsoelim, , gsoelim, gsoelim
5352 @subsection Invoking @code{gsoelim}
5353 @cindex invoking @code{gsoelim}
5354 @cindex @code{gsoelim}, invoking
5358 @node Output Devices, File formats, Preprocessors, Top
5359 @chapter Output Devices
5360 @cindex output devices
5361 @cindex devices for output
5364 * Special Characters::
5374 @node Special Characters, grotty, Output Devices, Output Devices
5375 @section Special Characters
5376 @cindex special characters
5377 @cindex characters, special
5379 @c distribute these through the text
5383 @node grotty, grops, Special Characters, Output Devices
5384 @section @code{grotty}
5385 @cindex @code{grotty}
5391 @node Invoking grotty, , grotty, grotty
5392 @subsection Invoking @code{grotty}
5393 @cindex invoking @code{grotty}
5394 @cindex @code{grotty}, invoking
5397 @node grops, grodvi, grotty, Output Devices
5398 @section @code{grops}
5399 @cindex @code{grops}
5403 * Embedding PostScript::
5406 @node Invoking grops, Embedding PostScript, grops, grops
5407 @subsection Invoking @code{grops}
5408 @cindex invoking @code{grops}
5409 @cindex @code{grops}, invoking
5411 @node Embedding PostScript, , Invoking grops, grops
5412 @subsection Embedding PostScript
5413 @cindex embedding postscript
5414 @cindex postscript, embedding
5417 @node grodvi, grolj4, grops, Output Devices
5418 @section @code{grodvi}
5419 @cindex @code{grodvi}
5425 @node Invoking grodvi, , grodvi, grodvi
5426 @subsection Invoking @code{grodvi}
5427 @cindex invoking @code{grodvi}
5428 @cindex @code{grodvi}, invoking
5431 @node grolj4, grohtml, grodvi, Output Devices
5432 @section @code{grolj4}
5433 @cindex @code{grolj4}
5439 @node Invoking grolj4, , grolj4, grolj4
5440 @subsection Invoking @code{grolj4}
5441 @cindex invoking @code{grolj4}
5442 @cindex @code{grolj4}, invoking
5445 @node grohtml, gxditview, grolj4, Output Devices
5446 @section @code{grohtml}
5447 @cindex @code{grohtml}
5450 * Invoking grohtml::
5453 @node Invoking grohtml, , grohtml, grohtml
5454 @subsection Invoking @code{grohtml}
5455 @cindex invoking @code{grohtml}
5456 @cindex @code{grohtml}, invoking
5459 @node gxditview, , grohtml, Output Devices
5460 @section @code{gxditview}
5461 @cindex @code{gxditview}
5464 * Invoking gxditview::
5467 @node Invoking gxditview, , gxditview, gxditview
5468 @subsection Invoking @code{gxditview}
5469 @cindex invoking @code{gxditview}
5470 @cindex @code{gxditview}, invoking
5474 @node File formats, Installation, Output Devices, Top
5475 @chapter File formats
5476 @cindex file formats
5477 @cindex formats, file
5485 @node gtroff Output, Font Files, File formats, File formats
5486 @section @code{gtroff} Output
5487 @cindex @code{gtroff} output
5488 @cindex output, @code{gtroff}
5491 This section describes the format output by GNU troff. The output
5492 format used by GNU troff is very similar to that used by @sc{Unix}
5493 device-independent troff.
5495 The output format is text based, as opposed to a binary format (like
5497 The output format is 8 bit clean, thus single characters can have the
5498 eighth bit set, as can the names of fonts and special characters.
5500 The output format consists of single command characters with attached
5501 parameters which are separated from subsequent text by whitespace, or
5504 The names of characters and fonts an be of arbitrary length; drivers
5505 should not assume that they will be only two characters long (as
5506 device-independent troff did).
5508 When a character is to be printed, that character will always be in the
5510 Unlike device-independent troff, it is not necessary for
5511 drivers to search special fonts to find a character.
5520 @item @var{nn}@var{c}
5522 @var{xxx} is any sequence of characters terminated by a space or a
5523 newline; the first character should be printed at the current
5524 position, the the current horizontal position should be increased by
5525 the width of the first character, and so on for each character.
5526 The width of the character is that given in the font file,
5527 appropriately scaled for the current point size,
5528 and rounded so that it is a multiple of the horizontal resolution.
5529 Special characters cannot be printed using this command.
5531 This command is only allowed if the @samp{tcommand} line is present
5532 in the @file{DESC} file.
5533 @item u@var{n} @var{xxx}
5535 This is same as the @code{t} command except that after printing each
5536 character, the current horizontal position is increased by the sum of
5537 the width of that character and @code{n}.
5539 This command is only allowed if the @samp{tcommand} line is present
5540 in the @file{DESC} file.
5541 @item n@var{a}@var{b}
5544 The argument to the s command is in scaled points (units of points/n,
5545 where n is the argument to the sizescale command in the DESC file.)
5549 @item D@var{c} @var{x}@dots{}\n
5552 @subsection Device Control
5554 The @code{x} command is normally followed by a letter or word
5555 indicating the function to perform, followed by white space separated
5558 The first argument can be abreviated to the first letter.
5563 @item x res @var{n} @var{h} @var{v}
5565 The argument to the x Height command is also in scaled points.
5568 The first three output commands are guaranteed to be:
5576 For example, the input @samp{crunchy \fH\s+2frog\s0\fP!?} will produce:
5579 ... sample output here ...
5582 @subsection Drawing Functions
5584 The D drawing command has been extended. These extensions will only be
5585 used by GNU pic if the -x option is given.
5590 Set the shade of gray to be used for filling solid objects to n; n must
5591 be an integer between 0 and 1000, where 0 corresponds solid white and
5592 1000 to solid black, and values in between correspond to intermediate
5593 shades of gray. This applies only to solid circles, solid ellipses and
5594 solid polygons. By default, a level of 1000 will be used. Whatever
5595 color a solid object has, it should completely obscure everything
5596 beneath it. A value greater than 1000 or less than 0 can also be used:
5597 this means fill with the shade of gray that is currently being used for
5598 lines and text. Normally this will be black, but some drivers may
5599 provide a way of changing this.
5601 Draw a solid circle with a diameter of d with the leftmost point at the
5604 Draw a solid ellipse with a horizontal diameter of dx and a vertical
5605 diameter of dy with the leftmost point at the current position.
5606 @item Dp $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub
5608 Draw a polygon with, for $i = 1 ,..., n+1$, the i-th vertex at the
5609 current position $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. At
5610 the moment, GNU pic only uses this command to generate triangles and
5612 @item DP $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub
5614 Like Dp but draw a solid rather than outlined polygon.
5616 Set the current line thickness to n machine units. Traditionally @sc{Unix}
5617 troff drivers use a line thickness proportional to the current point
5618 size; drivers should continue to do this if no Dt command has been
5619 given, or if a Dt command has been given with a negative value of n. A
5620 zero value of n selects the smallest available line thickness.
5623 A difficulty arises in how the current position should be changed after
5624 the execution of these commands. This is not of great importance since
5625 the code generated by GNU pic does not depend on this. Given a drawing
5628 \D'c $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$'
5630 where c is not one of c, e, l, a or ~, @sc{Unix} troff will treat each of the
5631 $x sub i$ as a horizontal quantity, and each of the $y sub i$ as a
5632 vertical quantity and will assume that the width of the drawn object is
5633 $sum from i=1 to n x sub i$, and that the height is $sum from i=1 to n y
5634 sub i$. (The assumption about the height can be seen by examining the
5635 st and sb registers after using such a D command in a \w escape
5636 sequence.) This rule also holds for all the original drawing commands
5637 with the exception of De. For the sake of compatibility GNU troff also
5638 follows this rule, even though it produces an ugly result in the case of
5639 the Df, Dt, and, to a lesser extent, DE commands. Thus after executing
5640 a D command of the form
5642 Dc $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\n
5644 the current position should be increased by $( sum from i=1 to n x sub i
5645 , sum from i=1 to n y sub i )$.
5647 @subsection Line Continuation
5649 There is a continuation convention which permits the argument to the x X
5650 command to contain newlines: when outputting the argument to the x X
5651 command, GNU troff will follow each newline in the argument with a +
5652 character (as usual, it will terminate the entire argument with a
5653 newline); thus if the line after the line containing the x X command
5654 starts with +, then the newline ending the line containing the x X
5655 command should be treated as part of the argument to the x X command,
5656 the + should be ignored, and the part of the line following the + should
5657 be treated like the part of the line following the x X command.
5660 @node Font Files, , gtroff Output, File formats
5665 The groff font format is roughly a superset of the ditroff font
5666 format. Unlike the ditroff font format, there is no associated binary
5667 format. The font files for device name are stored in a directory
5668 @file{dev@var{name}}. There are two types of file: a device
5669 description file called @file{DESC} and for each font @samp{F} a font
5670 file called @file{F}. These are text files; there is no associated
5673 @subsection @file{DESC} file format
5676 The @file{DESC} file can contain the following types of line:
5680 There are @var{n} machine units per inch.
5682 The horizontal resolution is @var{n} machine units.
5684 The vertical resolution is @var{n} machine units.
5685 @item sizescale @var{n}
5686 The scale factor for pointsizes. By default this has a value of 1. One
5687 scaled point is equal to one point/@var{n}. The arguments to the
5688 @code{unitwidth} and @code{sizes} commands are given in scaled points.
5689 @xref{Fractional Type Sizes}, for more information.
5690 @item unitwidth @var{n}
5691 Quantities in the font files are given in machine units for fonts whose
5692 point size is @var{n} scaled points.
5694 This means that the postprocessor can handle the @code{t} and
5695 @code{u} output commands.
5696 @item sizes @var{s1} @var{s2}@dots{}@var{sn} 0
5697 This means that the device has fonts at @var{s1}, @var{s2},
5698 @dots{}@var{sn} scaled points. The list of sizes must be terminated
5699 by a 0. Each @var{si} can also be a range of
5700 sizes @var{m}-@var{n}. The list can extend over more than one line.
5701 @item styles @var{S1 S2@dots{}Sm}
5702 The first @var{m} font positions will be associated with styles
5703 @var{S1}@dots{}@var{Sm}.
5704 @item fonts @var{n} @var{F1 F2 F3@dots{}Fn}
5705 Fonts @var{F1@dots{}Fn} will be mounted in the font positions
5706 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m}
5707 is the number of styles. This command may extend over more than one
5708 line. A font name of 0 will cause no font to be mounted on the
5709 corresponding font position.
5710 @item family @var{fam}
5711 The default font family is @var{fam}.
5713 This line and everything following in the file are ignored. It is
5714 allowed for the sake of backwards compatibility.
5717 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
5718 are compulsory. Other commands are ignored by troff but may be used
5719 by postprocessors to store arbitrary information about the device in
5720 the @file{DESC} file.
5723 @subsection Font file format
5725 A font file has two sections. The first section is a sequence of lines
5726 each containing a sequence of blank delimited words; the first word in
5727 the line is a key, and subsequent words give a value for that key.
5731 The name of the font is @var{F}.
5732 @item spacewidth @var{n}
5733 The normal width of a space is @var{n}.
5735 The characters of the font have a slant of @var{n} degrees.
5736 (Positive means forward.)
5737 @item ligatures @var{lig1} @var{lig2}@dots{}@var{lign} [0]
5738 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
5739 possible ligatures are ff, fi, fl and ffl. For backwards
5740 compatibiliy, the list of ligatures may be terminated with a 0. The
5741 list of ligatures may not extend over more than one line.
5743 The font is special; this means that when a character is requested that
5744 is not present in the current font, it will be searched for in any
5745 special fonts that are mounted.
5748 Other commands are ignored by troff but may be used by postprocessors to
5749 store arbitrary information about the font in the font file.
5751 The first section can contain comments which start with the # character
5752 and extend to the end of a line.
5754 The second section contains one or two subsections. It must contain a
5755 @code{charset} subsection and it may also contain a @code{kernpairs}
5756 subsection. These subsections can appear in any order. Each
5757 subsection starts with a word on a line by itself.
5759 The word @code{charset} starts the @code{charset} subsection. The
5760 @code{charset} line is followed by a sequence of lines. Each line
5761 gives information for one character. A line comprises a number of
5762 fields separated by blanks or tabs. The format is
5765 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
5768 @var{name} identifies the character: if @var{name} is a single
5769 character @var{c} then it corresponds to the groff input character
5770 @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is a
5771 single character, then it corresponds to the groff input character
5772 @samp{\@var{c}}; otherwise it corresponds to the groff input character
5773 @samp{\[@var{name}]} (if it is exactly two characters @var{xx} it can
5774 be entered as @samp{\(@var{xx}}.) Groff supports eight bit characters;
5775 however some utilities has difficulties with eight bit characters.
5776 For this reason, there is a convention that the @var{name}
5777 @samp{char@var{n}} is equivalent to the single character whose code is
5778 @var{n}. For example, @samp{char163} would be equivalent to the
5779 character with @var{code} 163 which is the pounds sterling sign in ISO
5780 Latin-1 character set. The name @samp{---} is special and indicates
5781 that the character is unnamed; such characters can only be used by
5782 means of the @code{\N} escape sequence in troff.
5784 The @var{type} field gives the character type:
5788 means the character has an descender, for example, p;
5790 means the character has an ascender, for example, b;
5792 means the character has both an ascender and a descender, for example,
5796 The @var{code} field gives the code which the postprocessor uses to
5797 print the character. The character can also be input to groff using
5798 this code by means of the @code{\N} escape sequence. The code can be any
5799 integer. If it starts with a 0 it will be interpreted as octal; if it
5800 starts with 0x or 0X it will be intepreted as hexdecimal.
5802 Anything on the line after the @var{code} field will be ignored.
5804 The @var{metrics} field has the form:
5807 @var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]}
5810 There must not be any spaces between these subfields. Missing
5811 subfields are assumed to be 0. The subfields are all decimal
5812 integers. Since there is no associated binary format, these values
5813 are not required to fit into a variable of type @samp{char} as they
5814 are in ditroff. The @var{width} subfields gives the width of the
5815 character. The @var{height} subfield gives the height of the
5816 character (upwards is positive); if a character does not extend above
5817 the baseline, it should be given a zero height, rather than a negative
5818 height. The @var{depth} subfield gives the depth of the character,
5819 that is, the distance below the lowest point below the baseline to
5820 which the character extends (downwards is positive); if a character
5821 does not extend below above the baseline, it should be given a zero
5822 depth, rather than a negative depth. The @var{italic_correction}
5823 subfield gives the amount of space that should be added after the
5824 character when it is immediately to be followed by a character from a
5825 roman font. The @var{left_italic_correction} subfield gives the
5826 amount of space that should be added before the character when it is
5827 immediately to be preceded by a character from a roman font. The
5828 @var{subscript_correction} gives the amount of space that should be
5829 added after a character before adding a subscript. This should be less
5830 than the italic correction.
5832 A line in the @code{charset} section can also have the format
5838 This indicates that @var{name} is just another name for the character
5839 mentioned in the preceding line.
5841 The word @code{kernpairs} starts the kernpairs section. This contains a
5842 sequence of lines of the form:
5848 This means that when character @var{c1} appears next to character
5849 @var{c2} the space between them should be increased by @var{n}. Most
5850 entries in kernpairs section will have a negative value for @var{n}.
5854 @node Installation, Request Index, File formats, Top
5855 @chapter Installation
5856 @cindex installation
5860 @node Request Index, Register Index, Installation, Top
5861 @chapter Request Index
5867 @node Register Index, String Index, Request Index, Top
5868 @chapter Register Index
5873 @node String Index, Macro Index, Register Index, Top
5874 @chapter String Index
5878 @node Macro Index, Program Index, String Index, Top
5879 @chapter Macro Index
5883 @node Program Index, Concept Index, Macro Index, Top
5884 @chapter Program Index
5890 @node Concept Index, , Program Index, Top
5891 @chapter Concept Index