1 \input texinfo @c -*-texinfo-*-
4 @c If you use texinfo.tex 1999-09-25.10 or earlier please convert this
5 @c manual with `texi2dvi -e groff.texinfo' due to a bug in expanding
6 @c user-defined macros.
9 @c %**start of header (This is for running Texinfo on a region.)
11 @settitle The GNU Troff Manual
12 @setchapternewpage odd
13 @footnotestyle separate
14 @c %**end of header (This is for running Texinfo on a region.)
17 @c We use the following indices:
20 @c findex: requests, escapes, and functions
22 @c kindex: commands in font files
23 @c pindex: programs and files
24 @c tindex: environment variables
25 @c maindex: macros and strings
26 @c glindex: glyph names
29 @c tindex and cindex are merged.
37 @macro Deffn{category, name, arg}
38 @deffn \category\ @t{\name\} \arg\
45 @macro Deffnx{category, name, arg}
46 @deffnx \category\ @t{\name\} \arg\
53 @macro Defmac{name, arg}
54 @defmac @t{\name\} \arg\
61 @macro Defmacx{name, arg}
62 @defmacx @t{\name\} \arg\
70 @c XXX comment all examples
73 @dircategory Miscellaneous
75 * Groff: (groff). The GNU troff document formatting system.
88 This Info file documents GNU troff version 1.16.
90 Published by the Free Software Foundation
91 59 Temple Place, Suite 330
92 Boston, MA 02111-1307 USA
94 Copyright (C) 1994-2000 Free Software Foundation, Inc.
96 Permission is granted to make and distribute verbatim copies of this
97 manual provided the copyright notice and this permission notice are
98 preserved on all copies.
101 Permission is granted to process this file through TeX and print the
102 results, provided the printed document carries copying permission notice
103 identical to this one except for the removal of this paragraph (this
104 paragraph not being relevant to the printed manual).
107 Permission is granted to copy and distribute modified versions of this
108 manual under the conditions for verbatim copying, provided that the
109 entire resulting derived work is distributed under the terms of a
110 permission notice identical to this one.
112 Permission is granted to copy and distribute translations of this manual
113 into another language, under the above conditions for modified versions,
114 except that this permission notice may be stated in a translation
115 approved by the Foundation.
117 Permission is granted to copy and distribute modified versions of this
118 manual under the conditions for verbatim copying, provided also that the
119 section entitled ``GNU General Public License'' is included exactly as
120 in the original, and provided that the entire resulting derived work is
121 distributed under the terms of a permission notice identical to this
124 Permission is granted to copy and distribute translations of this manual
125 into another language, under the above conditions for modified versions,
126 except that the section entitled ``GNU General Public License'' may be
127 included in a translation approved by the Free Software Foundation
128 instead of in the original English.
134 @subtitle The GNU implementation of @code{troff}
135 @subtitle Edition 1.16
136 @subtitle Spring 2000
137 @author by Trent A.@w{ }Fisher
138 @author and Werner Lemberg
140 @c Include the Distribution inside the titlepage environment so
141 @c that headings are turned off. Headings on and off do not work.
144 @vskip 0pt plus 1filll
145 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
147 Version 1.16 of @code{groff}, @*
150 Published by the Free Software Foundation @*
151 59 Temple Place, Suite 330 @*
152 Boston, MA 02111-1307 USA
155 Permission is granted to make and distribute verbatim copies of this
156 manual provided the copyright notice and this permission notice are
157 preserved on all copies.
159 Permission is granted to copy and distribute modified versions of this
160 manual under the conditions for verbatim copying, provided also that the
161 section entitled ``GNU General Public License'' is included exactly as
162 in the original, and provided that the entire resulting derived work is
163 distributed under the terms of a permission notice identical to this
166 Permission is granted to copy and distribute translations of this manual
167 into another language, under the above conditions for modified versions,
168 except that the section entitled ``GNU General Public License'' may be
169 included in a translation approved by the Free Software Foundation
170 instead of in the original English.
172 Cover art by Etienne Suvasa.
178 @node Top, Copying, (dir), (dir)
181 This Info file documents groff version 1.16, the GNU implementation of
182 the troff typesetting system.
184 This is an in-progress document; contributions, comments, or
185 contributions are welcome. Send them to bug-groff@@gnu.org.
192 * Tutorial for Macro Users::
194 * Programming Tutorial::
199 * Request and Escape Index::
202 * Macro and String Index::
204 * Font File Keyword Index::
205 * Program and File Index::
211 @node Copying, Introduction, Top, Top
213 @unnumbered GNU GENERAL PUBLIC LICENSE
214 @center Version 2, June 1991
217 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
218 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
220 Everyone is permitted to copy and distribute verbatim copies of this
221 license document, but changing it is not allowed.
224 @unnumberedsec Preamble
226 The licenses for most software are designed to take away your freedom to
227 share and change it. By contrast, the GNU General Public License is
228 intended to guarantee your freedom to share and change free software --
229 to make sure the software is free for all its users. This General
230 Public License applies to most of the Free Software Foundation's
231 software and to any other program whose authors commit to using it.
232 (Some other Free Software Foundation software is covered by the GNU
233 Library General Public License instead.) You can apply it to your
236 When we speak of free software, we are referring to freedom, not price.
237 Our General Public Licenses are designed to make sure that you have the
238 freedom to distribute copies of free software (and charge for this
239 service if you wish), that you receive source code or can get it if you
240 want it, that you can change the software or use pieces of it in new
241 free programs; and that you know you can do these things.
243 To protect your rights, we need to make restrictions that forbid anyone
244 to deny you these rights or to ask you to surrender the rights. These
245 restrictions translate to certain responsibilities for you if you
246 distribute copies of the software, or if you modify it.
248 For example, if you distribute copies of such a program, whether gratis
249 or for a fee, you must give the recipients all the rights that you have.
250 You must make sure that they, too, receive or can get the source code.
251 And you must show them these terms so they know their rights.
253 We protect your rights with two steps: (1)@w{ }copyright the software,
254 and (2)@w{ }offer you this license which gives you legal permission to
255 copy, distribute and/or modify the software.
257 Also, for each author's protection and ours, we want to make certain
258 that everyone understands that there is no warranty for this free
259 software. If the software is modified by someone else and passed on, we
260 want its recipients to know that what they have is not the original, so
261 that any problems introduced by others will not reflect on the original
262 authors' reputations.
264 Finally, any free program is threatened constantly by software patents.
265 We wish to avoid the danger that redistributors of a free program will
266 individually obtain patent licenses, in effect making the program
267 proprietary. To prevent this, we have made it clear that any patent
268 must be licensed for everyone's free use or not licensed at all.
270 The precise terms and conditions for copying, distribution and
274 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
277 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
282 This License applies to any program or other work which contains a
283 notice placed by the copyright holder saying it may be distributed under
284 the terms of this General Public License. The ``Program'', below,
285 refers to any such program or work, and a ``work based on the Program''
286 means either the Program or any derivative work under copyright law:
287 that is to say, a work containing the Program or a portion of it, either
288 verbatim or with modifications and/or translated into another language.
289 (Hereinafter, translation is included without limitation in the term
290 ``modification''.) Each licensee is addressed as ``you''.
292 Activities other than copying, distribution and modification are not
293 covered by this License; they are outside its scope. The act of running
294 the Program is not restricted, and the output from the Program is
295 covered only if its contents constitute a work based on the Program
296 (independent of having been made by running the Program). Whether that
297 is true depends on what the Program does.
300 You may copy and distribute verbatim copies of the Program's source code
301 as you receive it, in any medium, provided that you conspicuously and
302 appropriately publish on each copy an appropriate copyright notice and
303 disclaimer of warranty; keep intact all the notices that refer to this
304 License and to the absence of any warranty; and give any other
305 recipients of the Program a copy of this License along with the Program.
307 You may charge a fee for the physical act of transferring a copy, and
308 you may at your option offer warranty protection in exchange for a fee.
311 You may modify your copy or copies of the Program or any portion of it,
312 thus forming a work based on the Program, and copy and distribute such
313 modifications or work under the terms of Section@w{ }1 above, provided
314 that you also meet all of these conditions:
318 You must cause the modified files to carry prominent notices stating
319 that you changed the files and the date of any change.
322 You must cause any work that you distribute or publish, that in whole or
323 in part contains or is derived from the Program or any part thereof, to
324 be licensed as a whole at no charge to all third parties under the terms
328 If the modified program normally reads commands interactively when run,
329 you must cause it, when started running for such interactive use in the
330 most ordinary way, to print or display an announcement including an
331 appropriate copyright notice and a notice that there is no warranty (or
332 else, saying that you provide a warranty) and that users may
333 redistribute the program under these conditions, and telling the user
334 how to view a copy of this License. (Exception: if the Program itself
335 is interactive but does not normally print such an announcement, your
336 work based on the Program is not required to print an announcement.)
339 These requirements apply to the modified work as a whole. If
340 identifiable sections of that work are not derived from the Program, and
341 can be reasonably considered independent and separate works in
342 themselves, then this License, and its terms, do not apply to those
343 sections when you distribute them as separate works. But when you
344 distribute the same sections as part of a whole which is a work based on
345 the Program, the distribution of the whole must be on the terms of this
346 License, whose permissions for other licensees extend to the entire
347 whole, and thus to each and every part regardless of who wrote it.
349 Thus, it is not the intent of this section to claim rights or contest
350 your rights to work written entirely by you; rather, the intent is to
351 exercise the right to control the distribution of derivative or
352 collective works based on the Program.
354 In addition, mere aggregation of another work not based on the Program
355 with the Program (or with a work based on the Program) on a volume of a
356 storage or distribution medium does not bring the other work under the
357 scope of this License.
360 You may copy and distribute the Program (or a work based on it, under
361 Section@w{ }2) in object code or executable form under the terms of
362 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
367 Accompany it with the complete corresponding machine-readable source
368 code, which must be distributed under the terms of Sections@w{ }1 and@w{
369 }2 above on a medium customarily used for software interchange; or,
372 Accompany it with a written offer, valid for at least three years, to
373 give any third party, for a charge no more than your cost of physically
374 performing source distribution, a complete machine-readable copy of the
375 corresponding source code, to be distributed under the terms of
376 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
380 Accompany it with the information you received as to the offer to
381 distribute corresponding source code. (This alternative is allowed only
382 for noncommercial distribution and only if you received the program in
383 object code or executable form with such an offer, in accord with
384 Subsection@w{ }b above.)
387 The source code for a work means the preferred form of the work for
388 making modifications to it. For an executable work, complete source
389 code means all the source code for all modules it contains, plus any
390 associated interface definition files, plus the scripts used to control
391 compilation and installation of the executable. However, as a special
392 exception, the source code distributed need not include anything that is
393 normally distributed (in either source or binary form) with the major
394 components (compiler, kernel, and so on) of the operating system on
395 which the executable runs, unless that component itself accompanies the
398 If distribution of executable or object code is made by offering access
399 to copy from a designated place, then offering equivalent access to copy
400 the source code from the same place counts as distribution of the source
401 code, even though third parties are not compelled to copy the source
402 along with the object code.
405 You may not copy, modify, sublicense, or distribute the Program except
406 as expressly provided under this License. Any attempt otherwise to
407 copy, modify, sublicense or distribute the Program is void, and will
408 automatically terminate your rights under this License. However,
409 parties who have received copies, or rights, from you under this License
410 will not have their licenses terminated so long as such parties remain
414 You are not required to accept this License, since you have not signed
415 it. However, nothing else grants you permission to modify or distribute
416 the Program or its derivative works. These actions are prohibited by
417 law if you do not accept this License. Therefore, by modifying or
418 distributing the Program (or any work based on the Program), you
419 indicate your acceptance of this License to do so, and all its terms and
420 conditions for copying, distributing or modifying the Program or works
424 Each time you redistribute the Program (or any work based on the
425 Program), the recipient automatically receives a license from the
426 original licensor to copy, distribute or modify the Program subject to
427 these terms and conditions. You may not impose any further restrictions
428 on the recipients' exercise of the rights granted herein. You are not
429 responsible for enforcing compliance by third parties to this License.
432 If, as a consequence of a court judgment or allegation of patent
433 infringement or for any other reason (not limited to patent issues),
434 conditions are imposed on you (whether by court order, agreement or
435 otherwise) that contradict the conditions of this License, they do not
436 excuse you from the conditions of this License. If you cannot
437 distribute so as to satisfy simultaneously your obligations under this
438 License and any other pertinent obligations, then as a consequence you
439 may not distribute the Program at all. For example, if a patent license
440 would not permit royalty-free redistribution of the Program by all those
441 who receive copies directly or indirectly through you, then the only way
442 you could satisfy both it and this License would be to refrain entirely
443 from distribution of the Program.
445 If any portion of this section is held invalid or unenforceable under
446 any particular circumstance, the balance of the section is intended to
447 apply and the section as a whole is intended to apply in other
450 It is not the purpose of this section to induce you to infringe any
451 patents or other property right claims or to contest validity of any
452 such claims; this section has the sole purpose of protecting the
453 integrity of the free software distribution system, which is implemented
454 by public license practices. Many people have made generous
455 contributions to the wide range of software distributed through that
456 system in reliance on consistent application of that system; it is up to
457 the author/donor to decide if he or she is willing to distribute
458 software through any other system and a licensee cannot impose that
461 This section is intended to make thoroughly clear what is believed to be
462 a consequence of the rest of this License.
465 If the distribution and/or use of the Program is restricted in certain
466 countries either by patents or by copyrighted interfaces, the original
467 copyright holder who places the Program under this License may add an
468 explicit geographical distribution limitation excluding those countries,
469 so that distribution is permitted only in or among countries not thus
470 excluded. In such case, this License incorporates the limitation as if
471 written in the body of this License.
474 The Free Software Foundation may publish revised and/or new versions of
475 the General Public License from time to time. Such new versions will be
476 similar in spirit to the present version, but may differ in detail to
477 address new problems or concerns.
479 Each version is given a distinguishing version number. If the Program
480 specifies a version number of this License which applies to it and ``any
481 later version'', you have the option of following the terms and
482 conditions either of that version or of any later version published by
483 the Free Software Foundation. If the Program does not specify a version
484 number of this License, you may choose any version ever published by the
485 Free Software Foundation.
488 If you wish to incorporate parts of the Program into other free programs
489 whose distribution conditions are different, write to the author to ask
490 for permission. For software which is copyrighted by the Free Software
491 Foundation, write to the Free Software Foundation; we sometimes make
492 exceptions for this. Our decision will be guided by the two goals of
493 preserving the free status of all derivatives of our free software and
494 of promoting the sharing and reuse of software generally.
504 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
505 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
506 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
507 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
508 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
509 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
510 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
511 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
512 NECESSARY SERVICING, REPAIR OR CORRECTION.
515 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
516 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
517 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
518 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
519 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
520 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
521 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
522 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
523 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
527 @heading END OF TERMS AND CONDITIONS
530 @center END OF TERMS AND CONDITIONS
535 @unnumberedsec How to Apply These Terms to Your New Programs
537 If you develop a new program, and you want it to be of the greatest
538 possible use to the public, the best way to achieve this is to make it
539 free software which everyone can redistribute and change under these
542 To do so, attach the following notices to the program. It is safest to
543 attach them to the start of each source file to most effectively convey
544 the exclusion of warranty; and each file should have at least the
545 ``copyright'' line and a pointer to where the full notice is found.
548 @var{one line to give the program's name and an idea of what it does.}
549 Copyright (C) 19@var{yy} @var{name of author}
551 This program is free software; you can redistribute it and/or modify
552 it under the terms of the GNU General Public License as published by
553 the Free Software Foundation; either version 2 of the License, or (at
554 your option) any later version.
556 This program is distributed in the hope that it will be useful, but
557 WITHOUT ANY WARRANTY; without even the implied warranty of
558 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
559 General Public License for more details.
561 You should have received a copy of the GNU General Public License
562 along with this program; if not, write to the Free Software
563 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
566 Also add information on how to contact you by electronic and paper mail.
568 If the program is interactive, make it output a short notice like this
569 when it starts in an interactive mode:
572 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
573 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
574 `show w'. This is free software, and you are welcome to redistribute
575 it under certain conditions; type `show c' for details.
578 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
579 show the appropriate parts of the General Public License. Of course,
580 the commands you use may be called something other than @samp{show@w{
581 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items
582 -- whatever suits your program.
584 You should also get your employer (if you work as a programmer) or your
585 school, if any, to sign a ``copyright disclaimer'' for the program, if
586 necessary. Here is a sample; alter the names:
590 Yoyodyne, Inc., hereby disclaims all copyright interest
591 in the program `Gnomovision' (which makes passes at compilers)
592 written by James Hacker.
594 @var{signature of Ty Coon}, 1 April 1989
595 Ty Coon, President of Vice
599 This General Public License does not permit incorporating your program
600 into proprietary programs. If your program is a subroutine library, you
601 may consider it more useful to permit linking proprietary applications
602 with the library. If this is what you want to do, use the GNU Library
603 General Public License instead of this License.
607 @node Introduction, Invoking groff, Copying, Top
608 @chapter Introduction
611 GNU @code{troff} (or @code{groff}) is a system for typesetting
612 documents. @code{troff} is very flexible and has been in existence (and
613 use) for about 3@w{ }decades. It is quite widespread and firmly
614 entrenched in the @acronym{UNIX} community.
619 * groff Capabilities::
620 * Macro Package Intro::
621 * Preprocessor Intro::
622 * Output device intro::
627 @node What Is groff?, History, Introduction, Introduction
628 @section What Is @code{groff}?
629 @cindex what is @code{groff}?
630 @cindex @code{groff} -- what is it?
632 @code{groff} is of an older generation of document preparation systems,
633 which operate more like compilers than the more recent interactive
634 @acronym{WYSIWYG}@footnote{What You See Is What You Get} systems.
635 @code{groff} and its contemporary counterpart, @TeX{}, both work using a
636 @dfn{batch} paradigm: The input (or @dfn{source}) files are normal text
637 files with embedded formatting commands. These files can then be
638 processed by @code{groff} to produce a typeset document on a variety of
641 Likewise, @code{groff} should not be confused with a @dfn{word
642 processor}, since that term connotes an integrated system which includes
643 an editor and a text formatter. Also, many word processors follow the
644 @acronym{WYSIWYG} paradigm which was discussed earlier.
646 Although @acronym{WYSIWYG} systems may be easier to use, they have a
647 number of disadvantages compared to @code{troff}:
651 They must be used on a graphics display to do any operations on a
655 Most of the @acronym{WYSIWYG} systems are either non-free or are not
659 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
662 It is difficult to have a wide range of capabilities available within
663 the confines of a GUI/window system.
666 It is more difficult to make global changes to a document.
670 ``GUIs normally make it simple to accomplish simple actions and
671 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
672 @code{comp.unix.wizards})
676 @node History, groff Capabilities, What Is groff?, Introduction
680 @cindex @code{runoff}
682 @code{troff} can trace its origins back to a formatting program called
683 @code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS
684 system. This name came from the common phrase of the time ``I'll run
685 off a document.'' Bob Morris ported it to the 635 architecture and
686 called the program @code{roff} (an abbreviation of @code{runoff}). It
687 has then been rewritten as @code{rf} for the PDP-7 (before having
688 @acronym{UNIX}), and at the same time (1969), Doug McIllroy rewrote an
689 extended and simplified version of @code{roff} in the @acronym{BCPL}
690 programming language.
693 The first version of @acronym{UNIX} was developed on a PDP-7 which was
694 sitting around Bell Labs. In 1971 the developers wanted to get a PDP-11
695 for further work on the operating system. In order to justify the cost
696 for this system, they proposed that they would implement a document
697 formatting system for the AT&T patents division. This first formatting
698 program was a reimplementation of McIllroy's @code{roff}, written by
699 J.@w{ }F.@w{ }Ossanna.
702 When they needed a more flexible language, a new version of @code{roff}
703 called @code{nroff} (Newer @code{roff}) was written. It had a much more
704 complicated syntax, but provided the basis for all future versions.
705 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
706 version of @code{nroff} which would drive it. It was dubbed
707 @code{troff} for typesetter @code{roff}, although many people have
708 speculated that it actually means Times @code{roff} because of the use
709 of the Times font family in @code{troff} by default. As such, the name
710 @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
712 With @code{troff} came @code{nroff} (they were actually the same program
713 except for some @samp{#ifdefs}), which was for producing output for line
714 printers and character terminals. It understood everything @code{troff}
715 did, and ignored the commands which were not applicable (e.g.@: font
718 Since there are several things which cannot be done easily in
719 @code{troff}, work on several preprocessors began. These programs would
720 transform certain parts of a document into @code{troff}, which made a
721 very natural use of pipes in @acronym{UNIX}.
723 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
724 specified in a much simpler and more intuitive manner. @code{tbl} is a
725 preprocessor for formatting tables. The @code{refer} preprocessor (and
726 the similar program, @code{bib}) processes citations in a document
727 according to a bibliographic database.
729 Unfortunately, Ossanna's @code{troff} was written in PDP-11 assembly
730 language and produced output specifically for the CAT phototypesetter.
731 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
732 code and still dependent on the CAT. As the CAT became less common, and
733 was no longer supported by the manufacturer, the need to make it support
734 other devices became a priority. However, before this could be done, he
735 was killed in an auto accident.
738 @cindex @code{ditroff}
739 So, Brian Kernighan took on the task of rewriting @code{troff}. The
740 newly rewritten version produced a device independent code which was
741 very easy for postprocessors to read and translate to the appropriate
742 printer codes. Also, this new version of @code{troff} (called
743 @code{ditroff} for `device independent @code{troff}') had several
744 extensions, which included drawing functions.
746 Due to the additional abilities of the new version of @code{troff},
747 several new preprocessors appeared. The @code{pic} preprocessor
748 provides a wide range of drawing functions. Likewise the @code{ideal}
749 preprocessor did the same, although via a much different paradigm. The
750 @code{grap} preprocessor took specifications for graphs, but, unlike
751 other preprocessors, produced @code{pic} code.
753 James Clark began work on a GNU implementation of @code{ditroff} in
754 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
755 June@w{ }1990. @code{groff} included
759 A replacement for @code{ditroff} with many extensions.
762 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
765 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
766 X@w{ }windows. GNU @code{troff} also eliminated the need for a separate
767 @code{nroff} program with a postprocessor which would produce
768 @acronym{ASCII} output.
771 A version of the @file{me} macros and an implementation of the
775 Also, a front-end was included which could construct the, sometimes
776 painfully long, pipelines required for all the post- and preprocessors.
778 Development of GNU @code{troff} progressed rapidly, and saw the
779 additions of a replacement for @code{refer}, an implementation of the
780 @file{ms} and @file{mm} macros, and a program to deduce how to format a
781 document (@code{grog}).
783 It was declared a stable (i.e.@: non-beta) package with the release of
784 version@w{ }1.04 around November@w{ }1991.
786 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
787 an orphan for a few years). As a result, new features and programs like
788 @code{grn}, a preprocessor for gremlin images, and @code{grohtml}, an
789 output device to produce @acronym{HTML} output, have been added.
792 @node groff Capabilities, Macro Package Intro, History, Introduction
793 @section @code{groff} Capabilities
794 @cindex @code{groff} capabilities
795 @cindex capabilities of @code{groff}
797 So what exactly is @code{groff} capable of doing? @code{groff} provides
798 a wide range of low-level text formatting operations. Using these, it
799 is possible to perform a wide range of formatting tasks, such as
800 footnotes, table of contents, multiple columns, etc.
804 Text filling, adjusting, and centering
813 Font and character size control
816 Vertical spacing (i.e.@: double spacing)
819 Line length and indenting
822 Macros, strings, diversions, and traps
828 Tabs, leaders, and fields
831 Input and output conventions and character translation
834 Overstrike, bracket, line drawing, and zero-width functions
837 Local horizontal and vertical motions and the width function
843 Output line numbering
846 Conditional acceptance of input
849 Environment switching
852 Insertions from the standard input
855 Input/output file switching
858 Output and error messages
862 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
863 @section Macro Packages
864 @cindex macro packages
866 Since @code{groff} provides such low level facilities, it can be quite
867 difficult to use by itself. However, @code{groff} provides a
868 @dfn{macro} facility to specify how certain routine operations (e.g.@w{
869 }starting paragraphs, printing headers and footers, etc.)@: should be
870 done. These macros can be collected together into a @dfn{macro
871 package}. There are a number of macro packages available; the most
872 common (and the ones described in this manual) are @file{man},
873 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
876 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
877 @section Preprocessors
878 @cindex preprocessors
880 Although @code{groff} provides most functions needed to format a
881 document, some operations would be unwieldy (e.g.@: to draw pictures).
882 Therefore, programs called preprocessors were written which understand
883 their own language and produce the necessary @code{groff} operations.
884 These preprocessors are able to differentiate their own input from the
885 rest of the document via markers.
887 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
888 from the preprocessor into @code{groff}. Any number of preprocessors
889 may be used on a given document; in this case, the preprocessors are
890 linked together into one pipeline. However, in @code{groff}, the user
891 does not need to construct the pipe, but only tell @code{groff} what
892 preprocessors to use.
894 @code{groff} currently has preprocessors for producing tables
895 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
896 (@code{pic} and @code{grn}), and for processing bibliographies
897 (@code{refer}). An associated program which is useful when dealing with
898 preprocessors is @code{soelim}.
900 A free implementation of @code{grap}, a preprocessor for drawing graphs,
901 can be obtained as an extra package; @code{groff} can use @code{grap}
904 There are other preprocessors in existence, but, unfortunately, no free
905 implementations are available. Among them are preprocessors for drawing
906 mathematical pictures (@code{ideal}) and chemical structures
910 @node Output device intro, Credits, Preprocessor Intro, Introduction
911 @section Output Devices
912 @cindex postprocessors
913 @cindex output devices
914 @cindex devices for output
916 @code{groff} actually produces device independent code which may be fed
917 into a postprocessor which will produce output for a particular device.
918 Currently, @code{groff} has postprocessors for @sc{PostScript},
919 character terminals, X@w{ }Windows (for previewing), @TeX{} DVI format,
920 HP LaserJet@w{ }4 and Canon LBP printers (which use @acronym{CAPSL}),
924 @node Credits, , Output device intro, Introduction
928 Large portions of this manual were taken from existing documents, most
929 notably, the manual pages for the @code{groff} package by James Clark,
930 and Eric Allman's papers on the @file{me} macro package.
932 The section on the @file{man} macro package is partly based on Susan@w{
933 }G.@: Kleinmann's @file{groff_man} manual page written for the Debian
938 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
939 @chapter Invoking @code{groff}
940 @cindex invoking @code{groff}
941 @cindex @code{groff} invocation
945 This section focuses on how to invoke the @code{groff} front end. This
946 front end takes care of the details of constructing the pipeline among
947 the preprocessors, @code{gtroff} and the postprocessor.
949 It has become a tradition that GNU programs get the prefix @samp{g} to
950 distinguish it from its original counterparts provided by the host
951 (@pxref{Environment}, for more details). Thus, for example, @code{geqn}
952 is GNU @code{eqn}. On operating systems like Linux or the Hurd, which
953 don't contain proprietary software, this prefix is omitted since GNU
954 @code{troff} is the only used incarnation of @code{troff}. Exception:
955 @code{groff} is never replaced by @code{roff}.
960 * Invocation Examples::
964 @node Groff Options, Environment, Invoking groff, Invoking groff
977 @code{groff} normally runs the @code{gtroff} program and a postprocessor
978 appropriate for the selected device. The default device is @samp{ps}.
979 It can optionally preprocess with any of @code{gpic}, @code{geqn},
980 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
982 This section only documents options to the @code{groff} front end. Many
983 of the arguments to @code{groff} are passed on to @code{gtroff},
984 therefore those are also included. Arguments to pre- or postprocessors
985 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
986 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
987 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
988 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
989 grolbp}, and @ref{Invoking gxditview}.
991 The command line format for @code{groff} is:
994 groff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
995 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
996 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
997 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
998 [ @var{files}@dots{} ]
1001 The command line format for @code{gtroff} is as follows. As can be
1002 seen, many of the options to @code{groff} are actually passed on to
1006 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
1007 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
1008 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
1009 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
1012 Options without an argument can be grouped behind a single @option{-}.
1013 A filename of @samp{-} denotes the standard input. It is possible to
1014 have whitespace between an option and its parameter.
1017 The @code{grog} command can be used to guess the correct @code{groff}
1018 command to format a file.
1022 Print a help message.
1025 Preprocess with @code{geqn}.
1028 Preprocess with @code{gtbl}.
1031 Preprocess with @code{ggrn}.
1034 Preprocess with @code{grap}.
1037 Preprocess with @code{gpic}.
1040 Preprocess with @code{gsoelim}.
1043 Preprocess with @code{grefer}. No mechanism is provided for passing
1044 arguments to @code{grefer} because most @code{grefer} options have
1045 equivalent commands which can be included in the file. @xref{grefer},
1050 Note that @code{gtroff} also accepts a @option{-R} option, which is not
1051 accessible via @code{groff}. This option prevents the loading of the
1052 @file{troffrc} and @file{troffrc-end} files.
1055 Make programs run by @code{groff} print out their version number.
1058 Print the pipeline on stdout instead of executing it.
1061 Suppress output from @code{gtroff}. Only error messages will be
1065 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1066 will automatically run the appropriate postprocessor.
1069 Pass @var{arg} to the postprocessor. Each argument should be passed
1070 with a separate @option{-P} option. Note that @code{groff} does not
1071 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1074 Send the output to a printer. The command used for this is specified by
1075 the print command in the device description file.
1078 Pass @var{arg} to the spooler. Each argument should be passed with a
1079 separate @option{-L} option. Note that @code{groff} does not prepend a
1080 @samp{-} to @var{arg} before passing it to the postprocessor.
1083 Prepare output for device @var{dev}. The default device is @samp{ps}.
1084 The following are the output devices currently available:
1087 For @sc{PostScript} printers and previewers.
1090 For @TeX{} DVI format.
1093 For a 75@dmn{dpi} X11 previewer.
1096 For a 100@dmn{dpi} X11 previewer.
1099 For typewriter-like devices.
1102 For typewriter-like devices using the @w{ISO Latin-1} (@w{ISO 8859-1})
1106 For typewriter-like devices which use the Unicode (@w{ISO 10646})
1107 character set with @w{UTF-8} encoding.
1110 @cindex @acronym{EBCDIC} encoding
1113 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1117 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
1120 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1124 To produce @acronym{HTML} output.
1129 The predefined @code{gtroff} string register @code{.T} contains the
1130 current output device; the read-only number register @code{.T} is set
1131 to@w{ }1 if this option is used (which is always true if @code{groff} is
1132 used to call @code{gtroff}). @xref{Built-in Registers}.
1134 The postprocessor to be used for a device is specified by the
1135 @code{postpro} command in the device description file. (@xref{Font
1136 Files}, for more info.) This can be overridden with the @option{-X}
1140 Preview with @code{gxditview} instead of using the usual postprocessor.
1141 This is unlikely to produce good results except with @option{-Tps}.
1143 Note that this is not the same as using @option{-TX75} or
1144 @option{-TX100} to view a document with @code{gxditview}: The former
1145 will us the metrics of the specified device, whereas the latter will use
1146 X-specific fonts and metrics.
1149 Don't allow newlines with @code{eqn} delimiters. This is the same as
1150 the @option{-N} option in @code{geqn}.
1153 Safer mode. Pass the @option{-S} option to @code{gpic} and use the
1154 @option{-msafer} macros with @code{gtroff} (enabled by default).
1157 Unsafe mode. Reverts to the old unsafe behaviour.
1161 Generate an @acronym{ASCII} approximation of the typeset output. The
1162 read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
1166 Print a backtrace with each warning or error message. This backtrace
1167 should help track down the cause of the error. The line numbers given
1168 in the backtrace may not always be correct: @code{gtroff} can get
1169 confused by @code{as} or @code{am} requests while counting line numbers.
1172 Read the standard input after all the named input files have been
1176 Enable warning @var{name}. Available warnings are described in
1177 @ref{Debugging}. Multiple @option{-w} options are allowed.
1180 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1183 Inhibit all error messages.
1186 Enable compatibility mode.
1189 @itemx -d@var{name}=s
1190 Define @var{c} or @var{name} to be a string @var{s}. @var{c} must be a
1191 one-letter name; @var{name} can be of arbitrary length.
1194 Use @var{fam} as the default font family.
1197 Read in the file @file{tmac.@var{name}}. Normally this will be searched
1198 for in the library directory of @code{groff}.
1201 Number the first page @var{num}.
1205 Output only pages in @var{list}, which is a comma-separated list of page
1206 ranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means
1207 print every page between @var{m} and @var{n}, @samp{-@var{n}} means
1208 print every page up to @var{n}, @samp{@var{n}-} means print every page
1209 from @var{n}. @code{gtroff} will exit after printing the last page in
1212 Within @code{gtroff}, this information can be extracted with the
1213 @samp{.P} register. @xref{Built-in Registers}.
1216 @itemx -r@var{name}=@var{n}
1217 Set number register @var{c} or @var{name} to @var{n}. @var{c} must be a
1218 one-letter name; @var{name} can be of arbitrary length. @var{n} can be
1219 any @code{gtroff} numeric expression.
1222 Search @var{dir} for subdirectories dev@var{name} (@var{name} is the
1223 name of the device) for the @file{DESC} file and font files before the
1227 Search directory @var{dir} for macro files before the normal directory.
1230 This option is as described in @ref{gsoelim}. It implies the
1235 @node Environment, Invocation Examples, Groff Options, Invoking groff
1236 @section Environment
1237 @cindex environment variables
1238 @cindex variables in environment
1240 There are also several environment variables (of the operating system,
1241 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1244 @item GROFF_COMMAND_PREFIX
1245 @tindex GROFF_COMMAND_PREFIX
1246 If this is set to @var{X}, then @code{groff} will run
1247 @var{X}@code{troff} instead of @code{gtroff}. This also applies to
1248 @code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
1249 @code{soelim}. It does not apply to @code{grops}, @code{grodvi},
1250 @code{grotty}, @code{grohtml}, @code{grolj4}, and @code{gxditview}.
1252 @item GROFF_TMAC_PATH
1253 @tindex GROFF_TMAC_PATH
1254 A colon separated list of directories in which to search for macro
1257 @item GROFF_TYPESETTER
1258 @tindex GROFF_TYPESETTER
1259 The default output device.
1261 @item GROFF_FONT_PATH
1262 @tindex GROFF_FONT_PATH
1263 A colon separated list of directories in which to search for the
1264 @code{dev}@var{name} directory.
1268 The search path for commands executed by @code{groff}.
1271 @tindex GROFF_TMPDIR
1273 The directory in which temporary files will be created. If this is not
1274 set and @env{TMPDIR} is set, temporary files will be created in that
1275 directory. Otherwise temporary files will be created in @code{/tmp}.
1276 The @code{grops} and @code{grefer} commands can create temporary files.
1280 @node Invocation Examples, , Environment, Invoking groff
1281 @section Invocation Examples
1282 @cindex invocation examples
1283 @cindex examples of invocation
1285 This section will list several common uses of @code{groff} and the
1286 command line which will accomplish it.
1293 This command processes @var{file} without a macro package or a
1294 preprocessor. The output device is the default, @var{ps}, and the
1295 output is sent to stdout.
1298 groff -t -mandoc -Tascii file | less
1302 This is basically what a call to the @code{man} program does. The
1303 manual page @var{file} is processed with the @file{mandoc} macros (which
1304 in turn either calls the @file{man} or the @file{mdoc} macro package),
1305 using the @code{tbl} preprocessor and the @acronym{ASCII} output device.
1306 Finally, the result is displayed with the @code{less} pager.
1313 Preview @var{file} with @code{gxditview}, using the @file{me} macro
1314 package. Since no @option{-T} option is specified, use the default
1315 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1316 @w{@samp{-me}}; the latter is an anachronism from the early days of
1317 @acronym{UNIX}.@footnote{The same is true for the other main macro
1318 packages that come with @code{groff}: @file{man}, @file{mdoc},
1319 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1320 for example, to load @file{tmac.safer}, either @samp{-msafer} or
1321 @w{@samp{-m safer}} must be used.}
1324 groff -man -rD1 -z file
1328 Check @var{file} with the @file{man} macro package, forcing double-sided
1329 printing -- don't produce any output.
1331 @subsection @code{grog}
1333 @code{grog} reads files and guesses which of the @code{groff}
1334 preprocessors and/or macro packages are are required for formatting
1335 them, and prints the @code{groff} command including those options on the
1336 standard output. The options generated are one of @option{-e},
1337 @option{-man}, @option{-me}, @option{-mm}, @option{-ms}, @option{-p},
1338 @option{-R}, @option{-g}, @option{-G}, @option{-s}, and @option{-t}.
1340 A filename of @samp{-} is taken to refer to the standard input. If no
1341 files are specified the standard input will be read. Any specified
1342 options will be included in the printed command. No space is allowed
1343 between options and their arguments. For example,
1350 will guess the appropriate command to print @file{paper.ms} and then
1351 print it to the command line after adding the @option{-Tdvi} option.
1352 For direct execution, enclose the call to @code{grog} in backquotes on
1353 the @acronym{UNIX} shell prompt:
1356 `grog -Tdvi paper.ms` > paper.dvi
1360 As seen in the example, it is still necessary to redirect the output to
1361 something meaningful (i.e.@: either a file or a pager program like
1366 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1367 @chapter Tutorial for Macro Users
1368 @cindex tutorial for macro users
1369 @cindex macro tutorial for users
1370 @cindex user's tutorial for macros
1371 @cindex user's macro tutorial
1373 Most users tend to use a macro package to format their papers. This
1374 means that the whole breadth of @code{groff} is not necessary for most
1375 people. This chapter covers the material needed to efficiently use a
1384 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1388 This section covers some of the basic concepts necessary to understand
1389 how to use a macro package.@footnote{This section is derived from
1390 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1391 References are made throughout to more detailed information, if desired.
1393 @code{gtroff} reads an input file prepared by the user and outputs a
1394 formatted document suitable for publication or framing. The input
1395 consists of text, or words to be printed, and embedded commands
1396 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1397 format the output. For more detail on this @pxref{Embedded Commands}.
1399 The word @dfn{argument} is used in this manual to mean a word or number
1400 which appears on the same line as a request which modifies the meaning
1401 of that request. For example, the request
1408 spaces one line, but
1415 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1416 request which says to space four lines instead of one. Arguments are
1417 separated from the request and from each other by spaces. More details
1418 on this can be found in @ref{Request Arguments}.
1420 The primary function of @code{gtroff} is to collect words from input
1421 lines, fill output lines with those words, justify the right hand margin
1422 by inserting extra spaces in the line, and output the result. For
1430 Four score and seven
1435 will be read, packed onto output lines, and justified to produce:
1438 Now is the time for all good men to come to the aid of their party.
1439 Four score and seven years ago,...
1444 Sometimes a new output line should be started even though the current
1445 line is not yet full; for example, at the end of a paragraph. To do
1446 this it is possible to cause a @dfn{break}, which starts a new output
1447 line. Some requests cause a break automatically, as do blank input
1448 lines and input lines beginning with a space.
1450 Not all input lines are text to be formatted. Some of the input lines
1451 are requests which describe how to format the text. Requests always
1452 have a period (@samp{.}) or an apostrophe (@samp{'}) as the first
1453 character of the input line.
1455 The text formatter also does more complex things, such as automatically
1456 numbering pages, skipping over page boundaries, putting footnotes in the
1457 correct place, and so forth.
1459 Here a few hints for preparing text for input to @code{gtroff}. First,
1460 keep the input lines short. Short input lines are easier to edit, and
1461 @code{gtroff} will pack words onto longer lines anyhow. In keeping with
1462 this, it is helpful to begin a new line after every period, comma, or
1463 phrase, since common corrections are to add or delete sentences or
1464 phrases. Secondly, do not hyphenate words at the end of lines --
1465 @code{gtroff} is smart enough to hyphenate words for the user as needed,
1466 but is not smart enough to take hyphens out and join a word back
1467 together. Also, words such as ``mother-in-law'' should not be broken
1468 over a line, since then a space can occur where not wanted, such as
1469 ``@w{mother- in}-law''.
1472 @cindex double spacing
1474 @code{gtroff} will double space output text automatically if using the
1475 request @w{@samp{.ls 2}}. Single spaced mode can be reactivated by
1476 typing @w{@samp{.ls 1}}.
1478 A number of requests allow to change the way the output looks, sometimes
1479 called the @dfn{layout} of the output page. Most of these requests
1480 adjust the placing of @dfn{white space} (blank lines or spaces).
1484 The @samp{.bp} request starts a new page, causing a line break.
1489 @cindex lines, empty
1490 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1491 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1492 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1493 @var{N}@w{ }centimeters). For example, the input:
1497 My thoughts on the subject
1502 leaves one and a half inches of space, followed by the line ``My
1503 thoughts on the subject'', followed by a single blank line.
1506 @cindex centering lines
1507 @cindex lines, centering
1508 Text lines can be centered by using the @code{ce} request. The line
1509 after @code{ce} is centered (horizontally) on the page. To center more
1510 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1511 of lines to center), followed by the @var{N}@w{ }lines. To center many
1512 lines without counting them, type:
1521 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1522 lines, in other words, stop centering.
1527 All of these requests cause a break; that is, they always start a new
1528 line. To start a new line without performing any other action, use
1532 @node Common Features, , Basics, Tutorial for Macro Users
1533 @section Common Features
1534 @cindex common features
1535 @cindex features, common
1537 @code{gtroff} provides very low level operations for formatting a
1538 document. There are many common routine operations which are done in
1539 all documents. These common operations are written into @dfn{macros}
1540 and collected into a @dfn{macro package}.
1542 All macro packages provide certain common capabilities which fall into
1543 the following categories.
1545 @subsection Paragraphs
1548 One of the most common and most used capability is starting a paragraph.
1549 There are a number of different types of paragraphs, any of which can be
1550 initiated with macros supplied by the macro package. Normally,
1551 paragraphs start with a blank line and the first line indented, like the
1552 text in this manual. There are also block style paragraphs, which omit
1556 Some men look at constitutions with sanctimonious
1557 reverence, and deem them like the ark of the covenant, too
1558 sacred to be touched.
1562 And there are also indented paragraphs which begin with a tag or label
1563 at the margin and the remaining text indented.
1566 one This is the first paragraph. Notice how the first
1567 line of the resulting paragraph lines up with the
1568 other lines in the paragraph.
1570 This paragraph had a long label. The first
1571 character of text on the first line will not line up
1572 with the text on second and subsequent lines,
1573 although they will line up with each other.
1576 A variation of this is a bulleted list.
1579 @subsection Sections and Chapters
1581 Most macro packages supply some form of section headers. The simplest
1582 kind is simply the heading on a line by itself in bold type. Others
1583 supply automatically numbered section heading or different heading
1584 styles at different levels. Some, more sophisticated, macro packages
1585 supply macros for starting chapters and appendices.
1587 @subsection Headers and Footers
1589 Every macro package gives some way to manipulate the headers and
1590 footers (or @dfn{titles}) on each page. Some packages will allow for
1591 different ones on the even and odd pages (for material printed in a book
1594 The titles are called three-part titles, that is, there is a
1595 left-justified part, a centered part, and a right-justified part. An
1596 automatically generated page number may be put in any of these fields
1597 with the @samp{%} character (@pxref{Page Layout} for more details).
1599 @subsection Page Layout
1601 Most macro packages let thte user specify top and bottom margins and
1602 other details about the appearance of the printed pages.
1604 @subsection Displays
1607 Displays are sections of text to be set off from the body of the paper.
1608 Major quotes, tables, and figures are types of displays, as are all the
1609 examples used in this document.
1611 @cindex quotes, major
1612 @cindex major quotes
1613 @dfn{Major quotes} are quotes which are several lines long, and hence
1614 are set in from the rest of the text without quote marks around them.
1617 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1618 should be used when the material to be printed should not be filled and
1619 justified like normal text, such as columns of figures or the examples
1623 A @dfn{keep} is a display of lines which are kept on a single page if
1624 possible. An example for a keep might be a diagram. Keeps differ from
1625 lists in that lists may be broken over a page boundary whereas keeps
1628 @cindex keep, floating
1629 @cindex floating keep
1630 Floating keeps move relative to the text. Hence, they are good for
1631 things which will be referred to by name, such as ``See figure@w{ }3''.
1632 A floating keep will appear at the bottom of the current page if it will
1633 fit; otherwise, it will appear at the top of the next page. Meanwhile,
1634 the surrounding text will `flow' around the keep, thus leaving now blank
1637 @subsection Footnotes and annotations
1641 There are a number of requests to save text for later printing.
1643 @dfn{Footnotes} are printed at the bottom of the current page.
1645 @cindex delayed text
1646 @dfn{Delayed text} is very similar to a footnote except that it is
1647 printed when called for explicitly. This allows a list of references to
1648 appear (for example) at the end of each chapter, as is the convention in
1651 Most macro packages which supply this functionality also supply a means
1652 of automatically numbering either type of annotation.
1654 @subsection Table of Contents
1655 @cindex table of contents
1656 @cindex contents, table of
1658 @dfn{Tables of contents} are a type of delayed text having a tag
1659 (usually the page number) attached to each entry after a row of dots.
1660 The table accumulates throughout the paper until printed, usually after
1661 the paper has ended. Many macro packages will provide the ability to
1662 have several tables of contents (i.e.@: one standard one, one for
1668 While some macro packages will use the term @dfn{index}, none actually
1669 provide that functionality. The facilities they call indices are
1670 actually more appropriate for tables of contents.
1672 @subsection Paper formats
1673 @cindex paper formats
1675 Some macro packages provide stock formats for various kinds of
1676 documents. Many of them provide a common format for the title and
1677 opening pages of a technical paper. The @file{mm} macros in particular
1678 provide formats for letters and memoranda.
1680 @subsection Multiple Columns
1682 Some macro packages (except @file{man}) provide the ability to have two
1683 or more columns on a page.
1685 @subsection Font and Size changes
1687 The built-in font and size functions are not always intuitive, so all
1688 macro packages provide macros to make these operations simpler.
1690 @subsection Predefined Strings
1692 Most macro packages provide various predefined strings for a variety of
1693 uses; examples are sub- and superscripts, printable dates, quotes and
1694 various special characters.
1696 @subsection Preprocessor Support
1698 All macro packages provide support for the various preprocessors.
1700 @subsection Configuration and Customization
1702 Some macro packages provide means of customizing many of details of how
1703 the package behaves. This ranges from setting the default type size to
1704 changing the appearance of section headers.
1708 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
1709 @chapter Macro Packages
1710 @cindex macro packages
1711 @cindex packages, macros
1713 This chapter documents the main macro packages that come with
1725 @node man, mdoc, Macro Packages, Macro Packages
1728 @cindex manual pages
1732 This is the most popular and probably the most important macro package
1733 of @code{groff}. It is easy to use, and a vast majority of manual pages
1740 * Miscellaneous man stuff::
1743 @node Man options, Man usage, man, man
1746 The command line format for using the @file{man} macros with
1749 @c XXX document @TMAC_AN_PREFIX@
1752 groff -m man [ -rC1 ] [ -rD1 ] [ -rP @var{nnn} ] [ -rX @var{nnn} ]
1753 [ @var{files}@dots{} ]
1756 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
1760 If more than one manual page is given on the command line, number the
1761 pages continuously, rather than starting each at@w{ }1.
1764 Double-sided printing. Footers for even and odd pages are formatted
1768 Enumeration of pages will start with @var{nnn} rather than with@w{ }1.
1771 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
1772 @var{nnn}c, etc. For example, the option @option{-rX2} will produce the
1773 following page numbers: 1, 2, 2a, 2b, 2c, etc.
1776 @node Man usage, Man font macros, Man options, man
1780 This section describes the available macros for manual pages. For
1781 further customization, put additional macros and requests into the file
1782 @file{man.local} which will be loaded immediately after @file{tmac.an}.
1785 @Defmac{TH, title section [@var{extra1}] [@var{extra2}] [@var{extra3}]}
1786 Sets the title of the man page to @var{title} and the section to
1787 @var{section}, which must take on a value between 1 and@w{ }8. The
1788 value @var{section} may also have a string appended, e.g.@: @samp{.pm},
1789 to indicate a specific subsection of the man pages.
1791 Both @var{title} and @var{section} are positioned at the left and right
1792 in the header line (with @var{section} in parentheses immediately
1793 appended to @var{title}. @var{extra1} will be positioned in the middle
1794 of the footer line. @var{extra2} will be positioned at the left in the
1795 footer line (resp.@: at the left on even pages and at the right on odd
1796 pages if double-sided printing is active). @var{extra3} is centered in
1799 For @acronym{HTML} output, headers and footers are completely supressed.
1801 Additionally, this macro starts a new page; the new line number is@w{ }1
1802 again (except if the @option{-rC1} option is given on the command line)
1803 -- this feature is intended only for formatting multiple man pages; a
1804 single man page should contain exactly one @code{TH} macro at the
1805 beginning of the file.
1809 @Defmac{SH, [@var{heading}]}
1810 Sets up an unnumbered section heading sticking out to the left. Prints
1811 out all the text following @code{SH} up to the end of the line (resp.@:
1812 the text in the next line if there is no argument to @code{SH}) in bold
1813 face, at a default size of 9@w{ }point. Additionally, the left margin
1814 for the following text is reset to its default value.
1818 @Defmac{SS, [@var{heading}]}
1819 Sets up an unnumbered section heading. Prints out all the text
1820 following @code{SS} up to the end of the line (resp.@: the text in the
1821 next line if there is no argument to @code{SS}) in bold face, at a
1822 default size of 10@w{ }point. Additionally, the left margin for the
1823 following text is reset to its default value.
1827 @Defmac{TP, [@var{nnn}]}
1828 Sets up an indented paragraph with label. The indentation is set to
1829 @var{nnn} if that argument is supplied (the default unit is @samp{n} if
1830 omitted), otherwise it is set to the default indentation value.
1832 The first line of text following this macro is interpreted as a string
1833 to be printed flush-left, as it is appropriate for a label. It is not
1834 interpreted as part of a paragraph, so there is no attempt to fill the
1835 first line with text from the following input lines. Nevertheless, if
1836 the label is not as wide as the indentation, then the paragraph starts
1837 at the same line (but indented), continuing on the following lines. If
1838 the label is wider than the indentation, then the descriptive part of
1839 the paragraph begins on the line following the label, entirely indented.
1840 Note that neither font shape nor font size of the label is set to a
1841 default value; on the other hand, the rest of the text will have default
1851 These macros are mutual aliases. Any of them causes a line break at the
1852 current position, followed by a vertical space downwards by the amount
1853 specified by the @code{PD} macro. The font size and shape are reset to
1854 the default value (10@dmn{pt} resp.@: Roman). Finally, the current left
1859 @Defmac{IP, [@var{designator}] [@var{nnn}]}
1860 Sets up an indented paragraph, using @var{designator} as a tag to mark
1861 its beginning. The indentation is set to @var{nnn} if that argument is
1862 supplied (default unit is @samp{n}), otherwise the default indentation
1863 value is used. Font size and face of the paragraph (but not the
1864 designator) are reset to its default values. To start an indented
1865 paragraph with a particular indentation but without a designator, use
1866 @samp{""} (two doublequotes) as the first argument of @code{IP}.
1868 For example, to start a paragraph with bullets as the designator and
1869 4@dmn{en} indentation, write
1877 @Defmac{HP, [@var{nnn}]}
1878 Sets up a paragraph with hanging left indentation. The indentation is
1879 set to @var{nnn} if that argument is supplied (default unit is
1880 @samp{n}), otherwise the default indentation value is used. Font size
1881 and face are reset to its default values.
1885 @Defmac{RS, [@var{nnn}]}
1886 This macro moves the left margin to the right by the value @var{nnn} if
1887 specified (default unit is @samp{n}); otherwise the default indentation
1888 value is used. Calls to the @code{RS} macro can be nested.
1892 @Defmac{RE, [@var{nnn}]}
1893 This macro moves the left margin back to level @var{nnn}; if no argument
1894 is given, it moves one level back. The first level (i.e., no call to
1895 @code{RS} yet) has number@w{ }1, and each call to @code{RS} increases
1907 To summarize, the following macros cause a line break with the insertion
1908 of vertical space (which amount can be changed with the @code{PD}
1909 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
1910 @code{P}), @code{IP}, and @code{HP}.
1914 The macros @code{RS} and @code{RE} also cause a break but no insertion
1917 @node Man font macros, Miscellaneous man stuff, Man usage, man
1918 @subsection Macros to set fonts
1920 The standard font is Roman; the default text size is 10@w{ }point.
1923 @Defmac{SM, [@var{text}]}
1924 Causes the text on the same line or the text on the next line to appear
1925 in a font that is one point size smaller than the default font.
1929 @Defmac{SB, [@var{text}]}
1930 Causes the text on the same line or the text on the next line to appear
1931 in boldface font, one point size smaller than the default font.
1936 Causes text on the same line to appear alternately in bold face and
1937 italic. The text must be on the same line as the macro call. Thus
1940 .BI this "word and" that
1944 would cause `this' and `that' to appear in bold face, while `word and'
1950 Causes text to appear alternately in italic and bold face. The text
1951 must be on the same line as the macro call.
1956 Causes text on the same line to appear alternately in roman and italic.
1957 The text must be on the same line as the macro call.
1962 Causes text on the same line to appear alternately in italic and roman.
1963 The text must be on the same line as the macro call.
1968 Causes text on the same line to appear alternately in bold face and
1969 roman. The text must be on the same line as the macro call.
1974 Causes text on the same line to appear alternately in roman and bold
1975 face. The text must be on the same line as the macro call.
1979 @Defmac{R, [@var{text}]}
1980 Causes @var{text} to appear in roman font. If no text is present on the
1981 line where the macro is called, then the text of the next line appears
1982 in roman. This is the default font to which text is returned at the end
1983 of processing of the other macros.
1987 @Defmac{B, [@var{text}]}
1988 Causes @var{text} to appear in bold face. If no text is present on the
1989 line where the macro is called, then the text of the next line appears
1994 @Defmac{I, [@var{text}]}
1995 Causes @var{text} to appear in italic. If no text is present on the
1996 line where the macro is called, then the text of the next line appears
2000 @node Miscellaneous man stuff, , Man font macros, man
2001 @subsection Miscellaneous
2004 @cindex @file{man}, default indentation
2005 @cindex default indentation, @file{man}
2006 The default indentation is 7.2@dmn{n} for all output devices except for
2007 @code{grohtml} which uses 1.2@dmn{i} instead.
2012 Sets tabs every 0.5@w{ }inches. Since this macro is always called
2013 during a @code{TH} request, it makes sense to call it only if the tab
2014 positions have been changed.
2018 @Defmac{PD, [@var{nnn}]}
2019 Adjusts the empty space before a new paragraph (resp.@: section). The
2020 optional argument gives the amount of space (default units are
2021 @samp{v}); without parameter, the value is reset to its default value
2022 (1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise).
2033 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP}
2034 (resp.@: @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2036 The following strings are defined:
2040 Switch back to the default font size.
2045 The `registered' sign.
2050 The `trademark' sign.
2059 Left and right quote.
2060 This is equal to @code{\(lq} and @code{\(rq}, respectively.
2063 @cindex preprocessor, calling convention
2064 @cindex calling convention of preprocessors
2065 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2066 become usage to make the first line of the man page look like this:
2076 Note the single space character after the double quote. @var{word}
2077 consists of letters for the needed preprocessors: @samp{e} for
2078 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2079 Modern implementations of the @code{man} program read this first line
2080 and automatically call the right preprocessor(s).
2083 @node mdoc, ms, man, Macro Packages
2084 @section @file{mdoc}
2087 @c XXX documentation
2090 @node ms, me, mdoc, Macro Packages
2094 @c XXX documentation
2097 @node me, mm, ms, Macro Packages
2101 @c XXX documentation
2104 @node mm, , me, Macro Packages
2108 @c XXX documentation
2112 @node Programming Tutorial, Preprocessors, Macro Packages, Top
2113 @chapter Programming Tutorial
2114 @cindex programming tutorial
2115 @cindex tutorial for programming
2117 This chapter covers @strong{all} of the facilities of @code{gtroff}.
2118 Users of macro packages may skip it if not interested in details.
2123 * Input Conventions::
2127 * Embedded Commands::
2129 * Manipulating Filling and Adjusting::
2130 * Manipulating Hyphenation::
2131 * Manipulating Spacing::
2133 * Character Translations::
2134 * Troff and Nroff Mode::
2141 * Conditionals and Loops::
2144 * Drawing Requests::
2149 * Postprocessor Access::
2152 * Implementation Differences::
2157 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
2161 @code{gtroff} input files contain text with control commands
2162 interspersed throughout. But, even without control codes, @code{gtroff}
2163 will still do several things with the input text: filling and adjusting,
2164 adding additional space after sentences, hyphenating and inserting
2165 implicit line breaks.
2168 * Filling and Adjusting::
2172 * Implicit Line Breaks::
2175 @node Filling and Adjusting, Hyphenation, Text, Text
2176 @subsection Filling and Adjusting
2177 @cindex filling and adjusting
2178 @cindex adjusting and filling
2180 When @code{gtroff} reads in text it collects words from input and fits
2181 as many of them together on one output line as it can. This is known as
2184 @cindex leading spaces
2185 @cindex spaces, leading
2186 @cindex extra spaces
2187 @cindex spaces, extra
2188 @cindex trailing spaces
2189 @cindex spaces, trailing
2190 Once @code{gtroff} has a @dfn{filled} line it will try to @dfn{adjust}
2191 it. Which means it will widen the spacing between words until the text
2192 reaches the right margin (in the default adjustment mode). Extra spaces
2193 between words are preserved, but spaces at the end of lines are ignored.
2194 Spaces at the front of a line will cause a @dfn{break} (breaks will be
2195 explained in @ref{Implicit Line Breaks})
2197 @xref{Manipulating Filling and Adjusting}.
2199 @node Hyphenation, Sentences, Filling and Adjusting, Text
2200 @subsection Hyphenation
2203 Since the odds of finding a set of words, for every output line, which
2204 will fit nicely on a line without inserting excessive amounts of space
2205 between words is not great, @code{gtroff} will hyphenate words so that
2206 lines can be justified without there being too much space between words.
2207 It uses an internal hyphenation algorithm (a simplified version of the
2208 algorithm used within @TeX{}) to indicate which words can be hyphenated
2209 and how to do so. When a word is hyphenated the first part of the word
2210 will be added to the current filled line being output (with an attached
2211 hyphen), and the other portion will be added to the next line to be
2214 @xref{Manipulating Hyphenation}.
2216 @node Sentences, Tab Stops, Hyphenation, Text
2217 @subsection Sentences
2220 Although it is often debated, some typesetting rules say there should be
2221 different amounts of space after various punctuation marks. For
2222 example, the @emph{Chicago typsetting manual} says that a period at the
2223 end of a sentence should have twice as much space following it as would
2224 a comma or a period as part of an abbreviation.
2226 @c XXX exact citation of Chigago manual
2228 @cindex sentence space
2229 @cindex space between sentences
2230 @cindex french-spacing
2231 @code{gtroff} does this by flagging certain characters (normally
2232 @samp{!}, @samp{?} and @samp{.}) as @dfn{end of sentence} characters.
2233 When @code{gtroff} encounters one of these characters at the end of a
2234 line it will append two @dfn{sentence spaces} in the formatted output.
2235 (Thus, one of the conventions mentioned in @ref{Input Conventions}.)
2237 @cindex transparent characters
2238 @cindex character, transparent
2246 In addition, the following characters resp.@: glyphs are treated
2247 transparently while handling end of sentence characters: @samp{"},
2248 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}.
2250 See the @code{cflags} request in @ref{Using Symbols}, for more details.
2253 To prevent the insertion of extra space after an end of sentence
2254 character (at the end of a line), append @code{\&}.
2257 @node Tab Stops, Implicit Line Breaks, Sentences, Text
2258 @subsection Tab Stops
2260 @cindex stops, tabulator
2261 @cindex tab character
2262 @cindex character, tabulator
2264 @cindex @acronym{EBCDIC} encoding
2265 @code{gtroff} translates @dfn{tabulator characters}, also called
2266 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} resp.@:
2267 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
2268 tabulator stop. These tab stops are initially located every half inch
2269 across the page. Using this simple tables can easily be made. However,
2270 it can often be deceptive as the appearance (and width) of the text on a
2271 terminal and the results from @code{gtroff} can vary greatly.
2273 Also, a possible sticking point is that lines beginning with tab
2274 characters will still be filled, again producing unexpected results.
2275 For example, the following input
2277 @multitable {12345678} {12345678} {12345678} {12345678}
2279 @tab 1 @tab 2 @tab 3
2287 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
2289 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
2292 @xref{Tabs and Fields}.
2294 @node Implicit Line Breaks, , Tab Stops, Text
2295 @subsection Implicit Line Breaks
2296 @cindex implicit line breaks
2297 @cindex line, implicit breaks
2299 @cindex break, implicit
2302 An important concept in @code{gtroff} is the @dfn{break}. When a break
2303 occurs, @code{gtroff} will output the partially filled line
2304 (unjustified), and resume collecting and filling text on the next output
2310 There are several ways to cause a break in @code{gtroff}. A blank line
2311 will not only cause a break, but it will also cause a one line vertical
2312 space (effectively a blank line) to be output.
2316 A line which begins with a space will cause a break and the space will
2317 be output at the beginning of the next line. Note that this space isn't
2318 adjusted, even in fill mode.
2320 The end of file will also cause a break -- otherwise the last line of
2321 the document may vanish!
2323 Certain requests also cause breaks, implicitly or explicitly. This will
2324 be discussed in @ref{Manipulating Filling and Adjusting}.
2327 @node Input Conventions, Measurements, Text, Programming Tutorial
2328 @section Input Conventions
2329 @cindex input conventions
2330 @cindex conventions for input
2332 Since @code{gtroff} does filling automatically, it is traditional in
2333 @code{groff} not to try and type things in as nicely formatted
2334 paragraphs. These are some conventions commonly used when typing
2339 Break lines after punctuation, particularly at the end of sentences,
2340 and in other logical places. Keep separate phrases on lines by
2341 themselves, as entire phrases are often added or deleted when editing.
2344 Try to keep lines less than 40-60@w{ }characters, to allow space for
2345 inserting more text.
2348 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
2349 don't try and use spaces to get proper indentation).
2353 @node Measurements, Expressions, Input Conventions, Programming Tutorial
2354 @section Measurements
2355 @cindex measurements
2357 @cindex units of measurement
2359 @cindex machine units
2360 @cindex measurement units
2361 @cindex @code{u} unit
2362 @cindex unit, @code{u}
2363 @code{gtroff} (like any other programs) requires numeric parameters to
2364 specify various measurements. Most numeric parameters@footnote{those
2365 that specify vertical or horizontal motion or a type size} may have a
2366 @dfn{measurement unit} attached. These units are specified as a single
2367 character which immediately follows the number or expression. Each of
2368 these units are understood, by @code{gtroff}, to be a multiple of its
2369 @dfn{basic unit}. So, whenever a different measurement unit is
2370 specified @code{gtroff} converts this into its @dfn{basic units}. This
2371 basic unit, represented by a @samp{u}, is a device dependent measurement
2372 which is quite small, ranging from 1/75th to 1/72000th of an inch. The
2373 values may be given as fractional numbers -- nevertheless, fractional
2374 basic units are always rounded to integers.
2376 Some of the measurement units are completely independent of any of the
2377 current settings (e.g.@: type size) of @code{gtroff}.
2382 @cindex @code{i} unit
2383 @cindex unit, @code{i}
2384 Inches. An antiquated measurement unit still in use in certain
2385 backwards countries. One inch is equal to@w{ }2.54@dmn{cm}.
2389 @cindex @code{c} unit
2390 @cindex unit, @code{c}
2391 Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
2395 @cindex @code{p} unit
2396 @cindex unit, @code{p}
2397 Points. This is a typesetter's measurement used for measure type size.
2398 It is 72@w{ }points to an inch.
2402 @cindex @code{P} unit
2403 @cindex unit, @code{P}
2404 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
2405 12@w{ }points to a pica).
2409 @cindex @code{s} unit
2410 @cindex unit, @code{s}
2411 @cindex @code{z} unit
2412 @cindex unit, @code{z}
2413 @xref{Fractional Type Sizes}, for a discussion of these units.
2416 The other measurements understood by @code{gtroff} are dependent on
2417 settings currently in effect in @code{gtroff}. These are very useful
2418 for specifying measurements which should look proper with any size of
2424 @cindex @code{m} unit
2425 @cindex unit, @code{m}
2426 Ems. This unit is equal to the current font size in points. So called
2427 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
2428 in the current font.
2432 @cindex @code{n} unit
2433 @cindex unit, @code{n}
2434 Ens. This is half of an em.
2437 @cindex vertical space
2438 @cindex space, vertical
2439 @cindex @code{v} unit
2440 @cindex unit, @code{v}
2441 Vertical space. This is equivalent to the current line spacing.
2442 @xref{Sizes}, for more information about this.
2445 @cindex @code{M} unit
2446 @cindex unit, @code{M}
2454 @node Default Units, , Measurements, Measurements
2455 @subsection Default Units
2456 @cindex default units
2457 @cindex units, default
2459 Many requests take a default unit. While this can be helpful at times,
2460 it can cause strange errors in some expressions. For example, the line
2461 length request expects em units. Here are several attempts to get a
2462 line length of 3.5@w{ }inches and the results:
2469 7i/2u @result{} 3.5i
2473 Everything will be converted to basic units first. In the above example
2474 it is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m}
2475 equals@w{ }10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value
2476 7i/2 will be first handled as 7i/2m, then converted to 1680u/66u which
2477 is 25@dmn{u}, and this is approximately 0.1@dmn{i}.
2479 As a conclusion, the safest way to specify measurements is to always
2480 attach a scaling indicator. If you want to multiply or divide by a
2481 certain scalar value, use @samp{u} as the unit for that value.
2484 @node Expressions, Identifiers, Measurements, Programming Tutorial
2485 @section Expressions
2488 @code{gtroff} has most of operators common to other languages:
2490 @c XXX more details; examples
2494 @cindex arithmetic operators
2495 @cindex operators, arithmetic
2501 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
2502 (division), @samp{*} (multiplication), @samp{%} (modulo).
2504 @code{gtroff} only provides integer arithmetic. The internal type used
2505 for computing results is @samp{int}, which is usually a 32@dmn{bit}
2509 @cindex comparison operators
2510 @cindex operators, comparison
2517 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
2518 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
2519 (equal), @samp{==} (the same as @samp{=}).
2522 @cindex logical operators
2523 @cindex operators, logical
2526 Logical: @samp{&} (logical and), @samp{:} (logical or).
2529 @cindex unary operators
2530 @cindex operators, unary
2536 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
2537 (just for completeness; does nothing in expressions), @samp{!} (logical
2538 not; this works only within @code{if} and @code{while} requests). See
2539 below for the use of unary operators in motion requests.
2542 @cindex extremum operators
2543 @cindex operators, extremum
2546 Extrema: @samp{>?} (maximum), @samp{<?} (minimum). For example,
2547 @samp{5>?3} yields@w{ }@samp{5}.
2552 @cindex scaling operator
2553 @cindex operator, scaling
2554 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
2555 the default scaling indicator. If @var{c} is missing, ignore scaling
2556 indicators in the evaluation of @var{e}.
2560 @cindex order of evaluation in expressions
2561 @cindex expression, order of evaluation
2564 Parentheses may be used as in any other language. However, in
2565 @code{gtroff} they are necessary to ensure order of evaluation.
2566 @code{gtroff} has no operator precedence; expressions are evaluated left
2567 to right. This means that @samp{3+5*4} is evaluated as if it were
2568 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as expected.
2573 @cindex motion operators
2574 @cindex operators, motion
2575 For many requests which cause a motion on the page, the unary operators
2576 work differently. The @samp{+} and @samp{-} operators then indicate a
2577 motion relative to the current position (down or up, respectively), and
2578 the @samp{|} operator indicates an absolute position on the page or
2581 @samp{+} and @samp{-} are also treated differently by the following
2582 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
2583 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
2584 @code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus
2585 signs indicate increments resp.@: decrements.
2587 @c XXX add more xref
2588 @xref{Setting Registers}.
2590 @cindex space characters in expressions
2591 @cindex expressions and space characters
2592 Due to the way arguments are parsed, spaces are not allowed in
2593 expressions, unless the entire expression is surrounded by parentheses.
2595 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2598 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
2599 @section Identifiers
2602 Like any other language, @code{gtroff} has rules for properly formed
2603 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
2604 almost any printable character. The exception are the following
2609 @cindex whitespace characters
2610 @cindex newline character
2611 @cindex character, whitespace
2612 Whitespace characters (space, tabs, and newlines).
2615 @cindex character, backspace
2616 @cindex backspace character
2617 @cindex @acronym{EBCDIC} encoding
2618 Backspace (@acronym{ASCII}@w{ }@code{0x08} resp.@: @acronym{EBCDIC}@w{
2619 }@code{0x16}) and character code @code{0x01}.
2622 @cindex illegal input characters
2623 @cindex input characters, illegal
2624 @cindex characters, illegal input
2626 The following input characters are illegal and will be ignored if
2627 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
2628 warning message of type @samp{input} (@pxref{Debugging}, for more
2629 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
2630 @code{0x80}-@code{0x9F}.
2632 And here the illegal input characters if @code{groff} runs on an
2633 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
2634 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
2635 @code{0x30}-@code{0x3F}.
2637 Currently, some of these reserved codepoints are used internally, thus
2638 making it non-trivial to extend @code{gtroff} to cover Unicode or other
2639 character sets resp.@: encodings which use characters of these ranges.
2641 Note that illegal characters will be removed before parsing; an
2642 identifier `foo', followed by an illegal character, followed by `bar'
2643 will be treated as `foobar'.
2646 For example, any of the following is valid.
2657 Note that identifiers longer than two characters with a closing bracket
2658 (@samp{]}) in its name can't be accessed with escape sequences which
2659 expect an identifier as a parameter. For example, @samp{\[foo]]} will
2660 access the glyph @samp{foo}, followed by @samp{]}, whereas
2661 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
2665 @Deffn{Escape, \\A, ident}
2666 Whether an identifier @var{ident} is valid in @code{gtroff} can be
2667 tested with the @code{\A} escape. It expands to the character@w{ }1
2668 or@w{ }0 according to whether its argument (delimited by quotes usually)
2669 is or is not acceptable as the name of a string, macro, diversion,
2670 number register, environment, or font. It will return@w{ }0 if no
2671 argument is given. This is useful for looking up user input in some
2672 sort of associative table.
2680 @xref{Escapes}, for details on parameter delimiting characters.
2682 @c XXX add xrefs above
2684 Identifiers in @code{gtroff} can be any length, but, in some contexts,
2685 @code{gtroff} needs to be told where identifiers end and text begins
2686 (and in different ways depending on their length).
2696 Two characters. Must be prefixed with @samp{(} in some situations.
2699 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
2700 and@w{ }@samp{]} in some situations. Any length identifier can be put
2704 @cindex undefined identifiers
2705 @cindex indentifiers, undefined
2706 Unlike many other programming languages, undefined identifiers are
2707 silently ignored or expanded to nothing.
2709 @c XXX add info about -ww command line option.
2711 @xref{Interpolating Registers}, and @ref{Strings}.
2714 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
2715 @section Embedded Commands
2716 @cindex embedded commands
2717 @cindex commands, embedded
2719 Most documents need more functionality beyond filling, adjusting and
2720 implicit line breaking. In order to gain further functionality,
2721 @code{gtroff} allows commands to be embedded into the text, in two ways.
2723 The first is a @dfn{request} which takes up an entire line, and does
2724 some large scale operation (e.g.@: break lines, start new pages).
2726 The other is an @dfn{escape} which can be embedded anywhere in the text,
2727 or even as an argument to a request.
2728 @c XXX (Not always?)
2729 Escapes generally do more minor operations like sub- and superscripts,
2730 print a symbol, etc.
2738 @node Requests, Macros, Embedded Commands, Embedded Commands
2739 @subsection Requests
2742 @cindex control character
2743 @cindex character, control
2746 A request line begins with a control character, which is either a single
2747 quote (@samp{'}) or a period (@samp{.}). These can be changed; see
2748 @ref{Character Translations}, for details. After this there may be
2749 optional tabs or spaces followed by an identifier which is the name of
2750 the request. This may be followed by any number of space-separated
2753 @cindex zero width space character
2754 @cindex character, zero width space
2755 @cindex space character, zero width
2757 To begin a line with a control character without it being interpreted,
2758 precede it with @code{\&}. This represents a zero width space, which
2759 means it will not affect the output.
2761 In most cases the period is used as a control character. Several
2762 requests will cause a break; using the single quote control character
2766 * Request Arguments::
2769 @node Request Arguments, , Requests, Requests
2770 @subsubsection Request Arguments
2771 @cindex request arguments
2772 @cindex arguments to requests
2774 Arguments to requests (and macros) are processed much like the shell:
2775 The line is split into arguments according to spaces. An argument which
2776 is intended to contain spaces can either be enclosed in quotes (single
2777 or double), or have the spaces @dfn{escaped} with backslashes.
2780 .uh The Mouse Problem
2781 .uh "The Mouse Problem"
2782 .uh The\ Mouse\ Problem
2788 The first line is the @code{uh} macro being called with 3 arguments,
2789 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
2790 same effect or calling the @code{uh} macro with one argument @samp{The
2791 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
2792 is `classical' in the sense that it can be found in most @code{troff}
2793 documents. Nevertheless, it is not optimal in all situations since
2794 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
2795 can't stretch. @code{gtroff} provides a different command @code{\~} to
2796 insert a stretchable, non-breaking space.}
2799 Note, however, that the @code{ds} request works differently.
2800 @xref{Strings}, for more details.
2802 @node Macros, Escapes, Requests, Embedded Commands
2806 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
2807 which can be invoked by name. They are called in the same manner as
2808 requests -- arguments also may be passed in the same manner.
2810 @xref{Writing Macros}, and @ref{Request Arguments}.
2812 @node Escapes, , Macros, Embedded Commands
2816 Escapes may occur anywhere in the input to @code{gtroff}. They begin
2817 with a backslash usually and are followed by a single character which
2818 indicates the function to be performed. The escape character can be
2819 changed; see @ref{Character Translations}.
2824 Escape sequences which require an identifier as a parameter accept three
2825 possible syntax forms.
2829 The next single character is the identifier.
2832 If this single character is an opening parenthesis, take the following
2833 two characters as the identifier. Note that there is no closing
2834 parenthesis after the identifier.
2837 If this single character is an opening bracket, take all characters
2838 until a closing bracket as the identifier.
2851 @cindex argument delimiting characters
2852 @cindex characters, argument delimiting
2853 @cindex delimiting characters for arguments
2854 Other escapes may require several arguments and/or some special format.
2855 In such cases the argument is traditionally enclosed in single quotes
2856 (and quotes are always used in this manual for the definitions of escape
2857 sequences). The enclosed text is then processed according to what that
2858 escape expects. Example:
2867 Note that the quote character can be replaced with any other character
2868 which does not occur in the argument (even a newline or a space
2869 character) in the following escapes: @code{\o}, @code{\b}, and
2870 @code{\X}. This makes e.g.
2879 @result{} A caf@'e in Paris
2883 possible, but it is better not to use this feature to avoid confusion.
2913 The following escapes sequences (which are handled similarly to
2914 characters since they don't take a parameter) are also allowed as
2915 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
2916 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
2917 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
2918 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
2919 @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't
2920 use these if possible.
2926 No newline characters as delimiters are allowed in the following
2927 escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}.
2940 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
2941 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
2942 @code{\x} can't use the following characters as delimiters:
2948 The digits @code{0}-@code{9}.
2965 The (single character) operators @samp{+-/*%<>=&:().}.
2968 @cindex space character
2969 @cindex character, space
2970 @cindex tab character
2971 @cindex character, tab
2972 @cindex newline character
2973 @cindex character, newline
2974 The space, tab, and newline characters.
2990 All escape sequences except @code{\%}, @code{\@{}, @code{\@}},
2991 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
2992 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
2998 To have a backslash (resp.@: the current escape character) appear in the
2999 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
3000 These are very similar, and only differ with respect to being used in
3001 macros or diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for
3004 @c XXX explanation of \E
3006 @xref{Identifiers}, and @ref{Character Translations}.
3012 @node Comments, , Escapes, Escapes
3013 @subsubsection Comments
3016 Probably one of the most@footnote{Unfortunately, this is a lie. But
3017 hopefully future @code{gtroff} hackers will believe it :-)} common forms
3018 of escapes is the comment.
3021 Start a comment. Everything to the end of the input line is ignored.
3023 This may sound simple, but it can be tricky to keep the comments from
3024 interfering with the appearance of the final output.
3027 If the escape is to the right of some text or a request, that portion of
3028 the line will be ignored, but the space leading up to it will be noticed
3029 by @code{gtroff}. This only affects the @code{.ds} request.
3030 @c XXX (any others?)
3032 One possibly irritating idiosyncracy is that tabs must not be used to
3033 line up comments. Tabs are not treated as white space between the
3034 request and macro arguments.
3036 @cindex undefined request
3037 @cindex request, undefined
3038 A comment on a line by itself will be treated as a blank line, because
3039 after eliminating the comment, that is all that remains:
3056 As a consequence, it is common to start the line with @code{.\"} which
3057 will cause the line to be treated as an undefined request and thus
3061 Another commenting scheme seen sometimes is three consecutive single
3062 quotes (@code{'''}) at the beginning of a line. This works, but
3063 @code{gtroff} will give a warning about an undefined macro (namely
3064 @code{''}), which is harmless, but irritating.
3068 Now to avoid all this @code{gtroff} has a new comment mechanism using
3069 the @code{\#} escape. This escape works the same as @code{\"} except
3070 that the newline is also ignored:
3090 For large blocks of text, the @code{ig} request may be useful.
3092 @c XXX definition of .ig
3096 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
3100 Numeric variables in @code{gtroff} are called @dfn{registers}. There
3101 are a number of built-in registers, supplying anything from the date to
3102 details of formatting parameters.
3104 @xref{Identifiers}, for details on register identifiers.
3107 * Setting Registers::
3108 * Interpolating Registers::
3110 * Assigning Formats::
3111 * Built-in Registers::
3114 @node Setting Registers, Interpolating Registers, Registers, Registers
3115 @subsection Setting Registers
3116 @cindex setting registers
3117 @cindex registers, setting
3119 Registers are defined resp.@: set via the @code{nr} request or the
3122 @Deffn{Request, nr, ident value}
3123 @Deffnx{Escape, \\R, ident value}
3124 Set number register @var{ident} to @var{value}. If @var{ident} doesn't
3125 exist, it will be created.
3127 The argument to @code{\R} has to be enclosed in quotes usually.
3128 @xref{Escapes}, for details on parameter delimiting characters.
3131 For example, the following two lines are equivalent:
3138 Both @code{nr} and @code{\R} have two additional special forms to
3139 increment resp.@: decrement a register.
3141 @Deffn{Request, nr, ident +value}
3142 @Deffnx{Request, nr, ident -value}
3143 @Deffnx{Escape, \\R, ident +value}
3144 @Deffnx{Escape, \\R, ident -value}
3145 Increment (decrement) register @var{ident} by @var{value}.
3154 To assign the negated value of a register to another register, some care
3155 must be taken to get the desired result:
3169 The surrounding parentheses prevent the interpretation of the minus sign
3170 as a decrementing operator. An alternative is to start the assignment
3185 @Deffn{Request, rr, ident}
3186 Remove number register @var{ident}. If @var{ident} doesn't exist, the
3190 @Deffn{Request, rnn, ident1 ident2}
3191 Rename number register @var{ident1} to @var{ident2}. If either
3192 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
3195 @Deffn{Request, aln, ident1 ident2}
3196 This request creates an alias @var{ident1} for a number register
3197 @var{ident2}. The new name and the old name will be exactly equivalent.
3198 If @var{ident1} is undefined, a warning of type @samp{reg} will be
3199 generated, and the request will be ignored. @xref{Debugging}, for
3200 information about warnings.
3203 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
3204 @subsection Interpolating Registers
3205 @cindex interpolating registers
3206 @cindex registers, interpolating
3208 Numeric registers can be accessed via the @code{\n} escape.
3210 @Deffn{Escape, \\n, ident}
3211 @c XXX is the following correct?
3212 Interpolate number register @var{ident}. This means that the value of
3213 the register is expanded in-place while @code{gtroff} is parsing the
3224 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
3225 @subsection Auto-increment
3226 @cindex auto-increment
3227 @cindex increment, automatic
3229 Number registers can also be auto-incremented and auto-decremented. The
3230 increment resp.@: decrement factor can be specified with a third
3231 argument to the @code{nr} request or @code{\R} escape.
3234 @Deffn{Request, nr, ident value incr}
3235 Set number register @var{ident} to @var{value}; the increment for
3236 auto-incrementing is set to @var{incr}. Note that the @code{\R} escape
3237 doesn't support this notation.
3240 To activate auto-incrementing, the escape @code{\n} has a special syntax
3243 @Deffn{Escape, \\n, +ident}
3244 @Deffnx{Escape, \\n, -ident}
3245 Before interpolating, increment resp.@: decrement @var{ident} by the
3246 auto-increment value as specified with the @code{nr} request (or the
3247 @code{\R} escape). If no auto-increment value has been specified, both
3248 syntax forms are identical to @code{\n}.
3257 \n+a, \n+a, \n+a, \n+a, \n+a
3259 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
3261 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
3269 -5, -10, -15, -20, -25
3273 To change the increment value without changing the value of a register,
3274 the following can be used.
3280 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
3281 @subsection Assigning Formats
3282 @cindex assigning formats
3283 @cindex formats, assigning
3285 When a register is used in the text of an input file (as opposed to part
3286 of an expression) it is textually replaced (or interpolated) with a
3287 representation of that number. This output format can be changed to a
3288 variety of formats (numbers, Roman numerals, etc). This is done using
3289 the @code{af} request.
3291 @Deffn{Request, af, ident format}
3292 Change the output format of a number register. The first argument
3293 @var{ident} is the name of the number register to be changed, and the
3294 second argument @var{format} is the output format. The following output
3295 formats are available:
3299 Decimal numbers. This is the default format: 1, 2, 3,@w{ }@dots{}
3302 Decimal numbers with as many digits as specified. So, @samp{00} would
3303 result in printing numbers as 01, 02, 03,@w{ }@dots{}
3305 In fact, any digit instead of zero will do; @code{gtroff} only counts
3306 how many digits are specified. As a consequence, @code{af}'s default
3307 format @samp{1} could be specified as @samp{0} also (and exactly this is
3308 returned by the @code{\g} escape).
3311 @cindex roman numerals
3312 @cindex numerals, Roman
3313 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@dots{}
3316 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@dots{}
3319 Upper-case letters: A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@dots{}
3322 Lower-case letters: a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@dots{}
3325 Omitting the number register format will cause a warning of type
3326 @samp{missing}. @xref{Debugging}, for more details. Specifying a
3327 nonexistent format causes an error.
3329 The following example will produce @samp{10, X, j, 010}:
3333 .af a 1 \" the default format
3343 The largest number representable for the @samp{i} and @samp{I} formats
3344 is 39999 (resp.@: -39999); @acronym{UNIX} @code{troff} uses @samp{z} and
3345 @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
3346 @code{gtroff}. Currently, the correct glyphs (Unicode code points
3347 @code{U+2182} and @code{U+2181}, respectively) are not available.
3349 If @var{ident} doesn't exist, it will be created.
3351 Changing the output format of a read-only register causes an error. It
3352 is necessary to first copy the register's value to a writeable register,
3353 then apply the @code{af} request to this other register.
3356 @Deffn{Escape, \\g, ident}
3357 Return the current format of the specified register @var{ident}. For
3358 example, @samp{\ga} after the previous example would produce the string
3359 @samp{000}. If the register hasn't been defined yet, nothing is
3363 @node Built-in Registers, , Assigning Formats, Registers
3364 @subsection Built-in Registers
3365 @cindex built-in registers
3366 @cindex registers, built-in
3368 The following lists some built-in registers which are not described
3369 elsewhere in this manual. Any register which begin with a @samp{.} is
3370 read-only. A complete listing of all built-in registers can be found in
3371 @ref{Register Index}.
3375 @cindex horizontal resolution
3376 @cindex resolution, horizontal
3378 Horizontal resolution in basic units.
3381 @cindex vertical resolution
3382 @cindex resolution, vertical
3384 Vertical resolution in basic units.
3387 @cindex day of the week
3388 @cindex date, day of the week
3390 Day of the week (1-7).
3393 @cindex day of the month
3394 @cindex date, day of the month
3396 Day of the month (1-31).
3399 @cindex month of the year
3400 @cindex date, month of the year
3402 Current month (1-12).
3406 @cindex year, current
3412 The current year minus@w{ }1900. Unfortunately, the documentation of
3413 @acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
3414 incorrectly claimed that @code{yr} contains the last two digits of the
3415 year. That claim has never been true of either traditional @code{troff}
3416 or GNU @code{troff}. Old @code{troff} input that looks like this:
3419 '\" The following line stopped working after 1999
3420 This document was formatted in 19\n(yr.
3424 can be corrected as follows:
3427 This document was formatted in \n[year].
3431 or, to be portable to older @code{troff} versions, as follows:
3435 This document was formatted in \n(y4.
3442 @cindex input line number
3443 @cindex line number, input
3444 The current @emph{input} line number. Register @samp{.c} is read-only,
3445 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
3446 affecting both @samp{.c} and @samp{c.}.
3451 @cindex output line number
3452 @cindex line number, output
3453 The current @emph{output} line number after a call to the @code{nm}
3454 request to activate line numbering.
3456 @c XXX xref nm request
3460 @cindex major version number
3461 @cindex version number, major
3462 The major version number. For example, if the version number is@w{
3463 }1.03 then @code{.x} will contain@w{ }@samp{1}.
3467 @cindex minor version number
3468 @cindex version number, minor
3469 The minor version number. For example, if the version number is@w{
3470 }1.03 then @code{.y} will contain@w{ }@samp{03}.
3474 @cindex revision number
3475 The revision number of @code{groff}.
3479 Always@w{ }1. Macros should use this to determine whether they are
3480 running under GNU @code{troff}.
3484 If the command line option @option{-a} is used to produce an
3485 @acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
3486 otherwise. @xref{Groff Options}.
3490 This register indicates whether the current page is actually being
3491 printed, i.e., whether the @option{-o} option is being used to only
3492 print selected pages. @xref{Groff Options}, for more information.
3496 If @code{gtroff} is called with the @option{-T} command line option, the
3497 number register @code{.T} is set to@w{ }1, and zero otherwise.
3498 @xref{Groff Options}.
3501 Additionally, @code{gtroff} predefines a single (read/write) string
3502 register @code{.T} which contains the current output device (for
3503 example, @samp{latin1} or @samp{ps}).
3507 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
3508 @section Manipulating Filling and Adjusting
3509 @cindex manipulating filling and adjusting
3510 @cindex filling and adjusting, manipulating
3511 @cindex adjusting and filling, manipulating
3512 @cindex justifying text
3513 @cindex text, justifying
3528 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
3529 Breaks}. The @code{br} request will likewise cause a break. Several
3530 other requests will also cause breaks, but implicitly. These are
3531 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
3532 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
3534 @Deffn{Request, br, }
3535 Break the current line, i.e., the input collected so far will be emitted
3540 Initially, @code{gtroff} will fill and adjust text to both margins.
3541 Filling can be disabled via the @code{nf} request and re-enabled with
3542 the @code{fi} request.
3546 @Deffn{Request, fi, }
3547 Activate fill mode (which is the default). This request implicitly
3548 enables adjusting; it will also cause a break in the text currently
3549 being filled. The number register @code{.u} is set to@w{ }1.
3551 The fill mode status is associated with the current environment
3552 (@pxref{Environments}).
3555 @cindex no-fill mode
3556 @cindex mode, no-fill
3557 @Deffn{Request, nf, }
3558 Activate no-fill mode. Input lines are output as-is, retaining line
3559 breaks. The current line length will be ignored. This command
3560 implicitly disables adjusting; it also causes a break. The number
3561 register @code{.u} will be set to@w{ }0.
3563 The fill mode status is associated with the current environment
3564 (@pxref{Environments}).
3567 @Deffn{Request, ad, [@var{mode}]}
3570 Activation and deactivation of adjusting will be implicitly done with
3571 calls to the @code{fi} resp.@: @code{nf} requests.
3573 @var{mode} can have one of the following values:
3577 @cindex ragged-right
3578 Adjust text to the left margin. This produces what is traditionally
3579 called ragged-right text.
3583 Adjust text to the right margin, producing ragged-left text.
3586 @cindex centered text
3588 Center filled text. This is different to the @code{ce} request which
3589 only centers text without filling.
3593 Justify to both margins. This is default of @code{gtroff}.
3596 With no argument, @code{gtroff} will adjust lines the same way before
3597 adjusting has been deactivated (with a call to @code{na}, for example).
3607 .ad \" back to centering
3612 The current adjustment mode is available in the number register
3613 @code{.j}; it can be stored and subsequently used to set adjustment.
3615 The adjustment mode status is associated with the current environment
3616 (@pxref{Environments}).
3619 @Deffn{Request, na, }
3620 Disable adjusting. This request won't change the current adjustment
3621 mode: A call to @code{ad} afterwards will use the previous adjustment
3624 The adjustment mode status is associated with the current environment
3625 (@pxref{Environments}).
3628 @Deffn{Escape, \\p, }
3629 Adjust the current line and cause a break.
3631 In most cases this will produce very ugly results, since @code{gtroff}
3632 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
3633 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
3637 This is an uninteresting sentence.
3638 This is an uninteresting sentence.\p
3639 This is an uninteresting sentence.
3645 This is an uninteresting sentence. This is an
3646 uninteresting sentence.
3647 This is an uninteresting sentence.
3651 @cindex word space size
3652 @cindex size of word space
3653 @cindex space between words
3654 @cindex sentence space size
3655 @cindex size of sentence space
3656 @cindex space between sentences
3657 @Deffn{Request, ss, word_space_size [@var{sentence_space_size}]}
3658 Change the minimum size of a space between filled words. It takes its
3659 units as one twelfth of the space width parameter for the current font.
3660 Initially both the @var{word_space_size} and @var{sentence_space_size}
3665 If two arguments are given to the @code{ss} request, the second argument
3666 sets the sentence space size. If the second argument is not given,
3667 @var{sentence_space_size} will be the same as @var{word_space_size}.
3668 The sentence space size is used in two circumstances: If the end of a
3669 sentence occurs at the end of a line in fill mode, then both an
3670 inter-word space and a sentence space will be added; if two spaces
3671 follow the end of a sentence in the middle of a line, then the second
3672 space will be a sentence space. Note that the behaviour of
3673 @acronym{UNIX} @code{troff} will be exactly that exhibited by GNU
3674 @code{troff} if a second argument is never given to the @code{ss}
3675 request. In GNU @code{troff}, as in @acronym{UNIX} @code{troff}, a
3676 sentence should always be followed with either a newline or two spaces.
3680 The number registers @code{.ss} and @code{.sss} are the values of the
3681 parameters set by the first and second arguments of the @code{ss}
3684 The space and sentence space values are associated with the current
3685 environment (@pxref{Environments}).
3688 @cindex centering lines
3689 @cindex lines, centering
3690 @Deffn{Request, ce, [@var{nnn}]}
3691 Center text. While the @w{@samp{ad c}} request will also center text,
3692 it has the side effect of filling the text. @code{ce} will not fill the
3693 text it affects. This request causes a break.
3695 With no arguments, @code{ce} will center the next line of text.
3696 @var{nnn} is a number indicating the number of lines to be centered. If
3697 the argument is zero or negative, centering is disabled.
3699 A common idiom is to turn on centering for a large number of lines, and
3700 to turn off centering after text to be centered. This is useful for any
3701 request which takes a number of lines as an argument.
3714 The @code{.ce} number register contains the number of lines remaining to
3715 be centered, as set by the @code{ce} request.
3718 @cindex justifying text
3719 @cindex text, justifying
3720 @cindex right-justifying
3722 @Deffn{Request, rj, [@var{nnn}]}
3723 Justify unfilled text to the right margin. Its arguments are identical
3724 to the @code{ce} request. The @code{.rj} number register is the number
3725 of lines to be right-justified as set by the @code{rj} request. This
3726 request causes a line break.
3729 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
3730 @section Manipulating Hyphenation
3731 @cindex manipulating hyphenation
3732 @cindex hyphenation, manipulating
3734 As discussed in @ref{Hyphenation}, @code{gtroff} will hyphenate words.
3735 There are a number of ways to influence how hyphenation is done.
3737 @Deffn{Request, hy, [@var{mode}]}
3739 Enable hyphenation. The request has an optional numeric argument,
3740 @var{mode}, to restrict hyphenation if necessary:
3744 The default argument if @var{mode} is omitted. Hyphenate without
3748 Do not hyphenate the last word on a page or column.
3751 Do not hyphenate the last two characters of a word.
3754 Do not hyphenate the first two characters of a word.
3757 Values in the previous table are additive. For example, the value@w{
3758 }12 causes @code{gtroff} to neither hyphenate the last two nor the first
3759 two characters of a word.
3762 The current hyphenation restrictions can be found in the number register
3765 The hyphenation mode is associated with the current environment
3766 (@pxref{Environments}).
3769 @Deffn{Request, nh, }
3770 Disable hyphenation (i.e., set the hyphenation mode to zero). Note that
3771 the hyphenation mode of the last call to @code{hy} is not remembered.
3773 The hyphenation mode is associated with the current environment
3774 (@pxref{Environments}).
3780 @cindex explicit hyphens
3781 @cindex hyphen, explicit
3782 @cindex consecutive hyphenated lines
3783 @cindex lines, consecutive hyphenated
3784 @cindex hyphenated lines, consecutive
3785 @Deffn{Request, hlm, [@var{nnn}]}
3786 Set the maximum number of consecutive hyphenated lines to @var{nnn}. If
3787 this number is negative, there is no maximum. The default is@w{ }-1 if
3788 @var{nnn} is omitted. This value is associated with the current
3789 environment (@pxref{Environments}). Only lines output from a given
3790 environment count towards the maximum associated with that environment.
3791 Hyphens resulting from @code{\%} are counted; explicit hyphens are not.
3793 The current setting of @code{hlm} is available in the @code{.hlm}
3794 register. Also the number of immediately preceding consecutive
3795 hyphenated lines are available in the number register @samp{.hlc}.
3798 @Deffn{Request, hw, word1 word2 @dots{}}
3799 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
3800 words must be given with hyphens at the hyphenation points. For
3808 Besides the space character, any character which hyphenation code value
3809 is zero can be used to separate the arguments of @code{hw} (see the
3810 documentation for the @code{hcode} request below for more information).
3811 In addition, this request can be used more than once.
3813 Hyphenation exceptions specified with the @code{hw} request are
3814 associated with the current hyphenation language; it will cause an error
3815 if there is no current hyphenation language.
3817 In old versions of @code{troff} there was a limited amount of space to
3818 store such information; fortunately, with @code{gtroff}, this is no
3819 longer a restriction.
3822 @cindex hyphenation character
3823 @cindex character, hyphenation
3824 @cindex disabling hyphenation
3825 @cindex hyphenation, disabling
3826 @Deffn{Escape, \\%, }
3827 To tell @code{gtroff} how to hyphenate words on the fly, the @code{\%}
3828 escape, also known as the @dfn{hyphenation character}, can be used.
3829 Preceding a word with this character will prevent it from being
3830 hyphenated, putting it in a word will indicate to @code{gtroff} that the
3831 word may be hyphenated at that point. Note that this mechanism will
3832 only affect one word; to change the hyphenation of a word for the entire
3833 document, use the @code{hw} request.
3836 @Deffn{Request, hc, [@var{char}]}
3837 Change the hyphenation character to @var{char}. This character will
3838 then work the same as the @code{\%} escape, and, thus, no longer appear
3839 in the output. Without an argument, @code{hc} will reset the
3840 hyphenation character to be @code{\%} only.
3842 The hyphenation character is associated with the current environment
3843 (@pxref{Environments}).
3846 @cindex hyphenation patterns
3847 @cindex patterns for hyphenation
3848 @Deffn{Request, hpf, pattern_file}
3849 Read in a file of hyphenation patterns. This file will be searched for
3850 in the same way as @file{tmac.@var{name}} is searched for if the
3851 @option{-m@var{name}} option is specified.
3853 It should have the same format as the argument to the @code{\patterns}
3854 primitive in @TeX{} (without using @TeX{}'s macro expansion); the
3855 letters appearing in this file are interpreted as hyphenation codes. A
3856 @samp{%} character in the patterns file introduces a comment that
3857 continues to the end of the line.
3859 If no @code{hpf} request is specified (either in the document or in a
3860 macro package), @code{gtroff} won't hyphenate at all.
3866 The set of hyphenation patterns is associated with the current language
3867 set by the @code{hla} request. The @code{hpf} request is usually
3868 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
3869 @file{troffrc} loads hyphenation patterns for American English (in file
3872 It will cause an error if there is no current hyphenation language.
3875 @cindex hyphenation code
3876 @cindex code, hyphenation
3877 @Deffn{Request, hcode, c1 code1 c2 code2 @dots{}}
3878 Sets the hyphenation code of character @var{c1} to @var{code1}, that of
3879 @var{c2} to @var{code2}, etc. A hyphenation code must be a single input
3880 character (not a special character) other than a digit or a space.
3881 Initially each lower-case letter (@samp{a}-@samp{z}) has a hyphenation
3882 code, which is itself, and each upper-case letter (@samp{A}-@samp{Z})
3883 has a hyphenation code which is the lower-case version of itself.
3886 @cindex hyphenation margin
3887 @cindex margin for hyphenation
3889 @Deffn{Request, hym, [@var{length}]}
3890 Set the (right) hyphenation margin to @var{length}. If the current
3891 adjustment mode is not@w{ }@samp{b}, the line will not be hyphenated if
3892 it is shorter than @var{length}. Without argument, the hyphenation
3893 margin will be reset to its default value, which is@w{ }0. The default
3894 scaling indicator for this request is@w{ }@code{m}. The hyphenation
3895 margin is associated with the current environment
3896 (@pxref{Environments}).
3898 A negative argument will reset the hyphenation margin to zero, emitting
3899 a warning of type @samp{range}.
3902 The current hyphenation margin is available in the @code{.hym} register.
3905 @cindex hyphenation space
3907 @Deffn{Request, hys, [@var{hyphenation_space}]}
3908 Set the hyphenation space to @var{hyphenation_space}. If the current
3909 adjustment mode is@w{ }@samp{b}, don't hyphenate the line if the line
3910 can be justified by adding no more than @var{hyphenation_space} extra
3911 space to each word space. Without argument, the hyphenation space is
3912 set to its default value, which is@w{ }0. The default scaling indicator
3913 for this request is@w{ }@code{m}. The hyphenation space is associated
3914 with the current environment (@pxref{Environments}).
3916 A negative argument will reset the hyphenation space to zero, emitting a
3917 warning of type @samp{range}.
3920 The current hyphenation space is available in the @code{.hys} register.
3923 @cindex soft hyphen character
3924 @cindex character, soft hyphen
3928 @Deffn{Request, shc, [@var{char}]}
3929 Set the soft hyphen character to @var{char}. If the argument is
3930 omitted, the soft hyphen character will be set to the default character
3931 @code{\(hy}. The soft hyphen character is the character which will be
3932 inserted when a word is hyphenated at a line break. If the soft hyphen
3933 character does not exist in the font of the character immediately
3934 preceding a potential break point, then the line will not be broken at
3935 that point. Neither definitions (specified with the @code{char}
3936 request) nor translations (specified with the @code{tr} request) are
3937 considered when finding the soft hyphen character.
3944 @Deffn{Request, hla, language}
3945 Set the current hyphenation language to the string @var{language}.
3946 Hyphenation exceptions specified with the @code{hw} request and
3947 hyphenation patterns specified with the @code{hpf} request are both
3948 associated with the current hyphenation language. The @code{hla}
3949 request is usually invoked by the @file{troffrc} or the
3950 @file{troffrc-end} files; @file{troffrc} sets the default language to
3954 The current hyphenation language is available in the read-only register
3959 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
3960 @section Manipulating Spacing
3961 @cindex manipulating spacing
3962 @cindex spacing, manipulating
3964 @Deffn{Request, sp, [@var{distance}]}
3965 Space downwards @var{distance}. With no argument it will advance 1@w{
3966 }line. A negative argument will cause @code{gtroff} to move up the page
3967 the specified distance. If the argument is preceded by a @samp{|}
3968 @code{gtroff} will move that distance from the top of the page. This
3969 request causes a line break. The default scaling indicator is@w{
3973 @cindex double-spacing
3974 @Deffn{Request, ls, [@var{nnn}]}
3975 Output @var{nnn}-1 blank lines after each line of text. With no
3976 argument @code{gtroff} will go back to single spacing. For example,
3977 @w{@samp{.ls 2}} causes double-spaced output. The line spacing is
3978 associated with the current environment (@pxref{Environments}).
3981 The number register @code{.L} contains the current line spacing setting.
3984 @Deffn{Escape, \\x, spacing}
3985 Sometimes, extra vertical spacing is only needed occasionally, e.g.@: to
3986 allow space for a tall construct (like an equation). The @code{\x}
3987 escape will do this. The escape is given a numerical argument, usually
3988 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
3989 is@w{ }@code{v}. If this number is positive extra vertical space will
3990 be inserted below the current line. A negative number will add space
3991 above. If this escape is used multiple times on the same line, the
3992 maximum of the values is used.
3994 @xref{Escapes}, for details on parameter delimiting characters.
3997 The @code{.a} number register contains the most recent (nonnegative)
3998 extra vertical line space.
4002 ... example of inline equation ...
4007 @cindex no-space mode
4008 @cindex mode, no-space
4010 @cindex lines, blank
4011 @Deffn{Request, ns, }
4012 Enable @dfn{no-space mode}. In this mode, spacing (either via @code{sp}
4013 or via blank lines) is disabled. The @code{bp} request to advance to
4014 the next page is also disabled, except if it is accompanied by a page
4015 number (@pxref{Page Control}, for more information). This mode will end
4016 when actual text is output or the @code{rs} request is encountered.
4018 This request is useful for macros which want to avoid that subsequent
4019 macros inadvertently insert some vertical space before the text starts
4020 (for example, to set up the first paragraph after a section header).
4023 @Deffn{Request, rs, }
4024 Disable no-space mode.
4028 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
4029 @section Tabs and Fields
4030 @cindex tabs and fields
4031 @cindex fields and tabs
4033 @cindex @acronym{EBCDIC} encoding
4034 A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
4035 }5) causes a horizontal movement to the next tab stop (which is much
4036 like that on a typewriter).
4038 @Deffn{Escape, \\t, }
4039 This escape is a non-interpreted tab character. In copy mode
4040 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
4043 @Deffn{Request, ta, [@var{n1} @var{n2} @dots{} @var{nn} @t{T} @var{r1} @var{r2} @dots{} @var{rn}]}
4044 Change tab stop positions. This request takes a series of tab
4045 specifiers as arguments (optionally divided into two groups with the
4046 letter @samp{T}) which indicate where each tab stop is to be (overriding
4047 any previous settings).
4049 Tab stops can be specified absolutely, i.e., as the distance from the
4050 left margin. For example, the following will set 6@w{ }tab stops every
4054 .ta 1i 2i 3i 4i 5i 6i
4057 Tab stops can also be specified relatively (using a leading @samp{+})
4058 which means that the specified tab stop will be set that distance from
4059 the previous tab stop. For example, the following is equivalent to the
4063 .ta 1i +1i +1i +1i +1i +1i
4066 @code{gtroff} supports an extended syntax to specify repeat values after
4067 the @samp{T} mark (these values are always taken as relative) -- this is
4068 the usual way to specify tabs set at equal intervals. The following is,
4069 yet again, the same as the previous examples. It does even more since
4070 it defines an infinite number of tab stops separated by one inch.
4076 Now we are ready to interpret the full syntax given at the beginning:
4077 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
4078 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
4079 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
4080 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
4082 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
4083 20c 23c 28c 30c @dots{}}.
4085 The material in each tab column (i.e., the column between two tab stops)
4086 may be justified to the right or left or centered in the column. This
4087 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
4088 specifier. The default justification is @samp{L}. Example:
4098 The default unit of the @code{ta} request is @samp{m}.
4101 A tab stop is converted into a non-breakable horizontal movement which
4102 can be neither stretched nor squeezed. For example,
4111 creates a single line which is a bit longer than 10@w{ }inches (a string
4112 is used to show exactly where the tab characters are). Now consider the
4122 @code{gtroff} first converts the tab stops of the line into unbreakable
4123 horizontal movements, then splits the line after the second @samp{b}
4124 (assuming a sufficiently short line length). Usually, this isn't what
4128 Superfluous tabs (i.e., tab characters which do not correspond to a tab
4129 stop) are ignored except the first one which delimits the characters
4130 belonging to the last tab stop for right-justifying resp.@: centering.
4131 Consider the following example
4135 .ds ZZ foo\tbar\tfoobar
4136 .ds ZZZ foo\tbar\tfoo\tbar
4147 which produces the following output:
4156 The first line right-justifies the second `foo' relative to the tab
4157 stop. The second line right-justifies `foobar'. The third line finally
4158 right-justifies only `foo' because of the additional tab character which
4159 marks the end of the string belonging to the last defined tab stop.
4162 Tab stops are associated with the current environment
4163 (@pxref{Environments}).
4167 The number register @code{.tabs} contains a string representation of the
4168 current tab settings suitable for use as an argument to the @code{ta}
4172 @cindex tab repitition character
4173 @cindex character, tab repitition
4174 @Deffn{Request, tc, [@var{fill-char}]}
4175 Normally @code{gtroff} will fill the space to the next tab stop with
4176 space characters. This can be changed with the @code{tc} request. With
4177 no argument @code{gtroff} will revert to using spaces. The value of
4178 this @dfn{tab repitition} character is associated with the current
4179 environment (@pxref{Environments}).
4187 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
4191 Sometimes it may may be desirable to use the @code{tc} request to fill a
4192 particular tab stop with a given character (for example dots in a table
4193 of contents), but also normal tab stops on the rest of the line. For
4194 this @code{gtroff} provides an alternate tab mechanism, called
4195 @dfn{leaders} which will do just that.
4197 @cindex leader character
4198 A leader character (character code@w{ }1) behaves similarly to a tab
4199 character: It moves to the next tab stop. The only difference is that
4200 for this movement, the fill character defaults to a period and not to a
4203 @Deffn{Escape, \\a, }
4204 This escape is a non-interpreted leader character. In copy mode
4205 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
4209 @cindex leader repitition character
4210 @cindex character, leader repitition
4211 @Deffn{Request, lc, [@var{fill-char}]}
4212 The character that will be repeated can be declared with the @code{lc}
4213 request. Without an argument, leaders will act the same as tabs (i.e.,
4214 using space characters for filling). The value of this @dfn{leader
4215 repitition} character is associated with the current environment
4216 (@pxref{Environments}).
4219 @cindex table of contents
4220 @cindex contents, table of
4221 For a table of contents, to name an example, tab stops may be defined so
4222 that the section number is one tab stop, the title is the second with
4223 the remaining space being filled with a line of dots, and then the page
4224 number slightly separated from the dots.
4227 .ds entry 1.1\tFoo\a\t12
4237 1.1 Foo.......................................... 12
4240 @node Fields, , Leaders, Tabs and Fields
4244 @cindex field delimiting character
4245 @cindex delimiting character for fields
4246 @cindex character, field delimiting
4247 @cindex field padding character
4248 @cindex padding character for fields
4249 @cindex character, field padding
4250 @dfn{Fields} are a more general way of laying out tabular data. A field
4251 is defined as the data between a pair of @dfn{delimiting characters}.
4252 It contains substrings which are separated by @dfn{padding characters}.
4253 The width of a field is the distance on the @emph{input} line from the
4254 position where the field starts to the next tab stop. A padding
4255 character inserts stretchable space similar to @TeX{}'s @code{\hss}
4256 command (thus it can even be negative) to make the sum of all substring
4257 lengths plus the stretchable space equal to the field width. If more
4258 than one padding character is inserted, the available space is evenly
4259 distributed among them.
4261 @Deffn{Request, fc, [@var{delim-char} [@var{padding-char}]]}
4262 Define a delimiting and a padding character for fields. If the latter
4263 is missing, the padding character defaults to a space character. If
4264 there is no argument at all, the field mechanism is disabled. Note that
4265 contrary to e.g.@: the tab repitition character, delimiting and padding
4266 characters are not associated to the current environment
4267 (@pxref{Environments}).
4281 and here the result:
4289 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, Programming Tutorial
4290 @section Character Translations
4291 @cindex character translations
4292 @cindex translations of characters
4296 @cindex control character
4297 @cindex character, control
4298 @cindex no-break control character
4299 @cindex character, no-break control
4300 @cindex control character, no-break
4301 The control character (@samp{.}) and the no-break control character
4302 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
4305 @Deffn{Request, cc, [@var{c}]}
4306 Set the control character to @var{c}. With no argument the normal
4307 control character @samp{.} is restored. The value of the control
4308 character is associated with the current environment
4309 (@pxref{Environments}).
4312 @Deffn{Request, c2, [@var{c}]}
4313 Set the no-break control character to @var{c}. With no argument the
4314 normal control character @samp{'} is restored. The value of the
4315 no-break control character is associated with the current environment
4316 (@pxref{Environments}).
4320 @Deffn{Request, eo, }
4321 Disable the escape mechanism completely. After executing this request,
4322 the backslash character @samp{\} no longer starts an escape sequence.
4325 @cindex escape character
4326 @cindex character, escape
4327 @Deffn{Request, ec, [@var{c}]}
4328 Set the escape character to @var{c}. With no argument the normal escape
4329 character @samp{\} is restored. It can be also used to re-enable the
4330 escape mechanism after an @code{eo} request.
4332 Note that changing the escape character globally will likely break macro
4333 packages since @code{gtroff} has no mechanism (like @TeX{}) to `intern'
4334 macros, i.e., to convert a macro definition into an internal form which
4335 is independent of its printed representation. If a macro is called, it
4336 will be executed literally.
4339 @Deffn{Escape, \\e, }
4340 This escape sequence prints the current escape character (which is the
4341 backslash character @samp{\} by default).
4344 A @dfn{translation} is a mapping of an input character to an output
4345 character. The default mappings are given in the font definition files
4346 for the specific output device (@pxref{Font Files}); all mappings (both
4347 with @code{tr} and in the font definition files) occur at output time,
4348 i.e., the input character gets assigned the metric information of the
4349 mapped output character.
4351 @Deffn{Request, tr, @var{a}@var{b}@var{c}@var{d}@dots{}}
4352 Translate character @var{a} to @var{b}, character @var{c} to @var{d},
4353 etc. If there is an odd number of arguments, the last one will be
4354 translated to the space character.
4369 @cindex special character
4370 @cindex character, special
4371 @cindex numbered character
4372 @cindex character, numbered
4373 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
4374 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
4375 characters defined with the @code{char} request, and numbered characters
4376 (@code{\N'@var{xxx}'}) can be translated also.
4380 The @code{\e} escape can be translated also.
4384 Characters can be mapped onto the @code{\%} escape (but @code{\%} can't
4385 be mapped onto another character).
4388 @cindex backspace character
4389 @cindex character, backspace
4390 @cindex leader character
4391 @cindex character, leader
4392 @cindex newline character
4393 @cindex character, newline
4394 @cindex tab character
4395 @cindex character, tab
4398 The following characters can't be translated: space (with one exception,
4399 see below), backspace, newline, leader (and @code{\a}), tab (and
4404 Translations are not considered for finding the soft hyphen character
4405 set with the @code{shc} request.
4409 The character pair @samp{@var{c}\&} (this is an arbitrary character@w{
4410 }@var{c} followed by the zero width space character) will map this
4411 character to nothing.
4420 It is even possible to map the space character to nothing:
4429 As shown in the example, the space character can't be the first
4430 character pair as an argument of @code{tr}. It is also not possible to
4431 map the space character to any other character; requests like
4432 @w{@samp{.tr aa x}} will undo @w{@samp{.tr aa \&}} instead.
4434 If justification is active, lines will be justified inspite of the
4435 `empty' space character (but there is no minimal distance, i.e.@: the
4436 space character, between words).
4439 After an output character has been constructed (this happens at the
4440 moment immediately before the character is appended to an output
4441 character list, either by direct output, in a macro, diversion, or
4442 string), it is no longer affected by @code{tr}.
4449 @Deffn{Request, trnt, @var{a}@var{b}@var{c}@var{d}@dots{}}
4450 @code{trnt} is the same as the @code{tr} request except that the
4451 translations do not apply to text that is transparently throughput into
4452 a diversion with @code{\!}. @xref{Diversions}, for more information.
4465 will print @samp{b}; if @code{trnt} is used instead of @code{tr} it will
4470 @node Troff and Nroff Mode, Line Layout, Character Translations, Programming Tutorial
4471 @section Troff and Nroff Mode
4477 @c XXX .troff, .nroff
4480 @node Line Layout, Page Layout, Troff and Nroff Mode, Programming Tutorial
4481 @section Line Layout
4483 @cindex layout, line
4485 @cindex dimensions, line
4486 @cindex line dimensions
4487 The following drawing shows the dimensions which @code{gtroff} uses for
4488 placing a line of output onto the page. They are labeled with the
4489 request which manipulates that dimension.
4494 |<-----------ll------------>|
4495 +----+----+----------------------+----+
4497 +----+----+----------------------+----+
4499 |<--------paper width---------------->|
4504 These dimensions are:
4509 @cindex margin, left
4511 @cindex offset, page
4513 @dfn{Page offset} -- This is the leftmost position of text on the final
4514 output, defining the @dfn{left margin}.
4518 @cindex line indentation
4521 @dfn{Indentation} -- This is the distance from the left margin where
4522 text will be printed. This can be adjusted with the @code{in} request,
4523 and the current setting can be found in the built-in number register.
4524 @code{.i}. This request causes a break.
4528 There is also the request @code{ti} which will cause one output line to
4529 be indented, after which the indentation returns to@w{ }0. This request
4530 causes a break. The number register @code{.in} is the indent that
4531 applies to the current output line.
4535 @cindex length of line
4538 @dfn{Line length} -- This is the distance from the left margin to right
4539 margin. This can be adjusted with the @code{ll} request, and the
4540 current setting can be found in the built-in number register @code{.l}
4541 Note, as the figure implies, line length is not affected by the current
4542 indentation. The number register @code{.ll} is the line length that
4543 applies to the current output line.
4549 A bunch of really boring text which should
4550 be indented from both margins.
4551 Replace me with a better (and more) example!
4560 @Deffn{Request, po, [@var{offset}]}
4562 Set horizontal page offset to @var{offset}. Note that this request does
4563 not cause a break, so changing the page offset in the middle of text
4564 being filled may not yield the expected result. The initial value is
4565 1@dmn{i} if in troff mode, and 0 if in nroff mode (@pxref{Troff and
4566 Nroff Mode}); the default scaling indicator is@w{ }@code{m} (and not@w{
4567 }@code{v} as incorrectly documented in the original @acronym{UNIX} troff
4571 The current page offset can be found in the built-in number register
4574 If @code{po} is called without an argument, the page offset is reset to
4592 @node Page Layout, Page Control, Line Layout, Programming Tutorial
4593 @section Page Layout
4595 @cindex layout, page
4597 @code{gtroff} provides some very primitive operations for controlling
4601 @cindex length of page
4604 The @dfn{page length} can be specified via the @code{pl} request. This
4605 is the length of the physical output page. The current setting can be
4606 found in the built-in number register @code{.p}. Note that this only
4607 specifies the size of the page, not the top and bottom margins. Those
4608 are not done by groff directly. @xref{Traps}, for further information
4614 @code{gtroff} provides several operations which help in setting up top
4615 and bottom titles (or headers and footers)
4618 @cindex three-part title
4621 The @code{tl} request will print a @dfn{title line}, which consists of
4622 three parts: a left justified portion, a centered portion and a right
4623 justified portion. The argument to @code{tl} is specified as
4624 @code{'@var{left}'@var{center}'@var{right}'}. The @samp{%} character is
4625 replaced with the current page number. This character can be changed
4626 with the @code{pc} request (see below).
4628 @cindex length of title line
4629 @cindex title line, length
4632 The title line is printed using its own line length, which is specified
4633 with the @code{lt} request. The current setting of this is available in
4634 the @code{.lt} number register.
4637 @cindex number, page
4639 The @code{pn} request will change the page number of the @emph{next}
4640 page. The only argument is the page number.
4644 The current page number is stored in the number register @code{%}. The
4645 number register @code{.pn} contains the number of the next page: either
4646 the value set by a @code{pn} request, or the number of the current page
4649 @cindex changing the page number character
4650 @cindex page number character, changing
4652 The @code{pc} request will change the page number character (used by the
4653 @code{tl} request) to a different character. With no argument, this
4654 mechanism is disabled.
4659 @node Page Control, Fonts, Page Layout, Programming Tutorial
4660 @section Page Control
4661 @cindex page control
4662 @cindex control, page
4666 To stop processing the current page, and move to the next page, invoke
4667 the @code{bp} request. This request will also cause a break. It can
4668 also take an argument of what the next page should be numbered. The
4669 only difference between @code{bp} and @code{pn} is that @code{pn} does
4670 not cause a break or actually eject a page.
4676 .tl 'left top'center top'right top'
4683 It is often necessary to force a certain amount of space before a new
4684 page occurs. This is most useful to make sure that there is not a
4685 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
4686 request will ensure that there is a certain distance, specified by the
4687 first argument, before the next page is triggered (@pxref{Traps}, for
4688 further information). The default unit for @code{ne} is @code{v} and
4689 the default argument is@w{ }1@dmn{v}.
4691 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
4692 do the following before each paragraph:
4703 @code{sv} is similar to the @code{ne} request; it reserves the specified
4704 amount of vertical space. If the desired amount of space exists before
4705 the next trap (bottom page boundary), the space will be output
4706 immediately. If there is not enough space, it is stored for later
4707 output via the @code{os} request. The default argument is@w{ }1@dmn{v}
4708 and the default unit is @code{v}.
4711 @node Fonts, Sizes, Page Control, Programming Tutorial
4717 @code{gtroff} has the ability to switch fonts at any point in the text.
4718 There are two ways to do this, via the @code{ft} request and the
4721 Fonts are generally specified as upper-case strings, which are usually
4722 1@w{ }to 4 characters representing an abbreviation or acronym of the font
4725 The basic set of fonts are @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
4726 These are Times Roman, Italic, Bold, and Bold Italic. There is also at
4727 least one symbol font which contains various special symbols (Greek,
4728 mathematics). Such symbols fonts cannot be used directly, but should be
4736 * Artificial Fonts::
4737 * Ligatures and Kerning::
4740 @node Changing Fonts, Font Families, Fonts, Fonts
4741 @subsection Changing Fonts
4742 @cindex changing fonts
4743 @cindex fonts, changing
4746 @cindex previous font
4747 @cindex font, previous
4748 Font changes can be done either with the @code{ft} request or the
4749 @code{\f} request. With no arguments it will switch to the previous
4750 font (also known as @samp{P}).
4761 The @code{\f} escape is useful for changing fonts in the middle of
4765 eggs, bacon, \fBspam\fP and sausage.
4769 Both of the above examples will produce the same output. Note the usage
4770 of @samp{P} to indicate the previous font -- using @code{\f} it is not
4771 possible to omit this parameter.
4773 Sometimes when putting letters of different fonts, more or less space at
4774 such boundaries are needed. There are two escapes to help with this.
4777 @cindex italic correction
4778 @cindex correction, italic
4779 The @code{\/} escape increases the width of the preceding character so
4780 that the spacing between that character and the following character will
4781 be correct if the following character is a Roman character. For
4782 example, if an italic@w{ }f is immediately followed by a Roman right
4783 parenthesis, then in many fonts the top right portion of the f will
4784 overlap the top left of the right parenthesis. It is a good idea to use
4785 this escape sequence whenever an italic character is immediately
4786 followed by a Roman character without any intervening space. This small
4787 amount of space is also called @dfn{italic correction}.
4790 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids
4794 @cindex left italic correction
4795 @cindex correction, left italic
4796 The @code{\,} escape modifies the spacing of the following character so
4797 that the spacing between that character and the preceding character will
4798 be correct if the preceding character is a Roman character. It is a
4799 good idea to use this escape sequence whenever a Roman character is
4800 immediately followed by an italic character without any intervening
4801 space. In analogy to above, this space could be called @dfn{left italic
4802 correction}, but this term isn't used widely.
4805 @c For example, inserting \, between the parenthesis and the f changes
4819 The @code{ftr} request will translate fonts; its syntax is
4822 .ftr @var{F} @var{G}
4826 which translates font@w{ }@var{F} to font@w{ }@var{G}. Whenever a font
4827 named @var{F} is referred to in a @code{\f} escape sequence, or in the
4828 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
4829 @code{fspecial}, @code{fp}, or @code{code} requests, font@w{ }@var{G} will
4830 be used. If @var{G} is missing, or equal to @var{F} then font@w{
4831 }@var{F} will not be translated.
4833 @node Font Families, Font Positions, Changing Fonts, Fonts
4834 @subsection Font Families
4835 @cindex font families
4836 @cindex families, font
4838 Due to the variety of fonts available, @code{gtroff} has added the
4839 concept of font families. Each of these families has four styles
4840 (@samp{R}, @samp{I}, @samp{B} and @samp{BI}).
4842 The fonts are specified as the concatenation of the font family and
4843 style. Specifying a font without the family part will cause
4844 @code{gtroff} to use that style of the current family. By default,
4845 @code{gtroff} uses the Times family.
4847 This way, it is possible to use the basic four fonts and to select a
4848 different font family on the command line.
4852 Font families can be switched with the @code{fam} request. The current
4853 font family is available in the number register @code{.fam}. This is a
4854 string-valued register.
4870 @node Font Positions, Using Symbols, Font Families, Fonts
4871 @subsection Font Positions
4872 @cindex font positions
4873 @cindex positions, font
4875 For the sake of old phototypesetters and compatability with old versions
4876 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
4877 on which various fonts are mounted. The last one or two are reserved
4878 for the symbol font(s).
4881 New fonts can be mounted with the @code{fp} request. These numeric
4882 positions can then be referred to with font changing commands. When
4883 @code{gtroff} starts it is using font number one.
4899 Note that after these font changes have taken place the original font
4903 The current font in use, as a font position, is available in number
4904 register @code{.f}. This can be useful to remember the current font,
4909 ... lots 'o text ...
4914 The number of the next free font position is available in the number
4915 register @code{.fp}. This is useful when mounting a new font, like so:
4918 .fp \n[.fp] NEATOFONT
4922 Fonts not listed in the @file{DESC} file are automatically mounted on
4923 the next available font position when they are referenced. If a font is
4924 to be mounted explicitly with the @code{fp} request on an unused font
4925 position, it should be mounted on the first unused font position, which
4926 can be found in the @code{.fp} register. Although @code{gtroff} does
4927 not enforce this strictly, it will not allow a font to be mounted at a
4928 position whose number is much greater than that of any currently used
4932 The @code{fp} request has an optional third argument. This argument
4933 gives the external name of the font, which is used for finding the font
4934 description file. The second argument gives the internal name of the
4935 font which is used to refer to the font in @code{gtroff} after it has
4936 been mounted. If there is no third argument then the internal name will
4937 be used as the external name. This feature make it possible to use
4938 fonts with long names in compatibility mode.
4940 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
4941 @subsection Using Symbols
4942 @cindex using symbols
4943 @cindex symbols, using
4947 Symbols can be inserted by using a special escape sequence. This escape
4948 is simply the escape character (usually a backslash) followed by an
4949 identifier. The symbol identifiers have to be two or more characters,
4950 since single characters conflict with all the other escapes. The
4951 identifier can be either preceded by a parenthesis if it is two
4952 characters long, or surrounded by square brackets. So, the symbol for
4953 the mathematical Greek letter `pi' can be produced either by @code{\(*p}
4957 area = \(*p\fIr\fP\u2\d
4961 The escape @code{\C'@var{xxx}'} will typeset the character named
4962 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
4963 But @code{\C} has the advantage that it is compatible with recent
4964 versions of @code{ditroff} and is available in compatibility mode.
4968 The escape @code{\N'@var{n}'} will typeset the character with code@w{
4969 }@var{n} in the current font. @var{n} can be any integer. Most devices
4970 only have characters with codes between 0 and@w{ }255. If the current
4971 font does not contain a character with that code, special fonts will
4972 @emph{not} be searched. The @code{\N} escape sequence can be
4973 conveniently used on conjunction with the @code{char} request:
4976 .char \[phone] \f(ZD\N'37'
4981 @cindex unnamed characters
4982 @cindex characters, unnamed
4983 The code of each character is given in the fourth column in the font
4984 description file after the charset command. It is possible to include
4985 unnamed characters in the font description file by using a name of
4986 @samp{---}; the @code{\N} escape sequence is the only way to use these.
4988 @c XXX should be `glyph', not `character'
4991 @cindex character properties
4992 @cindex properties of characters
4993 Each character has certain properties associated with it. These
4994 properties can be modified with the @code{cflags} request. The first
4995 argument is the the sum of the desired flags and the remaining arguments
4996 are the characters to have those properties.
5000 @cindex end of sentence characters
5001 @cindex characters, end of sentence
5002 the character ends sentences (initially characters @samp{.?!} have this
5006 @cindex hyphenating characters
5007 @cindex characters, hyphenation
5008 lines can be broken before the character (initially no characters have
5014 lines can be broken after the character (initially the characters
5015 @samp{-\(hy\(em} have this property)
5018 @cindex overlapping characters
5019 @cindex characters, overlapping
5023 the character overlaps horizontally (initially the characters
5024 @samp{\(ul\(rn\(ru} have this property)
5028 the character overlaps vertically (initially character @samp{\(br} has
5032 @cindex transparent characters
5033 @cindex character, transparent
5041 an end of sentence character followed by any number of characters with
5042 this property will be treated as the end of a sentence if followed by a
5043 newline or two spaces; in other words the character is @dfn{transparent}
5044 for the purposes of end of sentence recognition -- this is the same as
5045 having a zero space factor in @TeX{} (initially characters
5046 @samp{"')]*\(dg\(rq} have this property).
5050 @cindex defining characters
5051 @cindex characters, defining
5052 New characters can be created with the @code{char} request. It is
5056 .char @var{c} @var{string}
5065 This defines character@w{ }@var{c} to be @var{string}. Every time
5066 character@w{ }@var{c} needs to be printed, @var{string} will be
5067 processed in a temporary environment and the result will be wrapped up
5068 into a single object. Compatibility mode will be turned off and the
5069 escape character will be set to @samp{\} while @var{string} is being
5070 processed. Any emboldening, constant spacing or track kerning will be
5071 applied to this object rather than to individual characters in
5072 @var{string}. A character defined by this request can be used just like
5073 a normal character provided by the output device. In particular other
5074 characters can be translated to it with the @code{tr} request; it can be
5075 made the leader character by the @code{lc} request; repeated patterns
5076 can be drawn with the character using the @code{\l} and @code{\L} escape
5077 sequences; words containing the character can be hyphenated correctly,
5078 if the @code{hcode} request is used to give the character a hyphenation
5079 code. There is a special anti-recursion feature: use of character
5080 within the character's definition will be handled like normal characters
5081 not defined with @code{char}.
5084 @cindex removing character definition
5085 @cindex character, removing definition
5086 A character definition can be removed with the @code{rchar} request.
5087 Its arguments are the characters to be removed. This undoes the effect
5088 of a @code{char} request.
5090 @xref{Special Characters}.
5092 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
5093 @subsection Artificial Fonts
5094 @cindex artificial fonts
5095 @cindex fonts, artificial
5097 There are a number of requests for artificially creating fonts. These
5098 are largely vestigial remains from the days when output devices did not
5099 have a wide variety of fonts, and when @code{nroff} and @code{troff}
5100 were separate programs. These are no longer necessary in GNU
5105 The @code{ul} request will print subsequent lines in italics on a device
5106 capable of it, or underline the text on an character output device. The
5107 single argument is the number of lines to be ``underlined,'' with no
5108 argument, the next line will be underlined.
5111 @cindex continuous underlining
5112 @cindex underlining, continuous
5113 The @code{cu} request is similar to @code{ul} ...
5118 @cindex underline font
5119 @cindex font for underlining
5120 The @code{uf} request will set the underline font used by @code{ul} and
5124 @cindex imitating bold face
5125 @cindex bold face, imitating
5126 The @code{bd} request artificially creates a bold font by printing each
5127 character twice, slightly offset. The first argument specifies the font
5128 to embolden, and the second is the number of basic units, minus one, by
5129 which the two characters will be offset. If the second argument is
5130 missing, emboldening will be turned off.
5132 @node Ligatures and Kerning, , Artificial Fonts, Fonts
5133 @subsection Ligatures and Kerning
5134 @cindex ligatures and kerning
5135 @cindex kerning and ligatures
5143 The ligature mechanism can be switched on or off with the @code{lg}
5144 request; if the parameter is non-zero or missing, ligatures are enabled,
5145 otherwise disabled. Default is on. The current ligature mode can be
5146 found in the number register @code{.lg} (set to@w{ }1 if ligatures are
5147 enabled, 0@w{ }otherwise).
5153 @cindex zero width space character
5154 @cindex character, zero width space
5155 @cindex space character, zero width
5156 If the font description file contains pairwise kerning information,
5157 characters from that font will be kerned. Kerning between two
5158 characters can be inhibited by placing @code{\&} between them.
5162 Kerning can be activated with the @code{kern} request. If the parameter
5163 is non-zero or missing, enable pairwise kerning, otherwise disable it.
5164 The number register @code{.kern} is set to@w{ }1 if pairwise kerning is
5165 enabled, 0@w{ }otherwise.
5168 @cindex track kerning
5169 @cindex kerning, track
5170 What is track kerning?
5174 Track kerning must be used with great care since it is usually
5175 considered bad typography if the reader notices the effect. The syntax
5176 of the @code{tkf} request is
5179 .tkf @var{f} @var{s1} @var{n1} @var{s2} @var{n2}
5183 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
5184 }@var{f} the width of every character will be increased by an amount
5185 between @var{n1} and @var{n2}; if the current point size is less than or
5186 equal to @var{s1} the width will be increased by @var{n1}; if it is
5187 greater than or equal to @var{s2} the width will be increased by
5188 @var{n2}; if the point size is greater than or equal to @var{s1} and
5189 less than or equal to @var{s2} the increase in width is a linear
5190 function of the point size.
5193 @node Sizes, Strings, Fonts, Programming Tutorial
5199 @cindex size of type
5200 @cindex vertical spacing
5201 @cindex spacing, vertical
5202 @code{gtroff} uses two dimensions with each line of text, type size and
5203 vertical spacing. The @dfn{type size} is the height from the text
5204 @dfn{baseline} to the top of the tallest character (descenders may drop
5205 below this baseline). @dfn{Vertical spacing} is the amount of space
5206 @code{gtroff} allows for a line of text; normally, this is about 20%@w{
5207 }larger than the current type size. Ratios smaller than this can result
5208 in hard-to-read text; larger that this, it will spread the text out more
5209 vertically (useful for term papers). By default, @code{gtroff} uses
5210 10@w{ }point type on 12@w{ }point spacing.
5213 The difference between type size and vertical spacing is known, by
5214 typesetters, as @dfn{leading}.
5217 * Changing Type Sizes::
5218 * Fractional Type Sizes::
5221 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
5222 @subsection Changing Type Sizes
5223 @cindex changing type sizes
5224 @cindex type sizes, changing
5231 Using the @code{ps} request and the @code{\s} escape the type size can
5232 be changed. The @code{vs} request will change the vertical spacing.
5233 The default unit for the @code{ps} and @code{vs} requests are points.
5234 The number registers @code{.s} and @code{.v} contain the current type
5235 size and vertical spacing.
5237 These requests take parameters in units of points. It is possible to
5238 specify sizes as an absolute size, or as a relative change from the
5239 current size. The size@w{ }0 means go back to the previous size. With
5240 no argument it will also revert to the previous size.
5247 wink, wink, \s+2nudge, nudge,\s+8 say no more!
5251 The @code{\s} escape may be called in a variety of ways. Much like
5252 other escapes there must be a way to determine where the argument ends
5253 and the text begins. Any of the following forms are valid:
5257 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 0
5258 or in the range 4 to@w{ }39.
5262 Increase resp.@: decrease the point size by @var{n}@w{ }points.
5263 @var{n}@w{ }must be exactly one digit.
5266 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly two
5273 Increase resp.@: decrease the point size by @var{nn}@w{ }points.
5274 @var{nn} must be exactly two digits.
5277 @xref{Fractional Type Sizes}, for yet another syntactical form of using
5278 the @code{\s} escape.
5280 Some devices may only have certain permissible sizes, in which case
5281 @code{gtroff} will round to the nearest permissible size.
5286 ... .sz macro example?? ...
5289 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
5290 @subsection Fractional Type Sizes
5291 @cindex fractional type sizes
5292 @cindex type sizes, fractional
5294 @cindex @code{s} unit
5295 @cindex unit, @code{s}
5296 @cindex @code{z} unit
5297 @cindex unit, @code{z}
5303 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
5304 @var{sizescale} is specified in the @file{DESC} file (1@w{ }by default.)
5305 There is a new scale indicator @samp{z} which has the effect of
5306 multiplying by @var{sizescale}. Requests and escape sequences in
5307 @code{gtroff} interpret arguments that represent a point size as being in
5308 units of scaled points, but they evaluate each such argument using a
5309 default scale indicator of @samp{z}. Arguments treated in this way are
5310 the argument to the @code{ps} request, the third argument to the
5311 @code{cs} request, the second and fourth arguments to the @code{tkf}
5312 request, the argument to the @code{\H} escape sequence, and those
5313 variants of the @code{\s} escape sequence that take a numeric expression
5314 as their argument (see below).
5316 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
5317 will be equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
5318 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 10250
5319 scaled points, which is equal to 10.25@w{ }points.
5321 It would make no sense to use the @samp{z} scale indicator in a numeric
5322 expression whose default scale indicator was neither @samp{u} nor
5323 @samp{z}, and so @code{gtroff} disallows this. Similarly it would make
5324 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
5325 numeric expression whose default scale indicator was @samp{z}, and so
5326 @code{gtroff} disallows this as well.
5328 There is also new scale indicator @samp{s} which multiplies by the
5329 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
5330 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
5335 The number register @code{.s} returns the point size in points as decimal
5336 fraction. There is also a new number register @code{.ps} that returns
5337 the point size in scaled points.
5341 The last-requested point size in scaled points is contained in the
5342 @code{.psr} number register. The last requested point size in points as
5343 a decimal fraction can be found in @code{.psr}. This is a string-valued
5349 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
5350 expression with a default scale indicator of @samp{z}.
5360 Increases resp.@: decreases the point size by @var{n} scaled points;
5361 @var{n} is a numeric expression with a default scale indicator of
5368 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
5373 @code{gtroff} has string variables, which are entirely for user
5374 convenience (i.e.@: there are no built-in strings). They are defined
5375 via the @code{ds} request.
5378 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
5382 @cindex string interpolation
5383 @cindex string expansion
5384 @cindex interpolation of strings
5385 @cindex expansion of strings
5386 They are interpolated, or expanded in-place, via the @code{\*} escape:
5389 The \*(UX Operating System
5392 If the string named by the @code{\*} does not exist, the escape will be
5393 replaced by nothing.
5395 @cindex comments, with @code{ds}
5396 @strong{Caution:} Unlike other requests, the second argument to the
5397 @code{ds} request takes up the entire line including trailing spaces.
5398 This means that comments on a line with such a request can introduce
5399 unwanted space into a string.
5402 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
5406 Instead the comment should be put on another line or have the comment
5407 escape adjacent with the end of the string.
5410 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
5413 @cindex trailing quotes
5414 @cindex quotes, trailing
5415 @cindex leading spaces with @code{ds}
5416 @cindex spaces with @code{ds}
5417 To produce leading space the string can be started with a double quote.
5418 No trailing quote is needed; in fact, any trailing quote is included in
5422 .ds sign " Yours in a white wine sauce,
5426 @cindex appending to strings
5427 @cindex strings, appending
5428 The @code{as} request will append a string to another string. It works
5429 similar to the @code{ds} request except that it appends the second
5430 argument onto the string named by the first argument.
5433 .as sign " with shallots, onions and garlic,
5437 @cindex multi-line strings
5438 @cindex strings, multi-line
5439 @cindex newline character, escaping
5440 @cindex escaping newline characters
5441 Strings are not limited to a single line of text. A string can span
5442 several lines by escaping the newlines with a backslash. The resulting
5443 string will be stored @emph{without} the newlines.
5446 .ds foo lots and lots \
5447 of text are on these \
5453 Rudimentary string manipulation routines are given with the
5454 @code{substring} and @code{length} requests. The former has the
5458 .substring @var{xx} @var{n1} [@var{n2}]
5462 It replaces the string in register@w{ }@var{xx} with the substring
5463 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
5464 in the string has index one. If @var{n2} is omitted, it is taken to be
5465 equal to the string's length. If the index value @var{n1} or @var{n2}
5466 is negative or zero, it will be counted from the end of the string,
5467 going backwards: The last character has index@w{ }0, the character
5468 before the last character has index@w{ }-1, etc.
5471 @cindex length of a string
5472 @cindex string, length of
5473 Here the syntax of the @code{length} request:
5476 .length @var{xx} @var{string}
5480 It computes the length of @var{string} and returns it in the number
5481 register@w{ }@var{xx} (which is not necessarily defined before).
5503 @xref{Identifiers}, and @ref{Comments}.
5506 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
5507 @section Conditionals and Loops
5508 @cindex conditionals and loops
5509 @cindex loops and conditionals
5513 In @code{if} and @code{while} requests, there are several more operators
5519 True if the current page is even or odd numbered (respectively).
5523 True if the document is being processed in nroff mode.
5527 True if the document is being processed in troff mode.
5529 @item '@var{xxx}'@var{yyy}'
5530 True if the string @var{xxx} is equal to the string @var{yyy}. Other
5531 characters can be used in place of the single quotes.
5533 The strings are `formatted' before being compared.
5537 True if there is a number register named @var{xxx}.
5540 True if there is a string, macro, diversion, or request named @var{xxx}.
5544 True if there is a character @var{ch} available; @var{ch} is either an
5545 @acronym{ASCII} character or a special character (@code{\(@var{ch}} or
5546 @code{\[@var{ch}]}); the condition will also be true if @var{ch} has
5547 been defined by the @code{char} request.
5555 @node if-else, while, Conditionals and Loops, Conditionals and Loops
5559 @code{gtroff} has if-then-else constructs like other languages, although
5560 the formatting can be painful.
5563 The @code{if} request has the following syntax:
5566 .if @var{expr} @var{anything}
5570 where @var{expr} is the expression to be evaluated; @var{anything} (the
5571 remainder of the line) will be executed if @var{expr} evaluates to
5572 non-zero (true). @var{anything} will be interpreted as though it was on
5573 a line by itself. @xref{Expressions}, for more info.
5575 Here are some examples:
5578 .if t .ls 2 \" double spacing in troff
5579 .if 0 .ab how'd this happen?
5584 An if-then-else is written using two requests @code{ie} and @code{el}.
5585 The first request is the `if' part and the latter is the `else' part.
5596 In many cases more than one request is to be executed as a result of any
5597 of these requests. This can be done using the @code{\@{} and @code{\@}}
5598 escapes. The following example shows the possible ways to use these
5599 escapes (note the position of the opening and closing braces).
5615 @node while, , if-else, Conditionals and Loops
5620 @code{gtroff} provides a looping construct using the @code{while}
5621 request, which is used much like the @code{if} (and related) requests.
5622 The first argument is an expression which will be evaluated. The
5623 @code{while} request will interpret the remainder of the line until the
5624 expression evaluates to 0 or false.
5628 .while (\na<9) \&\n+a,
5633 The preceding example produces:
5636 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
5639 @cindex zero width space character
5640 @cindex character, zero width space
5641 @cindex space character, zero width
5644 Note the usage of the @code{\&} escape to avoid a control character at
5645 the beginning of a line.
5649 The @code{break} request will @dfn{break} out of a while loop. Be sure
5650 not to confuse this with the @code{br} request (causing a line break).
5651 The @code{continue} request will finish the current iteration of a while
5652 loop, immediately restarting the next iteration.
5657 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
5658 @section Writing Macros
5659 @cindex writing macros
5660 @cindex macros, writing
5663 A @dfn{macro} is a collection of text and embedded commands which can be
5664 invoked multiple times. Macros are used for defining common operations.
5665 Macros are defined using the @code{de} request. This request takes a
5666 name for the macro as the first argument. Subsequent lines are copied
5667 into an internal buffer until the line @code{..} is encountered. The
5668 optional second argument to @code{de} can change this ending token.
5670 Here a small example macro called @samp{P} which will cause a break and
5671 the insertion of some vertical space. It could be used to separate
5682 The @code{am} request works similarly to @code{de} except it appends
5683 onto the macro named by the first argument. So, to make the previously
5684 defined @samp{P} macro actually do indented instead of block paragraphs,
5685 is is possible to add the necessary code to the existing macro like
5695 @cindex aliases, macro
5696 @cindex macro aliases
5697 Macros can be aliased with the @code{als} request.
5706 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
5707 @subsection Copy-in Mode
5708 @cindex copy-in mode
5709 @cindex mode, copy-in
5716 When @code{gtroff} reads in the text for a macro or diversion it copies
5717 the text (including request lines, but excluding escapes) into an
5718 internal buffer. Escapes will be converted into an internal form,
5719 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
5720 @code{\@key{RET}} which are evaluated and inserted into the text where
5721 the escape was located. This is known as @dfn{copy-in} mode or
5724 What this means is that you can specify when these escapes are to be
5725 evaluated (either at copy-in time or at the time of use) by insulating
5726 the escapes with an extra backslash. Compare this to the @code{\def}
5727 and @code{\edef} commands in @TeX{}.
5729 For example, the following will result in the numbers 20 and@c{ }10
5742 @node Parameters, , Copy-in Mode, Writing Macros
5743 @subsection Parameters
5748 The arguments to a macro can be examined using a variety of escapes.
5749 The number of arguments is available in the @code{.$} number register.
5750 Any individual argument can be retrieved with one of the following
5753 @cindex copy-in mode
5754 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
5755 @code{\$[@var{nnn}]} will result in the @var{n}th, @var{nn}th or
5756 @var{nnn}th argument. As usual, the first form only accepts a single
5757 number (larger than zero), the second only a two-digit number (larger or
5758 equal to@w{ }10), and the third any positive integer value (larger than
5759 zero). Macros can have an unlimited number of arguments. Note that due
5760 to copy-in mode, two backslashes should be used on these in actual use
5761 to prevent interpolation until the macro is actually invoked.
5764 The request @code{shift} will shift the arguments 1@w{ }position, or as
5765 many positions as specified by its argument. After executing this
5766 request, argument@w{ }@var{i} will become argument @var{i}-@var{n};
5767 arguments 1 to@w{ }@var{n} will no longer be available. Shifting by
5768 negative amounts is currently undefined.
5772 In some cases it is convenient to use all of the arguments at once (for
5773 example, to pass the arguments along to another macro). The @code{\$*}
5774 escape is the concatenation of all the arguments separated by spaces. A
5775 similar escape is @code{\$@@}, which is the concatenation of all the
5776 arguments with each surrounded by double quotes, and separated by
5781 The @code{\$0} escape is the name by which the current macro was
5782 invoked. The @code{als} request can make a macro have more than one
5787 .ie \\n(.$=1 .ds Vl Pre-Release Version
5788 .el .ds Vl Version \\$3, \\$4.
5792 This would be called as
5798 @xref{Request Arguments}.
5801 @node Page Motions, Drawing Requests, Writing Macros, Programming Tutorial
5802 @section Page Motions
5803 @cindex page motions
5804 @cindex motions, page
5807 Motions up and down the page can be done with the @code{sp} request.
5808 However, this causes a break so that the actual effect is to move to the
5809 left margin and then to the specified location.
5813 The request @code{mk} can be used to mark a location on a page, for
5814 movement to later. This request takes a register name as an argument in
5815 which to store the current page location. With no argument it will
5816 store the location in an internal register. The results of this can be
5817 used later by the @code{rt} or the @code{sp} request. The @code{rt}
5818 request will return @emph{upwards} to the location given in the register
5819 name given as an argument, with no argument it will return to the
5820 location marked with the @code{mk} request
5825 ... dual column example ...
5828 The following escapes give fine control of movements about the page.
5831 @cindex vertical motion
5832 @cindex motion, vertical
5833 The @code{\v'@var{e}'} enables arbitrary vertical motion from the
5834 current location on the page. The argument@w{ }@var{e} specifies the
5835 distance to move; positive is downwards and negative upwards. The
5836 default unit for this escape is vertical spaces, @code{v}'s. Beware,
5837 however, that @code{gtroff} will leave text processing to continue
5838 wherever the motion ends, so to avoid interference with text processing,
5839 motions should be balanced.
5841 There are some special case escapes for vertical motion.
5845 move upwards@w{ }1@dmn{v}.
5848 move upwards@w{ }.5@dmn{v}.
5851 move down@w{ }.5@dmn{v}.
5855 Horizontal motions can be done via the @code{\h'@var{e}'} escape. The
5856 expression@w{ }@var{e} indicates how far to move: positive is rightwards
5857 and negative leftwards.
5859 There are a number of special case escapes for horizontal motion:
5863 an unbreakable and unpaddable (i.e.@: not expanded during filling)
5864 space. (Note: It is a backslash followed by a space.)
5867 an unbreakable space that stretches like a normal inter-word space when a
5877 a space the size of a digit.
5880 @cindex zero width space character
5881 @cindex character, zero width space
5882 @cindex space character, zero width
5886 Like @code{\&} except that it behaves like a character declared with the
5887 @code{cflags} request to be transparent for the purposes of end of
5888 sentence recognition.
5894 ... tex logo example ...
5898 @cindex width escape
5899 @cindex escape, width
5900 A frequent need is to do horizontal movement based on the width of some
5901 arbitrary text (e.g.@: given as an argument to a macro). For that,
5902 there is the escape @code{\w'@var{text}'} which will interpolate to the
5903 width of the given @var{text} in basic units.
5908 ... strlen example ...
5911 Font changes may occur in @var{text} which don't affect current
5914 After use, @code{\w} sets several registers:
5921 The highest and lowest point, respectively, in @var{text}.
5927 Like the @code{st} and @code{sb} registers, but takes account of the
5928 heights and depths of characters.
5932 is set according to what kinds of characters occur in @var{text}:
5935 only short characters, no descenders or tall characters.
5944 both a descender and a tall character
5949 The amount of horizontal space (possibly negative) that should be added
5950 to the last character before a subscript.
5954 How far to right of the center of the last character in the @code{\w}
5955 argument, the center of an accent from a Roman font should be placed
5956 over that character.
5965 @c XXX documentation
5968 @node Drawing Requests, Traps, Page Motions, Programming Tutorial
5969 @section Drawing Requests
5970 @cindex drawing requests
5971 @cindex requests for drawing
5973 @code{gtroff} provides a number of ways to draw lines and other figures
5974 on the page. Used in combination with the page motion commands
5975 (@pxref{Page Motions}, for more info), a wide variety of figures can be
5976 drawn. However, for complex drawings these operations can be quite
5977 cumbersome, and it may be wise to use graphic preprocessors like
5978 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
5981 All drawing is done via escapes.
5984 @cindex horizontal line
5985 @cindex line, horizontal
5986 The @code{\l} escape will draw a line rightwards from the current
5987 location. The full syntax for this escape is
5994 where @var{l} is the length of the line to be drawn, starting at the
5995 current location; positive numbers will draw to the right, and negative
5996 will draw towards the left. This can also be specified absolutely
5997 (i.e.@: with a leading @samp{|}) which will draw back to the beginning
6000 @cindex underscore character
6001 @cindex character, underscore
6002 @cindex line drawing character
6003 @cindex character for line drawing
6004 The optional second parameter @var{c} is a character to draw the line
6005 with. If this second argument is not specified, @code{gtroff} will use
6006 the underscore character.
6008 @cindex zero width space character
6009 @cindex character, zero width space
6010 @cindex space character, zero width
6012 To separate the two arguments (to prevent @code{gtroff} from
6013 interpreting a drawing character as a scaling indicator) use @code{\&}.
6015 Here a small useful example:
6019 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
6025 Note that this works by outputting a box rule (a vertical line), then
6026 the text given as an argument and then another box rule. Then the line
6027 drawing escapes both draw from the current location to the beginning of
6028 the @emph{input} line.
6031 @cindex vertical line
6032 @cindex line, vertical
6033 @cindex line drawing character
6034 @cindex character for line drawing
6035 @cindex box rule character
6036 @cindex character, box rule
6037 Vertical lines are drawn using the @code{\L} escape. Its parameters are
6038 specified similar to the @code{\l} escape. If the length is positive,
6039 the movement will be downwards, and upwards for negative values. The
6040 default character is the box rule character. As with the vertical
6041 motion escapes, text processing will blindly continue where the line
6051 More flexible drawing functions are available via the @code{\D} escape.
6052 While the previous escapes will work on a character device, these
6056 @item \D'l @var{dx} @var{dy}'
6057 Draw a line from the current location to the relative point specified by
6058 (@var{dx},@var{dy}).
6063 ...revised box macro...
6068 Draw a circle with a diameter of @var{d} with the leftmost point at the
6072 Draw a solid circle with the same parameters as an outlined circle.
6074 @item \D'e @var{dx} @var{dy}'
6076 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
6077 diameter of @var{dy} with the leftmost point at the current position.
6079 @item \D'E @var{dx} @var{dy}'
6080 Draw a solid ellipse with the same parameters as an outlined ellipse.
6082 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
6084 Draw an arc clockwise from the current location through the two
6085 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
6087 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
6089 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
6090 then to (@var{dx2},@var{dy2}), and so on.
6093 @cindex gray shading
6095 Set the shade of gray to be used for filling solid objects to@w{
6096 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
6097 corresponds solid white and 1000 to solid black, and values in between
6098 correspond to intermediate shades of gray. This applies only to solid
6099 circles, solid ellipses and solid polygons. By default, a level of@w{
6102 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
6104 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
6105 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
6106 are exhausted, a line is drawn back to the starting point.
6111 ... box example (yes, again)...
6114 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
6115 Draw a solid polygon with the same parameters as an outlined polygon.
6120 ... shaded box example ...
6124 @cindex line thickness
6125 @cindex thickness of lines
6126 Set the current line thickness to @var{n} machine units. A value of
6127 zero selects the smallest available line thickness. A negative value
6128 makes the line thickness proportional to the current point size (this is
6129 the default behaviour of @code{ditroff}).
6133 @cindex pile, character
6134 @cindex character pile
6135 The @code{\b} escape will @dfn{pile} a sequence of characters
6136 vertically, and center it vertically on the current line. This can be
6137 used to build large brackets and braces.
6140 \b'\(lt\(bv\(lk\(bv\(lb'
6143 @xref{Drawing Functions}.
6145 @node Traps, Diversions, Drawing Requests, Programming Tutorial
6149 @dfn{Traps} are locations, which, when reached, will call a specified
6150 macro. These traps can occur at a given location on the page, at a
6151 given location in the current diversion, after a certain number of input
6152 lines or at the end of input.
6155 * Page Location Traps::
6157 * Input Line Traps::
6158 * End-of-input Traps::
6161 @node Page Location Traps, Diversion Traps, Traps, Traps
6162 @subsection Page Location Traps
6163 @cindex page location traps
6164 @cindex traps, page location
6166 @c XXX definition of wh request
6168 @cindex page headers
6169 @cindex page footers
6172 Page location traps are frequently used for page headers and footers.
6173 The following is a simple example of this.
6176 .de hd \" Page header
6181 .de fo \" Page footer
6186 .wh 0 hd \" trap at top of the page
6187 .wh -1i fo \" trap one inch from bottom
6191 @cindex distance to next trap
6192 @cindex trap, distance
6193 The number register @code{.t} is the distance to the next trap.
6196 @cindex changing trap location
6197 @cindex trap, changing location
6198 The location of a trap can be changed later on with the @code{ch}
6199 request. The first argument is the name of the macro to be invoked at
6200 the trap, and the second argument is the new location for the trap.
6201 This is useful for building up footnotes in a diversion to allow more
6202 space at the bottom of the page for them.
6207 ... (simplified) footnote example ...
6214 The @code{vpt} request will enable vertical position traps if the
6215 argument is non-zero, disable them otherwise. Vertical position traps
6216 are traps set by the @code{wh} or @code{dt} requests. Traps set by the
6217 @code{it} request are not vertical position traps. The parameter that
6218 controls whether vertical position traps are enabled is global.
6219 Initially vertical position traps are enabled. The current setting of
6220 this is available in the number register @code{.vpt}.
6224 The number register @code{.trunc} contains the amount of vertical space
6225 truncated by the most recently sprung vertical position trap, or, if the
6226 trap was sprung by a @code{ne} request, minus the amount of vertical
6227 motion produced by the @code{ne} request. In other words, at the point
6228 a trap is sprung, it represents the difference of what the vertical
6229 position would have been but for the trap, and what the vertical
6230 position actually is.
6233 The number register @code{.ne} contains the amount of space that was
6234 needed in the last @code{ne} request that caused a trap to be sprung.
6235 Useful in conjunction with the @code{.trunc} register. @xref{Page
6236 Control}, for more information.
6238 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
6239 @subsection Diversion Traps
6240 @cindex diversion traps
6241 @cindex traps, diversion
6245 Traps can also be set @emph{within} a diversion using the @code{dt}
6246 request. Like @code{wh} the first argument is the location of the trap
6247 and the second argument is the name of the macro to be invoked. The
6248 number register @code{.t} will still work within diversions.
6249 @xref{Diversions}, for more information.
6251 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
6252 @subsection Input Line Traps
6253 @cindex input line traps
6254 @cindex traps, input line
6257 The @code{it} request will set an input line trap. The format for
6261 .it @var{n} @var{name}
6265 where @var{n} is the number of lines of input which may be read before
6266 @dfn{springing} the trap, @var{name} is the macro to be invoked.
6267 Request lines are not counted as input lines.
6269 For example, one possible use is to have a macro which will print the
6270 next @var{n}@w{ }lines in a bold font.
6282 @node End-of-input Traps, , Input Line Traps, Traps
6283 @subsection End-of-input Traps
6284 @cindex end-of-input traps
6285 @cindex traps, end-of-input
6288 The @code{em} request will set a trap at the end of input. The macro
6289 specified as an argument will be executed after the last line of the
6290 input file has been processed.
6292 For example, if the document had to have a section at the bottom of the
6293 last page for someone to approve it, the @code{em} request could be
6311 @node Diversions, Environments, Traps, Programming Tutorial
6315 In @code{gtroff} it is possible to @dfn{divert} text into a named
6316 storage area. Due to the similarity to defining macros it is sometimes
6317 said to be stored in a macro. This is used for saving text for output
6318 at a later time, which is useful for keeping blocks of text on the same
6319 page, footnotes, tables of contents and indices.
6323 A diversion is initiated by the @code{di} request. Like the @code{de}
6324 request, it takes an argument of a macro name to divert subsequent text
6325 into. The @code{da} macro will append to an existing diversion.
6327 @code{di} (resp.@: @code{da}) without an argument ends the diversion.
6332 ... end-note example ...
6339 @cindex nested diversions
6340 @cindex diversion, nested
6341 Diversions may be nested. The number register @code{.z} contains the
6342 name of the current diversion. The number register @code{.d} contains
6343 the current vertical place in the diversion. If not in a diversion it
6344 is the same as the register @code{nl}.
6352 After completing a diversion, the built-in number registers @code{dn}
6353 and @code{dl} contain the vertical and horizontal size of the diversion.
6356 .\" Center text both horizontally & vertically
6365 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
6380 @cindex transparent output
6381 @cindex output, transparent
6382 Requests, macros and escapes are interpreted when read into a diversion.
6383 There are two ways to prevent this; either way will take the given text
6384 and @dfn{transparently} embed it into the diversion. The first method
6385 is to prefix the line with @code{\!}. This will cause the entire line
6386 to be transparently inserted into the diversion. This is useful for
6387 macros which shouldn't be invoked until the diverted text is actually
6390 @c XXX anything is read in copy mode. (what about \! ??)
6393 The other way is to surround the text by the @code{\?} escape, i.e.
6400 @var{anything} may not contain newlines; use @code{\!} to embed
6401 newlines in a diversion. The escape sequence @code{\?} is also
6402 recognized in copy mode and turned into a single internal code; it is
6403 this code that terminates anything. Thus the following example will
6410 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
6425 @cindex unformatting diversions
6426 @cindex diversion, unformatting
6427 The @code{asciify} request only exists in order to make certain gross
6428 hacks work with GNU @code{troff}. It @dfn{unformats} the diversion
6429 specified as an argument in such a way that @acronym{ASCII} characters
6430 that were formatted and diverted will be treated like ordinary input
6431 characters when the diversion is reread. For example, the following
6432 will set register @code{n} to@w{ }1.
6445 @xref{Copy-in Mode}.
6448 @node Environments, I/O, Diversions, Programming Tutorial
6449 @section Environments
6450 @cindex environments
6452 It happens frequently that some text should be printed in a certain
6453 format regardless of what may be in effect at the time, for example, in
6454 a trap invoked macro to print headers and footers. To solve this
6455 @code{gtroff} has @dfn{environments} in which text is processed. An
6456 environment contains most of the parameters that control text
6457 processing. It is possible to switch amongst these environments; by
6458 default @code{gtroff} processes text in environment@w{ }0. The
6459 following is the information kept in an environment.
6463 font parameters (size, family, style, character height and slant, space
6464 and sentence space size)
6467 page parameters (line length, title length, vertical spacing,
6468 line spacing, indentation, line numbering, hyphenation data)
6471 fill and adjust mode
6474 tab stops, tab and leader characters, escape character, no-break and
6475 hyphen indicators, margin character data
6478 partially collected lines
6481 These environments may be given arbitrary names (@pxref{Identifiers},
6482 for more info). Old versions of @code{troff} only had environments
6483 named @samp{0}, @samp{1} and@w{ }@samp{2}.
6487 The @code{ev} request will switch among environments. The single
6488 argument is the name of the environment to switch to. With no argument
6489 @code{gtroff} will switch back to the previous environment. There is no
6490 limit on the number of named environments; they will be created the
6491 first time that they are referenced. The @code{.ev} register contains
6492 the name or number of the current environment. This is a string-valued
6495 Note that a call to @code{ev} (with argument) will push the previously
6496 active environment onto a stack. If, say, environments @samp{foo},
6497 @samp{bar}, and @samp{zap} are called (in that order), the first
6498 @code{ev} request without parameter will switch back to environment
6499 @samp{bar} (which will be popped off the stack), and a second call will
6500 switch back to environment @samp{foo}.
6505 ... page break macro, revised ...
6508 Here another example:
6519 \(dg Note the large, friendly letters.
6524 To copy an environment into the current one, use the @code{evc} request,
6525 which takes the name of the environment to copy from as an argument.
6528 @node I/O, Postprocessor Access, Environments, Programming Tutorial
6531 @cindex input and output requests
6532 @cindex requests for input and output
6533 @cindex output and input requests
6536 The @code{so} request will read in the file given as an argument and
6537 include it in place of the @code{so} request. This is quite useful for
6538 large documents, i.e.@: keeping each chapter in a separate file.
6539 @xref{gsoelim}, for more information.
6542 The @code{mso} request is the same as the @code{so} request except that
6543 the file is searched for in the same directories as
6544 @file{tmac.@var{name}} is searched for when the @option{-m@var{name}}
6545 option is specified.
6548 @cindex transparent output
6549 @cindex output, transparent
6550 The @code{cf} and @code{trf} requests are to include a file. It will
6551 transparently output the contents of file filename. Each line is output
6552 as it were preceded by @code{\!}; however, the lines are not subject to
6553 copy mode interpretation. If the file does not end with a newline, then
6554 a newline will be added. For example, to define a macro@w{ }@code{x}
6555 containing the contents of file@w{ }@file{f}, use
6563 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
6564 will embed in the diversion an object which, when reread, will cause the
6565 contents of @var{filename} to be transparently copied through to the
6566 output. In @acronym{UNIX} @code{troff}, the contents of @var{filename}
6567 is immediately copied through to the output regardless of whether there
6568 is a current diversion; this behaviour is so anomalous that it must be
6569 considered a bug. This request causes a line break.
6572 With @code{trf}, unlike @code{cf}, the file cannot contain characters
6573 such as NUL that are not legal @code{gtroff} input characters. This
6574 request causes a line break.
6576 @c XXX xref to illegal input characters
6579 The @code{nx} request will force @code{gtroff} to continue processing of
6580 the file specified as an argument.
6583 The @code{rd} request will read from standard input, and include what is
6584 read as though it were part of the input file. Text is read until a
6585 blank line is encountered.
6587 @cindex form letters
6588 @cindex letters, form
6589 Using these two requests it is easy to set up form letters. The form
6590 letter template is constructed like this:
6608 When this is run, the following file should be redirected in. Note that
6609 requests included in this file are executed as though they were part of
6610 the form letter. The last block of input is the @code{ex} requests
6611 which tells groff to stop processing. If this was not there, groff
6612 would not know when to stop.
6616 708 NW 19th Av., #202
6633 @c XXX documentation
6636 The @code{sy} request will allow arbitrary system commands to be
6637 executed from within a @code{gtroff} document. The output is not saved
6638 anyplace, so it is up to the user to do so.
6640 @c XXX add info about safer and unsafe mode
6642 For example, the following example will introduce the current time
6645 @cindex time, current
6646 @cindex current time
6649 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
6650 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
6657 Note that this works by having the @code{perl} script (run by @code{sy})
6658 print out the @code{nr} requests which will set the number registers
6659 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
6660 the @code{so} request.
6663 The @code{systat} number register contains the return value of the
6664 @code{system()} function executed by the last @code{sy} request.
6667 The @code{open} request will open a file (specified as the second
6668 argument) for writing and associate the stream (specified as the first
6672 The @code{opena} is like @code{open}, but if the file exists, append to
6673 it instead of truncating it.
6677 @cindex copy-in mode
6678 @cindex mode, copy-in
6679 The @code{write} request will write to the file associated with the
6680 stream specified by the first argument. The stream must previously have
6681 been the subject of an open request. The remainder of the line is
6682 interpreted as the @code{ds} request reads its second argument: A
6683 leading @samp{"} will be stripped, and it will be read in copy-in mode.
6686 The @code{close} request will close the stream specified by the first
6687 argument; stream will no longer be an acceptable argument to the
6688 @code{write} request.
6693 ... example of open write &c...
6697 The @code{\V} escape will interpolate the contents of the specified
6698 environment variable, as returned by @code{getenv()}. The argument to
6699 @code{\V} is specified as an identifier, i.e.@: @samp{\V@var{x}},
6700 @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} is interpreted in
6704 @node Postprocessor Access, Miscellaneous, I/O, Programming Tutorial
6705 @section Postprocessor Access
6706 @cindex postprocessor access
6707 @cindex access of postprocessor
6709 There are two escapes which will allow information to be directly given
6710 to the postprocessor. This is particularly useful for embedding
6711 @sc{PostScript} into the final document.
6714 The @code{\X} escape will embed its argument into the @code{gtroff}
6715 output preceded with @w{@samp{x X}}.
6718 The @code{\Y} escape is called with an identifier (i.e.@:
6719 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
6720 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
6721 contents of the string or macro @var{xxx} are not interpreted; also it
6722 is permitted for @var{xxx} to have been defined as a macro and thus
6723 contain newlines (it is not permitted for the argument to @code{\X} to
6724 contain newlines). The inclusion of newlines requires an extension to
6725 the @acronym{UNIX} @code{troff} output format, and will confuse drivers
6726 that do not know about this extension.
6728 @xref{Output Devices}.
6731 @node Miscellaneous, Debugging, Postprocessor Access, Programming Tutorial
6732 @section Miscellaneous
6733 @cindex miscellaneous
6735 This section contains parts of @code{gtroff} which cannot (yet) be
6736 categorized elsewhere in this manual.
6739 @cindex line numbers
6740 @cindex numbers, line
6741 Line numbers can be printed in the left margin using the @code{nm}
6742 request. The first argument is the line number of the @emph{next}
6743 output line; this defaults to@w{ }1. The second argument indicates on
6744 which lines numbers will be printed, i.e.@: 5 means put line numbers on
6745 every 5@w{ }lines; this defaults to@w{ }1. The third argument is the
6746 space to be left between the number and the text; this defaults to@w{
6747 }1. The fourth argument is the indentation of the line numbers.
6748 Without arguments, line numbers are turned off.
6750 @c XXX xref ln register
6753 The @code{nn} request will temporarily turn off line numbering. The
6754 first argument is the number of lines not to be numbered; this defaults
6757 @c XXX (does this disable incrementing or display?)
6762 ... line numbering example ...
6766 @cindex margin characters
6767 @cindex characters for margins
6768 Margin characters can be automatically printed to the right of the text
6769 with the @code{mc} request. The first argument is the character to be
6770 printed, and the second argument is the distance away from the main body
6771 text. With no arguments the margin characters are turned off. If this
6772 occurs before a break, no margin character will be printed.
6776 This is quite useful for indicating text that has changed, and, in fact,
6777 there are programs available for doing this (they are called
6778 @code{nrchbar} and @code{changebar} and can be found in any
6779 @samp{comp.sources.unix} archive.
6784 ... margin char example ...
6789 @cindex multi-file documents
6790 @cindex documents, multi-file
6791 The primary reason for the existence of @code{lf} is to make debugging
6792 documents which are split into many files, which are then put together
6793 with @code{soelim} and other preprocessors. The first argument is the
6794 name of the file and the second argument is the input line number in
6795 that file. This way @code{gtroff} can produce error messages which are
6796 intelligible to the user.
6801 ... example of soelim'ed doc ...
6805 @node Debugging, Implementation Differences, Miscellaneous, Programming Tutorial
6809 @code{gtroff} is not easy to debug, but there are some useful features
6810 and strategies for debugging.
6815 The @code{tm} request will send output to stderr; this is very useful
6816 for printing debugging output.
6819 When doing something involved it is useful to leave the debugging
6820 statements in the code and have them turned on by a command line flag.
6823 .if \n(DB .tm debugging output
6827 To activate these statements say
6836 The @code{ab} request is similar to the @code{tm} request, except that
6837 it will cause @code{gtroff} to stop processing. With no argument it
6838 will print @samp{User Abort}.
6843 The @code{ex} request will also cause @code{gtroff} to stop processing
6844 (if encountered at the topmost level; see also @ref{I/O}.
6847 If it is known in advance that there will be many errors and no useful
6848 output, @code{gtroff} can be forced to suppress formatted output with
6849 the @option{-z} flag.
6853 @cindex dumping symbol table
6854 @cindex symbol table, dumping
6855 The @code{pm} request will dump out the entire symbol table.
6859 @cindex dumping number registers
6860 @cindex number registers, dumping
6861 The @code{pnr} request will print the names and contents of all
6862 currently defined number registers on stderr.
6866 @cindex dumping traps
6867 @cindex traps, dumping
6868 The @code{ptr} request will print the names and positions of all traps
6869 (not including input line traps and diversion traps) on stderr. Empty
6870 slots in the page trap list are printed as well, because they can affect
6871 the priority of subsequently planted traps.
6875 @cindex flush output
6876 @cindex output, flush
6877 @cindex interactive use of @code{gtroff}
6878 @cindex @code{gtroff}, interactive use
6879 The @code{fl} request instructs @code{gtroff} to flush its output
6880 immediately. The intention is that this be used when using
6881 @code{gtroff} interactively. There is little other use for it. This
6882 request causes a line break.
6886 @cindex backtrace of input stack
6887 @cindex input stack, backtrace
6888 The @code{backtrace} request will print a backtrace of the input stack
6893 @code{gtroff} has command line options for printing out more warnings
6894 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
6895 or an error occurs. The most verbose level of warnings is @option{-ww}.
6900 @cindex level of warnings
6901 @cindex warnings, level
6902 The @code{warn} request controls the level of warnings checked for. The
6903 only argument is the sum of the numbers associated with each warning
6904 that is to be enabled; all other warnings will be disabled. The number
6905 associated with each warning is listed below. For example,
6906 @w{@code{.warn 0}} will disable all warnings, and @w{@code{.warn 1}}
6907 will disable all warnings except that about missing characters. If an
6908 argument is not given, all warnings will be enabled. The number
6909 register @code{.warn} contains the current warning level.
6912 @subsection Warnings
6915 The warnings that can be given to @code{gtroff} are divided into the
6916 following categories. The name associated with each warning is used by
6917 the @option{-w} and @option{-W} options; the number is used by the
6918 @code{warn} request and by the @code{.warn} register.
6923 Non-existent characters. This is enabled by default.
6927 Invalid numeric expressions. This is enabled by default.
6934 In fill mode, lines which could not be broken so that their length was
6935 less than the line length. This is enabled by default.
6939 Missing or mismatched closing delimiters.
6945 Use of the @code{el} request with no matching @code{ie} request.
6950 Meaningless scaling indicators.
6954 Out of range arguments.
6958 Dubious syntax in numeric expressions.
6964 Use of @code{di} or @code{da} without an argument when there is no
6970 @c XXX more findex entries
6971 Use of undefined strings, macros and diversions. When an undefined
6972 string, macro or diversion is used, that string is automatically defined
6973 as empty. So, in most cases, at most one warning will be given for each
6979 @c XXX more findex entries
6980 Use of undefined number registers. When an undefined number register is
6981 used, that register is automatically defined to have a value of@w{ }0.
6982 A definition is automatically made with a value of@w{ }0. So, in most
6983 cases, at most one warning will be given for use of a particular name.
6987 Use of a tab character where a number was expected.
6992 Use of @code{\@}} where a number was expected.
6996 Requests that are missing non-optional arguments.
7000 Illegal input characters.
7004 Unrecognized escape sequences. When an unrecognized escape sequence is
7005 encountered, the escape character is ignored.
7009 @cindex compatibility mode
7010 Missing space between a request or macro and its argument. This warning
7011 will be given when an undefined name longer than two characters is
7012 encountered, and the first two characters of the name make a defined
7013 name. The request or macro will not be invoked. When this warning is
7014 given, no macro is automatically defined. This is enabled by default.
7015 This warning will never occur in compatibility mode.
7019 Non-existent fonts. This is enabled by default.
7022 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
7023 intended that this covers all warnings that are useful with traditional
7031 @node Implementation Differences, Summary, Debugging, Programming Tutorial
7032 @section Implementation Differences
7033 @cindex implementation differences
7034 @cindex differences in implementation
7035 @cindex compatibility mode
7036 @cindex mode, compatibility
7038 GNU @code{troff} has a number of features which cause incompatibilities
7039 with documents written with old versions of @code{troff}.
7043 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
7055 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
7056 @code{troff} will interpret this as a call of a macro named
7057 @code{dsabcd}. Also @acronym{UNIX} @code{troff} will interpret
7058 @code{\*[} or @code{\n[} as references to a string or number register
7059 called @samp{[}. In GNU @code{troff}, however, this will normally be
7060 interpreted as the start of a long name. In compatibility mode GNU
7061 @code{troff} will interpret these things in the traditional way. In
7062 compatibility mode, however, long names are not recognized.
7063 Compatibility mode can be turned on with the @option{-C} command line
7064 option, and turned on or off with the @code{cp} request. The number
7065 register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{
7082 GNU @code{troff} does not allow the use of the escape sequences
7083 @code{\|}, @code{\^}, @code{\&}, @code{\@}}, @code{\@{},
7084 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
7085 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
7086 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
7087 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
7088 avoiding use of these escape sequences in names.
7090 @cindex fractional point sizes
7091 @cindex point sizes, fractional
7093 Fractional point sizes cause one noteworthy incompatibility. In
7094 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
7102 will set the point size to 10@w{ }points, whereas in GNU @code{troff} it
7103 will set the point size to 10@w{ }scaled points. @xref{Fractional Type
7104 Sizes}, for more information.
7111 @cindex input and output characters
7112 @cindex output characters
7113 @cindex characters, input and output
7114 In GNU @code{troff} there is a fundamental difference between
7115 unformatted, input characters, and formatted, output characters.
7116 Everything that affects how an output character will be output is stored
7117 with the character; once an output character has been constructed it is
7118 unaffected by any subsequent requests that are executed, including
7119 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
7120 Normally output characters are constructed from input characters at the
7121 moment immediately before the character is added to the current output
7122 line. Macros, diversions and strings are all, in fact, the same type of
7123 object; they contain lists of input characters and output characters in
7124 any combination. An output character does not behave like an input
7125 character for the purposes of macro processing; it does not inherit any
7126 of the special properties that the input character from which it was
7127 constructed might have had. For example,
7140 @cindex transparent output
7141 @cindex output, transparent
7143 will print @samp{\\} in GNU @code{troff}; each pair of input backslashes
7144 is turned into one output backslash and the resulting output backslashes
7145 are not interpreted as escape characters when they are reread.
7146 @acronym{UNIX} @code{troff} would interpret them as escape characters
7147 when they were reread and would end up printing one @samp{\}. The
7148 correct way to obtain a printable backslash is to use the @code{\e}
7149 escape sequence: This will always print a single instance of the current
7150 escape character, regardless of whether or not it is used in a
7151 diversion; it will also work in both GNU @code{troff} and @acronym{UNIX}
7152 @code{troff}. To store, for some reason, an escape sequence in a
7153 diversion that will be interpreted when the diversion is reread, either
7154 use the traditional @code{\!} transparent output facility, or, if this
7155 is unsuitable, the new @code{\?} escape sequence.
7157 @xref{Diversions}, for more information.
7160 @node Summary, , Implementation Differences, Programming Tutorial
7164 @c XXX documentation
7168 @node Preprocessors, Output Devices, Programming Tutorial, Top
7169 @chapter Preprocessors
7170 @cindex preprocessors
7172 This chapter describes all preprocessors that come with @code{groff} or
7173 which are freely available.
7186 @node geqn, gtbl, Preprocessors, Preprocessors
7187 @section @code{geqn}
7197 @node Invoking geqn, , geqn, geqn
7198 @subsection Invoking @code{geqn}
7199 @cindex invoking @code{geqn}
7200 @cindex @code{geqn}, invoking
7205 @node gtbl, gpic, geqn, Preprocessors
7206 @section @code{gtbl}
7216 @node Invoking gtbl, , gtbl, gtbl
7217 @subsection Invoking @code{gtbl}
7218 @cindex invoking @code{gtbl}
7219 @cindex @code{gtbl}, invoking
7224 @node gpic, ggrn, gtbl, Preprocessors
7225 @section @code{gpic}
7235 @node Invoking gpic, , gpic, gpic
7236 @subsection Invoking @code{gpic}
7237 @cindex invoking @code{gpic}
7238 @cindex @code{gpic}, invoking
7243 @node ggrn, grap, gpic, Preprocessors
7244 @section @code{ggrn}
7254 @node Invoking ggrn, , ggrn, ggrn
7255 @subsection Invoking @code{ggrn}
7256 @cindex invoking @code{ggrn}
7257 @cindex @code{ggrn}, invoking
7262 @node grap, grefer, ggrn, Preprocessors
7263 @section @code{grap}
7266 A freely available implementation of @code{grap}, written by Ted Faber,
7267 is available as an extra package from the following address:
7270 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
7274 @node grefer, gsoelim, grap, Preprocessors
7275 @section @code{grefer}
7276 @cindex @code{refer}
7277 @cindex @code{grefer}
7285 @node Invoking grefer, , grefer, grefer
7286 @subsection Invoking @code{grefer}
7287 @cindex invoking @code{grefer}
7288 @cindex @code{grefer}, invoking
7293 @node gsoelim, , grefer, Preprocessors
7294 @section @code{gsoelim}
7295 @cindex @code{soelim}
7296 @cindex @code{gsoelim}
7301 * Invoking gsoelim::
7304 @node Invoking gsoelim, , gsoelim, gsoelim
7305 @subsection Invoking @code{gsoelim}
7306 @cindex invoking @code{gsoelim}
7307 @cindex @code{gsoelim}, invoking
7313 @node Output Devices, File formats, Preprocessors, Top
7314 @chapter Output Devices
7315 @cindex output devices
7316 @cindex devices for output
7321 * Special Characters::
7332 @node Special Characters, grotty, Output Devices, Output Devices
7333 @section Special Characters
7334 @cindex special characters
7335 @cindex characters, special
7342 @node grotty, grops, Special Characters, Output Devices
7343 @section @code{grotty}
7344 @cindex @code{grotty}
7352 @node Invoking grotty, , grotty, grotty
7353 @subsection Invoking @code{grotty}
7354 @cindex invoking @code{grotty}
7355 @cindex @code{grotty}, invoking
7360 @node grops, grodvi, grotty, Output Devices
7361 @section @code{grops}
7362 @cindex @code{grops}
7368 * Embedding PostScript::
7371 @node Invoking grops, Embedding PostScript, grops, grops
7372 @subsection Invoking @code{grops}
7373 @cindex invoking @code{grops}
7374 @cindex @code{grops}, invoking
7378 @node Embedding PostScript, , Invoking grops, grops
7379 @subsection Embedding @sc{PostScript}
7380 @cindex embedding postscript
7381 @cindex postscript, embedding
7386 @node grodvi, grolj4, grops, Output Devices
7387 @section @code{grodvi}
7388 @cindex @code{grodvi}
7396 @node Invoking grodvi, , grodvi, grodvi
7397 @subsection Invoking @code{grodvi}
7398 @cindex invoking @code{grodvi}
7399 @cindex @code{grodvi}, invoking
7404 @node grolj4, grolbp, grodvi, Output Devices
7405 @section @code{grolj4}
7406 @cindex @code{grolj4}
7414 @node Invoking grolj4, , grolj4, grolj4
7415 @subsection Invoking @code{grolj4}
7416 @cindex invoking @code{grolj4}
7417 @cindex @code{grolj4}, invoking
7422 @node grolbp, grohtml, grolj4, Output Devices
7423 @section @code{grolbp}
7424 @cindex @code{grolbp}
7432 @node Invoking grolbp, , grolbp, grolbp
7433 @subsection Invoking @code{grolbp}
7434 @cindex invoking @code{grolbp}
7435 @cindex @code{grolbp}, invoking
7440 @node grohtml, gxditview, grolbp, Output Devices
7441 @section @code{grohtml}
7442 @cindex @code{grohtml}
7447 * Invoking grohtml::
7450 @node Invoking grohtml, , grohtml, grohtml
7451 @subsection Invoking @code{grohtml}
7452 @cindex invoking @code{grohtml}
7453 @cindex @code{grohtml}, invoking
7458 @node gxditview, , grohtml, Output Devices
7459 @section @code{gxditview}
7460 @cindex @code{gxditview}
7465 * Invoking gxditview::
7468 @node Invoking gxditview, , gxditview, gxditview
7469 @subsection Invoking @code{gxditview}
7470 @cindex invoking @code{gxditview}
7471 @cindex @code{gxditview}, invoking
7478 @node File formats, Installation, Output Devices, Top
7479 @chapter File formats
7480 @cindex file formats
7481 @cindex formats, file
7491 @node gtroff Output, Font Files, File formats, File formats
7492 @section @code{gtroff} Output
7493 @cindex @code{gtroff} output
7494 @cindex output, @code{gtroff}
7496 This section describes the format output of GNU @code{troff}. The
7497 output format used by GNU @code{troff} is very similar to that used by
7498 @acronym{UNIX} device-independent @code{troff} (@code{ditroff}).
7503 * Drawing Functions::
7504 * Line Continuation::
7507 @node Output Format, Device Control, gtroff Output, gtroff Output
7508 @subsection Output Format
7509 @cindex output format
7510 @cindex format of output
7513 @cindex input, 8-bit
7514 The output format is text based, as opposed to a binary format (like
7515 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
7516 characters can have the eighth bit set, as can the names of fonts and
7519 The output format consists of single command characters with attached
7520 parameters which are separated from subsequent text by whitespace or a
7523 The names of characters and fonts can be of arbitrary length; drivers
7524 should not assume that they will be only two characters long (as
7525 @code{ditroff} does).
7527 When a character is to be printed, that character will always be in the
7528 current font. Unlike @code{ditroff}, it is not necessary for drivers to
7529 search special fonts to find a character.
7550 @item @var{nn}@var{c}
7554 @var{xxx} is any sequence of characters terminated by a space or a
7555 newline; the first character should be printed at the current position,
7556 the the current horizontal position should be increased by the width of
7557 the first character, and so on for each character. The width of the
7558 character is that given in the font file, appropriately scaled for the
7559 current point size, and rounded so that it is a multiple of the
7560 horizontal resolution. Special characters cannot be printed using this
7565 This command is only allowed if the @samp{tcommand} line is present in
7566 the @file{DESC} file.
7568 @item u@var{n} @var{xxx}
7569 This is same as the @samp{t} command except that after printing each
7570 character, the current horizontal position is increased by the sum of
7571 the width of that character and@w{ }@var{n}.
7573 This command is only allowed if the @samp{tcommand} line is present in
7574 the @file{DESC} file.
7576 @item n@var{a}@var{b}
7585 The argument to the @samp{s} command is in scaled points (units of
7586 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
7587 command in the @file{DESC} file).
7594 @item D@var{c} @var{x}@dots{}\n
7598 @node Device Control, Drawing Functions, Output Format, gtroff Output
7599 @subsection Device Control
7600 @cindex device control
7601 @cindex control of devices
7603 The @samp{x} command is normally followed by a letter or word indicating
7604 the function to perform, followed by white space separated arguments.
7606 The first argument can be abbreviated to the first letter.
7615 @item x res @var{n} @var{h} @var{v}
7620 The argument to the @w{@samp{x Height}} command is also in scaled
7624 The first three output commands are guaranteed to be:
7633 For example, the input
7636 crunchy \fH\s+2frog\s0\fP!?
7645 ... sample output here ...
7648 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
7649 @subsection Drawing Functions
7650 @cindex drawing functions
7651 @cindex functions for drawing
7654 The @samp{D} drawing command has been extended. These extensions will
7655 only be used by GNU @code{pic} if the @option{-x} option is given.
7657 @xref{Drawing Requests}.
7662 Set the shade of gray to be used for filling solid objects to@w{
7663 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
7664 corresponds solid white and 1000 to solid black, and values in between
7665 correspond to intermediate shades of gray. This applies only to solid
7666 circles, solid ellipses and solid polygons. By default, a level of@w{
7667 }1000 will be used. Whatever color a solid object has, it should
7668 completely obscure everything beneath it. A value greater than@w{ }1000
7669 or less than@w{ }0 can also be used: this means fill with the shade of
7670 gray that is currently being used for lines and text. Normally this
7671 will be black, but some drivers may provide a way of changing this.
7674 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
7675 point at the current position.
7677 @item DE @var{dx} @var{dy}
7678 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
7679 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
7682 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
7683 Draw a polygon with. The first vertex is at the current position, the
7684 second vertex at an offset (@var{dx1},@var{dy1}) from the current
7685 position, the second vertex at an offset (@var{dx2},@var{dy2}) from the
7686 first vertex, and so on up to the @var{n}-th vertex. At the moment, GNU
7687 @code{pic} only uses this command to generate triangles and rectangles.
7689 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
7690 Like @code{Dp} but draw a solid rather than outlined polygon.
7693 @cindex line thickness
7694 @cindex thickness of lines
7695 Set the current line thickness to @var{n}@w{ }machine units.
7696 Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness
7697 proportional to the current point size; drivers should continue to do
7698 this if no @code{Dt} command has been given, or if a @code{Dt} command
7699 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
7700 }@var{n} selects the smallest available line thickness.
7704 A difficulty arises in how the current position should be changed after
7705 the execution of these commands. This is not of great importance since
7706 the code generated by GNU @code{pic} does not depend on this. Given a
7707 drawing command of the form
7710 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
7717 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
7718 @samp{~}, @acronym{UNIX} @code{troff} will treat each of the x@w{ }value
7719 as a horizontal quantity, and each of the y@w{ }values as a vertical
7720 quantity and will assume that the width of the drawn object is sum if
7721 all x@w{ }values, and that the height is the sum of all y@w{ }values.
7722 (The assumption about the height can be seen by examining the @code{st}
7723 and @code{sb} registers after using such a @code{D}@w{ }command in a
7724 @code{\w} escape sequence.) This rule also holds for all the original
7725 drawing commands with the exception of @code{De}. For the sake of
7726 compatibility GNU @code{troff} also follows this rule, even though it
7727 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
7728 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
7729 @code{D}@w{ }command of the form
7732 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
7736 the current position should be increased horizontally by the sum of all
7737 x@w{ }values and vertically by the sum of all y@w{ }values.
7739 @node Line Continuation, , Drawing Functions, gtroff Output
7740 @subsection Line Continuation
7741 @cindex line continuation in output commands
7742 @cindex output commands, line continuation
7744 There is a continuation convention which permits the argument to the
7745 @w{@samp{x X}} command to contain newlines: When outputting the argument
7746 to the @w{@samp{x X}} command, GNU @code{troff} will follow each newline
7747 in the argument with a @samp{+} character (as usual, it will terminate
7748 the entire argument with a newline); thus if the line after the line
7749 containing the @w{@samp{x X}} command starts with @samp{+}, then the
7750 newline ending the line containing the @w{@samp{x X}} command should be
7751 treated as part of the argument to the @w{@samp{x X}} command, the
7752 @samp{+} should be ignored, and the part of the line following the
7753 @samp{+} should be treated like the part of the line following the
7754 @w{@samp{x X}} command.
7757 @node Font Files, , gtroff Output, File formats
7762 The @code{gtroff} font format is roughly a superset of the
7763 @code{ditroff} font format. Unlike the @code{ditroff} font format,
7764 there is no associated binary format; all files are text files. The
7765 font files for device @var{name} are stored in a directory
7766 @file{dev@var{name}}. There are two types of file: a device description
7767 file called @file{DESC} and for each font@w{ }@samp{F} a font file
7768 called@w{ }@file{F}.
7771 * DESC file format::
7772 * Font file format::
7775 @node DESC file format, Font file format, Font Files, Font Files
7776 @subsection @file{DESC} file format
7777 @cindex @file{DESC} file format
7778 @cindex font description file format
7779 @cindex format of font description file
7782 The @file{DESC} file can contain the following types of line:
7787 There are @var{n} machine units per inch.
7791 The horizontal resolution is @var{n} machine units.
7795 The vertical resolution is @var{n} machine units.
7797 @item sizescale @var{n}
7799 The scale factor for point sizes. By default this has a value of@w{ }1.
7800 One scaled point is equal to one point/@var{n}. The arguments to the
7801 @code{unitwidth} and @code{sizes} commands are given in scaled points.
7802 @xref{Fractional Type Sizes}, for more information.
7804 @item unitwidth @var{n}
7806 Quantities in the font files are given in machine units for fonts whose
7807 point size is @var{n}@w{ }scaled points.
7811 This means that the postprocessor can handle the @samp{t} and @samp{u}
7814 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
7816 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
7817 @var{sn} scaled points. The list of sizes must be terminated by a@w{
7818 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
7819 list can extend over more than one line.
7821 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
7823 The first @var{m}@w{ }font positions will be associated with styles
7824 @var{S1} @dots{} @var{Sm}.
7826 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
7828 Fonts @var{F1} @dots{} @var{Fn} will be mounted in the font positions
7829 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
7830 styles. This command may extend over more than one line. A font name
7831 of@var{ }0 will cause no font to be mounted on the corresponding font
7834 @item family @var{fam}
7836 The default font family is @var{fam}.
7840 This line and everything following in the file are ignored. It is
7841 allowed for the sake of backwards compatibility.
7844 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
7845 are compulsory. Other commands are ignored by @code{gtroff} but may be
7846 used by postprocessors to store arbitrary information about the device
7847 in the @file{DESC} file.
7849 @c XXX add other commands resp. xrefs to output devices
7850 @c XXX add obsolete commands
7852 @node Font file format, , DESC file format, Font Files
7853 @subsection Font file format
7854 @cindex font file format
7855 @cindex format of font files
7857 A font file has two sections. The first section is a sequence of lines
7858 each containing a sequence of blank delimited words; the first word in
7859 the line is a key, and subsequent words give a value for that key.
7864 The name of the font is@w{ }@var{F}.
7866 @item spacewidth @var{n}
7868 The normal width of a space is@w{ }@var{n}.
7872 The characters of the font have a slant of @var{n}@w{ }degrees.
7873 (Positive means forward.)
7875 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
7877 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
7878 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
7879 @samp{ffl}. For backwards compatibility, the list of ligatures may be
7880 terminated with a@w{ }0. The list of ligatures may not extend over more
7885 The font is special; this means that when a character is requested that
7886 is not present in the current font, it will be searched for in any
7887 special fonts that are mounted.
7890 Other commands are ignored by @code{gtroff} but may be used by
7891 postprocessors to store arbitrary information about the font in the font
7894 @cindex comments in font files
7895 @cindex font files, comments
7897 The first section can contain comments which start with the @samp{#}
7898 character and extend to the end of a line.
7900 The second section contains one or two subsections. It must contain a
7901 @code{charset} subsection and it may also contain a @code{kernpairs}
7902 subsection. These subsections can appear in any order. Each
7903 subsection starts with a word on a line by itself.
7906 The word @code{charset} starts the character set subsection. The
7907 @code{charset} line is followed by a sequence of lines. Each line gives
7908 information for one character. A line comprises a number of fields
7909 separated by blanks or tabs. The format is
7911 @c XXX fix it for new HTML additions
7914 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
7918 @cindex input, 8-bit
7922 @var{name} identifies the character: If @var{name} is a single
7923 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
7924 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
7925 a single character, then it corresponds to the @code{gtroff} input
7926 character@w{ }\@var{c}; otherwise it corresponds to the groff input
7927 character @samp{\[@var{name}]}. (If it is exactly two characters
7928 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
7929 supports 8-bit characters; however some utilities have difficulties with
7930 eight-bit characters. For this reason, there is a convention that the
7931 name @samp{char@var{n}} is equivalent to the single character whose code
7932 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
7933 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
7934 Latin-1} character set. The name @samp{---} is special and indicates
7935 that the character is unnamed; such characters can only be used by means
7936 of the @code{\N} escape sequence in @code{gtroff}.
7938 @c XXX input encodings vs. output encodings
7940 The @var{type} field gives the character type:
7944 the character has an descender, for example, `p';
7947 the character has an ascender, for example, `b';
7950 the character has both an ascender and a descender, for example, `('.
7953 The @var{code} field gives the code which the postprocessor uses to
7954 print the character. The character can also be input to @code{gtroff}
7955 using this code by means of the @code{\N} escape sequence. The code can
7956 be any integer. If it starts with @samp{0} it will be interpreted as
7957 octal; if it starts with @samp{0x} or @samp{0X} it will be interpreted as
7960 Anything on the line after the @var{code} field will be ignored.
7962 The @var{metrics} field has the form:
7965 @var{width}[,@var{height}[,@var{depth}[,@var{italic_correction}
7966 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]]
7970 There must not be any spaces between these subfields (it has been split
7971 here into two lines for better legibility only). Missing subfields are
7972 assumed to be@w{ }0. The subfields are all decimal integers. Since
7973 there is no associated binary format, these values are not required to
7974 fit into a variable of type @samp{char} as they are in @code{ditroff}.
7975 The @var{width} subfield gives the width of the character. The
7976 @var{height} subfield gives the height of the character (upwards is
7977 positive); if a character does not extend above the baseline, it should
7978 be given a zero height, rather than a negative height. The @var{depth}
7979 subfield gives the depth of the character, that is, the distance below
7980 the lowest point below the baseline to which the character extends
7981 (downwards is positive); if a character does not extend below above the
7982 baseline, it should be given a zero depth, rather than a negative depth.
7983 The @var{italic_correction} subfield gives the amount of space that
7984 should be added after the character when it is immediately to be
7985 followed by a character from a Roman font. The
7986 @var{left_italic_correction} subfield gives the amount of space that
7987 should be added before the character when it is immediately to be
7988 preceded by a character from a Roman font. The
7989 @var{subscript_correction} gives the amount of space that should be
7990 added after a character before adding a subscript. This should be less
7991 than the italic correction.
7993 A line in the @code{charset} section can also have the format
8000 This indicates that @var{name} is just another name for the character
8001 mentioned in the preceding line.
8004 The word @code{kernpairs} starts the kernpairs section. This contains a
8005 sequence of lines of the form:
8008 @var{c1} @var{c2} @var{n}
8011 This means that when character @var{c1} appears next to character
8012 @var{c2} the space between them should be increased by@w{ }@var{n}.
8013 Most entries in kernpairs section will have a negative value for@w{
8018 @node Installation, Request and Escape Index, File formats, Top
8019 @chapter Installation
8020 @cindex installation
8026 @node Request and Escape Index, Operator Index, Installation, Top
8027 @chapter Request and Escape Index
8029 In this index, escapes are listed with a leading backslash (@samp{\}) to
8030 distinguish them from requests which appear without the leading control
8031 character (normally either @samp{.} or @samp{'}).
8037 @node Operator Index, Register Index, Request and Escape Index, Top
8038 @chapter Operator Index
8044 @node Register Index, Macro and String Index, Operator Index, Top
8045 @chapter Register Index
8051 @node Macro and String Index, Glyph Name Index, Register Index, Top
8052 @chapter Macro and String Index
8054 In this index, strings are listed with the calling escape sequence
8055 (@samp{\*}) to distinguish them from macros which appear without the
8056 leading control character (normally either @samp{.} or @samp{'}).
8062 @node Glyph Name Index, Font File Keyword Index, Macro and String Index, Top
8063 @chapter Glyph Name Index
8065 A glyph name @code{xx} consisting of exactly two characters can be
8066 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
8067 accessed as @samp{\[xxx]}.
8073 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
8074 @chapter Font File Keyword Index
8080 @node Program and File Index, Concept Index, Font File Keyword Index, Top
8081 @chapter Program and File Index
8087 @node Concept Index, , Program and File Index, Top
8088 @chapter Concept Index