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 @dircategory Miscellaneous
12 * Groff: (groff). The GNU troff document formatting system.
25 This Info file documents GNU troff version 1.16.
27 Published by the Free Software Foundation
28 59 Temple Place, Suite 330
29 Boston, MA 02111-1307 USA
31 Copyright (C) 1994-2000 Free Software Foundation, Inc.
33 Permission is granted to make and distribute verbatim copies of this
34 manual provided the copyright notice and this permission notice are
35 preserved on all copies.
38 Permission is granted to process this file through TeX and print the
39 results, provided the printed document carries copying permission notice
40 identical to this one except for the removal of this paragraph (this
41 paragraph not being relevant to the printed manual).
44 Permission is granted to copy and distribute modified versions of this
45 manual under the conditions for verbatim copying, provided that the
46 entire resulting derived work is distributed under the terms of a
47 permission notice identical to this one.
49 Permission is granted to copy and distribute translations of this manual
50 into another language, under the above conditions for modified versions,
51 except that this permission notice may be stated in a translation
52 approved by the Foundation.
54 Permission is granted to copy and distribute modified versions of this
55 manual under the conditions for verbatim copying, provided also that the
56 section entitled ``GNU General Public License'' is included exactly as
57 in the original, and provided that the entire resulting derived work is
58 distributed under the terms of a permission notice identical to this
61 Permission is granted to copy and distribute translations of this manual
62 into another language, under the above conditions for modified versions,
63 except that the section entitled ``GNU General Public License'' may be
64 included in a translation approved by the Free Software Foundation
65 instead of in the original English.
71 @subtitle The GNU implementation of @code{groff}
72 @subtitle Edition 1.16
74 @author by Trent A.@w{ }Fisher
75 @author and the maintainer of groff
77 @c Include the Distribution inside the titlepage environment so
78 @c that headings are turned off. Headings on and off do not work.
81 @vskip 0pt plus 1filll
82 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
84 Version 1.16 of @code{groff}, @*
87 Published by the Free Software Foundation @*
88 59 Temple Place, Suite 330 @*
89 Boston, MA 02111-1307 USA
92 Permission is granted to make and distribute verbatim copies of this
93 manual provided the copyright notice and this permission notice are
94 preserved on all copies.
96 Permission is granted to copy and distribute modified versions of this
97 manual under the conditions for verbatim copying, provided also that the
98 section entitled ``GNU General Public License'' is included exactly as
99 in the original, and provided that the entire resulting derived work is
100 distributed under the terms of a permission notice identical to this
103 Permission is granted to copy and distribute translations of this manual
104 into another language, under the above conditions for modified versions,
105 except that the section entitled ``GNU General Public License'' may be
106 included in a translation approved by the Free Software Foundation
107 instead of in the original English.
109 Cover art by Etienne Suvasa.
115 @node Top, Copying, (dir), (dir)
118 This Info file documents groff version 1.16, the GNU implementation of
119 the troff typesetting system.
121 This is an in-progress document; contributions, comments, or
122 contributions are welcome. Send them to bug-groff@@gnu.org.
129 * Tutorial for Macro Users::
131 * Programming Tutorial::
146 @node Copying, Introduction, Top, Top
148 @unnumbered GNU GENERAL PUBLIC LICENSE
149 @center Version 2, June 1991
152 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
153 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
155 Everyone is permitted to copy and distribute verbatim copies of this
156 license document, but changing it is not allowed.
159 @unnumberedsec Preamble
161 The licenses for most software are designed to take away your freedom to
162 share and change it. By contrast, the GNU General Public License is
163 intended to guarantee your freedom to share and change free software --
164 to make sure the software is free for all its users. This General
165 Public License applies to most of the Free Software Foundation's
166 software and to any other program whose authors commit to using it.
167 (Some other Free Software Foundation software is covered by the GNU
168 Library General Public License instead.) You can apply it to your
171 When we speak of free software, we are referring to freedom, not price.
172 Our General Public Licenses are designed to make sure that you have the
173 freedom to distribute copies of free software (and charge for this
174 service if you wish), that you receive source code or can get it if you
175 want it, that you can change the software or use pieces of it in new
176 free programs; and that you know you can do these things.
178 To protect your rights, we need to make restrictions that forbid anyone
179 to deny you these rights or to ask you to surrender the rights. These
180 restrictions translate to certain responsibilities for you if you
181 distribute copies of the software, or if you modify it.
183 For example, if you distribute copies of such a program, whether gratis
184 or for a fee, you must give the recipients all the rights that you have.
185 You must make sure that they, too, receive or can get the source code.
186 And you must show them these terms so they know their rights.
188 We protect your rights with two steps: (1)@w{ }copyright the software,
189 and (2)@w{ }offer you this license which gives you legal permission to
190 copy, distribute and/or modify the software.
192 Also, for each author's protection and ours, we want to make certain
193 that everyone understands that there is no warranty for this free
194 software. If the software is modified by someone else and passed on, we
195 want its recipients to know that what they have is not the original, so
196 that any problems introduced by others will not reflect on the original
197 authors' reputations.
199 Finally, any free program is threatened constantly by software patents.
200 We wish to avoid the danger that redistributors of a free program will
201 individually obtain patent licenses, in effect making the program
202 proprietary. To prevent this, we have made it clear that any patent
203 must be licensed for everyone's free use or not licensed at all.
205 The precise terms and conditions for copying, distribution and
209 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
212 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
217 This License applies to any program or other work which contains a
218 notice placed by the copyright holder saying it may be distributed under
219 the terms of this General Public License. The ``Program'', below,
220 refers to any such program or work, and a ``work based on the Program''
221 means either the Program or any derivative work under copyright law:
222 that is to say, a work containing the Program or a portion of it, either
223 verbatim or with modifications and/or translated into another language.
224 (Hereinafter, translation is included without limitation in the term
225 ``modification''.) Each licensee is addressed as ``you''.
227 Activities other than copying, distribution and modification are not
228 covered by this License; they are outside its scope. The act of running
229 the Program is not restricted, and the output from the Program is
230 covered only if its contents constitute a work based on the Program
231 (independent of having been made by running the Program). Whether that
232 is true depends on what the Program does.
235 You may copy and distribute verbatim copies of the Program's source code
236 as you receive it, in any medium, provided that you conspicuously and
237 appropriately publish on each copy an appropriate copyright notice and
238 disclaimer of warranty; keep intact all the notices that refer to this
239 License and to the absence of any warranty; and give any other
240 recipients of the Program a copy of this License along with the Program.
242 You may charge a fee for the physical act of transferring a copy, and
243 you may at your option offer warranty protection in exchange for a fee.
246 You may modify your copy or copies of the Program or any portion of it,
247 thus forming a work based on the Program, and copy and distribute such
248 modifications or work under the terms of Section@w{ }1 above, provided
249 that you also meet all of these conditions:
253 You must cause the modified files to carry prominent notices stating
254 that you changed the files and the date of any change.
257 You must cause any work that you distribute or publish, that in whole or
258 in part contains or is derived from the Program or any part thereof, to
259 be licensed as a whole at no charge to all third parties under the terms
263 If the modified program normally reads commands interactively when run,
264 you must cause it, when started running for such interactive use in the
265 most ordinary way, to print or display an announcement including an
266 appropriate copyright notice and a notice that there is no warranty (or
267 else, saying that you provide a warranty) and that users may
268 redistribute the program under these conditions, and telling the user
269 how to view a copy of this License. (Exception: if the Program itself
270 is interactive but does not normally print such an announcement, your
271 work based on the Program is not required to print an announcement.)
274 These requirements apply to the modified work as a whole. If
275 identifiable sections of that work are not derived from the Program, and
276 can be reasonably considered independent and separate works in
277 themselves, then this License, and its terms, do not apply to those
278 sections when you distribute them as separate works. But when you
279 distribute the same sections as part of a whole which is a work based on
280 the Program, the distribution of the whole must be on the terms of this
281 License, whose permissions for other licensees extend to the entire
282 whole, and thus to each and every part regardless of who wrote it.
284 Thus, it is not the intent of this section to claim rights or contest
285 your rights to work written entirely by you; rather, the intent is to
286 exercise the right to control the distribution of derivative or
287 collective works based on the Program.
289 In addition, mere aggregation of another work not based on the Program
290 with the Program (or with a work based on the Program) on a volume of a
291 storage or distribution medium does not bring the other work under the
292 scope of this License.
295 You may copy and distribute the Program (or a work based on it, under
296 Section@w{ }2) in object code or executable form under the terms of
297 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
302 Accompany it with the complete corresponding machine-readable source
303 code, which must be distributed under the terms of Sections@w{ }1 and@w{
304 }2 above on a medium customarily used for software interchange; or,
307 Accompany it with a written offer, valid for at least three years, to
308 give any third party, for a charge no more than your cost of physically
309 performing source distribution, a complete machine-readable copy of the
310 corresponding source code, to be distributed under the terms of
311 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
315 Accompany it with the information you received as to the offer to
316 distribute corresponding source code. (This alternative is allowed only
317 for noncommercial distribution and only if you received the program in
318 object code or executable form with such an offer, in accord with
319 Subsection@w{ }b above.)
322 The source code for a work means the preferred form of the work for
323 making modifications to it. For an executable work, complete source
324 code means all the source code for all modules it contains, plus any
325 associated interface definition files, plus the scripts used to control
326 compilation and installation of the executable. However, as a special
327 exception, the source code distributed need not include anything that is
328 normally distributed (in either source or binary form) with the major
329 components (compiler, kernel, and so on) of the operating system on
330 which the executable runs, unless that component itself accompanies the
333 If distribution of executable or object code is made by offering access
334 to copy from a designated place, then offering equivalent access to copy
335 the source code from the same place counts as distribution of the source
336 code, even though third parties are not compelled to copy the source
337 along with the object code.
340 You may not copy, modify, sublicense, or distribute the Program except
341 as expressly provided under this License. Any attempt otherwise to
342 copy, modify, sublicense or distribute the Program is void, and will
343 automatically terminate your rights under this License. However,
344 parties who have received copies, or rights, from you under this License
345 will not have their licenses terminated so long as such parties remain
349 You are not required to accept this License, since you have not signed
350 it. However, nothing else grants you permission to modify or distribute
351 the Program or its derivative works. These actions are prohibited by
352 law if you do not accept this License. Therefore, by modifying or
353 distributing the Program (or any work based on the Program), you
354 indicate your acceptance of this License to do so, and all its terms and
355 conditions for copying, distributing or modifying the Program or works
359 Each time you redistribute the Program (or any work based on the
360 Program), the recipient automatically receives a license from the
361 original licensor to copy, distribute or modify the Program subject to
362 these terms and conditions. You may not impose any further restrictions
363 on the recipients' exercise of the rights granted herein. You are not
364 responsible for enforcing compliance by third parties to this License.
367 If, as a consequence of a court judgment or allegation of patent
368 infringement or for any other reason (not limited to patent issues),
369 conditions are imposed on you (whether by court order, agreement or
370 otherwise) that contradict the conditions of this License, they do not
371 excuse you from the conditions of this License. If you cannot
372 distribute so as to satisfy simultaneously your obligations under this
373 License and any other pertinent obligations, then as a consequence you
374 may not distribute the Program at all. For example, if a patent license
375 would not permit royalty-free redistribution of the Program by all those
376 who receive copies directly or indirectly through you, then the only way
377 you could satisfy both it and this License would be to refrain entirely
378 from distribution of the Program.
380 If any portion of this section is held invalid or unenforceable under
381 any particular circumstance, the balance of the section is intended to
382 apply and the section as a whole is intended to apply in other
385 It is not the purpose of this section to induce you to infringe any
386 patents or other property right claims or to contest validity of any
387 such claims; this section has the sole purpose of protecting the
388 integrity of the free software distribution system, which is implemented
389 by public license practices. Many people have made generous
390 contributions to the wide range of software distributed through that
391 system in reliance on consistent application of that system; it is up to
392 the author/donor to decide if he or she is willing to distribute
393 software through any other system and a licensee cannot impose that
396 This section is intended to make thoroughly clear what is believed to be
397 a consequence of the rest of this License.
400 If the distribution and/or use of the Program is restricted in certain
401 countries either by patents or by copyrighted interfaces, the original
402 copyright holder who places the Program under this License may add an
403 explicit geographical distribution limitation excluding those countries,
404 so that distribution is permitted only in or among countries not thus
405 excluded. In such case, this License incorporates the limitation as if
406 written in the body of this License.
409 The Free Software Foundation may publish revised and/or new versions of
410 the General Public License from time to time. Such new versions will be
411 similar in spirit to the present version, but may differ in detail to
412 address new problems or concerns.
414 Each version is given a distinguishing version number. If the Program
415 specifies a version number of this License which applies to it and ``any
416 later version'', you have the option of following the terms and
417 conditions either of that version or of any later version published by
418 the Free Software Foundation. If the Program does not specify a version
419 number of this License, you may choose any version ever published by the
420 Free Software Foundation.
423 If you wish to incorporate parts of the Program into other free programs
424 whose distribution conditions are different, write to the author to ask
425 for permission. For software which is copyrighted by the Free Software
426 Foundation, write to the Free Software Foundation; we sometimes make
427 exceptions for this. Our decision will be guided by the two goals of
428 preserving the free status of all derivatives of our free software and
429 of promoting the sharing and reuse of software generally.
439 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
440 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
441 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
442 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
443 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
444 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
445 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
446 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
447 NECESSARY SERVICING, REPAIR OR CORRECTION.
450 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
451 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
452 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
453 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
454 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
455 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
456 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
457 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
458 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
462 @heading END OF TERMS AND CONDITIONS
465 @center END OF TERMS AND CONDITIONS
470 @unnumberedsec How to Apply These Terms to Your New Programs
472 If you develop a new program, and you want it to be of the greatest
473 possible use to the public, the best way to achieve this is to make it
474 free software which everyone can redistribute and change under these
477 To do so, attach the following notices to the program. It is safest to
478 attach them to the start of each source file to most effectively convey
479 the exclusion of warranty; and each file should have at least the
480 ``copyright'' line and a pointer to where the full notice is found.
483 @var{one line to give the program's name and an idea of what it does.}
484 Copyright (C) 19@var{yy} @var{name of author}
486 This program is free software; you can redistribute it and/or modify
487 it under the terms of the GNU General Public License as published by
488 the Free Software Foundation; either version 2 of the License, or (at
489 your option) any later version.
491 This program is distributed in the hope that it will be useful, but
492 WITHOUT ANY WARRANTY; without even the implied warranty of
493 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
494 General Public License for more details.
496 You should have received a copy of the GNU General Public License
497 along with this program; if not, write to the Free Software
498 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
501 Also add information on how to contact you by electronic and paper mail.
503 If the program is interactive, make it output a short notice like this
504 when it starts in an interactive mode:
507 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
508 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
509 `show w'. This is free software, and you are welcome to redistribute
510 it under certain conditions; type `show c' for details.
513 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
514 show the appropriate parts of the General Public License. Of course,
515 the commands you use may be called something other than @samp{show@w{
516 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu
517 items---whatever suits your program.
519 You should also get your employer (if you work as a programmer) or your
520 school, if any, to sign a ``copyright disclaimer'' for the program, if
521 necessary. Here is a sample; alter the names:
525 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
526 `Gnomovision' (which makes passes at compilers) written by James
529 @var{signature of Ty Coon}, 1 April 1989 Ty Coon, President of Vice
533 This General Public License does not permit incorporating your program
534 into proprietary programs. If your program is a subroutine library, you
535 may consider it more useful to permit linking proprietary applications
536 with the library. If this is what you want to do, use the GNU Library
537 General Public License instead of this License.
541 @node Introduction, Invoking groff, Copying, Top
542 @chapter Introduction
545 GNU @code{troff} (or @code{groff}) is a system for typesetting
546 documents. @code{troff} is very flexible and has been in existence (and
547 use) for about 3@w{ }decades. It is quite widespread and firmly
548 entrenched in the @sc{Unix} community.
555 * groff Capabilities::
556 * Macro Package Intro::
557 * Preprocessor Intro::
558 * Output device intro::
562 @node What Is groff?, History, Introduction, Introduction
563 @section What Is @code{groff}?
564 @cindex what is @code{groff}?
565 @cindex @code{groff} -- what is it?
568 @code{groff} is of an older generation of document preparation systems,
569 which operate more like compilers than the more recent interactive
570 WYSIWYG@footnote{What You See Is What You Get} systems. @code{groff}
571 and its contemporary counterpart, @TeX{}, both work using a @dfn{batch}
572 paradigm: The input (or @dfn{source}) files are normal text files with
573 embedded formatting commands. These files can then be processed by
574 @code{groff} to produce a typeset document on a variety of devices.
576 Likewise, @code{groff} should not be confused with a @dfn{word
577 processor}, since that term connotes an integrated system which includes
578 an editor and a text formatter. Also, many word processors follow the
579 WYSIWYG paradigm which was discussed earlier.
581 Although WYSIWYG systems may be easier to use, they have a number of
582 disadvantages compared to @code{troff}:
586 They must be used on a bitmapped display to do any operations on your
589 Most of the WYSIWYG systems are either non-free or are not very
592 @code{troff} is firmly entrenched in all @sc{Unix} systems.
594 It is difficult to have a wide range of capabilities available within
595 the confines of a GUI/window system.
597 It is more difficult to make global changes to a document.
601 ``GUIs normally make it simple to accomplish simple actions and
602 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
603 @code{comp.unix.wizards})
608 @node History, groff Capabilities, What Is groff?, Introduction
612 @code{troff} can trace its origins back to a formatting program called
613 @code{runoff} which ran on MIT's CTSS system. This name came from the
614 common phrase of the time ``I'll run off a document.''
616 The first version of @sc{Unix} was developed on a PDP-7 which was
617 sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11
618 for further work on the operating system. In order to justify the cost
619 for this system, they proposed that they would implement a document
620 formatting system for the AT&T patents division. This first formatting
621 program was a reimplementation of @code{runoff}. In accordance with
622 @sc{Unix}'s penchant for abreviations, it was named @code{roff} (an
623 abreviation of @code{runoff}).
625 When they needed a more flexible language, a new version of @code{roff}
626 called @code{nroff} (Newer @code{roff}) was written. It had a much more
627 complicated syntax, but provided the basis for all future versions.
628 When they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{
629 }Ossanna wrote a version of @code{nroff} which would drive it. It was
630 dubbed @code{troff} for typesetter @code{roff}, although many people
631 have speculated that it actually means Times @code{roff} because of
632 @code{troff}'s use of the Times font family by default. As such, the
633 name @code{troff} is pronounced t-roff rather than trough.
635 With @code{troff} came @code{nroff} (they were actually the same program
636 except for some @samp{#ifdefs}), which was for producing output for line
637 printers and ascii terminals. It understood everything @code{troff}
638 did, and ignored the commands which were not aplicable (i.e.@: font
641 Since there are several things which cannot be done easily in
642 @code{troff}, work on several preprocessors began. These programs would
643 transform certain parts of a document into @code{troff}, which made a
644 very natural use of pipes in @sc{Unix}.
646 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
647 specified in a much simpler and more intuitive manner. @code{tbl} is a
648 preprocessor for formatting tables. The @code{refer} preprocessor (and
649 the similar program, @code{bib}) processes citations in a document
650 according to a bibliographic database.
652 Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
653 language and produced output specifically for the CAT phototypesetter.
654 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
655 code and still dependent on the CAT. As the CAT became less common, and
656 was no longer supported by the manufacturer, the need to make it support
657 other devices became a priority. However, before this could be done, he
658 was killed in an auto accident.
661 So, Brian Kernighan took on the task of rewriting @code{troff}. The
662 newly rewritten version produced a device independent code which was
663 very easy for postprocessors to read and translate to the appropriate
664 printer codes. Also, this new version of @code{troff} (called
665 @code{ditroff}) had several extentions, which included drawing
668 Due to the additional abilities of the new version of @code{troff},
669 several new preprocessors appeared. The @code{pic} preprocessor
670 provides a wide range of drawing functions. Likewise the @code{ideal}
671 preprocessor did the same, although via a much different paradigm. The
672 @code{grap} preprocessor took specifications for graphs, but, unlike
673 other preprocessors, produced @code{pic} code.
675 James Clark began work on a GNU implementation of @code{ditroff} in
676 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
677 June@w{ }1990. @code{groff} included
681 A replacement for @code{ditroff} with many extentions.
683 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
685 Postprocessors for ascii devices, PostScript, @TeX{} DVI, and X@w{
686 }windows. GNU @code{troff} also eliminated the need for a separate
687 @code{nroff} program with a postprocessor which would produce ascii
690 A version of the @code{-me} macros and an implementation of the
694 Also, a front-end was included which could construct the, sometimes
695 painfully long, pipelines required for all the post- and preprocessors.
697 Development of GNU @code{troff} progressed rapidly, and saw the
698 additions of a replacement for @code{refer}, an implementation of the
699 @code{-ms} and @code{-mm} macros, and a program to deduce how to format
700 a document (@code{grog}).
702 It was declared a stable (i.e.@: non beta) package with the release of
703 version@w{ }1.04 around November@w{ }1991.
705 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
706 an orphan for a few years). As a result, new features and programs like
707 @code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an
708 output device to produce HTML output, have been added.
712 @node groff Capabilities, Macro Package Intro, History, Introduction
713 @section @code{groff} Capabilities
714 @cindex @code{groff} capabilities
715 @cindex capabilities of @code{groff}
717 So what exactly is @code{groff} capable of doing? @code{groff} provides
718 a wide range of low-level text formatting operations. Using these, you
719 can perform a wide range of formatting tasks, such as footnotes, table
720 of contents, multiple columns, etc.
724 Text filling, adjusting, and centering
730 Font and character size control
732 Vertical spacing (i.e.@: double spacing)
734 Line length and indenting
736 Macros, strings, diversions, and traps
740 Tabs, leaders, and fields
742 Input and output conventions and character translation
744 Overstrike, bracket, line drawing, and zero-width functions
746 Local horizontal and vertical motions and the width function
750 Output line numbering
752 Conditional acceptance of input
754 Environment switching
756 Insertions from the standard input
758 Input/output file switching
760 Output and error messages
764 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
765 @section Macro Packages
766 @cindex macro packages
768 Since @code{groff} provides such low level facilities, it can be quite
769 difficult to use by itself. However, @code{groff} provides a
770 @dfn{macro} facility which allows you to specify how certain routine
771 operations (e.g.@w{ }starting paragraphs, printing headers and footers,
772 etc.)@: should be done. These macros can be collected together into a
773 @dfn{macro package}. There are a number of macro packages available;
774 the most common (and the ones described in this manual) are @code{-man},
775 @code{-mdoc}, @code{-me}, @code{-ms}, and @code{-mm}.
778 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
779 @section Preprocessors
780 @cindex preprocessors
782 Although @code{groff} provides most functions needed to format a
783 document, some operations would be unwieldy (i.e.@: drawing pictures).
784 Therefore, programs called preprocessors were written which understand
785 their own language and produce the necessary groff operations. These
786 preprocessors are able to differentiate their own input from the rest of
787 the document via markers.
789 To use a preprocessor, @sc{Unix} pipes are used to feed the output from
790 the preprocessor into @code{groff}. Any number of preprocessors may be
791 used on a given document; in this case, the preprocessors are linked
792 together into one pipeline. However, in @code{groff}, the user does not
793 need to construct the pipe, but only tell @code{groff} what
794 preprocessors to use.
796 @code{groff} currently has preprocessors for producing tables
797 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
798 (@code{pic} and @code{grn}), and for processing bibliographies
799 (@code{refer}). An associated program which is useful when dealing with
800 preprocessors is @code{soelim}.
802 There are other preprocessors in existence, but there are,
803 unfortunately, no free implementations available. They are for drawing
804 pictures (@code{ideal}), for drawing graphs
805 (@code{grap}), and chemical structures (@code{chem}).
807 A free implementation of @code{grap}, a preprocessor for drawing graphs,
808 can be obtained as an extra package.
810 @node Output device intro, Credits, Preprocessor Intro, Introduction
811 @section Output Devices
812 @cindex postprocessors
813 @cindex output devices
814 @cindex devices for output
816 @code{groff} actually produces device independent code which may be fed
817 into a postprocessor which will produce output for a particular device.
818 Currently, @code{groff} has postprocessors for PostScript, ascii
819 terminals, X@w{ }Windows (for previewing), @TeX{} DVI format, and HTML.
822 @node Credits, , Output device intro, Introduction
827 Large portions of this manual were taken from existing documents, most
828 notably, the manual pages for the @code{groff} package by James Clark,
829 and Eric Allman's papers on the @code{-me} macro package.
833 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
834 @chapter Invoking @code{groff}
835 @cindex invoking @code{groff}
836 @cindex @code{groff} invocation
841 This section focuses on how to invoke the @code{groff} front end. This
842 front end takes care of the details of constructing the pipeline among
843 the preprocessors, @code{gtroff} and the postprocessor.
845 It has become a tradition that GNU programs get the prefix @dfn{g} to
846 distinguish it from its original counterparts provided by the host
847 (@pxref{Environment}, for more details). Thus, for example, @code{geqn}
848 is GNU @code{eqn}. On operating systems like Linux or the Hurd, which
849 don't contain proprietary software, this prefix is omitted since GNU
850 @code{troff} is the only used incarnation of @code{troff}. Exception:
851 @code{groff} is never replaced by `roff'.
857 * Invocation Examples::
860 @node Options, Environment, Invoking groff, Invoking groff
873 @code{groff} is a front-end to the groff document formatting system.
874 Normally it runs the @code{gtroff} program and a postprocessor
875 appropriate for the selected device. The default device is @samp{ps}.
876 It can optionally preprocess with any of @code{gpic}, @code{geqn},
877 @code{gtbl}, @code{ggrn}, @code{grefer}, or @code{gsoelim}.
879 This section only documents options to the @code{groff} front end.
880 Many of the arguments to @code{groff} are passed on to @code{gtroff},
881 therefore those are also included. Arguments to pre- or postprocessors
882 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
883 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
884 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
885 grohtml}, @ref{Invoking grodvi}, and @ref{Invoking gxditview}
887 The command line format for @code{groff} is:
890 groff [ -abeghilpstvzCENRSVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
891 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
892 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
893 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ]
894 [ @var{files}@dots{} ]
897 The command line format for @code{gtroff} is as follows. As you can
898 see, many of the options to @code{groff} are actually passed on to
902 gtroff [ -abivzCER ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
903 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
904 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
905 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
908 Options without an argument can be grouped behind a single @samp{-}. A
909 filename of @samp{-} denotes the standard input.
912 The @code{grog} command can be used to guess the correct @code{groff}
913 command to use to format a file.
917 Print a help message.
919 Preprocess with @code{geqn}.
921 Preprocess with @code{gtbl}.
923 Preprocess with @code{ggrn}.
925 Preprocess with @code{gpic}.
927 Preprocess with @code{gsoelim}.
929 Preprocess with @code{grefer}. No mechanism is provided for passing
930 arguments to @code{grefer} because most @code{grefer} options have
931 equivalent commands which can be included in the file. @xref{grefer},
935 Note that @code{gtroff} also accepts a @samp{-R} option, which is not
936 accessible via @code{groff}. This option prevents the loading of the
939 Make programs run by @code{groff} print out their version number.
941 Print the pipeline on stdout instead of executing it.
943 Suppress output from @code{gtroff}. Only error messages will be printed.
945 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
946 will automatically run the appropriate postprocessor.
948 Pass @var{arg} to the postprocessor. Each argument should be passed
949 with a separate @samp{-P} option. Note that groff does not prepend
950 @samp{-} to @var{arg} before passing it to the postprocessor.
952 Send the output to a printer. The command used for this is specified by
953 the print command in the device description file.
955 Pass @var{arg} to the spooler. Each argument should be passed with a
956 separate @samp{-L} option. Note that @code{groff} does not prepend a
957 @samp{-} to @var{arg} before passing it to the postprocessor.
959 Prepare output for device @var{dev}. The default device is @samp{ps}.
960 The following are the output devices currently available:
963 For PostScript printers and previewers.
967 For a 75 dpi X11 previewer.
969 For a 100dpi X11 previewer.
971 For typewriter-like devices.
973 For typewriter-like devices using the ISO Latin-1 (ISO 8859-1) character set.
975 For typewriter-like devices using the Unicode (ISO 10646) character set with
978 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
980 To produce HTML output.
983 The postprocessor to be used for a device is specified by the
984 @code{postpro} command in the device description file. (@xref{Font
985 Files}, for more info.) This can be overridden with the @samp{-X}
988 Preview with @code{gxditview} instead of using the usual postprocessor.
989 This is unlikely to produce good results except with @samp{-Tps}.
991 Don't allow newlines with @code{eqn} delimiters. This is the same as
992 the @samp{-N} option in @code{geqn}.
994 Safer mode. Pass the @samp{-S} option to @code{gpic} and use the
995 @samp{-msafer} macros with @code{gtroff}.
997 Generate an ASCII approximation of the typeset output.
999 Print a backtrace with each warning or error message. This backtrace
1000 should help track down the cause of the error. The line numbers given
1001 in the backtrace may not always be correct: @code{troff}'s idea of line
1002 numbers gets confused by @code{as} or @code{am} requests.
1004 Read the standard input after all the named input files have been
1007 Enable warning @var{name}. Available warnings are described in
1008 @ref{Debugging}. Multiple @samp{-w} options are allowed.
1010 Inhibit warning @var{name}. Multiple @samp{-W} options are allowed.
1012 Inhibit all error messages.
1014 Enable compatibility mode.
1016 @itemx -d@var{name}=s
1017 Define @var{c} or @var{name} to be a string @var{s}; @var{c} must be a
1018 one-letter @var{name}.
1020 Use @var{fam} as the default font family.
1022 Read in the file @file{tmac.@var{name}}. Normally this will be searched
1023 for in @code{groff}'s lib directory.
1025 Number the first page @var{num}.
1027 Output only pages in @var{list}, which is a comma-separated list of page
1028 ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
1029 print every page between @var{m} and @var{n}, @samp{-@var{n}} means
1030 print every page up to @var{n}, @samp{@var{n}-} means print every page
1031 from @var{n}. @code{troff} will exit after printing the last page in
1034 @itemx -r@var{name}=@var{n}
1035 Set number register @var{c} or @var{name} to @var{n}; @var{c} must be a
1036 one-letter @var{name}; @var{n} can be any troff numeric expression.
1038 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1039 name of the device) for the @file{DESC} file and font files before the
1042 Search directory @var{dir} for macro files before the normal directory.
1047 @node Environment, Invocation Examples, Options, Invoking groff
1048 @section Environment
1052 There are also several environment variables which can modify groff's
1056 @item GROFF_COMMAND_PREFIX
1057 If this is set to @var{X}, then @code{groff} will run
1058 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1059 @code{tbl}, @code{pic}, @code{eqn}, @code{refer}, and @code{soelim}. It
1060 does not apply to @code{grops}, @code{grodvi}, @code{grotty},
1061 @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1062 @item GROFF_TMAC_PATH
1063 A colon separated list of directories in which to search for macro
1065 @item GROFF_TYPESETTER
1067 @item GROFF_FONT_PATH
1068 A colon separated list of directories in which to search for the
1069 @code{dev}@var{name} directory.
1071 The search path for commands executed by groff.
1073 The directory in which temporary files will be created. If this is not
1074 set and @code{TMPDIR} is set, temporary files will be created in that
1075 directory. Otherwise temporary files will be created in @code{/tmp}.
1076 The @code{grops} and @code{grefer} commands can create temporary files.
1080 @node Invocation Examples, , Environment, Invoking groff
1081 @section Invocation Examples
1082 @cindex invocation examples
1083 @cindex examples of invocation
1086 This section will list several common uses of @code{groff} and the
1087 command line which will accomplish it.
1092 groff -mm -rD1 -z file
1093 groff -tps -me file | lpr -Plw2
1097 @subsection @code{grog}
1099 @code{grog} reads files and guesses which of the @code{groff}
1100 preprocessors and/or macro packages are are required for formatting
1101 them, and prints the @code{groff} command including those options on the
1102 standard output. The options generated are one of @samp{-e},
1103 @samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-s},
1106 A filename of @samp{-} is taken to refer to the standard input. If no
1107 files are specified the standard input will be read. Any specified
1108 options will be included in the printed command. No space is allowed
1109 between options and their arguments. For example,
1115 will guess the approriate command to print @file{paper.ms} and then run
1116 it after adding the @samp{-Tdvi} option.
1119 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1120 @chapter Tutorial for Macro Users
1121 @cindex tutorial for macro users
1122 @cindex macro tutorial for users
1123 @cindex user's tutorial for macros
1124 @cindex user's macro tutorial
1126 Most users tend to use a macro package to format their papers. This
1127 means that the whole breadth of @code{groff} is not neccessary for most
1128 people. This chapter covers the material needed to efficiently use a
1137 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1142 This section covers some of the basic concepts you will need to
1143 understand to use a macro package.@footnote{This section is derived from
1144 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman}
1145 References are made throughout to more detailed information, if desired.
1147 @code{groff} reads an input file prepared by the user and outputs a
1148 formatted paper suitable for publication or framing. The input consists
1149 of text, or words to be printed, and embedded commands (@dfn{requests}
1150 and @dfn{escapes}), which tell @code{groff} how to format the printed
1151 copy. For more detail on this @pxref{Embedded Commands}.
1153 The word @dfn{argument} is used in this manual to mean a word or number
1154 which appears on the same line as a request which modifies the meaning
1155 of that request. For example, the request
1162 spaces one line, but
1169 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1170 request which says to space four lines instead of one. Arguments are
1171 separated from the request and from each other by spaces. More details
1172 on this can be found in @ref{Request Arguments}.
1174 The primary function of @code{groff} is to collect words from input
1175 lines, fill output lines with those words, justify the right hand margin
1176 by inserting extra spaces in the line, and output the result. For
1184 Four score and seven
1189 will be read, packed onto output lines, and justified to produce:
1192 Now is the time for all good men to come to the aid of their party.
1193 Four score and seven years ago,...
1198 Sometimes you may want to start a new output line even though the line
1199 you are on is not yet full; for example, at the end of a paragraph. To
1200 do this you can cause a @dfn{break}, which starts a new output line.
1201 Some requests cause a break automatically, as do blank input lines and
1202 input lines beginning with a space.
1204 Not all input lines are text to be formatted. Some of the input lines
1205 are requests which describe how to format the text. Requests always
1206 have a period or an apostrophe (@samp{'}) as the first character of the
1209 The text formatter also does more complex things, such as automatically
1210 numbering pages, skipping over page boundaries putting footnotes in the
1211 correct place, and so forth.
1213 Here a few hints for preparing text for input to @code{groff}. First,
1214 keep the input lines short. Short input lines are easier to edit, and
1215 @code{groff} will pack words onto longer lines for you anyhow. In
1216 keeping with this, it is helpful to begin a new line after every period,
1217 comma, or phrase, since common corrections are to add or delete
1218 sentences or phrases. Secondly, do not hyphenate words at the end of
1219 lines -- @code{groff} is smart enough to hyphenate words for you as
1220 needed, but is not smart enough to take hyphens out and join a word back
1221 together. Also, words such as ``mother-in-law'' should not be broken
1222 over a line, since then you will get a space where not wanted, such as
1226 @cindex double spacing
1228 Groff will double space output text automatically if you use the request
1229 @samp{.ls 2}. You can revert to single spaced mode by typing @samp{.ls
1232 A number of requests allow you to change the way the printed copy looks,
1233 sometimes called the @dfn{layout} of the output page. Most of these
1234 requests adjust the placing of @dfn{white space} (blank lines or
1239 The @samp{.bp} request starts a new page.
1244 The request @samp{.sp @var{N}} leaves @var{N} lines of blank space.
1245 @var{N} can be omitted (meaning skip a single line) or can be of the
1246 form @var{N}i (for @var{N} inches) or @var{N}c (for @var{N}
1247 centimeters). For example, the input:
1251 My thoughts on the subject
1256 leaves one and a half inches of space, followed by the line ``My
1257 thoughts on the subject'', followed by a single blank line.
1260 @cindex centering lines
1261 Text lines can be centered by using the @samp{.ce} request. The line
1262 after @samp{.ce} is centered (horizontally) on the page. To center more
1263 than one line, use @samp{.ce @var{N}} (where @var{N} is the number of
1264 lines to center), followed by the @var{N} lines. If you want to center
1265 many lines but don't want to count them, type:
1274 The @samp{.ce 0} request tells @code{groff} to center zero more lines,
1275 in other words, stop centering.
1280 All of these requests cause a break; that is, they always start a new
1281 line. If you want to start a new line without performing any other
1282 action, use @samp{.br}.
1285 @node Common Features, , Basics, Tutorial for Macro Users
1286 @section Common Features
1287 @cindex common features
1288 @cindex features, common
1291 Groff provides very low level operations for formatting a document.
1292 There are many common routine operations which are done in all documents.
1293 These common operations are written into @dfn{macros} and collected into a
1294 @dfn{macro package}.
1296 All macro packages provide certain common capabilities which fall
1297 into the following categories.
1299 @subsection Paragraphs
1302 One of the most common and most used capability is starting a
1303 paragraph. There are a number of different types of paragraphs,
1304 any of which can be initiated with macros supplied by the macro
1305 package. Normally paragraphs start with a blank line and the first
1306 line indented, like the text in this manual. There are also block
1307 style paragraphs, which omit the indentation:
1310 Some men look at constitutions with sanctimonious
1311 reverence, and deem them like the ark of the covenant, too
1312 sacred to be touched.
1315 And there are also indented paragraphs which begin with a tag or label
1316 at the margin and the remaining text indented.
1319 one This is the first paragraph. Notice how the first
1320 line of the resulting paragraph lines up with the
1321 other lines in the paragraph.
1323 This paragraph had a long label. The first
1324 character of text on the first line will not line up
1325 with the text on second and subsequent lines,
1326 although they will line up with each other.
1329 A variation of this is a bulleted list....
1331 @subsection Sections and Chapters
1333 Most macro packages supply some form of section headers.
1334 The simplest kind is simply the heading on a line by itself in bold
1335 type. Others supply automatically numbered section heading or
1336 different heading styles at different levels.
1337 Some, more sophisticated, macro packages supply macros for starting
1338 chapters and appendicies.
1340 @subsection Headers and Footers
1342 Every macro packages gives you some way to manipulate the headers and
1343 footers (or @dfn{titles} on each page. Some packages will allow you
1344 to have different ones on the even and odd pages (for material
1345 printed in a book form).
1346 The titles are called three-part titles, that is, there is a
1347 left-justified part, a centered part, and a right-justified part.
1348 An automatically generated page number may be put in any of these
1349 fields with the @samp{%} character.
1351 @subsection Page Layout
1353 Most macro packages let you specify top and bottom margins and other
1354 details about the appearance of the printed pages.
1356 @subsection Displays
1359 Displays are sections of text to be set off from the body
1360 of the paper. Major quotes, tables, and figures are types of
1361 displays, as are all the examples used in this document.
1363 @cindex quotes, major
1364 @cindex major quotes
1365 Major quotes are quotes which are several lines long,
1366 and hence are set in from the rest of the text without
1367 quote marks around them.
1370 A list is an indented, single spaced, unfilled display. Lists should
1371 be used when the material to be printed
1372 should not be filled and justified like normal text, such
1373 as columns of figures or the examples used in this paper.
1376 A keep is a display of lines which are kept on a single page if
1377 possible. An example of where you would use a
1378 keep might be a diagram. Keeps differ from lists in that
1379 lists may be broken over a page boundary whereas keeps will
1382 @cindex keep, floating
1383 @cindex floating keep
1384 Floating keeps move relative to the text. Hence, they
1385 are good for things which will be referred to by name, such
1386 as ``See figure 3''. A floating keep will appear at the bottom of the
1387 current page if it will fit; otherwise, it will
1388 appear at the top of the next page. Meanwhile, the surrounding text
1389 will `flow' around the keep, thus leaving now blank areas.
1391 @subsection Footnotes and annotations
1395 There are a number of requests to save text for later
1396 printing. Footnotes are printed at the bottom of the current
1397 page. Delayed text is intended to be a variant form of foot-
1398 note; the text is printed only when explicitly called for,
1399 such as at the end of each chapter.
1401 Delayed text is very similar to a footnote except that
1402 it is printed when called for explicitly. This allows a
1403 list of references to appear (for example) at the end of
1404 each chapter, as is the convention in some disciplines.
1406 Most macro packages which supply this functionality also supply a
1407 means of automatically numbering either type of annotation.
1409 @subsection Table of Contents
1411 Tables of contents are a type of
1412 delayed text having a tag (usually the page number) attached
1413 to each entry after a row of dots. The table accumulates
1414 throughought the paper until printed, usually after the paper has
1415 ended. Many macro packages will provide the abilitly to have several
1416 tables of contents (i.e. one standard one, one for tables, &c.)
1420 While some macro packages will use the term @dfn{index}, none
1421 actually provide that functionality. The facilities they call
1422 indexes are actually more appropriate for tables of contents.
1424 @subsection Paper formats
1426 Some macro packages provide stock formats for various kinds of
1427 documents. Many of them provide a common format for the title and
1428 opening pages of a technical paper. The -mm macros in particular
1429 provide formats for letters and memorandums.
1431 @subsection Multiple Columns
1433 Some macro packages (except -man) provide the ability to have two or
1434 more columns on a page.
1436 @subsection Font and Size changes
1438 The builtin font and size functions are not always intuitive, so all
1439 macro packages provide macros to make these operations simpler.
1441 @subsection Predefined Strings
1443 Most macro packages provide various predefined strings for a variety
1444 of uses, examples are sub- and super-scripts, printable dates, quotes
1445 and various special characters.
1447 @subsection Preprocessor Support
1449 All macro packages provide support for the various preprocessors.
1451 @subsection Configuration and Customization
1453 Some macro packages provide means of customizing many of details of
1454 how the package behaves. This ranges from setting the default type
1455 size to changing the appearance of section headers.
1458 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1459 @chapter Macro Packages
1460 @cindex macro packages
1461 @cindex packages, macros
1463 This chapter documents the main macro packages that come with
1475 @node -man, -mdoc, Macro Packages, Macro Packages
1481 @node -mdoc, -ms, -man, Macro Packages
1483 @cindex @code{-mdoc}
1487 @node -ms, -me, -mdoc, Macro Packages
1493 @node -me, -mm, -ms, Macro Packages
1499 @node -mm, , -me, Macro Packages
1505 @node Programming Tutorial, Preprocessors, Macro Packages, Top
1506 @chapter Programming Tutorial
1507 @cindex programming tutorial
1508 @cindex tutorial for programming
1510 This chapter covers @strong{all} of the facilities of groff.
1511 If you are intending to use a macro package, you probably do not want
1512 to read this chapter.
1517 * Input Conventions::
1521 * Embedded Commands::
1523 * Manipulating Filling and Adjusting::
1524 * Manipulating Hyphenation::
1525 * Manipulating Spacing::
1527 * Character Translations::
1534 * Conditionals and Loops::
1537 * Drawing Functions::
1542 * Postprocessor Access::
1545 * Implementation Differences::
1549 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
1553 @code{groff} input files contain text with control commands
1554 interspersed throughout. But, even without control codes,
1555 @code{groff} will still do several things with your text:
1556 filling and adjusting,
1557 adding additional space after sentences,
1560 inserting implicit line breaks.
1564 * Filling and Adjusting::
1568 * Implicit Line Breaks::
1571 @node Filling and Adjusting, Hyphenation, Text, Text
1572 @subsection Filling and Adjusting
1573 @cindex filling and adjusting
1574 @cindex adjusting and filling
1577 When troff reads in text it collects words from input and fits as many
1578 of them together on one output line as it can. This is known as
1581 Once troff has a @dfn{filled} line it will try to @dfn{adjust} it.
1582 which means it will widen the spacing between words until
1583 the text reaches the right margin (in the default adjustment mode).
1584 Extra spaces between words are preserved, but
1585 spaces at the end of lines are ignored.
1586 Spaces at the front of a line will cause a @dfn{break}
1587 (breaks will be explained in @ref{Implicit Line Breaks})
1589 @c distribute these through the text
1590 @xref{Manipulating Filling and Adjusting}
1592 @node Hyphenation, Sentences, Filling and Adjusting, Text
1593 @subsection Hyphenation
1597 Since the odds of finding a set of words, for every output line,
1598 which will fit nicely on a
1599 line without inserting excessive amounts of space between words
1601 troff will hyphenate words so that lines can be justified
1602 without there being too much space between words.
1603 It uses an internal hyphenation algorithm, to indicate which words can
1604 be hyphenated and how to do so.
1605 When a word is hyphenated the first part of the word will be added
1606 to the current filled line being output (with an attached hyphen),
1607 and the other portion will be added to the next line to be filled.
1609 @c distribute these through the text
1610 @xref{Manipulating Hyphenation}
1612 @node Sentences, Tab Stops, Hyphenation, Text
1613 @subsection Sentences
1617 Although it is often debated,
1618 some typesetting rules say there should be different amounts of space
1619 after various puctuation marks.
1620 For example, a period at the end of a sentence
1621 should have twice as much space following it
1622 as would a comma or a period as part of an abbreviation.
1624 @cindex sentence spaces
1625 @cindex spaces between sentences
1626 Troff does this by flagging certain characters (normally
1627 @samp{!}, @samp{?} and @samp{.})
1628 as @dfn{end of sentence} characters.
1629 When troff encounters one of these characters at the end of a line it
1630 will append two @dfn{sentence spaces} in the formatted output.
1631 (thus, one of the conventions mentioned in @ref{Input Conventions}).
1633 @c also describe how characters like ) are treated here -jjc
1634 @c gotta do some research on this -trent
1638 @node Tab Stops, Implicit Line Breaks, Sentences, Text
1639 @subsection Tab Stops
1641 @cindex stops, tabulator
1644 Groff translates tabs in the input into movements to the next tab
1645 stop. These tab stops are initially located every half inch across
1647 Using this you can make simple tables. However, this can often be
1648 deceptive as the appearance (and width) of your text on a terminal and
1649 the results from groff can vary greatly.
1651 Also, a possible sticking point is that lines beginning with tab
1652 characters will still be filled, again producing unexpected results.
1653 For example, the following input
1667 @c Tab stops are with respect to the input line. -jjc
1668 @c did that last section address that?? -trent
1672 @c distribute these through the text
1673 @xref{Tabs and Fields}
1675 @node Implicit Line Breaks, , Tab Stops, Text
1676 @subsection Implicit Line Breaks
1677 @cindex implicit line breaks
1678 @cindex implicit breaks of lines
1679 @cindex line, implicit breaks
1681 @cindex break, implicit
1684 An important concept in troff is the @dfn{break}. When a @dfn{break}
1685 occurs, troff will output the partially filled line (unadjusted),
1686 and resume collecting and filling text on the next output line.
1691 There are several ways to cause a break in troff.
1692 A blank line will not only cause a break, but it will also cause a
1693 one line vertical space (effectively a blank line) to be output.
1695 A line which begins with a space will cause a break and the space
1696 will be output at the beginning of the next line.
1697 Note that this space isn't adjusted, even in fill mode.
1699 The end of file will also cause a break (otherwise the last line of
1700 your document may vanish!)
1702 Certain @dfn{requests} also cause breaks, implicitly or explicity.
1703 This will be discussed later.
1705 @c distribute these through the text
1706 @xref{Manipulating Filling and Adjusting}
1708 @node Input Conventions, Measurements, Text, Programming Tutorial
1709 @section Input Conventions
1710 @cindex input conventions
1711 @cindex conventions for input
1714 Since groff does filling automatically, it is traditional in groff not
1715 to try and type things in as nicely formatted paragraphs. These are
1716 some conventions commonly used when typing groff text:
1720 Break lines after punctuation, particularily at the ends of
1721 sentences, and in other logical places. Keep separate phrases on
1722 lines by themselves, as entire phrases are often added or deleted
1725 Try to keep lines less than 40-60 characters,
1726 to allow space for inserting more text.
1728 Do not try to do any formatting in a WYSIWYG manner (i.e. don't
1729 try and use spaces to get proper indentation).
1733 @node Measurements, Expressions, Input Conventions, Programming Tutorial
1734 @section Measurements
1735 @cindex measurements
1738 @cindex units of measurement
1740 @cindex machine units
1741 Troff (like any other programs) requires numeric parameters to
1742 specify various measurements. Most numeric parameters
1743 @footnote{those that specify vertical or horizontal motion or a type
1744 size} may have a measurement unit attached.
1745 These units are specified as a single
1746 character which immediately follows the number or expression.
1747 Each of these units are understood, by troff, to be a multiple of its
1748 @dfn{basic unit}. So, whenever a different measurement unit is
1749 specified troff converts this into its basic units.
1750 This basic unit, represented by a @samp{u} is a
1751 device dependent measurement which is quite small, ranging from
1752 1/75th to 1/72000th of an inch.
1754 Some of the measurement units are compleatly independent of any of
1755 the current settings (e.g. type size) of groff.
1760 Inches. An antiquated measurement unit still in use in certain
1761 backwards countries.
1767 Points. This is a typesetter's measurement used for measure type size.
1768 It is 72 points to an inch.
1771 Pica. Another typesetting measurement. 6 Picas to an inch.
1776 The other measurements understood by troff are dependent on settings
1777 currently in effect in troff. These are very useful for specifying
1778 measurements which should look proper with any size of text.
1783 Ems. This unit is equal to the current font size in points.
1784 So called because it is @emph{approximately} the width of the letter
1785 @samp{m} in the current font.
1788 Ens. This is half of an em.
1790 @cindex vertical space
1791 @cindex space, vertical
1792 Vertical space. This is equivalent to the current line spacing.
1793 @xref{Sizes}, for more information about this.
1798 @c distribute these through the text
1799 @xref{Fractional Type Sizes}
1805 @node Default Units, , Measurements, Measurements
1806 @subsection Default Units
1807 @cindex default units
1808 @cindex units, default
1811 Many requests take a default unit. While this can be helpful at
1812 times, it can cause strange errors in some expressions.
1813 For example, the line length request expects em's.
1814 Here are several attempts to get 3.5 inches and the results:
1821 7i/2u @result{} 3.5i
1824 As you can see, the safest way to specify measurements is to always
1825 attach a scaling indicator.
1827 @node Expressions, Identifiers, Measurements, Programming Tutorial
1828 @section Expressions
1832 Troff has most of operators common to other languages:
1836 Arithmetic: +, -, /, *, %
1838 Comparison: <, >, >=, <=, =, == (the last two are the same)
1842 Unary operators: -, +, ! (if/while only??)
1844 Maximum and minimum: >?, <?
1846 Scaling: (@var{c};@var{e})
1847 Evaluate @var{e} using @var{c} as the default scaling indicator.
1848 If @var{c} is missing, ignore scaling indicators in the
1849 evaluation of @var{e}.
1852 Parenthesis may be used as in any other language.
1853 However, in groff they are necessary to ensure order of evaluation.
1854 Groff has no operator precedence,
1855 expressions are evaluated left to right.
1856 This means that @samp{3+5*4} is evaluated as if it were parenthesized
1857 like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may expect.
1859 For many requests which cause a motion on the page, the unary
1860 operators work differently.
1861 The @samp{+} and @samp{-} operators indicate a motion relative to the
1862 current position (down or up, respectively). The @samp{|} operator
1863 indicates an absolute position on the page or input line. (????)
1864 @code{+} and @code{-} are also treated differently by @code{nr} (?)
1866 Due to the way arguments are parsed, spaces are not allowed in
1867 expressions, unless the entire expression is surrounded by parenthesis.
1869 @c distribute these through the text
1870 @xref{Request Arguments}
1871 @c distribute these through the text
1872 @xref{Conditionals and Loops}
1874 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
1875 @section Identifiers
1878 Like any other language troff, has rules for properly formed
1880 In troff an identifier can be made up of most any printable
1882 The only exception is characters which are interpreted by troff
1883 (backslash, square bracket and ?). So, for example, any of the following
1894 You can test whether an identifier is valid in groff with the
1895 @code{\A} escape. It expands to 1 or 0 according whether its argument
1896 (given in quotes) is or is not acceptable as the name of a string,
1897 macro, diversion, number register, environment or font. It will return
1898 0 if no argument is given. This is useful if you want to lookup user
1899 input in some sort of associative table.
1901 Identifiers in groff can be any length, but, in some contexts,
1903 where identifiers end and text begins (and in different ways
1904 depending on their length)
1911 Must be prefixed with @samp{(} in some situations.
1913 Arbitrary length (groff only)
1914 Must be bracketed with @samp{[}, @samp{]} in some situations.
1915 Any length identifier can be put in brackets.
1918 Unlike many other programming languages, undefined identifiers are
1919 silently ignored or expanded to nothing.
1922 @c distribute these through the text
1923 @xref{Interpolating Registers}
1924 @c distribute these through the text
1927 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
1928 @section Embedded Commands
1929 @cindex embedded commands
1930 @cindex commands, embedded
1933 With most documents you need more funtionality beyond filling,
1934 adjusting and implicit line breaking.
1935 In order to gain further functionality, groff allows commands to be
1936 embeded into your text, in two ways.
1938 The first is a @dfn{request} which takes up an entire line, and does
1939 some large scale operation (e.g. break lines, start new pages).
1941 The other is an @dfn{escape} which can be embedded anywhere
1942 in your text, or even as an argument to a request. (Not always?)
1943 Escapes generally do more minor operations like sub- and super-
1944 scripts, print a symbol, &c.
1954 @node Requests, Macros, Embedded Commands, Embedded Commands
1955 @subsection Requests
1959 @cindex control character
1960 @cindex character, control
1961 A request line begins with a control character,
1962 which is either a single quote (@samp{'}) or a period (@samp{.}).
1963 These can be changed @pxref{Character Translations}, for details.
1964 After this there may be optional tabs or spaces followed by an
1965 identifier which is the name of the request.
1966 This may be followed by any number of space separated arguments.
1969 If you want to begin a line with a control character without it being
1970 interpreted, precede it with a @code{\&}. This represents a zero
1971 width space, which means it will not affect you output.
1973 In most cases you will use the period as a control character.
1974 Several requests will cause a break, using the single quote control
1975 character will prevent this.
1979 * Request Arguments::
1982 @node Request Arguments, , Requests, Requests
1983 @subsubsection Request Arguments
1984 @cindex request arguments
1985 @cindex arguments to requests
1988 Argument to requests (and macros) are processed much like the shell:
1989 The line is split into arguments according to spaces.
1990 An argument which is intended to contain spaces can either be enclosed
1991 in quotes (single or double), or have the spaces @dfn{escaped} with
1997 .uh The Mouse Problem
1998 .uh "The Mouse Problem"
1999 .uh The\ Mouse\ Problem
2002 The first line is the @code{.uh} macro being called with 3 arguments,
2003 @samp{The}, @samp{Mouse}, and @samp{Problem}.
2004 The latter two have the same effect or calling the @code{.uh} macro
2005 with one argument @samp{The Mouse Problem}.
2007 Note, however, that the @code{.ds} request works differently.
2009 @c distribute these through the text
2012 @node Macros, Escapes, Requests, Embedded Commands
2017 Troff has a @dfn{macro} facility for defining a series of lines which
2018 can be invoked by name.
2019 They are called in the same manner as requests
2020 and arguments may be passed in the same manner.
2023 @c distribute these through the text
2024 @xref{Writing Macros}
2025 @c distribute these through the text
2026 @xref{Request Arguments}
2028 @node Escapes, , Macros, Embedded Commands
2035 Escapes may occur anywhere in the input to groff.
2036 They begin with a backslash and are followed by a single character
2037 which indicates the function to be performed.
2038 If you want to have a backslash appear in your document, you should
2039 use the escape sequence @code{\e}. Merely escaping the backslash
2040 with another backslash will work in @emph{some} curcumstances.
2042 Many escapes have no parameters, those that do, do so in one of two
2043 ways. For escapes which require an identifier there must be a way for
2044 groff to tell where the identifier ends and the text begins.
2045 It assumes that the next single character is the identifier, but if
2046 that character is an open parenthesis, it takes the next two
2047 characters as the identifier; and if the next character is an open
2048 bracket, all characters until a close bracket are taken as the
2049 identifier. Note that in the second case there is no closing
2050 parenthesis. For example:
2058 Other escapes may require several arguments and/or some special
2059 format. In these cases the @dfn{argument} is enclosed in single
2060 quotes (not required??) and the enclosing text is decoded according
2061 to what that escape expects.
2070 If you want to have a backslash appear in your output, you can use several
2071 escapes: @code{\\}, @code{\e} or @code{\E}.
2072 These are very similar, and only differ with respect to being used in
2073 macros or diversions (@xref{Copy-in Mode}, and @ref{Diversions}, for
2078 @c distribute these through the text
2085 @node Comments, , Escapes, Escapes
2086 @subsubsection Comments
2091 Probably one of the most@footnote{Unfortunately, this is a lie. But
2092 hopefully future troff hackers will believe it :-)}
2093 common forms of escapes is the comment.
2094 They begin with the @code{\"} escape and end at the end of the input
2097 This may sound simple, but it can be tricky to keep the comments from
2098 interfering with the apperarance of your final outupt.
2100 If the escape is to the right of some text or a request, that portion
2101 of the line will be ignored, but the space leading up to it will be
2102 noticed by groff. This only affects the @code{.ds} request (any
2105 One possibly irritating idiosyncracy is that you mustn't use tabs to
2106 line up your comments.
2107 Tabs are not treated as white space between request and macro
2110 If you have a comment on a line by itself, it will be treated as a
2111 blank line, because after eliminating the comment, that is all that
2112 remains. So, it is common to start the line with @code{.\"} which
2113 will cause the line to be treated as an undefined request.
2115 Another commenting scheme seen sometimes is three consecutive single
2116 quotes (@code{'''}) at the begining of a line. This works, but groff
2117 will give a warning about an undefined macro, which is harmless, but
2121 Now to avoid all this groff has a new comment mechanism using the
2122 @code{\#} escape. This escape works the same as @code{\"} except
2123 that the newline is also ignored.
2126 For large blocks of text, the @code{ig} request may be useful.
2127 @c distribute these through the text
2130 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
2135 Registers are groff's numeric variables. groff has a number of
2136 builtin registers, supplying anything from the date to details of
2137 formatting parameters.
2139 @c distribute these through the text
2143 * Setting Registers::
2144 * Interpolating Registers::
2146 * Assigning Formats::
2147 * Builtin Registers::
2150 @node Setting Registers, Interpolating Registers, Registers, Registers
2151 @subsection Setting Registers
2152 @cindex setting registers
2153 @cindex registers, setting
2158 Registers are defined/set via the @code{nr}
2159 request or the @code{\R} escape, for example, the following two lines
2168 The @code{rr} request will
2169 remove the register specified by the argument.
2172 The @code{rnn} request will rename a number register.
2173 The format is @samp{.rnn @var{x} @var{y}}, which will
2174 rename number register @var{x} to @var{y}.
2177 Aliases can be created for a number register. The format is
2178 @samp{.aln @var{xx} @var{yy}}, which will create an alias @var{xx} for
2179 number register object named @var{yy}. The new name and the old name
2180 will be exactly equivalent. If @var{yy} is undefined, a warning of
2181 type @samp{reg} will be generated, and the request will be ignored.
2182 @xref{Debugging}, for information about warnings.
2185 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
2186 @subsection Interpolating Registers
2187 @cindex interpolating registers
2188 @cindex registers, interpolating
2192 Numeric registers are @dfn{interpolated} via the @code{\n} escape.
2193 @c the following is wrong. Should I say any more than the above??
2194 @c This means that the value of the number register in expanded in-place
2195 @c on the input line before any other actions, i.e. before requests and
2196 @c escapes are interpreted.
2204 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
2205 @subsection Auto-increment
2206 @cindex auto-increment
2207 @cindex increment, automatic
2209 Number registers can also be auto incremented/decremented. You can
2210 specify the increment/decrement factor with third argument to the
2211 @code{nr} request. The default value is 0. For example:
2216 \n+a, \n+a, \n+a, \n+a, \n+a
2218 \n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx
2228 If you want to change the increment factor without changing the value
2229 of a register, the following can be used.
2236 @node Assigning Formats, Builtin Registers, Auto-increment, Registers
2237 @subsection Assigning Formats
2238 @cindex assigning formats
2239 @cindex formats, assigning
2243 When a register is used in the text of an input file
2244 (as opposed to part of an expression)
2245 it is textually replaced (or interpolated) with a representation of
2247 This output format can be changed to a variety of formats
2248 (numbers, roman numerals, etc)
2249 This is done using the @code{af} request.
2250 The first argument to @code{af} is the name of the number register to
2252 and the second argument is the output format.
2253 The following output formats are available:
2257 This is the default format, decimal numbers:
2260 Decimal numbers with as many leading zeros as specified.
2261 So, @samp{001} would result in 001, 002, 003, @dots{}
2263 @cindex roman numerals
2264 @cindex numerals, roman
2265 Upper-case roman numerals:
2266 0, I, II, III, IV, @dots{}
2268 Lower-case roman numerals:
2269 0, i, ii, iii, iv, @dots{}
2272 A, B, C, @dots{}, Z, AA, AB, @dots{}
2275 a, b, c, @dots{}, z, aa, ab, @dots{}
2278 The following example will produce @samp{10, X, j, 010}.
2282 .af a 1 \" the default format
2293 The @code{\g} escape returns the current format of the specified
2294 register. For example, @samp{\ga} after the following example would
2299 @node Builtin Registers, , Assigning Formats, Registers
2300 @subsection Builtin Registers
2301 @cindex builtin registers
2302 @cindex registers, builtin
2305 The following are some builtin registers, which are not listed
2306 elsewhere in this manual. Any registers which begin with a @samp{.}
2307 are read-only. A compleat listing of all builtin registers can be
2308 found in @ref{Register Index}.
2313 Horizontal resolution in basic units.
2316 Vertical resolution in basic units.
2319 Day of the week (1-7).
2322 Day of the year (1-31).
2325 Current month (1-12).
2331 The year minus 1900. Unfortunately, the Unix Version 7 troff
2332 documentation had a year 2000 bug: it incorrectly claimed that
2333 @samp{\n(yr} was the last two digits of the year. That claim has never
2334 been true of either traditional troff or GNU troff. If you see old
2335 troff input that looks like this:
2338 '\" (The following line stopped working after 1999.)
2339 This document was formatted in 19\n(yr.
2342 you can correct it as follows:
2345 This document was formatted in \n[year].
2348 or, if you want to be portable to older troff versions, as follows:
2352 This document was formatted in \n(y4.
2359 The current @emph{input} line number.
2362 The current @emph{output} line number.
2365 The major version number. For example, if the version number is 1.03
2366 then @code{.x} will contain 1.
2369 The minor version number. For example, if the version number is 1.03
2370 then @code{.y} will contain 03.
2373 The revision number of groff.
2377 Macros should use this to determine whether they are running
2381 If the current output device is ascii, this is set to 1,
2385 This register indicates whether the current page is actualy being
2386 printed, i.e. if the @samp{-o} option is being used to only print
2388 @xref{Options}, for more information.
2391 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
2392 @section Manipulating Filling and Adjusting
2393 @cindex manipulating filling and adjusting
2394 @cindex filling and adjusting, manipulating
2395 @cindex adjusting and filling, manipulating
2401 Several ways of causing @dfn{breaks} were given in
2402 @ref{Implicit Line Breaks}.
2403 The @code{br} request will likewise cause a break.
2404 Several other requests will also cause breaks, implicitly.
2418 Initially, groff will fill and ajust text to both margins.
2419 Filling can be disabled via the @code{nf} request
2420 and re-enabled with the @code{fi} request.
2421 These implicitly disable and re-enable adjusting.
2422 Both of these will cause break in text currently being filled.
2423 The number register @code{.u} is equal to 1 in fill mode and 0 in
2429 Adjusting can be disabled with the @code{ad} request and re-enabled
2430 with the @code{na} request.
2431 The @code{ad} request takes a single argument to indicate how to
2433 The current adjustment mode is available in the number register
2438 @cindex ragged-right
2439 Adjust text to the left margin. This produces what is traditionally
2440 called ragged-right text.
2442 Adjust text to the right margin.
2447 Justify to both margins. This is groff's default.
2450 With no argument to @code{ad}, troff will adjust lines the same way
2451 it was the last time it was filling. For example:
2461 .ad \" back to centering
2466 The escape @code{\p} will cause a break and cause the remaining text
2470 The @code{ss} request allows you to change the minimum size of a
2471 space between filled words.
2472 This request takes it's units as one twelfth of the
2473 spacewidth parameter for the current font. Initially both the word
2474 space size and the sentence space size are 12.
2476 When two arguments are given to the @code{ss} request, the second argument
2477 gives the sentence space size. If the second argument is not given, the
2478 sentence space size will be the same as the word space size.
2479 The sentence space size
2480 is used in two circumstances: if the end of a sentence occurs at the end
2481 of a line in fill mode, then both an inter-word space and a sentence
2482 space will be added; if two spaces follow the end of a sentence in the
2483 middle of a line, then the second space will be a sentence space. Note
2484 that the behaviour of @sc{Unix} troff will be exactly that exhibited by GNU
2485 troff if a second argument is never given to the @code{ss} request. In GNU
2486 troff, as in @sc{Unix} troff, you should always follow a sentence with either
2487 a newline or two spaces.
2491 The number registers @code{.ss} and @code{.sss} are
2492 the values of the parameters set by the first and second
2493 arguments of the @code{ss} request.
2496 The @code{ce} request will center text.
2497 While the @samp{ad c} request will also center text, it has the side
2498 effect of filling the text. The @code{.ce} request will not fill the
2500 This request causes a break.
2502 With no arguments, @code{ce} will fill the next line of text.
2503 The single argument @code{ce} takes is a number indicating the
2504 number of lines to be centered. With no argument centering is
2507 A common idiom is to turn on centering for a large number of lines,
2508 and then turn off centering when you are done with the centered text.
2509 This is useful for any request which takes a number of lines as an
2523 The @code{.ce} number register contains the number of lines remaining
2524 to be centered, as set by the @code{ce} request.
2529 A similar request is @code{rj} request which will justify unfilled
2530 text to the right margin. Its arguments are identical to the
2532 The @code{.rj} number register is
2533 the number of lines to be right-justified as set by the @code{rj}
2538 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
2539 @section Manipulating Hyphenation
2540 @cindex manipulating hyphenation
2541 @cindex hyphenation, manipulating
2544 As discussed in @ref{Hyphenation}, groff will hyphenate words.
2545 There are a number of ways to modify the how hyphenation is done.
2550 This hyphenation can be turned off with the @code{nh} request, and
2551 turned back on with the @code{hy} request. However, troff's
2552 hyphenation facilities are far more flexible than this. The @code{hy}
2553 request can be used to tell troff to restrict hypenation to certain
2554 cases. The request takes a single numeric argument.
2555 The current hyphenation restrictions can be found in the number
2560 The default argument, which
2561 indicates to hyphenate without restrictions.
2563 Do not hyphenate the last word on a page or column.
2565 Do not hyphenate the last two characters of a word.
2567 Do not hyphenate the first two characters of a word.
2573 The @code{hlm} request will
2574 set the maximum number of consecutive hyphenated lines to the value
2575 given as the first argument.
2577 negative, there is no maximum. The default value is -1.
2579 associated with the current environment. Only lines output from an
2580 environment count towards the maximum associated with that environment.
2581 Hyphens resulting from @code{\%} are counted; explicit hyphens are not.
2582 The current setting of this is available in the @code{.hlm} request.
2583 Also the number of immediately preceding consecutive hyphenated lines
2584 are available in the number register @code{.hlc}.
2587 The @code{hw} request allows you to specify how a specific word is
2588 to be hyphenated. It takes only one argument which is the word with
2589 hyphens at the hyphenation points. For example:
2590 @samp{.hw in-sa-lub-rious}.
2591 @c In old versions of troff there was a
2592 @c limited amount of space to store such information, fortunately,
2593 @c with groff, this is no longer a restriction.
2596 @cindex hyphenation character
2597 @cindex character, hyphenation
2598 You can also tell troff how to hyphenate words on the fly with the
2599 use of the @code{\%} escape, also known as the @dfn{hyphenation
2600 character}. Preceding a word with this character will prevent it
2601 from being hyphenated, putting it in a word will indicate to troff
2602 that the word may be hyphenated at that point. Note that this
2603 mechanism will only affect one word, if you want to change the
2604 hyphenation of a word for the entire document, use the @code{hw}
2608 The @code{hc} request allows you to change the hyphenation character.
2609 The character specified as an argument will then work the same as the
2610 @code{\%} escape, and, thus, no longer appear in the output. Without
2611 an argument it will return the hyphenation character to @code{\%}.
2614 To further customize hyphenation the @code{hpf} request will read in
2615 a file of hyphenation patterns.
2616 This file will be searched for in the
2617 same way that @file{tmac.@var{name}} is searched for when the
2618 @samp{-m@var{name}} option is specified.
2620 It should have the same format as the argument to the
2621 \patterns primitive in @TeX{}; the letters appearing in this file are
2622 interpreted as hyphenation codes.
2623 A @samp{%} character in the patterns file
2624 introduces a comment that continues to the end of the line.
2630 hyphenation patterns is associated with the current language set by the
2631 @code{hla} request. The @code{hpf} request is usually invoked by the
2632 @file{troffrc} file.
2635 @code{.hcode @var{c1 code1 c2 code2...}}
2636 Set the hyphenation code of character @var{c1} to code1 and that of
2637 @var{c2} to @var{code2}.
2638 A hyphenation code must be a single input character (not a
2639 special character) other than a digit or a space. Initially each
2640 lower-case letter has a hyphenation code, which is itself, and each
2641 upper-case letter has a hyphenation code which is the lower case
2646 The @code{hym} request will set the hyphenation margin to the value
2647 given as the first argument: when the current adjustment mode is not
2648 @samp{b}, the line will not be hyphenated if the line is no more than
2650 The default hyphenation margin is 0. The default scaling
2651 indicator for this request is m. The hyphenation margin is associated
2652 with the current environment. The current hyphenation margin is
2653 available in the @code{.hym} register.
2657 The @code{hys} request set the hyphenation space to the value given as
2658 the first argument: when the current adjustment mode is b, don't
2659 hyphenate the line if the line can be justified by adding no more than
2660 that amount of extra space to each word space. The default
2661 hyphenation space is 0. The default scaling indicator for this
2662 request is m. The hyphenation space is associated with the current
2663 environment. The current hyphenation space is available in the
2664 @code{.hys} register.
2667 The @code{shc} request will set the soft hyphen character to the
2668 argument given as an argument. If the argument is omitted, the soft
2669 hyphen character will be set to the default @code{\(hy}. The soft
2670 hyphen character is the character which will be inserted when a word
2671 is hyphenated at a line break. If the soft hyphen character does not
2672 exist in the font of the character immediately preceding a potential
2673 break point, then the line will not be broken at that point. Neither
2674 definitions (specified with the @code{char} request) nor translations
2675 (specified with the @code{tr} request) are considered when finding the soft
2681 The @code{hla} request will set the current hyphenation language to
2682 that given by the first argument. Hyphenation exceptions specified
2683 with the @code{hw} request and hyphenation patterns specified with the
2684 @code{hpf} request are both associated with the current hyphenation
2685 language. The @code{hla} request is usually invoked by the
2686 @file{troffrc} file. The current hyphenation language is available
2687 in the number register @code{.hla}.
2691 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
2692 @section Manipulating Spacing
2693 @cindex manipulating spacing
2694 @cindex spacing, manipulating
2698 The @code{sp} request will cause troff to space downwards the
2699 distance specified as the first argument. With no argument it will
2701 A negative argument will cause troff to move up the page the
2703 If the argument is preceded by a @samp{|} troff will move that
2704 distance from the top of the page.
2708 Often you may want your output to be double or triple spaced.
2709 The @code{ls} request will cause troff to output @var{n}-1 blank
2710 lines after each line of text, where @var{n} is the argument given to
2711 the @code{ls} request. With no argument troff will go back to single
2712 spacing. The number register @code{.L} contains the current line
2717 Sometimes, extra vertical spacing is only needed occasionaly,
2718 i.e. to allow space for a tall construct (like an equation).
2719 The @code{\x} escape will do this.
2720 The escape is given a numerical argument (like @samp{\x'3p'}).
2721 If this number is positive extra vertical space will be inserted
2722 below the current line. A negative number will add space above.
2723 If this escape is used multiple times on the same line, the maximum
2725 The @code{.a} number register contains the most recent
2726 extra vertical @strong{emph} line space.
2729 ... example of inline equation ...
2734 @cindex no-space mode
2735 @cindex mode, no-space
2736 Spacing (via either @code{sp} or via blank lines) can be disabled
2737 with the @code{ns} request. This will enable @dfn{no-space mode}.
2738 This mode will end when actual text is output or the @code{rs}
2739 request is encountered. No-space mode will also prevent requests to
2740 advance to the next page unless they are accompanied by a page number
2741 (@pxref{Page Control}, for more information.)
2744 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
2745 @section Tabs and Fields
2746 @cindex tabs and fields
2747 @cindex fields and tabs
2751 Tab stops are much like those on a typewriter: a tab character (or the
2752 @code{\t} escape) on input will cause horizontal motion to the next
2756 Tab stops can be changed with the @code{ta} request.
2757 This request takes a series of numbers as arguments which indicate
2758 where each tab stop is to be (overriding any previous settings).
2759 These can be specified absolutely,
2760 i.e. as the distance from the left margin.
2761 For example, the following wil set tab stops every one inch.
2764 .ta 1i 2i 3i 4i 5i 6i
2767 Tab stops can also be specified relatively (using a leading @samp{+})
2768 which means that the specified tab stop will be set that distance
2769 from the previous tab stop. For example the following is equivalent
2770 to the previous example.
2773 .ta 1i +1i +1i +1i +1i +1i
2776 After the specified tab stops repeat values may be set for tabs beyond
2777 the last one specified. This is most commonly used to specify tabs
2778 set at equal intervals. The compleat syntax for setting tabs is
2779 @code{ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2}
2780 @dots{} @var{rn}} This will set tabs at positions @var{n1}, @var{n2},
2781 @dots{}, @var{nn} and then set tabs at @var{nn}+@var{r1},
2782 @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} and then at
2783 @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, @dots{},
2784 @var{nn}+@var{rn}+@var{rn}, and so on. For example the following is,
2785 yet again, the same as the previous examples.
2791 The material in each tab column may be justified to the right or left
2792 or centered in the column. This is specified by appending an
2793 @samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop.
2794 The default justification is @samp{L}.
2801 The number register @code{.tabs} contains
2802 a string representation of the current tab settings suitable for use as
2803 an argument to the @code{ta} request.
2806 Normally troff will fill the space to the next tab stop with spaces.
2807 In some cases you may wish to change this. The @code{tc} request
2808 will do this. With no argument troff will revert to using spaces.
2814 Sometimes you may wish to use the @code{tc} request to fill a tab
2815 stop with a given character, but also, you want to use normal tab
2816 stops on the rest of the line. For this groff provides an alternate
2817 tab mechanism, called @dfn{leaders} which will do just that.
2818 They are used exclusively to produce a repeated run of characters to
2821 You can declare what character will be repeated with the @code{lc}
2822 request. If you do not give it an argument, the leaders will act the
2826 The difference is that a leader is invoked by using the @code{\a}
2829 @cindex table of contents
2830 @cindex contents, table of
2831 So for a table of contents you may want to have tab stops defined so
2832 that the section number is one tab stop, the title is the second with
2833 the remaining space being filled with a line of dots and then the
2834 page number slightly separated from the dots.
2846 Fields are a more general way of laying out tabular data.
2849 @node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial
2850 @section Character Translations
2851 @cindex character translations
2852 @cindex translations of characters
2857 The control character (@samp{.}) and the no-break control character
2858 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
2860 The single argument is the new character to be used, with no argument
2861 the normal control character is restored.
2865 The @code{eo} request will compleatly disable the escape mechanism.
2866 The @code{ec} request can be used to change the escape character from
2867 the default @samp{\} to what is specified as an argument.
2870 The @code{tr} request will translate characters.
2875 This is the same as the @code{tr} request except that the
2877 apply to text that is transparently throughput into a diversion with
2878 @code{\!}. @xref{Diversions}, for more information.
2889 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it
2890 will print @samp{a}.
2893 @node Line Layout, Page Layout, Character Translations, Programming Tutorial
2894 @section Line Layout
2896 @cindex layout, line
2899 @cindex dimensions, line
2900 @cindex line dimensions
2901 The following drawing shows the dimensions which troff uses for
2902 placing a line of output onto the page. They are labeled with the
2903 request which manipulates that dimension.
2908 -->| po |<-----------ll------------>|
2909 +----+----+----------------------+----+
2911 +----+----+----------------------+----+
2915 These dimensions are:
2920 @dfn{Page offset}--This is the leftmost postition of text on the final
2921 output. This can be adjusted with the @code{po} request, and the
2922 current setting can be found in the builtin number register @code{.o}
2923 Note, that this request does not cause a break, so changing the page
2924 offset in the middle of text being filled may not do what you expect.
2927 @dfn{Indentation}--This is the distance from the left margin where text
2928 will be printed. This can be adjusted with the @code{in} request, and
2929 the current setting can be found in the builtin number register.
2931 This request causes a break.
2935 There is also the request @code{ti} which will cause one output line
2936 to be indented, after which the indentation returns to 0.
2937 This request causes a break.
2938 The number register @code{.in} is the indent that applies to the
2939 current output line.
2943 @dfn{Line length}--This is the distance from the left margin to right
2944 margin. This can be adjusted with the @code{.ll} request, and the
2945 current setting can be found in the builtin number register @code{.l}
2946 Note, as the figure implies, line length is not affected by the current
2948 The number register @code{.ll} is
2949 the line length that applies to the current output line.
2955 A bunch of really boring text which should
2956 be indented from both margins.
2957 replace me with a better (and more) example!
2963 @node Page Layout, Page Control, Line Layout, Programming Tutorial
2964 @section Page Layout
2966 @cindex layout, page
2969 Troff provides some very primitive operations for controlling page
2974 Troff lets you specify the @dfn{page length} via the @code{pl} request.
2975 This is the length of the physical output page.
2976 The current setting can
2977 be found in the builtin number register @code{.p}. Note that this only
2978 specifies the size of the page, not the not the top and bottom margins.
2979 Those are not done by groff directly, @xref{Traps}, for further
2980 information on how to do this.
2985 Troff provides several operations which help in setting up top and
2986 bottom titles (or headers and footers)
2989 The @code{tl} request will print a @dfn{title line}, which consists
2990 of three parts: a left justified portion, a centered portion and a
2991 right justified portion. The argument to @code{tl} is specified as
2992 @code{'@var{left}'@var{center}'@var{right}'}
2993 The @samp{%} character is replaced with the current page number.
2997 The title line is printed using its own line length, which is
2998 specified with the @code{lt} request. The current setting of this is
2999 available in the @code{.lt} number register.
3002 The @code{pn} request will change the page number of the @emph{next}
3003 page. The only argument is the page number.
3007 The current page number is stored in the number register @code{%}.
3008 The number register @code{.pn} contains the
3009 number of the next page:
3010 either the value set by a @code{pn} request, or
3011 the number of the current page plus 1.
3014 The @code{pc} request will change the page number character (used by
3015 the @code{tl} request) to a different character. With no argument,
3016 this mechanism is disabled.
3019 @c distribute these through the text
3022 @node Page Control, Fonts, Page Layout, Programming Tutorial
3023 @section Page Control
3024 @cindex page control
3025 @cindex control, page
3029 To stop processing the current page, and move to the next page, you
3030 can invoke the @code{bp} request. This request will also cause a
3031 break. This request can also take an argument of what the next page
3034 between @code{bp} and @code{pn} is that @code{pn} does not cause a
3035 break or actually eject a page.
3041 .tl 'left top'center top'right top'
3048 Often you may want to make sure that you have a certain amount of
3049 space before a new page occurs. This is most useful to make sure
3050 that there is not a single @dfn{orphan} line left at the bottom of a
3051 page. The @code{ne} request will ensure that there is a certain
3052 distance, specified by the first argument, before the next page is
3053 triggered (@pxref{Traps}, for further information).
3054 The default unit for @code{ne} is v's and the default argument
3057 For example, to make sure that no fewer than 2 lines get orphaned,
3058 you can do the following before each paragraph.
3068 The @code{sv} is similar to the @code{ne} request, it reserves the
3069 specified amount of vertical space. If the desired amount of space
3070 exists before the next trap (bottom page boundary), the space will be
3071 output immediately. If there is not enough space, it is stored for
3072 later output via the @code{os} request.
3073 The default argument is 1v and the default units are v's.
3076 @node Fonts, Sizes, Page Control, Programming Tutorial
3083 Groff gives you the ability to switch fonts at any point in your
3084 text. There are two ways to do this, via the @code{ft} request and
3085 the @code{\f} escape.
3087 Fonts are generaly specified as uppercase strings, which are usually
3088 1 to 4 characters representing an abreviation of acronym of the font
3091 The basic set of fonts are R, I, B, and BI. These are Times Roman,
3092 Italic, Bold, and Bold Italic. There is also at least one symbol
3093 font which contains various special symbols (greek, mathematics).
3094 These latter fonts cannot be used directly, but should be used via an
3103 * Artificial Fonts::
3104 * Ligatures and Kerning::
3107 @node Changing Fonts, Font Families, Fonts, Fonts
3108 @subsection Changing Fonts
3109 @cindex changing fonts
3110 @cindex fonts, changing
3114 You can change fonts with both the @code{ft} request.
3115 With no arguments it
3116 will switch to the previous font (also known as P).
3127 The @code{\f} escape is useful for changing fonts in the middle of words
3130 eggs, bacon, \fBspam\fP and sausage.
3133 Both of the above examples will produce the same output.
3135 Sometimes when putting letters of different fonts, you need more or
3136 less space at such boundaries. There are two escapes to help with
3140 The @code{\/} escape
3141 increases the width of the preceding character so that the spacing
3142 between that character and the following character will be correct if
3143 the following character is a roman character. For example, if an italic
3144 f is immediately followed by a roman right parenthesis, then in many
3145 fonts the top right portion of the f will overlap the top left of the
3147 It is a good idea to use this escape sequence
3148 whenever an italic character is immediately followed by a roman
3149 character without any intervening space.
3151 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids this problem.
3154 The @code{\,} escape
3155 modifies the spacing of the following character so that the spacing
3156 between that character and the preceding character will correct if the
3157 preceding character is a roman character.
3159 to use this escape sequence whenever a roman character is immediately
3160 followed by an italic character without any intervening space.
3162 @c For example, inserting \, between the parenthesis and the f changes (f to (f.
3165 The @code{ftr} request will translate fonts, it is called as
3166 @samp{.ftr @var{F G}}, which
3167 Translate font @var{F} to @var{G}.
3168 Whenever a font named @var{F} is referred to in @code{\f}
3170 or in the @code{ft}, @var{ul}, @var{bd}, @var{cs}, @var{tkf},
3171 @var{special}, @var{fspecial}, @var{fp},
3172 or @var{sty} requests, font @var{G} will be used. If @var{G} is
3173 missing, or equal to @var{F} then font @var{F} will not be translated.
3176 @node Font Families, Font Positions, Changing Fonts, Fonts
3177 @subsection Font Families
3178 @cindex font families
3179 @cindex families, font
3182 Due to the variety of fonts available, groff has added the concept of
3183 font families. Each of these families has four styles (R, I, B and BI),
3185 The fonts are specified as the concatenation of the font family and
3186 style. Specifying a font without the family part will cause groff to
3187 use that style of the current family.
3188 By default, groff uses the Times family.
3190 This way, you can just use the basic four fonts and select a
3191 different font family on the command line.
3195 You can also switch font families with the @code{fam} request
3196 The current font family is available in the number register
3198 This is a string-valued register.
3216 @node Font Positions, Using Symbols, Font Families, Fonts
3217 @subsection Font Positions
3218 @cindex font positions
3219 @cindex positions, font
3222 For the sake of old phototypesetters and compatability with old
3223 versions of troff, groff has the concept of font
3224 @dfn{positions}, on which various fonts are mounted.
3225 The last one or two are reserved for the symbol font(s).
3228 New fonts can be mounted with the @code{fp} request.
3229 These numeric positions can then be referred to with font changing commands.
3230 When groff starts it is using font number one.
3245 (note that after these font changes have taken place the original
3249 The current font in use, as a font position.
3250 This can be useful to remember the current font, for later recall.
3254 ... lots 'o text ...
3259 The number of the next free font position is available in the number
3260 register @code{.fp}. This is useful when mounting a new font, like so:
3263 .fp \n[.fp] NEATOFONT
3267 Fonts not listed in the @file{DESC} file are automatically mounted on
3268 the next available font position when they are referenced.
3270 mountfed explicitly with the @code{fp} request on an unused font position, it
3271 should be mounted on the first unused font position, which can be found
3272 in the @code{.fp} register; although troff does not enforce this strictly,
3273 it will not allow a font to be mounted at a position whose number is
3274 much greater than that of any currently used position.
3276 The @code{fp} request has an optional third argument.
3277 This argument gives the
3278 external name of the font, which is used for finding the font
3279 description file. The second argument gives the internal name of the
3280 font which is used to refer to the font in troff after it has been
3281 mounted. If there is no third argument then the internal name will be
3282 used as the external name. This feature allows you to use fonts with
3283 long names in compatibility mode.
3287 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
3288 @subsection Using Symbols
3289 @cindex using symbols
3290 @cindex symbols, using
3295 Symbols can be inserted by using a special escape sequence.
3296 This escape is simply the escape character (a backslash) followed by
3297 an identifier. The symbol identifiers have to be two or more
3298 characters, since single characters conflict with all the other
3299 escapes. The identifier can be either preceded by a parenthesis if
3300 it is two character, or surrounded by square brackets.
3301 So, the symbol for pi can be produced either by @code{\(*p} or
3305 area = \(*p\fIr\fP\u2\d
3309 The escape @code{\C'@var{xxx}'} will typeset character named
3310 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
3311 But @code{\C} has the advantage that it is compatible with recent
3312 versions of ditroff and is available in compatibility mode.
3315 The escape @code{\N'@var{n}'} will typeset the character with code
3316 @var{n} in the current font. @var{n} can be any integer. Most devices only
3317 have characters with codes between 0 and 255. If the current font
3318 does not contain a character with that code, special fonts will not be
3319 searched. The @code{\N} escape sequence can be conveniently used on
3320 conjunction with the @code{char} request:
3323 .char \[phone] \f(ZD\N'37'
3326 The code of each character is given in the fourth column in the font
3327 description file after the charset command. It is possible to include
3328 unnamed characters in the font description file by using a name of
3329 @samp{---}; the @code{\N} escape sequence is the only way to use these.
3332 Each character has certain properties associated with it.
3333 These properties can be modified with the @code{cflags} request.
3334 The first argument is the the sum of the desired flags and the
3335 remaining arguments are the characters to have those properties.
3338 the character ends sentences (initially characters @samp{.?!} have this
3341 lines can be broken before the character (initially no characters have
3344 lines can be broken after the character (initially characters
3345 @samp{-\(hy\(em} have this property);
3347 the character overlaps horizontally (initially characters
3348 @samp{\(ul\(rn\(ru} have this property);
3350 the character overlaps vertically (initially character @samp{\(br} has
3353 an end of sentence character followed by any number of characters with
3354 this property will be treated as the end of a sentence if followed by a
3355 newline or two spaces; in other words the character is transparent for
3356 the purposes of end of sentence recognition; this is the same as having
3357 a zero space factor in @TeX{} (initially characters
3358 @samp{"')]*\(dg\(rq} have this property).
3362 You can create new characters with the @code{char} request. It is
3363 called as @samp{.char @var{c} @var{string}} Define character @var{c}
3364 to be @var{string}. Every time character @var{c} needs to be printed,
3365 @var{string} will be processed in a temporary environment and the
3366 result will be wrapped up into a single object. Compatibility mode
3367 will be turned off and the escape character will be set to \ while
3368 @var{string} is being processed. Any emboldening, constant spacing or
3369 track kerning will be applied to this object rather than to individual
3370 characters in @var{string}. A character defined by this request can
3371 be used just like a normal character provided by the output device.
3372 In particular other characters can be translated to it with the
3373 @code{tr} request; it can be made the leader character by the
3374 @code{lc} request; repeated patterns can be drawn with the character
3375 using the @code{\l} and @code{\L} escape sequences; words containing
3376 the character can be hyphenated correctly, if the @code{hcode} request
3377 is used to give the character a hyphenation code. There is a special
3378 anti-recursion feature: use of character within the character's
3379 definition will be handled like normal characters not defined with
3383 A character definition can be removed with the @code{rchar} request. Its
3384 arguments are the characters to be removed. This undoes the effect of
3385 a @code{char} request.
3387 @c distribute these through the text
3388 @xref{Special Characters}
3390 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
3391 @subsection Artificial Fonts
3392 @cindex artificial fonts
3393 @cindex fonts, artificial
3396 There are a number of requests for artificially creating fonts.
3397 These are largely vestigal remains from the days when output devices
3398 did not have a wide variety of fonts, and when nroff and troff were
3400 These are no longer necessary in GNU Troff.
3403 The @code{ul} request will print subsequent lines in italics on a
3404 device capable of it, or underline the text on an ascii output device.
3405 The single argument is the number of lines to be ``underlined,''
3406 with no argument, the next line will be underlined.
3409 The @code{cu} request is similar to @code{ul} ...
3412 The @code{uf} request will set the underline font used by @code{ul}
3416 The @code{bd} request artificially creates a bold font by printing
3417 each character twice, slightly offset.
3418 The first argument specifies the font to embolden, and the second is
3419 the number of basic units, minus one, by which the two characters
3420 will be offset. If the second argument is missing, emboldening will
3424 @node Ligatures and Kerning, , Artificial Fonts, Fonts
3425 @subsection Ligatures and Kerning
3426 @cindex ligatures and kerning
3427 @cindex kerning and ligatures
3434 The current ligature mode.
3438 If the font description file contains pairwise kerning information,
3439 characters from that font will be kerned. Kerning between two
3440 characters can be inhibited by placing a @code{\&} between them.
3445 If n is non-zero or missing, enable pairwise kerning, otherwise disable
3448 1 if pairwise kerning is enabled, 0 otherwise.
3452 Enable track kerning for font f. When the current font is f the width
3453 of every character will be increased by an amount between n1 and n2;
3454 when the current point size is less than or equal to s1 the width will
3455 be increased by n1; when it is greater than or equal to s2 the width
3456 will be increased by n2; when the point size is greater than or equal to
3457 s1 and less than or equal to s2 the increase in width is a linear
3458 function of the point size.
3461 @node Sizes, Strings, Fonts, Programming Tutorial
3467 Groff uses two dimensions with each line of text, type size and
3468 vertical spacing. The type size is the height from the text
3469 @dfn{baseline} to the top of the tallest character (decenders may drop
3470 below this baseline). Vertical spacing is the amount of space groff
3471 allows for a line of text, normally, this is about 20% larger than the
3472 current type size. Ratios smaller than this can result in
3473 hard-to-read text, larger that this, it will spread your text out more
3474 vertically (useful for term papers). By default, troff uses 10 point
3475 type on 12 point spacing.
3478 The difference between type size and vertical spacing is known, by
3479 typesetters, as @dfn{leading}.
3483 * Changing Type Sizes::
3484 * Fractional Type Sizes::
3487 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
3488 @subsection Changing Type Sizes
3489 @cindex changing type sizes
3490 @cindex type sizes, changing
3498 Using the @code{ps} request and the @code{\s} escape you can change
3499 the type size. The @code{vs} request will change the vertical
3500 spacing. The default unit for the @code{ps} and @code{vs} requests are
3502 The number registers @code{.s} and @code{.v} contain the current
3503 type size and vertical spacing.
3505 These requests take parameters in units of points. You can specify
3506 sizes as an absolute size, or as a relative change from the current
3507 size. The size 0 means go back to the previous size. With no
3508 argument it will revert to the previous size.
3515 wink, wink, \s+2nudge, nudge,\s+8 say no more!
3519 The @code{\s} escape may be called in a variety of ways.
3520 Much like other escapes there must be a way to determine where the
3521 argument ends and the text begins.
3522 Any of the following forms are valid:
3527 @code{\s+(@var{nn}},
3528 @code{\s-(@var{nn}},
3529 @code{\s[+@var{nnn}]},
3530 @code{\s[-@var{nnn}]},
3531 @code{\s+[@var{nnn}]},
3532 @code{\s-[@var{nnn}]}.
3534 Some devices may only have certain permissible sizes, in which case
3535 groff will round to the nearest permissible size.
3538 ... .sz macro example?? ...
3541 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
3542 @subsection Fractional Type Sizes
3543 @cindex fractional type sizes
3544 @cindex type sizes, fractional
3547 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
3548 @var{sizescale} is specified in the @file{DESC} file (1 by default.)
3549 There is a new scale indicator @samp{z} which has the effect of
3550 multiplying by @var{sizescale}. Requests and escape sequences in
3551 troff interpret arguments that represent a pointsize as being in units
3552 of scaled points, but they evaluate each such argument using a default
3553 scale indicator of @samp{z}. Arguments treated in this way are the
3554 argument to the @code{ps} request, the third argument to the @code{cs}
3555 request, the second and fourth arguments to the @code{tkf} request,
3556 the argument to the @code{\H} escape sequence, and those variants of
3557 the @code{\s} escape sequence that take a numeric expression as their
3560 For example, suppose @var{sizescale} is 1000; then a scaled point will be
3561 equivalent to a millipoint; the request @samp{.ps 10.25} is equivalent to
3562 @samp{.ps 10.25z} and so sets the pointsize to 10250 scaled points, which is
3563 equal to 10.25 points.
3565 The number register @code{\n(.s} returns the pointsize in points as
3566 decimal fraction. There is also a new number register @code{\n[.ps]}
3567 that returns the pointsize in scaled points.
3569 It would make no sense to use the @samp{z} scale indicator in a
3570 numeric expression whose default scale indicator was neither @samp{u}
3571 nor @samp{z}, and so troff disallows this. Similarily it would make
3572 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
3573 numeric expression whose default scale indicator was @samp{z}, and so
3574 troff disallows this as well.
3576 There is also new scale indicator @samp{s} which multiplies by the
3577 number of units in a scaled point. So, for example, @samp{\n[.ps]s}
3578 is equal to 1m. Be sure not to confuse the @samp{s} and @samp{z}
3585 Set the point size to @var{n} scaled points; @var{n} is a numeric
3586 expression with a default scale indicator of @samp{z}.
3589 The current pointsize in scaled points.
3592 The last-requested pointsize in scaled points.
3595 The last requested pointsize in points as a decimal fraction. This is a
3596 string-valued register.
3599 @c distribute these through the text
3602 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
3608 Groff has string variables, which are entirely for user convenience
3609 (i.e. there are no builtin strings). They are defined via the
3613 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
3617 They are interpolated, or expanded in-place, via the @code{\*} escape:
3620 The \*(UX Operating System
3626 The UNIXtm Operating System
3629 If the string named by the @code{\*} does not exist, the escape will
3630 be replaced by nothing.
3632 @cindex comments, with @code{ds}
3633 NOTE: Unlike other requests the third argument takes up the entire
3634 line including trailing spaces. This means that comments on a line
3635 with such a request can introduce unwanted space into a string.
3638 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" trademark of you-know-who
3641 Instead you should either put the comment on another line or
3642 have the comment escape adjacent with the end of the string.
3645 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" trademark of you-know-who
3648 If you need leading space you can start the string with a double
3649 quote. No trailing quote is needed, in fact any trailing quote is
3650 included in your string.
3654 .ds sign " Yours in a white wine sauce,
3658 @cindex appending to strings
3659 @cindex strings, appending
3660 You can also append onto a string with the @code{as} request.
3661 It works the same as the @code{ds} request except that it appends the
3662 second argument onto the string named by the first argument.
3665 .as sign " with shallots, onions and garlic,
3669 Strings are not limited to a sigle line of text. A string can span
3670 several lines by escaping the newlines with a backslash. The
3671 resulting string will be stored @emph{without} the newlines.
3674 .ds foo lots and lots \
3675 of text are on these \
3681 @code{.substring xx n1 [n2]}
3682 Replace the string in register@w{ }xx with the substring defined by the
3683 indices n1 and@w{ }n2. The first character in the string has index one.
3684 If n2 is omitted, it is taken to be equal to the string's length. If
3685 the index value n1 or n2 is negative or zero, it will be counted from
3686 the end of the string, going backwards: The last character has index@w{
3687 }0, the character before the last character has index@w{ }-1, etc.
3690 @cindex length of a string
3691 @cindex string, length of
3692 @code{.length xx string}
3693 Compute the length of string and return it in the number register@w{ }xx
3694 (which is not necessarily defined before).
3708 @c distribute these through the text
3710 @c distribute these through the text
3713 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
3714 @section Conditionals and Loops
3715 @cindex conditionals and loops
3716 @cindex loops and conditionals
3721 In @code{if} and @code{while} requests, there are several more operators
3727 True if the current page is even or odd numbered (respectively)
3730 True if the document is being processed by
3731 nroff (or an ascii device) or troff.
3732 @item '@var{xxx}'@var{yyy}'
3733 True if the string @var{xxx} is equal to the string @var{yyy}.
3734 Other characters can be used in place of the single quotes.
3736 The strings are `formatted' before being compared. (?)
3738 True if there is a number register named @var{xxx}.
3740 True if there is a string, macro, diversion, or request named @var{xxx}.
3742 True if there is a character @var{ch} available; @var{ch} is
3743 either an ASCII character or a special character @code{\(@var{ch}} or
3744 @code{\[@var{ch}]}; the condition will also be true if @var{ch} has been
3745 defined by the @code{char} request.
3754 @node if-else, while, Conditionals and Loops, Conditionals and Loops
3759 Troff has if-then-else constructs like other languages, although
3760 the formatting can be painful.
3763 The @code{if} request is troff's if statement, it is called as
3764 @samp{.if @var{expr} @var{anything}}, where @var{expr} is the
3765 expression to be evaluated,
3766 and @var{anything} (the remainder of the line)
3767 which will be executed if
3768 the @var{expr} evaluates to non-zero (true).
3769 @var{anything} will be interpreted as though it was on a line by
3771 @xref{Expressions}, for more info.
3773 Here are some examples:
3776 .if t .ls 2 \" double spacing in troff
3777 .if 0 .ab how'd this happen??
3782 An if-then-else is written using two requests @code{ie} and @code{el}
3783 the first request is the if part and the latter is the else part.
3792 In many cases you will want more than one request to be executed as a
3793 result of any of these requests, this can be done using the \@{ and
3795 The following example shows the possible ways to use these escapes.
3810 @c distribute these through the text
3813 @node while, , if-else, Conditionals and Loops
3819 Groff provides a looping construct using the @code{while} request,
3820 which is used much like the @code{if} (and related) requests.
3821 The first argument is an expression which will be evaluated.
3822 The @code{while} request will interpret the remainder of the line
3823 until the expression evaluates to 0 or false.
3827 .while (\na<9) \&\n+a,
3831 The preceding example produces:
3834 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
3839 The @code{break} request will
3840 @dfn{break} out of a while loop.
3841 Be sure not to confuse this with the @code{.br} request.
3842 The @code{continue} request will
3843 finish the current iteration of a while loop.
3845 @c distribute these through the text
3848 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
3849 @section Writing Macros
3850 @cindex writing macros
3851 @cindex macros, writing
3855 A macro is a collection of text and embedded commands which can be
3856 invoked multiple times. Macros are used for defining common operations.
3857 Macros are defined using the @code{de} request. This request takes
3858 a name for the macro as the first argument. Subsequent lines are
3859 copied into an internal buffer until the line @code{..} is
3860 encountered. The optional second argument to @code{de} can change
3863 For example, suppose at the beginning of each paragraph, you want
3864 cause a break, move down a partial line and indent the first line.
3865 Such a macro could be defined as follows:
3875 The @code{am} request works similarily to @code{de} except it appends
3876 onto the macro named by the first argument. So, if we decide we want
3877 our previously @code{P} macro to actually do indented instead of
3878 block paragraphs we can add the necessary code to our existing macro.
3887 @cindex aliases, macro
3888 @cindex macro aliases
3889 Macros can be aliased with the @code{als} request.
3906 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
3907 @subsection Copy-in Mode
3908 @cindex copy-in mode
3909 @cindex mode, copy-in
3917 When troff reads in the test for a macro or diversion it copies the
3918 text (including request lines) into an internal buffer, except for
3919 escapes. Escapes will be converted into an internal form, except for
3920 @code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which
3921 are evaluated and inserted into the text where the escape was located.
3922 This is known as @dfn{copy-in} mode.
3924 What this means is that you can specify when these escapes are to be
3925 evaluated (copy-in time or time of use) by insulating the escapes
3926 with an extra backslash.
3928 For example, the following will result in the numbers 20 and 10 being
3943 @node Parameters, , Copy-in Mode, Writing Macros
3944 @subsection Parameters
3950 The arguments to a macro can be examined using a variety of escapes.
3951 The number of arguments is available in the @code{.$} number register.
3952 Any individual argument can be retrieved with one of the following
3955 The escapes @code{\$@var{n}}, @code{\$(@var{nn}}
3956 and @code{\$[@var{nnn}]}
3957 will result in the @var{n}th, @var{nn}th or @var{nnn}th
3958 argument. Macros can have a unlimited number of arguments.
3959 Note that due to copy-in mode, you will want to have two backslashes
3960 on these in actual use, since you do not want them interpolated until
3961 the macro is actually invoked.
3964 The request @code{shift} will shift the arguments 1 position, or as
3965 many positions as specified by the first argument.
3966 After executing this request, argument
3967 @var{i} will become argument @var{i}-@var{n}; arguments 1 to @var{n}
3968 will no longer be available.
3969 Shifting by negative amounts is currently undefined.
3973 In some cases you will want to just use all of the arguments at once.
3974 For example if you pass the arguments along to another macro.
3975 The @code{\$*} escape is
3976 the concatenation of all the arguments separated by spaces.
3977 A similar escape is @code{\$@@},
3979 the concatenation of all the arguments with each surrounded
3980 by double quotes, and separated by spaces.
3984 The @code{\$0} escape is
3985 the name by which the current macro was invoked. The @code{als}
3986 request can make a macro have more than one name.
3990 .ie \\n(.$=1 .ds Vl Pre-Release Version
3991 .el .ds Vl Version \\$3, \\$4.
3995 This would be called as
4002 @c distribute these through the text
4003 @xref{Request Arguments}
4005 @node Page Motions, Drawing Functions, Writing Macros, Programming Tutorial
4006 @section Page Motions
4007 @cindex page motions
4008 @cindex motions, page
4012 Motions up and down the page can be done with the @code{sp} request.
4013 However, this causes a break so that the actual effect is to move to
4014 the left margin and then to the specified location.
4018 The request @code{mk} can be used to mark a location on a page, for
4019 movement to later. This request takes a register name as an
4020 argument in which to store the current page location, with no
4021 argument it will store the location in an internal register.
4022 The results of this can be used later by the @code{rt} or the
4023 @code{sp} request. The @code{rt} request will return
4024 @strong{upwards} to the location given in the register name given as
4025 an argument, with no argument it will return to the location marked
4026 with the @code{mk} request
4029 ... dual column example ...
4032 There are escapes which will give you much finer control of movements
4036 The @code{\v'@var{e}'} will let you do arbitrary vertical motion from
4037 the current location on the page. The argument @var{e} specifies the
4038 distance to move, positive is downwards and negative upwards. The
4039 default unit for this escape is vertical spaces, @code{v}'s. Beware,
4040 however, that troff will leave text processing to continue wherever
4041 the motion ends, so if you don't want to interfere with text
4042 processing, make sure your motions are balanced.
4044 There are some special case escapes for vertical motion.
4056 Horizontal motions can be done via the @code{\h'@var{e}'} escape.
4057 The expression @var{e} indicates how far to move: positive is
4058 rightwards and negative leftwards.
4060 There are a number of special case escapes for horizontal motion:
4064 An unbreakable and unpadable (i.e. not expanded during filling) space.
4065 (Note: it is a backslash followed by a space.)
4067 This produces an unbreakable space that stretches like a normal
4068 interword space when a line is adjusted.
4074 a space the size of a digit.
4078 Like @code{\&} except that it behaves like a character declared with
4079 the @code{cflags} request to be transparent for the purposes of end
4080 of sentence recognition.
4084 ... tex logo example ...
4088 @cindex width escape
4089 @cindex escape, width
4090 Often you will want to do horizontal movement based on the width of
4091 some arbitrary text (e.g. given as an argument to a macro).
4092 For that, there is the escape @code{\w'@var{text}'} which will
4093 interpolate to the width of the given @var{text} in basic units.
4096 ... strlen example ...
4099 Font changes may occur in @var{text} and not affect current settings.
4101 Also after use, @code{\w} sets several registers:
4108 The highest and lowest point, respectively, in @var{text}.
4113 Like the @code{st} and @code{sb} registers, but takes account of the
4114 heights and depths of characters.
4117 is set according to what kinds of characters occur in @var{text}.
4120 all short characters, no decenders or tall characters.
4126 both a decender and a tall character
4130 The amount of horizontal space (possibly negative) that should be
4131 added to the last character before a subscript.
4134 How far to right of the center of the last character in the @code{\w}
4135 argument, the center of an accent from a roman font should be
4136 placed over that character.
4144 @node Drawing Functions, Traps, Page Motions, Programming Tutorial
4145 @section Drawing Functions
4146 @cindex drawing functions
4147 @cindex functions for drawing
4150 Groff provides a number of ways to draw lines, and other figures on
4151 the page. Used in combination with the page motion commands
4152 (@pxref{Page Motions}, for more info) you can draw a wide variety of
4153 figures. However, for complex drawings these operations can be quite
4154 cumbersome, and it may be wise to use the pic preprocessor.
4155 @xref{gpic}, for more information.
4157 All drawing is done via escapes.
4160 The @code{\l} will draw a line rightwards from the current location.
4161 The full syntax for this escape is @samp{\l'@var{l}@var{c}'}, where
4162 @var{l} is the length of the line to be drawn, starting at the
4163 current location, positive numbers will draw to the right, and
4164 negative will draw towards the left. This can also be specified
4165 absolutely (i.e. with a leading |) which will draw back to the
4166 begining of the line.
4168 The optional second parameter @var{c} is a character to draw the line
4169 with. If this second argument is not specified, troff will use the
4170 underscore character.
4172 If you need to separate the two arguments (to prevent troff from
4173 interpreting a drawing character as a scaling indicator), you can
4174 separate them with @code{\&}.
4176 And now, for a useful example:
4180 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
4184 Note that this works by outputing a box rule (a vertical line), then
4185 the text given as an argument and then another box rule.
4186 Then the line drawing escapes both draw from the current location to
4187 the beginning of the @emph{input} line.
4190 Vertical lines are drawn using the @code{\L} escape. It's parameters
4191 are specified the same as the @code{\l} escape. If the length is
4192 positive, the movement will be downwards, and upwards for negative.
4193 The default character is the box rule character.
4194 As with the vertical motion escapes, text processing will blindly
4195 continue where the line ends.
4202 More flexible drawing functions are available via the @code{\D}
4203 escape. While the previous escapes will work on an ascii device,
4204 these escapes will not.
4207 @item \D'l @var{x} @var{y}'
4208 Draw a line from the current location to the relative point specified
4209 by @var{x}, @var{y}.
4212 ...revised box macro...
4216 Draw a circle with a diameter of @var{d} with the leftmost point at
4217 the current position.
4219 Draw a solid circle with the same parameters as an outlined circle.
4220 @item \D'e @var{dx} @var{dy}'
4221 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
4222 diameter of @var{dy} with the leftmost point at the current position.
4223 @item \D'E @var{dx} @var{dy}'
4224 Draw a solid elipse with the same parameters as an outlined elipse.
4225 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
4226 Draw an arc clockwise from the current location through the two
4227 specified locations.
4228 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4229 Draw a spline from the current location to
4230 @var{dx1}, @var{dy1} and then to @var{dx2}, @var{dy2}, and so on.
4232 Set the shade of gray to be used for filling solid objects to @var{n};
4233 @var{n} must be an integer between 0 and 1000, where 0 corresponds
4234 solid white and 1000 to solid black, and values in between correspond
4235 to intermediate shades of gray. This applies only to solid circles,
4236 solid ellipses and solid polygons. By default, a level of 1000 will
4238 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4239 Draw a polygon from the current location to @var{dx1}, @var{dy1}
4240 and then to @var{dx2}, @var{dy2} and so on. When the specified data
4241 points are exhausted, a line is drawn back to the starting point.
4244 ... box example (yes, again)...
4247 @itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
4248 Draw a solid polygon with the same parameters as an outlined polygon.
4251 ... shaded box example ...
4255 Set the current line thickness to @var{n} machine units.
4256 A value of zero selects the smallest available line thickness.
4263 @cindex pile, character
4264 @cindex character pile
4265 The @code{\b} escape will @dfn{pile} a sequence of characters
4266 vertically, and center it vertically on the current line.
4267 This can be used to build large brackets and braces.
4270 \b'\(lt\(bv\(lk\(bv\(lb'
4276 @node Traps, Diversions, Drawing Functions, Programming Tutorial
4281 Traps are locations, which, when reached, will call a specified macro.
4282 These traps can occur at a given location on the page, at a given
4283 location in the current diversion, after a certain number of input
4284 lines or at the end of input.
4287 Any of these traps can be changed after they have been set with the
4288 @code{ch} request. The first arguemnt is the name of the trap or
4289 macro, and the second is the new value for that trap.
4293 * Page Location Traps::
4295 * Input Line Traps::
4296 * End-of-input Traps::
4299 @node Page Location Traps, Diversion Traps, Traps, Traps
4300 @subsection Page Location Traps
4301 @cindex page location traps
4302 @cindex traps, page location
4305 Page location traps are frequently used for page headers and
4306 footers. The following is a simple example of this.
4309 .de hd \" Page header
4314 .de fo \" Page footer
4319 .wh 0 hd \" top of the page
4320 .wh -1i fo \" one inch from bottom
4324 The number register @code{.t} is the distance to the next trap.
4327 The location of a trap can be changed later on with the @code{ch}
4329 The first argument is the name of the macro to be invoked at the trap
4330 and the second argument is the new location for the trap.
4331 This is useful when you are building up footnotes in a diversion, and
4332 you need to allow more space at the bottom of the page for them.
4335 ... (simplified) footnote example ...
4342 The @code{vpt} request will enable vertical position traps if the argment is
4343 non-zero, disable them otherwise. Vertical position traps are traps
4344 set by the @code{wh} or @code{dt} requests. Traps set by the
4345 @code{it} request are not vertical position traps. The parameter that
4346 controls whether vertical position traps are enabled is global.
4347 Initially vertical position traps are enabled. The current setting of
4348 this is available in the number register @code{.vpt}.
4352 The number register @code{.trunc} contains
4353 the amount of vertical space truncated by the most recently
4354 sprung vertical position trap, or, if the trap was sprung by a
4355 @code{ne} request, minus the amount of vertical motion produced by
4356 the @code{ne} request. In other words, at the point a trap is
4357 sprung, it represents the difference of what the vertical position
4358 would have been but for the trap, and what the vertical position
4362 The number register @code{.ne} contains
4363 the amount of space that was needed in the last @code{ne} request that caused
4364 a trap to be sprung. Useful in conjunction with the @code{.trunc}
4365 register. @xref{Page Control}, for more information.
4369 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
4370 @subsection Diversion Traps
4371 @cindex diversion traps
4372 @cindex traps, diversion
4377 Traps can also be set @emph{within} a diversion using the @code{dt}
4378 request. Like @code{wh} the first argument is the location of the
4379 trap and the second argument is the name of the macro to be invoked.
4380 The number register @code{.t} will still work within diversions.
4381 @xref{Diversions}, for more information.
4383 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
4384 @subsection Input Line Traps
4385 @cindex input line traps
4386 @cindex traps, input line
4390 The @code{it} request will set an input line trap. The format for
4391 calling this is @samp{.it @var{n} @var{name}}, where @var{n} is the
4392 number of lines of input which may be read before @dfn{springing} the
4393 trap, @var{name} is the macro to be invoked. Request lines are not
4394 counted as input lines.
4396 For example, one possible use is to have a macro which will print the
4397 next @var{n} lines in a bold font.
4409 @node End-of-input Traps, , Input Line Traps, Traps
4410 @subsection End-of-input Traps
4411 @cindex end-of-input traps
4412 @cindex traps, end-of-input
4416 The @code{em} request will set a trap at the end of input.
4417 The macro specified as an arguement will be executed after the last
4418 line of the input file has been processed.
4420 For example, if your document had to have a section at the bottom of
4421 the last page for someone to approve you document, you could set it
4439 @node Diversions, Environments, Traps, Programming Tutorial
4444 In Troff you can divert text into a named storage area, due to the
4445 similarity to defining macros it is sometimes said to be stored in a
4446 macro. This is used for saving text for output at a later time,
4447 which is useful for keeping blocks of text on the same page,
4448 footnotes, tables of contents and indexes.
4452 Diversion is initiated by the @code{di} request, like the @code{de}
4453 request it takes an argument of a macro name to divert subsequent
4454 text to into. The @code{da} macro will append to an existing diversion.
4457 ... end-note example ...
4464 Diversions may be nested.
4465 The number register @code{.z} contains the name of the current diversion.
4466 The number register @code{.d} contains the current vertical place in
4467 the diversion. If not in a diversion it is the same as the register
4473 After compleating a diversion, the builtin number registers @code{dn}
4474 and @code{dl} contain the vertical and horizontal size of the diversion.
4477 .\" Center text both horizontally & vertically
4486 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
4501 Requests, macros and escapes are interpreted when read into a
4503 There are two ways to prevent this, either way will take the given
4504 text and @dfn{transparently} embed it into the diversion.
4505 The first method is to prefix the line with @code{\!}. This will
4506 cause the entire line to be transparently inserted into the diversion.
4507 This is useful for macros you do not want invoked until the diverted
4508 text is actually output.
4510 @c anything is read in copy mode. (what about \! ??)
4513 The other way is to surround the text by the @code{\?} escape, i.e.
4514 @samp{\?@var{anything}\?}.
4515 @var{anything} may not contain
4516 newlines; use @code{\!} if you want to embed newlines in a diversion. The
4517 escape sequence @code{\?} is also recognised in copy mode and turned into a
4518 single internal code; it is this code that terminates anything. Thus
4519 the followin example will print 4.
4525 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
4553 This request only exists in order to make it possible to make certain
4554 gross hacks work with GNU troff. It @dfn{unformats} the diversion
4555 specified as an argument in
4556 such a way that ASCII characters that were formatted and diverted
4557 will be treated like ordinary input characters when the diversion is
4558 reread. For example, the following will set register @code{n} to 1.
4572 @c distribute these through the text
4575 @node Environments, I/O, Diversions, Programming Tutorial
4576 @section Environments
4577 @cindex environments
4580 Often you will need to print some text in a certain format regardless
4581 of what may be in effect at the time, for example, in a trap invoked
4582 macro to print headers and footers.
4583 To solve this groff has @dfn{environments} in which text is processed.
4584 An environment contains most of the parameters that control
4585 text processing. You can switch amongst these environments, by
4586 default groff processes text in environment 0.
4587 The following is the information kept in an environment.
4593 Font (family and style)
4601 Partially collected lines
4604 These environments may be given arbitrary names
4605 (@pxref{Identifiers}, for more info.)
4606 Old versions of troff only had environments named 0, 1 and 2.
4610 The @code{ev} request will switch among these environments.
4611 The single argument is the name of the environment to switch to, with
4612 no argument groff will switch back to the previous enviroment.
4613 There is no limit on the number of named environments;
4614 they will be created the first time that they are referenced.
4615 The @code{.ev} number register contains
4616 the name or number of the current environment. This is a string-valued
4620 ... page break macro, revised ...
4632 \(dg Note the large, friendly letters.
4639 @node I/O, Postprocessor Access, Environments, Programming Tutorial
4645 The @code{so} request will read in the file given as an argument and
4646 include it in place of the @code{so} request. This is quite useful
4647 for large documents, i.e. keeping each chapter in a separate file.
4648 @xref{gsoelim}, for more information.
4651 The @code{mso} request is
4652 the same as the @code{so} request except that file is searched for in
4653 the same way that @file{tmac.@var{name}} is searched for when the
4654 @samp{-m@var{name}} option is specified.
4658 The @code{cf} and @code{trf} requests are to include a file.
4659 It will transparently output the contents of file filename. Each
4661 as it would be were it preceded by @code{\!}; however, the lines are not
4662 subject to copy-mode interpretation. If the file does not end with a
4663 newline, then a newline will be added. For example, you can define a
4664 macro @code{x} containing the contents of file @file{f}, using
4673 When used in a diversion, this will embed in the diversion an object
4674 which, when reread, will cause the contents of filename to be
4675 transparently copied through to the output. In @sc{Unix} troff, the contents
4676 of filename is immediately copied through to the output regardless of
4677 whether there is a current diversion; this behaviour is so anomalous
4678 that it must be considered a bug.
4681 With @code{trf}, unlike @code{cf}, the file cannot contain characters
4682 such as NUL that are not legal troff input characters.
4685 The @code{nx} request will force groff to continue processing of the
4686 file specified as an argument.
4689 The @code{rd} request will read from standard input, and include what
4690 is read as though it were part of the input file. Text is read until
4691 a blank line is encountered.
4693 @cindex form letters
4694 @cindex letters, form
4695 Using these two requests you can set up form letters.
4696 The form letter template is constructed like this:
4713 When this is run, the following file should be redirected in.
4714 Note that requests included in this file are executed as though they
4715 were part of the form letter. The last block of input is the
4716 @code{ex} requests which tells groff to stop processing. If this was
4717 not there, groff would not know when to stop.
4719 @cindex Beagle Brothers
4722 708 NW 19th Av., #202
4740 The @code{sy} request will allow arbitrary system commands to be
4741 executed from within a groff document. The output is not saved
4742 anyplace, so it is up to you to do so.
4744 For example, the following example will introduce the current time
4750 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
4751 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
4757 Note that this works by having the perl script (run by @code{sy})
4758 print out the @code{nr} requests which will set the number registers
4759 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in
4760 with the @code{so} request.
4763 The @code{systat} number register contains
4764 The return value of the @code{system()} function executed by the last
4768 The @code{open} request will open
4769 a file (specified as the second argument) for writing and associate
4770 the stream (specified as the first argument) with it.
4774 like open, but if filename exists, append to it instead of truncating
4779 @cindex copy-in mode
4780 @cindex mode, copy-in
4781 The @code{write} request will write to the file associated with the
4782 stream specified by the first argument. The stream must previously
4783 have been the subject of an open request. The remainder of the line
4784 in interpreted as the @code{ds} request reads its second argument: a
4785 leading @code{"} will be stripped, and it will be read in copy-in mode.
4788 The @code{close} request will
4789 close the stream specified by the first argument; stream will no
4790 longer be an acceptable argument to the @code{write} request.
4793 ... example of open write &c...
4797 The @code{\V} escape will
4798 interpolate the contents of the specified environment variable, as returned
4800 The argument to @code{\V} is specified as an identifier, i.e.
4801 @samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}.
4802 @code{\V} is interpreted in copy-in mode.
4805 @node Postprocessor Access, Miscellany, I/O, Programming Tutorial
4806 @section Postprocessor Access
4807 @cindex postprocessor access
4808 @cindex access of postprocessor
4811 There are two escapes which will allow you to give information
4812 directly to the postprocessor. This is particularly useful for
4813 embedding PostScript into your final document.
4816 The @code{\X} escape will embed its argument into the gtroff output
4817 preceded with @samp{x X}.
4820 The @code{\Y} escape is called with an identifier (i.e.
4822 @code{\Y(@var{xx}} or
4823 @code{\Y[@var{xxx}]}).
4824 This is approximately equivalent to @samp{\X'\*[@var{xxx}]'}.
4825 However the contents
4826 of the string or macro @var{xxx} are not interpreted; also it is
4828 @var{xxx} to have been defined as a macro and thus contain newlines
4829 (it is not permitted for the argument to @code{\X} to contain newlines).
4831 newlines requires an extension to the @sc{Unix} troff output format, and will
4832 confuse drivers that do not know about this extension.
4835 @c distribute these through the text
4836 @xref{Output Devices}
4838 @node Miscellany, Debugging, Postprocessor Access, Programming Tutorial
4843 This section contains parts of troff which cannot (yet) be
4844 categorized elsewhere in this manual.
4847 Line numbers can be printed in the left margin
4848 using the @code{nm} request.
4849 The first argument is the line number of the @emph{next} output line,
4851 The second argument indicates on which lines numbers will be printed,
4852 i.e. 5 means put line numbers on every 5 lines, this defaults to 1.
4853 The third argument is the space to be left between the number and
4854 your text, this defaults to 1.
4855 The fourth argument is the indentation of the line numbers.
4856 Without arguments, line numbers are turned off.
4859 The @code{nn} request will temporarily turn off line numbering.
4860 The first argument is the number of lines not to be numbered,
4861 this defaults to 1. (does this disable incrementing or display?)
4864 ... line numbering example ...
4868 margin characters can be automatically printed to the right of your
4869 text with the @code{mc} request.
4870 The first argument is the character to be printed and the second
4871 argument is the distance away from your text.
4872 With no arguments the margin characters are turned off.
4873 If this occurs before a break, no margin character will be printed.
4875 This is quite useful for indicating text that has changed, and, in
4876 fact, there are programs available for doing this (they are called
4877 @code{nrchbar} and @code{changebar} and can be found in any
4878 @samp{comp.sources.unix} archive.
4881 ... margin char example ...
4886 The @code{lf} primary reason for existence is to make debugging
4887 documents which are split into many files, which are then put
4888 together with @code{soelim} and other preprocessors.
4889 The first argument is the name of the file and the second argument is
4890 the input line number in that file.
4891 This way troff can produce error messages which are intelligible to
4895 ... example of soelim'ed doc ...
4898 @node Debugging, Implementation Differences, Miscellany, Programming Tutorial
4903 Troff is not easy to debug, but there are some useful features and
4904 strategies for debugging.
4909 The @code{tm} request will send output to stderr, this is very useful for
4910 printing debugging output.
4912 When doing something involved it is useful to leave the debugging
4913 statements in the code and have them turned on by a command line
4917 .if \n(DB .tm debugging output
4920 Then you can activate these statements with:
4928 The @code{ab} request is similar to the @code{tm} request,
4929 except that it will cause groff to stop processing.
4930 With no argument it will print @samp{User Abort}.
4933 The @code{ex} request will also cause groff to stop processing.
4935 If you know you are going to get many errors and no useful output,
4936 you can tell groff to suppress formatted output with the @samp{-z}
4940 The @code{pm} request will dump out the entire symbol table.
4943 The @code{pnr} request will print the names and contents of all
4944 currently defined number registers on stderr.
4947 The @code{ptr} request will
4948 print the names and positions of all traps (not including input line
4949 traps and diversion traps) on stderr. Empty slots in the page trap list
4950 are printed as well, because they can affect the priority of
4951 subsequently planted traps.
4954 The @code{fl} request instructs groff to flush its output immediately.
4955 The intention is that this be used when using troff interactively.
4956 There is little other use for it.
4959 The @code{backtrace} request will
4960 print a backtrace of the input stack on stderr.
4962 Groff has command line options for printing out more warnings
4963 (@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or
4964 an error occurs. The most verbose level of warnings is @samp{-ww}.
4968 The @code{warn} request controls the level of warnings checked for.
4969 The one argument is the sum of the numbers associated with each
4970 warning that is to be enabled; all other warnings will be disabled.
4971 The number associated with each warning is listed below.
4972 For example, @code{.warn 0} will disable all warnings, and
4973 @code{.warn 1} will disable
4974 all warnings except that about missing characters. If an argument
4975 is not given, all warnings will be enabled.
4976 The number register @code{.warn} contains the current warning level.
4979 @subsection Warnings
4982 The warnings that can be given by troff are divided into the
4983 following categories. The name associated with each warning is used
4984 by the @samp{-w} and @samp{-W} options; the number is used by the
4985 @code{warn} request, and by the @code{.warn} register.
4990 Non-existent characters. This is enabled by default.
4993 Invalid numeric expressions. This is enabled by default.
4996 In fill mode, lines which could not be broken so that
4997 their length was less than the line length. This is
5001 Missing or mismatched closing delimiters.
5004 Use of the @code{el} request with no matching @code{ie} request.
5005 @xref{if-else}, for more information.
5008 Meaningless scaling indicators.
5011 Out of range arguments.
5014 Dubious syntax in numeric expressions.
5019 Use of @code{di} or @code{da} without an argument when there is no
5023 Use of undefined strings, macros and diversions.
5024 When an undefined string, macro or diversion is used,
5025 that string is automatically defined as empty. So,
5026 in most cases, at most one warning will be given for
5030 Use of undefined number registers. When an undefined
5031 number register is used, that register is
5032 automatically defined to have a value of 0. a
5033 definition is automatically made with a value of 0.
5034 So, in most cases, at most one warning will be given
5035 for use of a particular name.
5038 Use of a tab character where a number was expected.
5042 Use of @code{\@}} where a number was expected.
5045 Requests that are missing non-optional arguments.
5048 Illegal input characters.
5051 Unrecognized escape sequences. When an unrecognized
5052 escape sequence is encountered, the escape character
5056 Missing space between a request or macro and its
5057 argument. This warning will be given when an
5058 undefined name longer than two characters is
5059 encountered, and the first two characters of the name
5060 make a defined name. The request or macro will not
5061 be invoked. When this warning is given, no macro is
5062 automatically defined. This is enabled by default.
5063 This warning will never occur in compatibility mode.
5066 Non-existent fonts. This is enabled by default.
5068 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
5069 intended that this covers
5070 all warnings that are useful with traditional macro packages.
5076 @node Implementation Differences, Summary, Debugging, Programming Tutorial
5077 @section Implementation Differences
5078 @cindex implementation differences
5079 @cindex differences in implementation
5082 GNU troff has a number of features which cause incompatibilites with
5083 documents written with old versions of troff.
5085 Long names cause some incompatibilities. @sc{Unix} troff will interpret
5095 as defining a string @samp{ab} with contents @samp{cd}.
5096 Normally, GNU troff will interpret this as a call of a macro named
5097 @code{dsabcd}. Also @sc{Unix} troff will interpret @code{\*[} or
5098 @code{\n[} as references to a string or number register called
5099 @samp{[}. In GNU troff, however, this will normally be interpreted as the
5100 start of a long name. In compatibility mode GNU troff will interpret
5101 these things in the traditional way. In compatibility mode, however,
5102 long names are not recognised. Compatibility mode can be turned on with
5103 the @samp{-C} command line option, and turned on or off with the
5105 The number register @code{.C} is 1 if compatibility mode is on, 0 otherwise.
5108 GNU troff does not allow the use of the escape sequences
5109 @samp{\| \^ \& \@} \@{ \@key{SP} \' \` \- \_ \! \% \c} in names of
5111 diversions, number registers, fonts or environments; @sc{Unix} troff does.
5112 The @code{\A} escape sequence may be helpful in avoiding use of these escape
5115 @cindex fractional point sizes
5116 @cindex point sizes, fractional
5118 Fractional pointsizes cause one noteworthy incompatibility. In @sc{Unix}
5119 troff the @code{ps} request ignores scale indicators and so
5125 will set the pointsize to 10 points, whereas in GNU troff it will set
5126 the pointsize to 10 scaled points.
5127 @xref{Fractional Type Sizes}, for more information.
5134 In GNU troff there is a fundamental difference between unformatted,
5135 input characters, and formatted, output characters. Everything that
5136 affects how an output character will be output is stored with the
5137 character; once an output character has been constructed it is
5138 unaffected by any subsequent requests that are executed, including
5139 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp}
5140 requests. Normally output characters are constructed
5141 from input characters at the moment immediately before the character is
5142 added to the current output line. Macros, diversions and strings are
5143 all, in fact, the same type of object; they contain lists of input
5144 characters and output characters in any combination. An output
5145 character does not behave like an input character for the purposes of
5146 macro processing; it does not inherit any of the special properties that
5147 the input character from which it was constructed might have had. For
5161 will print @samp{\\} in GNU troff; each pair of input backslashes is
5163 output backslash and the resulting output backslashes are not
5164 interpreted as escape
5165 characters when they are reread. @sc{Unix} troff would interpret them as
5166 escape characters when they were reread and would end up printing one
5168 The correct way to obtain a printable backslash is to use the
5170 sequence: this will always print a single instance of the current escape
5171 character, regardless of whether or not it is used in a diversion; it
5172 will also work in both GNU troff and @sc{Unix} troff. If you wish for some
5173 reason to store in a diversion an escape sequence that will be
5174 interpreted when the diversion is reread, you can either use the
5175 traditional @code{\!} transparent output facility, or, if this is unsuitable,
5176 the new @code{\?} escape sequence. @xref{Diversions}, for more information.
5179 @node Summary, , Implementation Differences, Programming Tutorial
5184 @node Preprocessors, Output Devices, Programming Tutorial, Top
5185 @chapter Preprocessors
5186 @cindex preprocessors
5188 This chapter covers describes all preprocessors that come with
5189 @code{groff} or which are freely available.
5202 @node geqn, gtbl, Preprocessors, Preprocessors
5203 @section @code{geqn}
5212 @node Invoking geqn, , geqn, geqn
5213 @subsection Invoking @code{geqn}
5214 @cindex invoking @code{geqn}
5215 @cindex @code{geqn}, invoking
5219 @node gtbl, gpic, geqn, Preprocessors
5220 @section @code{gtbl}
5229 @node Invoking gtbl, , gtbl, gtbl
5230 @subsection Invoking @code{gtbl}
5231 @cindex invoking @code{gtbl}
5232 @cindex @code{gtbl}, invoking
5235 @node gpic, ggrn, gtbl, Preprocessors
5236 @section @code{gpic}
5245 @node Invoking gpic, , gpic, gpic
5246 @subsection Invoking @code{gpic}
5247 @cindex invoking @code{gpic}
5248 @cindex @code{gpic}, invoking
5252 @node ggrn, grap, gpic, Preprocessors
5253 @section @code{ggrn}
5262 @node Invoking ggrn, , ggrn, ggrn
5263 @subsection Invoking @code{ggrn}
5264 @cindex invoking @code{ggrn}
5265 @cindex @code{ggrn}, invoking
5269 @node grap, grefer, ggrn, Preprocessors
5270 @section @code{grap}
5273 @code{grap} is available as an extra package, written by Ted Faber.
5277 @node grefer, gsoelim, grap, Preprocessors
5278 @section @code{grefer}
5279 @cindex @code{refer}
5280 @cindex @code{grefer}
5287 @node Invoking grefer, , grefer, grefer
5288 @subsection Invoking @code{grefer}
5289 @cindex invoking @code{grefer}
5290 @cindex @code{grefer}, invoking
5294 @node gsoelim, , grefer, Preprocessors
5295 @section @code{gsoelim}
5296 @cindex @code{soelim}
5297 @cindex @code{gsoelim}
5301 * Invoking gsoelim::
5304 @node Invoking gsoelim, , gsoelim, gsoelim
5305 @subsection Invoking @code{gsoelim}
5306 @cindex invoking @code{gsoelim}
5307 @cindex @code{gsoelim}, invoking
5311 @node Output Devices, File formats, Preprocessors, Top
5312 @chapter Output Devices
5313 @cindex output devices
5314 @cindex devices for output
5319 * Special Characters::
5328 @node Special Characters, grotty, Output Devices, Output Devices
5329 @section Special Characters
5330 @cindex special characters
5331 @cindex characters, special
5334 @c distribute these through the text
5337 @node grotty, grops, Special Characters, Output Devices
5338 @section @code{grotty}
5339 @cindex @code{grotty}
5347 @node Invoking grotty, , grotty, grotty
5348 @subsection Invoking @code{grotty}
5349 @cindex invoking @code{grotty}
5350 @cindex @code{grotty}, invoking
5354 @node grops, grodvi, grotty, Output Devices
5355 @section @code{grops}
5356 @cindex @code{grops}
5362 * Embedding PostScript::
5365 @node Invoking grops, Embedding PostScript, grops, grops
5366 @subsection Invoking @code{grops}
5367 @cindex invoking @code{grops}
5368 @cindex @code{grops}, invoking
5372 @node Embedding PostScript, , Invoking grops, grops
5373 @subsection Embedding PostScript
5374 @cindex embedding postscript
5375 @cindex postscript, embedding
5379 @node grodvi, grolj4, grops, Output Devices
5380 @section @code{grodvi}
5381 @cindex @code{grodvi}
5389 @node Invoking grodvi, , grodvi, grodvi
5390 @subsection Invoking @code{grodvi}
5391 @cindex invoking @code{grodvi}
5392 @cindex @code{grodvi}, invoking
5396 @node grolj4, grohtml, grodvi, Output Devices
5397 @section @code{grolj4}
5398 @cindex @code{grolj4}
5406 @node Invoking grolj4, , grolj4, grolj4
5407 @subsection Invoking @code{grolj4}
5408 @cindex invoking @code{grolj4}
5409 @cindex @code{grolj4}, invoking
5413 @node grohtml, gxditview, grolj4, Output Devices
5414 @section @code{grohtml}
5415 @cindex @code{grohtml}
5420 * Invoking grohtml::
5423 @node Invoking grohtml, , grohtml, grohtml
5424 @subsection Invoking @code{grohtml}
5425 @cindex invoking @code{grohtml}
5426 @cindex @code{grohtml}, invoking
5430 @node gxditview, , grohtml, Output Devices
5431 @section @code{gxditview}
5432 @cindex @code{gxditview}
5437 * Invoking gxditview::
5440 @node Invoking gxditview, , gxditview, gxditview
5441 @subsection Invoking @code{gxditview}
5442 @cindex invoking @code{gxditview}
5443 @cindex @code{gxditview}, invoking
5447 @node File formats, Installation, Output Devices, Top
5448 @chapter File formats
5449 @cindex file formats
5450 @cindex formats, file
5459 @node gtroff Output, Font Files, File formats, File formats
5460 @section @code{gtroff} Output
5461 @cindex @code{gtroff} output
5462 @cindex output, @code{gtroff}
5465 This section describes the format output by GNU troff. The output
5466 format used by GNU troff is very similar to that used by @sc{Unix}
5467 device-independent troff.
5469 The output format is ascii based, as opposed to a binary format (like
5471 The output format is 8 bit clean, thus single characters can have the
5472 eighth bit set, as can the names of fonts and special characters.
5474 The output format consists of single command characters with attached
5475 parameters which are separated from subsequent text by whitespace, or
5478 The names of characters and fonts an be of arbitrary length; drivers
5479 should not assume that they will be only two characters long (as
5480 device-independent troff did).
5482 When a character is to be printed, that character will always be in the
5484 Unlike device-independent troff, it is not necessary for
5485 drivers to search special fonts to find a character.
5494 @item @var{nn}@var{c}
5496 @var{xxx} is any sequence of characters terminated by a space or a
5497 newline; the first character should be printed at the current
5498 position, the the current horizontal position should be increased by
5499 the width of the first character, and so on for each character.
5500 The width of the character is that given in the font file,
5501 appropriately scaled for the current point size,
5502 and rounded so that it is a multiple of the horizontal resolution.
5503 Special characters cannot be printed using this command.
5505 This command is only allowed if the @samp{tcommand} line is present
5506 in the @file{DESC} file.
5507 @item u@var{n} @var{xxx}
5509 This is same as the @code{t} command except that after printing each
5510 character, the current horizontal position is increased by the sum of
5511 the width of that character and @code{n}.
5513 This command is only allowed if the @samp{tcommand} line is present
5514 in the @file{DESC} file.
5515 @item n@var{a}@var{b}
5518 The argument to the s command is in scaled points (units of points/n,
5519 where n is the argument to the sizescale command in the DESC file.)
5523 @item D@var{c} @var{x}@dots{}\n
5526 @subsection Device Control
5528 The @code{x} command is normally followed by a letter or word
5529 indicating the function to perform, followed by white space separated
5532 The first argument can be abreviated to the first letter.
5537 @item x res @var{n} @var{h} @var{v}
5539 The argument to the x Height command is also in scaled points.
5542 The first three output commands are guaranteed to be:
5550 For example, the input @samp{crunchy \fH\s+2frog\s0\fP!?} will produce:
5553 ... sample output here ...
5556 @subsection Drawing Functions
5558 The D drawing command has been extended. These extensions will only be
5559 used by GNU pic if the -x option is given.
5564 Set the shade of gray to be used for filling solid objects to n; n must
5565 be an integer between 0 and 1000, where 0 corresponds solid white and
5566 1000 to solid black, and values in between correspond to intermediate
5567 shades of gray. This applies only to solid circles, solid ellipses and
5568 solid polygons. By default, a level of 1000 will be used. Whatever
5569 color a solid object has, it should completely obscure everything
5570 beneath it. A value greater than 1000 or less than 0 can also be used:
5571 this means fill with the shade of gray that is currently being used for
5572 lines and text. Normally this will be black, but some drivers may
5573 provide a way of changing this.
5575 Draw a solid circle with a diameter of d with the leftmost point at the
5578 Draw a solid ellipse with a horizontal diameter of dx and a vertical
5579 diameter of dy with the leftmost point at the current position.
5580 @item Dp $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub
5582 Draw a polygon with, for $i = 1 ,..., n+1$, the i-th vertex at the
5583 current position $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. At
5584 the moment, GNU pic only uses this command to generate triangles and
5586 @item DP $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub
5588 Like Dp but draw a solid rather than outlined polygon.
5590 Set the current line thickness to n machine units. Traditionally @sc{Unix}
5591 troff drivers use a line thickness proportional to the current point
5592 size; drivers should continue to do this if no Dt command has been
5593 given, or if a Dt command has been given with a negative value of n. A
5594 zero value of n selects the smallest available line thickness.
5597 A difficulty arises in how the current position should be changed after
5598 the execution of these commands. This is not of great importance since
5599 the code generated by GNU pic does not depend on this. Given a drawing
5602 \D'c $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$'
5604 where c is not one of c, e, l, a or ~, @sc{Unix} troff will treat each of the
5605 $x sub i$ as a horizontal quantity, and each of the $y sub i$ as a
5606 vertical quantity and will assume that the width of the drawn object is
5607 $sum from i=1 to n x sub i$, and that the height is $sum from i=1 to n y
5608 sub i$. (The assumption about the height can be seen by examining the
5609 st and sb registers after using such a D command in a \w escape
5610 sequence.) This rule also holds for all the original drawing commands
5611 with the exception of De. For the sake of compatibility GNU troff also
5612 follows this rule, even though it produces an ugly result in the case of
5613 the Df, Dt, and, to a lesser extent, DE commands. Thus after executing
5614 a D command of the form
5616 Dc $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\n
5618 the current position should be increased by $( sum from i=1 to n x sub i
5619 , sum from i=1 to n y sub i )$.
5621 @subsection Line Continuation
5623 There is a continuation convention which permits the argument to the x X
5624 command to contain newlines: when outputting the argument to the x X
5625 command, GNU troff will follow each newline in the argument with a +
5626 character (as usual, it will terminate the entire argument with a
5627 newline); thus if the line after the line containing the x X command
5628 starts with +, then the newline ending the line containing the x X
5629 command should be treated as part of the argument to the x X command,
5630 the + should be ignored, and the part of the line following the + should
5631 be treated like the part of the line following the x X command.
5636 @node Font Files, , gtroff Output, File formats
5642 The groff font format is roughly a superset of the ditroff font
5643 format. Unlike the ditroff font format, there is no associated binary
5644 format. The font files for device name are stored in a directory
5645 @file{dev@var{name}}. There are two types of file: a device
5646 description file called @file{DESC} and for each font @samp{F} a font
5647 file called @file{F}. These are text files; there is no associated
5650 @subsection @file{DESC} file format
5653 The @file{DESC} file can contain the following types of line:
5657 There are @var{n} machine units per inch.
5659 The horizontal resolution is @var{n} machine units.
5661 The vertical resolution is @var{n} machine units.
5662 @item sizescale @var{n}
5663 The scale factor for pointsizes. By default this has a value of 1. One
5664 scaled point is equal to one point/@var{n}. The arguments to the
5665 @code{unitwidth} and @code{sizes} commands are given in scaled points.
5666 @xref{Fractional Type Sizes}, for more information.
5667 @item unitwidth @var{n}
5668 Quantities in the font files are given in machine units for fonts whose
5669 point size is @var{n} scaled points.
5671 This means that the postprocessor can handle the @code{t} and
5672 @code{u} output commands.
5673 @item sizes @var{s1} @var{s2}@dots{}@var{sn} 0
5674 This means that the device has fonts at @var{s1}, @var{s2},
5675 @dots{}@var{sn} scaled points. The list of sizes must be terminated
5676 by a 0. Each @var{si} can also be a range of
5677 sizes @var{m}-@var{n}. The list can extend over more than one line.
5678 @item styles @var{S1 S2@dots{}Sm}
5679 The first @var{m} font positions will be associated with styles
5680 @var{S1}@dots{}@var{Sm}.
5681 @item fonts @var{n} @var{F1 F2 F3@dots{}Fn}
5682 Fonts @var{F1@dots{}Fn} will be mounted in the font positions
5683 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m}
5684 is the number of styles. This command may extend over more than one
5685 line. A font name of 0 will cause no font to be mounted on the
5686 corresponding font position.
5687 @item family @var{fam}
5688 The default font family is @var{fam}.
5690 This line and everything following in the file are ignored. It is
5691 allowed for the sake of backwards compatibility.
5694 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
5695 are compulsory. Other commands are ignored by troff but may be used
5696 by postprocessors to store arbitrary information about the device in
5697 the @file{DESC} file.
5700 @subsection Font file format
5702 A font file has two sections. The first section is a sequence of lines
5703 each containing a sequence of blank delimited words; the first word in
5704 the line is a key, and subsequent words give a value for that key.
5708 The name of the font is @var{F}.
5709 @item spacewidth @var{n}
5710 The normal width of a space is @var{n}.
5712 The characters of the font have a slant of @var{n} degrees.
5713 (Positive means forward.)
5714 @item ligatures @var{lig1} @var{lig2}@dots{}@var{lign} [0]
5715 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
5716 possible ligatures are ff, fi, fl and ffl. For backwards
5717 compatibiliy, the list of ligatures may be terminated with a 0. The
5718 list of ligatures may not extend over more than one line.
5720 The font is special; this means that when a character is requested that
5721 is not present in the current font, it will be searched for in any
5722 special fonts that are mounted.
5725 Other commands are ignored by troff but may be used by postprocessors to
5726 store arbitrary information about the font in the font file.
5728 The first section can contain comments which start with the # character
5729 and extend to the end of a line.
5731 The second section contains one or two subsections. It must contain a
5732 @code{charset} subsection and it may also contain a @code{kernpairs}
5733 subsection. These subsections can appear in any order. Each
5734 subsection starts with a word on a line by itself.
5736 The word @code{charset} starts the @code{charset} subsection. The
5737 @code{charset} line is followed by a sequence of lines. Each line
5738 gives information for one character. A line comprises a number of
5739 fields separated by blanks or tabs. The format is
5742 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
5745 @var{name} identifies the character: if @var{name} is a single
5746 character @var{c} then it corresponds to the groff input character
5747 @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is a
5748 single character, then it corresponds to the groff input character
5749 @samp{\@var{c}}; otherwise it corresponds to the groff input character
5750 @samp{\[@var{name}]} (if it is exactly two characters @var{xx} it can
5751 be entered as @samp{\(@var{xx}}.) Groff supports eight bit characters;
5752 however some utilities has difficulties with eight bit characters.
5753 For this reason, there is a convention that the @var{name}
5754 @samp{char@var{n}} is equivalent to the single character whose code is
5755 @var{n}. For example, @samp{char163} would be equivalent to the
5756 character with @var{code} 163 which is the pounds sterling sign in ISO
5757 Latin-1 character set. The name @samp{---} is special and indicates
5758 that the character is unnamed; such characters can only be used by
5759 means of the @code{\N} escape sequence in troff.
5761 The @var{type} field gives the character type:
5765 means the character has an descender, for example, p;
5767 means the character has an ascender, for example, b;
5769 means the character has both an ascender and a descender, for example,
5773 The @var{code} field gives the code which the postprocessor uses to
5774 print the character. The character can also be input to groff using
5775 this code by means of the @code{\N} escape sequence. The code can be any
5776 integer. If it starts with a 0 it will be interpreted as octal; if it
5777 starts with 0x or 0X it will be intepreted as hexdecimal.
5779 Anything on the line after the @var{code} field will be ignored.
5781 The @var{metrics} field has the form:
5784 @var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]}
5787 There must not be any spaces between these subfields. Missing
5788 subfields are assumed to be 0. The subfields are all decimal
5789 integers. Since there is no associated binary format, these values
5790 are not required to fit into a variable of type @samp{char} as they
5791 are in ditroff. The @var{width} subfields gives the width of the
5792 character. The @var{height} subfield gives the height of the
5793 character (upwards is positive); if a character does not extend above
5794 the baseline, it should be given a zero height, rather than a negative
5795 height. The @var{depth} subfield gives the depth of the character,
5796 that is, the distance below the lowest point below the baseline to
5797 which the character extends (downwards is positive); if a character
5798 does not extend below above the baseline, it should be given a zero
5799 depth, rather than a negative depth. The @var{italic_correction}
5800 subfield gives the amount of space that should be added after the
5801 character when it is immediately to be followed by a character from a
5802 roman font. The @var{left_italic_correction} subfield gives the
5803 amount of space that should be added before the character when it is
5804 immediately to be preceded by a character from a roman font. The
5805 @var{subscript_correction} gives the amount of space that should be
5806 added after a character before adding a subscript. This should be less
5807 than the italic correction.
5809 A line in the @code{charset} section can also have the format
5815 This indicates that @var{name} is just another name for the character
5816 mentioned in the preceding line.
5818 The word @code{kernpairs} starts the kernpairs section. This contains a
5819 sequence of lines of the form:
5825 This means that when character @var{c1} appears next to character
5826 @var{c2} the space between them should be increased by @var{n}. Most
5827 entries in kernpairs section will have a negative value for @var{n}.
5831 @node Installation, Request Index, File formats, Top
5832 @chapter Installation
5833 @cindex installation
5837 @node Request Index, Register Index, Installation, Top
5838 @chapter Request Index
5843 @node Register Index, String Index, Request Index, Top
5844 @chapter Register Index
5849 @node String Index, Macro Index, Register Index, Top
5850 @chapter String Index
5854 @node Macro Index, Program Index, String Index, Top
5855 @chapter Macro Index
5859 @node Program Index, Concept Index, Macro Index, Top
5860 @chapter Program Index
5866 @node Concept Index, , Program Index, Top
5867 @chapter Concept Index