1 \input texinfo @c -*-texinfo-*-
4 @c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug
5 @c in texinfo regarding expansion of user-defined macros.
8 @c %**start of header (This is for running Texinfo on a region.)
10 @settitle The GNU Troff Manual
11 @setchapternewpage odd
12 @footnotestyle separate
13 @c %**end of header (This is for running Texinfo on a region.)
16 @c We use the following indices:
22 @c kindex: commands in font files
23 @c pindex: programs and files
24 @c tindex: environment variables
27 @c glindex: glyph names
30 @c tindex and cindex are merged.
41 @c to avoid uppercasing in @deffn while converting to info, we define
44 @c due to a (not officially documented) `feature' in makeinfo 4.0,
45 @c macros are not expanded in @deffn (but the macro definition is
46 @c properly removed), so we have to define @Var{} directly in TeX also
56 @c definition of requests
58 @macro Defreq{name, arg}
60 @deffn Request @t{.\name\} \arg\
63 @macro Defreqx{name, arg}
65 @deffnx Request @t{.\name\} \arg\
73 @c definition of escapes
75 @macro Defesc{name, delimI, arg, delimII}
77 @deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
80 @macro Defescx{name, delimI, arg, delimII}
82 @deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
90 @c definition of registers
94 @deffn Register @t{\\n[\name\]}
99 @deffnx Register @t{\\n[\name\]}
107 @c definition of macros
109 @macro Defmac{name, arg}
111 @defmac @t{.\name\} \arg\
114 @macro Defmacx{name, arg}
116 @defmacx @t{.\name\} \arg\
124 @c definition of strings
126 @macro Defstr{name, arg}
128 @deffn String @t{\name\} \arg\
131 @macro Defstrx{name, arg}
133 @deffnx String @t{\name\} \arg\
154 @c We need special parentheses and brackets:
156 @c . Real parentheses in @deffn produce an error while compiling with
158 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
160 @c This is true for texinfo 4.0.
193 @c Note: We say `Roman numerals' but `roman font'.
196 @c XXX comment all examples
199 @dircategory Miscellaneous
201 * Groff: (groff). The GNU troff document formatting system.
214 This Info file documents GNU troff version 1.16.
216 Published by the Free Software Foundation
217 59 Temple Place, Suite 330
218 Boston, MA 02111-1307 USA
220 Copyright (C) 1994-2000 Free Software Foundation, Inc.
222 Permission is granted to make and distribute verbatim copies of this
223 manual provided the copyright notice and this permission notice are
224 preserved on all copies.
227 Permission is granted to process this file through TeX and print the
228 results, provided the printed document carries copying permission notice
229 identical to this one except for the removal of this paragraph (this
230 paragraph not being relevant to the printed manual).
233 Permission is granted to copy and distribute modified versions of this
234 manual under the conditions for verbatim copying, provided that the
235 entire resulting derived work is distributed under the terms of a
236 permission notice identical to this one.
238 Permission is granted to copy and distribute translations of this manual
239 into another language, under the above conditions for modified versions,
240 except that this permission notice may be stated in a translation
241 approved by the Foundation.
243 Permission is granted to copy and distribute modified versions of this
244 manual under the conditions for verbatim copying, provided also that the
245 section entitled ``GNU General Public License'' is included exactly as
246 in the original, and provided that the entire resulting derived work is
247 distributed under the terms of a permission notice identical to this
250 Permission is granted to copy and distribute translations of this manual
251 into another language, under the above conditions for modified versions,
252 except that the section entitled ``GNU General Public License'' may be
253 included in a translation approved by the Free Software Foundation
254 instead of in the original English.
260 @subtitle The GNU implementation of @code{troff}
261 @subtitle Edition 1.16
262 @subtitle Spring 2000
263 @author by Trent A.@w{ }Fisher
264 @author and Werner Lemberg
266 @c Include the Distribution inside the titlepage environment so
267 @c that headings are turned off. Headings on and off do not work.
270 @vskip 0pt plus 1filll
271 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
273 Version 1.16 of @code{groff}, @*
276 Published by the Free Software Foundation @*
277 59 Temple Place, Suite 330 @*
278 Boston, MA 02111-1307 USA
281 Permission is granted to make and distribute verbatim copies of this
282 manual provided the copyright notice and this permission notice are
283 preserved on all copies.
285 Permission is granted to copy and distribute modified versions of this
286 manual under the conditions for verbatim copying, provided also that the
287 section entitled ``GNU General Public License'' is included exactly as
288 in the original, and provided that the entire resulting derived work is
289 distributed under the terms of a permission notice identical to this
292 Permission is granted to copy and distribute translations of this manual
293 into another language, under the above conditions for modified versions,
294 except that the section entitled ``GNU General Public License'' may be
295 included in a translation approved by the Free Software Foundation
296 instead of in the original English.
298 Cover art by Etienne Suvasa.
304 @node Top, Copying, (dir), (dir)
307 This Info file documents groff version 1.16, the GNU implementation of
308 the troff typesetting system.
310 This is an in-progress document; contributions, comments, or
311 contributions are welcome. Send them to bug-groff@@gnu.org.
318 * Tutorial for Macro Users::
332 * Font File Keyword Index::
333 * Program and File Index::
339 @node Copying, Introduction, Top, Top
341 @unnumbered GNU GENERAL PUBLIC LICENSE
342 @center Version 2, June 1991
345 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
346 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
348 Everyone is permitted to copy and distribute verbatim copies of this
349 license document, but changing it is not allowed.
352 @unnumberedsec Preamble
354 The licenses for most software are designed to take away your freedom to
355 share and change it. By contrast, the GNU General Public License is
356 intended to guarantee your freedom to share and change free software --
357 to make sure the software is free for all its users. This General
358 Public License applies to most of the Free Software Foundation's
359 software and to any other program whose authors commit to using it.
360 (Some other Free Software Foundation software is covered by the GNU
361 Library General Public License instead.) You can apply it to your
364 When we speak of free software, we are referring to freedom, not price.
365 Our General Public Licenses are designed to make sure that you have the
366 freedom to distribute copies of free software (and charge for this
367 service if you wish), that you receive source code or can get it if you
368 want it, that you can change the software or use pieces of it in new
369 free programs; and that you know you can do these things.
371 To protect your rights, we need to make restrictions that forbid anyone
372 to deny you these rights or to ask you to surrender the rights. These
373 restrictions translate to certain responsibilities for you if you
374 distribute copies of the software, or if you modify it.
376 For example, if you distribute copies of such a program, whether gratis
377 or for a fee, you must give the recipients all the rights that you have.
378 You must make sure that they, too, receive or can get the source code.
379 And you must show them these terms so they know their rights.
381 We protect your rights with two steps: (1)@w{ }copyright the software,
382 and (2)@w{ }offer you this license which gives you legal permission to
383 copy, distribute and/or modify the software.
385 Also, for each author's protection and ours, we want to make certain
386 that everyone understands that there is no warranty for this free
387 software. If the software is modified by someone else and passed on, we
388 want its recipients to know that what they have is not the original, so
389 that any problems introduced by others will not reflect on the original
390 authors' reputations.
392 Finally, any free program is threatened constantly by software patents.
393 We wish to avoid the danger that redistributors of a free program will
394 individually obtain patent licenses, in effect making the program
395 proprietary. To prevent this, we have made it clear that any patent
396 must be licensed for everyone's free use or not licensed at all.
398 The precise terms and conditions for copying, distribution and
402 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
405 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
410 This License applies to any program or other work which contains a
411 notice placed by the copyright holder saying it may be distributed under
412 the terms of this General Public License. The ``Program'', below,
413 refers to any such program or work, and a ``work based on the Program''
414 means either the Program or any derivative work under copyright law:
415 that is to say, a work containing the Program or a portion of it, either
416 verbatim or with modifications and/or translated into another language.
417 (Hereinafter, translation is included without limitation in the term
418 ``modification''.) Each licensee is addressed as ``you''.
420 Activities other than copying, distribution and modification are not
421 covered by this License; they are outside its scope. The act of running
422 the Program is not restricted, and the output from the Program is
423 covered only if its contents constitute a work based on the Program
424 (independent of having been made by running the Program). Whether that
425 is true depends on what the Program does.
428 You may copy and distribute verbatim copies of the Program's source code
429 as you receive it, in any medium, provided that you conspicuously and
430 appropriately publish on each copy an appropriate copyright notice and
431 disclaimer of warranty; keep intact all the notices that refer to this
432 License and to the absence of any warranty; and give any other
433 recipients of the Program a copy of this License along with the Program.
435 You may charge a fee for the physical act of transferring a copy, and
436 you may at your option offer warranty protection in exchange for a fee.
439 You may modify your copy or copies of the Program or any portion of it,
440 thus forming a work based on the Program, and copy and distribute such
441 modifications or work under the terms of Section@w{ }1 above, provided
442 that you also meet all of these conditions:
446 You must cause the modified files to carry prominent notices stating
447 that you changed the files and the date of any change.
450 You must cause any work that you distribute or publish, that in whole or
451 in part contains or is derived from the Program or any part thereof, to
452 be licensed as a whole at no charge to all third parties under the terms
456 If the modified program normally reads commands interactively when run,
457 you must cause it, when started running for such interactive use in the
458 most ordinary way, to print or display an announcement including an
459 appropriate copyright notice and a notice that there is no warranty (or
460 else, saying that you provide a warranty) and that users may
461 redistribute the program under these conditions, and telling the user
462 how to view a copy of this License. (Exception: if the Program itself
463 is interactive but does not normally print such an announcement, your
464 work based on the Program is not required to print an announcement.)
467 These requirements apply to the modified work as a whole. If
468 identifiable sections of that work are not derived from the Program, and
469 can be reasonably considered independent and separate works in
470 themselves, then this License, and its terms, do not apply to those
471 sections when you distribute them as separate works. But when you
472 distribute the same sections as part of a whole which is a work based on
473 the Program, the distribution of the whole must be on the terms of this
474 License, whose permissions for other licensees extend to the entire
475 whole, and thus to each and every part regardless of who wrote it.
477 Thus, it is not the intent of this section to claim rights or contest
478 your rights to work written entirely by you; rather, the intent is to
479 exercise the right to control the distribution of derivative or
480 collective works based on the Program.
482 In addition, mere aggregation of another work not based on the Program
483 with the Program (or with a work based on the Program) on a volume of a
484 storage or distribution medium does not bring the other work under the
485 scope of this License.
488 You may copy and distribute the Program (or a work based on it, under
489 Section@w{ }2) in object code or executable form under the terms of
490 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
495 Accompany it with the complete corresponding machine-readable source
496 code, which must be distributed under the terms of Sections@w{ }1 and@w{
497 }2 above on a medium customarily used for software interchange; or,
500 Accompany it with a written offer, valid for at least three years, to
501 give any third party, for a charge no more than your cost of physically
502 performing source distribution, a complete machine-readable copy of the
503 corresponding source code, to be distributed under the terms of
504 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
508 Accompany it with the information you received as to the offer to
509 distribute corresponding source code. (This alternative is allowed only
510 for noncommercial distribution and only if you received the program in
511 object code or executable form with such an offer, in accord with
512 Subsection@w{ }b above.)
515 The source code for a work means the preferred form of the work for
516 making modifications to it. For an executable work, complete source
517 code means all the source code for all modules it contains, plus any
518 associated interface definition files, plus the scripts used to control
519 compilation and installation of the executable. However, as a special
520 exception, the source code distributed need not include anything that is
521 normally distributed (in either source or binary form) with the major
522 components (compiler, kernel, and so on) of the operating system on
523 which the executable runs, unless that component itself accompanies the
526 If distribution of executable or object code is made by offering access
527 to copy from a designated place, then offering equivalent access to copy
528 the source code from the same place counts as distribution of the source
529 code, even though third parties are not compelled to copy the source
530 along with the object code.
533 You may not copy, modify, sublicense, or distribute the Program except
534 as expressly provided under this License. Any attempt otherwise to
535 copy, modify, sublicense or distribute the Program is void, and will
536 automatically terminate your rights under this License. However,
537 parties who have received copies, or rights, from you under this License
538 will not have their licenses terminated so long as such parties remain
542 You are not required to accept this License, since you have not signed
543 it. However, nothing else grants you permission to modify or distribute
544 the Program or its derivative works. These actions are prohibited by
545 law if you do not accept this License. Therefore, by modifying or
546 distributing the Program (or any work based on the Program), you
547 indicate your acceptance of this License to do so, and all its terms and
548 conditions for copying, distributing or modifying the Program or works
552 Each time you redistribute the Program (or any work based on the
553 Program), the recipient automatically receives a license from the
554 original licensor to copy, distribute or modify the Program subject to
555 these terms and conditions. You may not impose any further restrictions
556 on the recipients' exercise of the rights granted herein. You are not
557 responsible for enforcing compliance by third parties to this License.
560 If, as a consequence of a court judgment or allegation of patent
561 infringement or for any other reason (not limited to patent issues),
562 conditions are imposed on you (whether by court order, agreement or
563 otherwise) that contradict the conditions of this License, they do not
564 excuse you from the conditions of this License. If you cannot
565 distribute so as to satisfy simultaneously your obligations under this
566 License and any other pertinent obligations, then as a consequence you
567 may not distribute the Program at all. For example, if a patent license
568 would not permit royalty-free redistribution of the Program by all those
569 who receive copies directly or indirectly through you, then the only way
570 you could satisfy both it and this License would be to refrain entirely
571 from distribution of the Program.
573 If any portion of this section is held invalid or unenforceable under
574 any particular circumstance, the balance of the section is intended to
575 apply and the section as a whole is intended to apply in other
578 It is not the purpose of this section to induce you to infringe any
579 patents or other property right claims or to contest validity of any
580 such claims; this section has the sole purpose of protecting the
581 integrity of the free software distribution system, which is implemented
582 by public license practices. Many people have made generous
583 contributions to the wide range of software distributed through that
584 system in reliance on consistent application of that system; it is up to
585 the author/donor to decide if he or she is willing to distribute
586 software through any other system and a licensee cannot impose that
589 This section is intended to make thoroughly clear what is believed to be
590 a consequence of the rest of this License.
593 If the distribution and/or use of the Program is restricted in certain
594 countries either by patents or by copyrighted interfaces, the original
595 copyright holder who places the Program under this License may add an
596 explicit geographical distribution limitation excluding those countries,
597 so that distribution is permitted only in or among countries not thus
598 excluded. In such case, this License incorporates the limitation as if
599 written in the body of this License.
602 The Free Software Foundation may publish revised and/or new versions of
603 the General Public License from time to time. Such new versions will be
604 similar in spirit to the present version, but may differ in detail to
605 address new problems or concerns.
607 Each version is given a distinguishing version number. If the Program
608 specifies a version number of this License which applies to it and ``any
609 later version'', you have the option of following the terms and
610 conditions either of that version or of any later version published by
611 the Free Software Foundation. If the Program does not specify a version
612 number of this License, you may choose any version ever published by the
613 Free Software Foundation.
616 If you wish to incorporate parts of the Program into other free programs
617 whose distribution conditions are different, write to the author to ask
618 for permission. For software which is copyrighted by the Free Software
619 Foundation, write to the Free Software Foundation; we sometimes make
620 exceptions for this. Our decision will be guided by the two goals of
621 preserving the free status of all derivatives of our free software and
622 of promoting the sharing and reuse of software generally.
632 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
633 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
634 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
635 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
636 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
637 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
638 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
639 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
640 NECESSARY SERVICING, REPAIR OR CORRECTION.
643 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
644 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
645 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
646 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
647 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
648 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
649 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
650 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
651 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
655 @heading END OF TERMS AND CONDITIONS
658 @center END OF TERMS AND CONDITIONS
663 @unnumberedsec How to Apply These Terms to Your New Programs
665 If you develop a new program, and you want it to be of the greatest
666 possible use to the public, the best way to achieve this is to make it
667 free software which everyone can redistribute and change under these
670 To do so, attach the following notices to the program. It is safest to
671 attach them to the start of each source file to most effectively convey
672 the exclusion of warranty; and each file should have at least the
673 ``copyright'' line and a pointer to where the full notice is found.
676 @var{one line to give the program's name and an idea of what it does.}
677 Copyright (C) 19@var{yy} @var{name of author}
679 This program is free software; you can redistribute it and/or modify
680 it under the terms of the GNU General Public License as published by
681 the Free Software Foundation; either version 2 of the License, or (at
682 your option) any later version.
684 This program is distributed in the hope that it will be useful, but
685 WITHOUT ANY WARRANTY; without even the implied warranty of
686 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
687 General Public License for more details.
689 You should have received a copy of the GNU General Public License
690 along with this program; if not, write to the Free Software
691 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
694 Also add information on how to contact you by electronic and paper mail.
696 If the program is interactive, make it output a short notice like this
697 when it starts in an interactive mode:
700 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
701 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
702 `show w'. This is free software, and you are welcome to redistribute
703 it under certain conditions; type `show c' for details.
706 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
707 show the appropriate parts of the General Public License. Of course,
708 the commands you use may be called something other than @samp{show@w{
709 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items
710 -- whatever suits your program.
712 You should also get your employer (if you work as a programmer) or your
713 school, if any, to sign a ``copyright disclaimer'' for the program, if
714 necessary. Here is a sample; alter the names:
718 Yoyodyne, Inc., hereby disclaims all copyright interest
719 in the program `Gnomovision' (which makes passes at compilers)
720 written by James Hacker.
722 @var{signature of Ty Coon}, 1 April 1989
723 Ty Coon, President of Vice
727 This General Public License does not permit incorporating your program
728 into proprietary programs. If your program is a subroutine library, you
729 may consider it more useful to permit linking proprietary applications
730 with the library. If this is what you want to do, use the GNU Library
731 General Public License instead of this License.
735 @c =====================================================================
736 @c =====================================================================
738 @node Introduction, Invoking groff, Copying, Top
739 @chapter Introduction
742 GNU @code{troff} (or @code{groff}) is a system for typesetting
743 documents. @code{troff} is very flexible and has been in existence (and
744 use) for about 3@w{ }decades. It is quite widespread and firmly
745 entrenched in the @acronym{UNIX} community.
750 * groff Capabilities::
751 * Macro Package Intro::
752 * Preprocessor Intro::
753 * Output device intro::
758 @c =====================================================================
760 @node What Is groff?, History, Introduction, Introduction
761 @section What Is @code{groff}?
762 @cindex what is @code{groff}?
763 @cindex @code{groff} -- what is it?
765 @code{groff} belongs to an older generation of document preparation
766 systems, which operate more like compilers than the more recent
767 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
768 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
769 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
770 normal text files with embedded formatting commands. These files can
771 then be processed by @code{groff} to produce a typeset document on a
774 Likewise, @code{groff} should not be confused with a @dfn{word
775 processor}, since that term connotes an integrated system that includes
776 an editor and a text formatter. Also, many word processors follow the
777 @acronym{WYSIWYG} paradigm discussed earlier.
779 Although @acronym{WYSIWYG} systems may be easier to use, they have a
780 number of disadvantages compared to @code{troff}:
784 They must be used on a graphics display to work on a document.
787 Most of the @acronym{WYSIWYG} systems are either non-free or are not
791 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
794 It is difficult to have a wide range of capabilities available within
795 the confines of a GUI/window system.
798 It is more difficult to make global changes to a document.
802 ``GUIs normally make it simple to accomplish simple actions and
803 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
804 @code{comp.unix.wizards})
808 @c =====================================================================
810 @node History, groff Capabilities, What Is groff?, Introduction
814 @cindex @code{runoff}
816 @code{troff} can trace its origins back to a formatting program called
817 @code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS
818 operating system in the mid-sixties. This name came from the common
819 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
820 the 635 architecture and called the program @code{roff} (an abbreviation
821 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
822 (before having @acronym{UNIX}), and at the same time (1969), Doug
823 McIllroy rewrote an extended and simplified version of @code{roff} in
824 the @acronym{BCPL} programming language.
827 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
828 was sitting around Bell Labs. In 1971 the developers wanted to get a
829 @w{PDP-11} for further work on the operating system. In order to
830 justify the cost for this system, they proposed that they would
831 implement a document formatting system for the AT&T patents division.
832 This first formatting program was a reimplementation of McIllroy's
833 @code{roff}, written by J.@w{ }F.@w{ }Ossanna.
836 When they needed a more flexible language, a new version of @code{roff}
837 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
838 more complicated syntax, but provided the basis for all future versions.
839 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
840 version of @code{nroff} that would drive it. It was dubbed
841 @code{troff}, for ``typesetter @code{roff}'', although many people have
842 speculated that it actually means ``Times @code{roff}'' because of the
843 use of the Times font family in @code{troff} by default. As such, the
844 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
846 With @code{troff} came @code{nroff} (they were actually the same program
847 except for some @samp{#ifdef}s), which was for producing output for line
848 printers and character terminals. It understood everything @code{troff}
849 did, and ignored the commands which were not applicable (e.g.@: font
852 Since there are several things which cannot be done easily in
853 @code{troff}, work on several preprocessors began. These programs would
854 transform certain parts of a document into @code{troff}, which made a
855 very natural use of pipes in @acronym{UNIX}.
857 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
858 specified in a much simpler and more intuitive manner. @code{tbl} is a
859 preprocessor for formatting tables. The @code{refer} preprocessor (and
860 the similar program, @code{bib}) processes citations in a document
861 according to a bibliographic database.
863 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
864 language and produced output specifically for the CAT phototypesetter.
865 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
866 code and still dependent on the CAT. As the CAT became less common, and
867 was no longer supported by the manufacturer, the need to make it support
868 other devices became a priority. However, before this could be done,
869 Ossanna was killed in an auto accident.
872 @cindex @code{ditroff}
873 So, Brian Kernighan took on the task of rewriting @code{troff}. The
874 newly rewritten version produced a device independent code which was
875 very easy for postprocessors to read and translate to the appropriate
876 printer codes. Also, this new version of @code{troff} (called
877 @code{ditroff} for ``device independent @code{troff}'') had several
878 extensions, which included drawing functions.
880 Due to the additional abilities of the new version of @code{troff},
881 several new preprocessors appeared. The @code{pic} preprocessor
882 provides a wide range of drawing functions. Likewise the @code{ideal}
883 preprocessor did the same, although via a much different paradigm. The
884 @code{grap} preprocessor took specifications for graphs, but, unlike
885 other preprocessors, produced @code{pic} code.
887 James Clark began work on a GNU implementation of @code{ditroff} in
888 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
889 June@w{ }1990. @code{groff} included:
893 A replacement for @code{ditroff} with many extensions.
896 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
899 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
900 X@w{ }windows. GNU @code{troff} also eliminated the need for a
901 separate @code{nroff} program with a postprocessor which would produce
902 @acronym{ASCII} output.
905 A version of the @file{me} macros and an implementation of the
909 Also, a front-end was included which could construct the, sometimes
910 painfully long, pipelines required for all the post- and preprocessors.
912 Development of GNU @code{troff} progressed rapidly, and saw the
913 additions of a replacement for @code{refer}, an implementation of the
914 @file{ms} and @file{mm} macros, and a program to deduce how to format a
915 document (@code{grog}).
917 It was declared a stable (i.e.@: non-beta) package with the release of
918 version@w{ }1.04 around November@w{ }1991.
920 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
921 an orphan for a few years). As a result, new features and programs like
922 @code{grn}, a preprocessor for gremlin images, and an output device to
923 produce @acronym{HTML} output have been added.
926 @c =====================================================================
928 @node groff Capabilities, Macro Package Intro, History, Introduction
929 @section @code{groff} Capabilities
930 @cindex @code{groff} capabilities
931 @cindex capabilities of @code{groff}
933 So what exactly is @code{groff} capable of doing? @code{groff} provides
934 a wide range of low-level text formatting operations. Using these, it
935 is possible to perform a wide range of formatting tasks, such as
936 footnotes, table of contents, multiple columns, etc. Here's a list of
937 the most important operations supported by @code{groff}:
941 text filling, adjusting, and centering
950 font and character size control
953 vertical spacing (i.e.@: double spacing)
956 line length and indenting
959 macros, strings, diversions, and traps
965 tabs, leaders, and fields
968 input and output conventions and character translation
971 overstrike, bracket, line drawing, and zero-width functions
974 local horizontal and vertical motions and the width function
980 output line numbering
983 conditional acceptance of input
986 environment switching
989 insertions from the standard input
992 input/output file switching
995 output and error messages
999 @c =====================================================================
1001 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
1002 @section Macro Packages
1003 @cindex macro packages
1005 Since @code{groff} provides such low-level facilities, it can be quite
1006 difficult to use by itself. However, @code{groff} provides a
1007 @dfn{macro} facility to specify how certain routine operations (e.g.@w{
1008 }starting paragraphs, printing headers and footers, etc.)@: should be
1009 done. These macros can be collected together into a @dfn{macro
1010 package}. There are a number of macro packages available; the most
1011 common (and the ones described in this manual) are @file{man},
1012 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
1015 @c =====================================================================
1017 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
1018 @section Preprocessors
1019 @cindex preprocessors
1021 Although @code{groff} provides most functions needed to format a
1022 document, some operations would be unwieldy (e.g.@: to draw pictures).
1023 Therefore, programs called preprocessors were written which understand
1024 their own language and produce the necessary @code{groff} operations.
1025 These preprocessors are able to differentiate their own input from the
1026 rest of the document via markers.
1028 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
1029 from the preprocessor into @code{groff}. Any number of preprocessors
1030 may be used on a given document; in this case, the preprocessors are
1031 linked together into one pipeline. However, in @code{groff}, the user
1032 does not need to construct the pipe, but only tell @code{groff} what
1033 preprocessors to use.
1035 @code{groff} currently has preprocessors for producing tables
1036 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
1037 (@code{pic} and @code{grn}), and for processing bibliographies
1038 (@code{refer}). An associated program which is useful when dealing with
1039 preprocessors is @code{soelim}.
1041 A free implementation of @code{grap}, a preprocessor for drawing graphs,
1042 can be obtained as an extra package; @code{groff} can use @code{grap}
1045 There are other preprocessors in existence, but, unfortunately, no free
1046 implementations are available. Among them are preprocessors for drawing
1047 mathematical pictures (@code{ideal}) and chemical structures
1051 @c =====================================================================
1053 @node Output device intro, Credits, Preprocessor Intro, Introduction
1054 @section Output Devices
1055 @cindex postprocessors
1056 @cindex output devices
1057 @cindex devices for output
1059 @code{groff} actually produces device independent code which may be
1060 fed into a postprocessor to produce output for a particular device.
1061 Currently, @code{groff} has postprocessors for @sc{PostScript}
1062 devices, character terminals, X@w{ }Windows (for previewing), @TeX{}
1063 DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use
1064 @acronym{CAPSL}), and @acronym{HTML}.
1067 @c =====================================================================
1069 @node Credits, , Output device intro, Introduction
1073 Large portions of this manual were taken from existing documents, most
1074 notably, the manual pages for the @code{groff} package by James Clark,
1075 and Eric Allman's papers on the @file{me} macro package.
1077 The section on the @file{man} macro package is partly based on Susan@w{
1078 }G.@: Kleinmann's @file{groff_man} manual page written for the Debian
1084 @c =====================================================================
1085 @c =====================================================================
1087 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
1088 @chapter Invoking @code{groff}
1089 @cindex invoking @code{groff}
1090 @cindex @code{groff} invocation
1092 This section focuses on how to invoke the @code{groff} front end. This
1093 front end takes care of the details of constructing the pipeline among
1094 the preprocessors, @code{gtroff} and the postprocessor.
1096 It has become a tradition that GNU programs get the prefix @samp{g} to
1097 distinguish it from its original counterparts provided by the host (see
1098 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
1099 GNU @code{eqn}. On operating systems like Linux or the Hurd, which
1100 don't contain proprietary software, and on MS-DOS/MS-Windows, where
1101 @code{troff} and associated programs are not available at all, this
1102 prefix is omitted since GNU @code{troff} is the only used incarnation of
1103 @code{troff}. Exception: @code{groff} is never replaced by @code{roff}.
1108 * Invocation Examples::
1112 @c =====================================================================
1114 @node Groff Options, Environment, Invoking groff, Invoking groff
1127 @code{groff} normally runs the @code{gtroff} program and a postprocessor
1128 appropriate for the selected device. The default device is @samp{ps}
1129 (but it can be changed when @code{groff} is configured and built). It
1130 can optionally preprocess with any of @code{gpic}, @code{geqn},
1131 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
1133 This section only documents options to the @code{groff} front end. Many
1134 of the arguments to @code{groff} are passed on to @code{gtroff},
1135 therefore those are also included. Arguments to pre- or postprocessors
1136 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
1137 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
1138 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
1139 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
1140 grolbp}, and @ref{Invoking gxditview}.
1142 The command line format for @code{groff} is:
1145 groff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
1146 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
1147 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
1148 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
1149 [ @var{files}@dots{} ]
1152 The command line format for @code{gtroff} is as follows.
1155 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
1156 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
1157 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
1158 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
1162 Obviously, many of the options to @code{groff} are actually passed on to
1165 Options without an argument can be grouped behind a single @option{-}.
1166 A filename of @file{-} denotes the standard input. It is possible to
1167 have whitespace between an option and its parameter.
1169 The @code{grog} command can be used to guess the correct @code{groff}
1170 command to format a file.
1172 Here's the description of the command-line options:
1174 @cindex command-line options
1177 Print a help message.
1180 Preprocess with @code{geqn}.
1183 Preprocess with @code{gtbl}.
1186 Preprocess with @code{ggrn}.
1189 Preprocess with @code{grap}.
1192 Preprocess with @code{gpic}.
1195 Preprocess with @code{gsoelim}.
1198 Preprocess with @code{grefer}. No mechanism is provided for passing
1199 arguments to @code{grefer} because most @code{grefer} options have
1200 equivalent commands which can be included in the file. @xref{grefer},
1205 Note that @code{gtroff} also accepts a @option{-R} option, which is not
1206 accessible via @code{groff}. This option prevents the loading of the
1207 @file{troffrc} and @file{troffrc-end} files.
1210 Make programs run by @code{groff} print out their version number.
1213 Print the pipeline on @code{stdout} instead of executing it.
1216 Suppress output from @code{gtroff}. Only error messages are printed.
1219 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1220 automatically runs the appropriate postprocessor.
1223 Pass @var{arg} to the postprocessor. Each argument should be passed
1224 with a separate @option{-P} option. Note that @code{groff} does not
1225 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1228 Send the output to a spooler for printing. The command used for this is
1229 specified by the @code{print} command in the device description file
1230 (see @ref{Font Files}, for more info). If not present, @option{-l} is
1234 Pass @var{arg} to the spooler. Each argument should be passed with a
1235 separate @option{-L} option. Note that @code{groff} does not prepend a
1236 @samp{-} to @var{arg} before passing it to the postprocessor. If the
1237 @code{print} keyword in the device description file is missing,
1238 @option{-L} is ignored.
1241 Prepare output for device @var{dev}. The default device is @samp{ps},
1242 unless changed when @code{groff} was configured and built. The
1243 following are the output devices currently available:
1247 For @sc{PostScript} printers and previewers.
1250 For @TeX{} DVI format.
1253 For a 75@dmn{dpi} X11 previewer.
1256 For a 100@dmn{dpi} X11 previewer.
1259 For typewriter-like devices.
1262 For typewriter-like devices that support the @w{Latin-1} (@w{ISO
1263 8859-1}) character set.
1266 For typewriter-like devices which use the Unicode (@w{ISO 10646})
1267 character set with @w{UTF-8} encoding.
1270 @cindex @acronym{EBCDIC} encoding
1273 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1277 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
1280 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1284 @pindex post-grohtml
1285 @cindex @code{grohtml}
1287 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1288 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1289 postprocessor (@code{post-grohtml}).
1294 The predefined @code{gtroff} string register @code{.T} contains the
1295 current output device; the read-only number register @code{.T} is set
1296 to@w{ }1 if this option is used (which is always true if @code{groff} is
1297 used to call @code{gtroff}). @xref{Built-in Registers}.
1299 The postprocessor to be used for a device is specified by the
1300 @code{postpro} command in the device description file. (@xref{Font
1301 Files}, for more info.) This can be overridden with the @option{-X}
1305 Preview with @code{gxditview} instead of using the usual postprocessor.
1306 This is unlikely to produce good results except with @option{-Tps}.
1308 Note that this is not the same as using @option{-TX75} or
1309 @option{-TX100} to view a document with @code{gxditview}: The former
1310 uses the metrics of the specified device, whereas the latter uses
1311 X-specific fonts and metrics.
1314 Don't allow newlines with @code{eqn} delimiters. This is the same as
1315 the @option{-N} option in @code{geqn}.
1318 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1319 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1320 requests. For security reasons, this is enabled by default.
1323 Unsafe mode. Reverts to the old unsafe behaviour.
1327 Generate an @acronym{ASCII} approximation of the typeset output. The
1328 read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
1329 Registers}. A typical example is
1332 groff -a -man -Tdvi troff.man | less
1336 which shows how lines are broken for the DVI device. Note that this
1337 option is rather useless today since graphic output devices are
1338 available virtually everywhere.
1341 Print a backtrace with each warning or error message. This backtrace
1342 should help track down the cause of the error. The line numbers given
1343 in the backtrace may not always be correct: @code{gtroff} can get
1344 confused by @code{as} or @code{am} requests while counting line numbers.
1347 Read the standard input after all the named input files have been
1351 Enable warning @var{name}. Available warnings are described in
1352 @ref{Debugging}. Multiple @option{-w} options are allowed.
1355 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1358 Inhibit all error messages.
1361 Enable compatibility mode. @xref{Implementation Differences}, for the
1362 list of incompatibilities between @code{groff} and traditional Unix
1366 @itemx -d@var{name}=s
1367 Define @var{c} or @var{name} to be a string @var{s}. @var{c} must be a
1368 one-letter name; @var{name} can be of arbitrary length. All string
1369 assignments happen before loading any macro file (including the start-up
1373 Use @var{fam} as the default font family. @xref{Font Families}.
1376 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1377 for this in its macro directories. If it isn't found, it tries
1378 @file{tmac.@var{name}} (and searches in the same directories).
1380 @c XXX document local and system macro dirs
1383 Number the first page @var{num}.
1387 Output only pages in @var{list}, which is a comma-separated list of page
1388 ranges; @samp{@var{n}} means print page @var{n}, @samp{@var{m}-@var{n}}
1389 means print every page between @var{m} and @var{n}, @samp{-@var{n}}
1390 means print every page up to @var{n}, @samp{@var{n}-} means print every
1391 page beginning with @var{n}. @code{gtroff} exits after printing the
1392 last page in the list. All the ranges are inclusive on both ends.
1394 Within @code{gtroff}, this information can be extracted with the
1395 @samp{.P} register. @xref{Built-in Registers}.
1397 If your document restarts page numbering at the beginning of each
1398 chapter, then @code{gtroff} prints the specified page range for each
1402 @itemx -r@var{name}=@var{n}
1403 Set number register @var{c} or @var{name} to the value @var{n}. @var{c}
1404 must be a one-letter name; @var{name} can be of arbitrary length.
1405 @var{n} can be any @code{gtroff} numeric expression. All register
1406 assignments happen before loading any macro file (including the start-up
1410 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1411 (@var{name} is the name of the device), for the @file{DESC} file, and
1412 for font files before looking in the standard directories.
1415 Search directory @file{@var{dir}} for macro files before the standard
1419 This option is as described in @ref{gsoelim}. It implies the
1424 @c =====================================================================
1426 @node Environment, Invocation Examples, Groff Options, Invoking groff
1427 @section Environment
1428 @cindex environment variables
1429 @cindex variables in environment
1431 There are also several environment variables (of the operating system,
1432 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1435 @item GROFF_COMMAND_PREFIX
1436 @tindex GROFF_COMMAND_PREFIX, environment variable
1437 If this is set to @var{X}, then @code{groff} runs @code{@var{X}troff}
1438 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1439 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1440 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1441 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1443 @c XXX document default values
1445 @item GROFF_TMAC_PATH
1446 @tindex GROFF_TMAC_PATH, environment variable
1447 A colon-separated list of directories in which to search for macro files
1448 (before the default directories are tried).
1450 @c XXX document local and system macro dirs
1452 @item GROFF_TYPESETTER
1453 @tindex GROFF_TYPESETTER, environment variable
1454 The default output device.
1456 @item GROFF_FONT_PATH
1457 @tindex GROFF_FONT_PATH, environment variable
1458 A colon-separated list of directories in which to search for the
1459 @code{dev}@var{name} directory (before the default directories are
1462 @item GROFF_BIN_PATH
1463 @tindex GROFF_BIN_PATH, environment variable
1464 This search path, followed by @code{PATH}, is used for commands executed
1468 @tindex GROFF_TMPDIR, environment variable
1469 @tindex TMPDIR, environment variable
1470 The directory in which @code{groff} creates temporary files. If this is
1471 not set and @env{TMPDIR} is set, temporary files are created in that
1472 directory. Otherwise temporary files are created in a system-dependent
1473 default directory (on Unix and GNU/Linux systems, this is usually
1474 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1475 @code{post-grohtml} can create temporary files in this directory.
1478 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1479 rather than colons, to separate the directories in the lists described
1483 @c =====================================================================
1485 @node Invocation Examples, , Environment, Invoking groff
1486 @section Invocation Examples
1487 @cindex invocation examples
1488 @cindex examples of invocation
1490 This section lists several common uses of @code{groff} and the
1491 corresponding command lines.
1498 This command processes @file{file} without a macro package or a
1499 preprocessor. The output device is the default, @samp{ps}, and the
1500 output is sent to @code{stdout}.
1503 groff -t -mandoc -Tascii file | less
1507 This is basically what a call to the @code{man} program does.
1508 @code{gtroff} processes the manual page @file{file} with the
1509 @file{mandoc} macro file (which in turn either calls the @file{man} or
1510 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1511 the @acronym{ASCII} output device. Finally, the @code{less} pager
1512 displays the result.
1519 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1520 package. Since no @option{-T} option is specified, use the default
1521 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1522 @w{@samp{-me}}; the latter is an anachronism from the early days of
1523 @acronym{UNIX}.@footnote{The same is true for the other main macro
1524 packages that come with @code{groff}: @file{man}, @file{mdoc},
1525 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1526 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1527 @w{@samp{-m trace}} must be used.}
1530 groff -man -rD1 -z file
1534 Check @file{file} with the @file{man} macro package, forcing
1535 double-sided printing -- don't produce any output.
1541 @c ---------------------------------------------------------------------
1543 @node grog, , Invocation Examples, Invocation Examples
1544 @subsection @code{grog}
1547 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1548 and/or macro packages are required for formatting them, and prints the
1549 @code{groff} command including those options on the standard output. It
1550 generates one or more of the options @option{-e}, @option{-man},
1551 @option{-me}, @option{-mm}, @option{-ms}, @option{-mdoc},
1552 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1553 @option{-s}, and @option{-t}.
1555 A special file name @file{-} refers to the standard input. Specifying
1556 no files also means to read the standard input. Any specified options
1557 are included in the printed command. No space is allowed between
1558 options and their arguments. The only options recognized are
1559 @option{-C} (which is also passed on) to enable compatibility mode, and
1560 @option{-v} (if it is the only parameter) to print the version number.
1569 guesses the appropriate command to print @file{paper.ms} and then prints
1570 it to the command line after adding the @option{-Tdvi} option. For
1571 direct execution, enclose the call to @code{grog} in backquotes at the
1572 @acronym{UNIX} shell prompt:
1575 `grog -Tdvi paper.ms` > paper.dvi
1579 As seen in the example, it is still necessary to redirect the output to
1580 something meaningful (i.e.@: either a file or a pager program like
1585 @c =====================================================================
1586 @c =====================================================================
1588 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1589 @chapter Tutorial for Macro Users
1590 @cindex tutorial for macro users
1591 @cindex macros, tutorial for users
1592 @cindex user's tutorial for macros
1593 @cindex user's macro tutorial
1595 Most users tend to use a macro package to format their papers. This
1596 means that the whole breadth of @code{groff} is not necessary for most
1597 people. This chapter covers the material needed to efficiently use a
1606 @c =====================================================================
1608 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1610 @cindex basics of macros
1611 @cindex macro basics
1613 This section covers some of the basic concepts necessary to understand
1614 how to use a macro package.@footnote{This section is derived from
1615 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1616 References are made throughout to more detailed information, if desired.
1618 @code{gtroff} reads an input file prepared by the user and outputs a
1619 formatted document suitable for publication or framing. The input
1620 consists of text, or words to be printed, and embedded commands
1621 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1622 format the output. For more detail on this, see @ref{Embedded
1625 The word @dfn{argument} is used in this chapter to mean a word or number
1626 which appears on the same line as a request, and which modifies the
1627 meaning of that request. For example, the request
1634 spaces one line, but
1641 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1642 request which says to space four lines instead of one. Arguments are
1643 separated from the request and from each other by spaces (@emph{no}
1644 tabs). More details on this can be found in @ref{Request Arguments}.
1646 The primary function of @code{gtroff} is to collect words from input
1647 lines, fill output lines with those words, justify the right-hand margin
1648 by inserting extra spaces in the line, and output the result. For
1656 Four score and seven
1661 is read, packed onto output lines, and justified to produce:
1664 Now is the time for all good men to come to the aid of their party.
1665 Four score and seven years ago,...
1670 Sometimes a new output line should be started even though the current
1671 line is not yet full; for example, at the end of a paragraph. To do
1672 this it is possible to cause a @dfn{break}, which starts a new output
1673 line. Some requests cause a break automatically, as normally do blank
1674 input lines and input lines beginning with a space.
1676 Not all input lines are text to be formatted. Some input lines are
1677 requests which describe how to format the text. Requests always have a
1678 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1681 The text formatter also does more complex things, such as automatically
1682 numbering pages, skipping over page boundaries, putting footnotes in the
1683 correct place, and so forth.
1685 Here are a few hints for preparing text for input to @code{gtroff}.
1689 First, keep the input lines short. Short input lines are easier to
1690 edit, and @code{gtroff} packs words onto longer lines anyhow.
1693 In keeping with this, it is helpful to begin a new line after every
1694 comma or phrase, since common corrections are to add or delete sentences
1698 End each sentence with two spaces -- or better, start each sentence on a
1699 new line. @code{gtroff} recognizes characters that usually end a
1700 sentence, and inserts sentence space accordingly.
1703 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1704 enough to hyphenate words as needed, but is not smart enough to take
1705 hyphens out and join a word back together. Also, words such as
1706 ``mother-in-law'' should not be broken over a line, since then a space
1707 can occur where not wanted, such as ``@w{mother- in}-law''.
1711 @cindex double spacing
1713 @code{gtroff} double spaces output text automatically if you use the
1714 request @w{@samp{.ls 2}}. Reactivate single spaced mode by typing
1717 A number of requests allow to change the way the output looks,
1718 sometimes called the @dfn{layout} of the output page. Most of these
1719 requests adjust the placing of @dfn{white space} (blank lines or
1723 The @samp{.bp} request starts a new page, causing a line break.
1728 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1729 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1730 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1731 @var{N}@w{ }centimeters). For example, the input:
1735 My thoughts on the subject
1740 leaves one and a half inches of space, followed by the line ``My
1741 thoughts on the subject'', followed by a single blank line (more
1742 measurement units are available, see @ref{Measurements}).
1745 @cindex centering lines
1746 @cindex lines, centering
1747 Text lines can be centered by using the @code{ce} request. The line
1748 after @code{ce} is centered (horizontally) on the page. To center more
1749 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1750 of lines to center), followed by the @var{N}@w{ }lines. To center many
1751 lines without counting them, type:
1760 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1761 lines, in other words, stop centering.
1766 All of these requests cause a break; that is, they always start a new
1767 line. To start a new line without performing any other action, use
1771 @c =====================================================================
1773 @node Common Features, , Basics, Tutorial for Macro Users
1774 @section Common Features
1775 @cindex common features
1776 @cindex features, common
1778 @code{gtroff} provides very low-level operations for formatting a
1779 document. There are many common routine operations which are done in
1780 all documents. These common operations are written into @dfn{macros}
1781 and collected into a @dfn{macro package}.
1783 All macro packages provide certain common capabilities which fall into
1784 the following categories.
1788 * Sections and Chapters::
1789 * Headers and Footers::
1790 * Page Layout Adjustment::
1792 * Footnotes and Annotations::
1793 * Table of Contents::
1796 * Multiple Columns::
1797 * Font and Size Changes::
1798 * Predefined Strings::
1799 * Preprocessor Support::
1800 * Configuration and Customization::
1803 @c ---------------------------------------------------------------------
1805 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1806 @subsection Paragraphs
1809 One of the most common and most used capability is starting a
1810 paragraph. There are a number of different types of paragraphs, any
1811 of which can be initiated with macros supplied by the macro package.
1812 Normally, paragraphs start with a blank line and the first line
1813 indented, like the text in this manual. There are also block style
1814 paragraphs, which omit the indentation:
1817 Some men look at constitutions with sanctimonious
1818 reverence, and deem them like the ark of the covenant, too
1819 sacred to be touched.
1823 And there are also indented paragraphs which begin with a tag or label
1824 at the margin and the remaining text indented.
1828 one This is the first paragraph. Notice how the first
1829 line of the resulting paragraph lines up with the
1830 other lines in the paragraph.
1834 This paragraph had a long label. The first
1835 character of text on the first line does not line up
1836 with the text on second and subsequent lines,
1837 although they line up with each other.
1841 A variation of this is a bulleted list.
1845 @c ---------------------------------------------------------------------
1847 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1848 @subsection Sections and Chapters
1850 Most macro packages supply some form of section headers. The simplest
1851 kind is simply the heading on a line by itself in bold type. Others
1852 supply automatically numbered section heading or different heading
1853 styles at different levels. Some, more sophisticated, macro packages
1854 supply macros for starting chapters and appendices.
1856 @c ---------------------------------------------------------------------
1858 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1859 @subsection Headers and Footers
1861 Every macro package gives some way to manipulate the headers and footers
1862 (or @dfn{titles}) on each page. Some packages allow for different ones
1863 on the even and odd pages (for material printed in a book form).
1865 The titles are called three-part titles, that is, there is a
1866 left-justified part, a centered part, and a right-justified part. An
1867 automatically generated page number may be put in any of these fields
1868 with the @samp{%} character (see @ref{Page Layout}, for more details).
1870 @c ---------------------------------------------------------------------
1872 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1873 @subsection Page Layout
1875 Most macro packages let the user specify top and bottom margins and
1876 other details about the appearance of the printed pages.
1878 @c ---------------------------------------------------------------------
1880 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1881 @subsection Displays
1884 Displays are sections of text to be set off from the body of the paper.
1885 Major quotes, tables, and figures are types of displays, as are all the
1886 examples used in this document.
1888 @cindex quotes, major
1889 @cindex major quotes
1890 @dfn{Major quotes} are quotes which are several lines long, and hence
1891 are set in from the rest of the text without quote marks around them.
1894 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1895 should be used when the material to be printed should not be filled and
1896 justified like normal text, such as columns of figures or the examples
1900 A @dfn{keep} is a display of lines which are kept on a single page if
1901 possible. An example for a keep might be a diagram. Keeps differ from
1902 lists in that lists may be broken over a page boundary whereas keeps are
1905 @cindex keep, floating
1906 @cindex floating keep
1907 Floating keeps move relative to the text. Hence, they are good for
1908 things which are referred to by name, such as ``See figure@w{ }3''. A
1909 floating keep appears at the bottom of the current page if it fits;
1910 otherwise, it appears at the top of the next page. Meanwhile, the
1911 surrounding text `flows' around the keep, thus leaving no blank areas.
1913 @c ---------------------------------------------------------------------
1915 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1916 @subsection Footnotes and Annotations
1920 There are a number of requests to save text for later printing.
1922 @dfn{Footnotes} are printed at the bottom of the current page.
1924 @cindex delayed text
1925 @dfn{Delayed text} is very similar to a footnote except that it is
1926 printed when called for explicitly. This allows a list of references to
1927 appear (for example) at the end of each chapter, as is the convention in
1930 Most macro packages which supply this functionality also supply a means
1931 of automatically numbering either type of annotation.
1933 @c ---------------------------------------------------------------------
1935 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1936 @subsection Table of Contents
1937 @cindex table of contents
1938 @cindex contents, table of
1940 @dfn{Tables of contents} are a type of delayed text having a tag
1941 (usually the page number) attached to each entry after a row of dots.
1942 The table accumulates throughout the paper until printed, usually after
1943 the paper has ended. Many macro packages provide the ability to have
1944 several tables of contents (e.g.@: a standard table of contents, a list
1947 @c ---------------------------------------------------------------------
1949 @node Indices, Paper Formats, Table of Contents, Common Features
1951 @cindex index, in macro package
1953 While some macro packages use the term @dfn{index}, none actually
1954 provide that functionality. The facilities they call indices are
1955 actually more appropriate for tables of contents.
1957 @c ---------------------------------------------------------------------
1959 @node Paper Formats, Multiple Columns, Indices, Common Features
1960 @subsection Paper Formats
1961 @cindex paper formats
1963 Some macro packages provide stock formats for various kinds of
1964 documents. Many of them provide a common format for the title and
1965 opening pages of a technical paper. The @file{mm} macros in particular
1966 provide formats for letters and memoranda.
1968 @c ---------------------------------------------------------------------
1970 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1971 @subsection Multiple Columns
1973 Some macro packages (but not @file{man}) provide the ability to have two
1974 or more columns on a page.
1976 @c ---------------------------------------------------------------------
1978 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
1979 @subsection Font and Size Changes
1981 The built-in font and size functions are not always intuitive, so all
1982 macro packages provide macros to make these operations simpler.
1984 @c ---------------------------------------------------------------------
1986 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
1987 @subsection Predefined Strings
1989 Most macro packages provide various predefined strings for a variety of
1990 uses; examples are sub- and superscripts, printable dates, quotes and
1991 various special characters.
1993 @c ---------------------------------------------------------------------
1995 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
1996 @subsection Preprocessor Support
1998 All macro packages provide support for the various preprocessors and may
1999 extend their functionality.
2001 For example, all macro packages mark tables (which are processed with
2002 @code{gtbl}) by placing them between @code{.TS} and @code{.TE} macros.
2003 The @file{ms} macro package has an option, @code{.TS@w{}H}, that prints
2004 a caption at the top of a new page (when the table is too long to fit on
2007 @c ---------------------------------------------------------------------
2009 @node Configuration and Customization, , Preprocessor Support, Common Features
2010 @subsection Configuration and Customization
2012 Some macro packages provide means of customizing many of the details of
2013 how the package behaves. This ranges from setting the default type size
2014 to changing the appearance of section headers.
2018 @c =====================================================================
2019 @c =====================================================================
2021 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
2022 @chapter Macro Packages
2023 @cindex macro packages
2024 @cindex packages, macros
2026 This chapter documents the main macro packages that come with
2038 @c =====================================================================
2040 @node man, mdoc, Macro Packages, Macro Packages
2043 @cindex manual pages
2046 @pindex man-old.tmac
2048 This is the most popular and probably the most important macro package
2049 of @code{groff}. It is easy to use, and a vast majority of manual pages
2056 * Miscellaneous man macros::
2057 * Predefined man strings::
2058 * Preprocessors in man pages::
2061 @c ---------------------------------------------------------------------
2063 @node Man options, Man usage, man, man
2066 The command line format for using the @file{man} macros with
2070 groff -m man [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ]
2071 [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ]
2075 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2079 This option (the default if a tty output device is used) creates a
2080 single, very long page instead of multiple pages. Use @code{-rcR=0}
2084 If more than one manual page is given on the command line, number the
2085 pages continuously, rather than starting each at@w{ }1.
2088 Double-sided printing. Footers for even and odd pages are formatted
2092 Page numbering starts with @var{nnn} rather than with@w{ }1.
2095 Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base
2096 document font size instead of the default value of@w{ }10@dmn{pt}.
2099 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2100 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2101 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2104 @c ---------------------------------------------------------------------
2106 @node Man usage, Man font macros, Man options, man
2108 @cindex @code{man} macros
2109 @cindex macros for manual pages
2112 This section describes the available macros for manual pages. For
2113 further customization, put additional macros and requests into the file
2114 @file{man.local} which is loaded immediately after the @file{man}
2117 @Defmac {TH, title section [@Var{extra1}] [@Var{extra2}] [@Var{extra3}]}
2118 Set the title of the man page to @var{title} and the section to
2119 @var{section}, which must have a value between 1 and@w{ }8. The value
2120 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2121 to indicate a specific subsection of the man pages.
2123 Both @var{title} and @var{section} are positioned at the left and right
2124 in the header line (with @var{section} in parentheses immediately
2125 appended to @var{title}. @var{extra1} is positioned in the middle of
2126 the footer line. @var{extra2} is positioned at the left in the footer
2127 line (or at the left on even pages and at the right on odd pages if
2128 double-sided printing is active). @var{extra3} is centered in the
2131 For @acronym{HTML} output, headers and footers are completely suppressed.
2133 Additionally, this macro starts a new page; the new line number is@w{ }1
2134 again (except if the @option{-rC1} option is given on the command line)
2135 -- this feature is intended only for formatting multiple man pages; a
2136 single man page should contain exactly one @code{TH} macro at the
2137 beginning of the file.
2140 @Defmac {SH, [@Var{heading}]}
2141 Set up an unnumbered section heading sticking out to the left. Prints
2142 out all the text following @code{SH} up to the end of the line (or the
2143 text in the next line if there is no argument to @code{SH}) in bold
2144 face, one size larger than the base document size. Additionally, the
2145 left margin for the following text is reset to its default value.
2148 @Defmac {SS, [@Var{heading}]}
2149 Set up an unnumbered (sub)section heading. Prints out all the text
2150 following @code{SS} up to the end of the line (or the text in the next
2151 line if there is no argument to @code{SS}) in bold face, at the same
2152 size as the base document size. Additionally, the left margin for the
2153 following text is reset to its default value.
2156 @Defmac {TP, [@Var{nnn}]}
2157 Set up an indented paragraph with label. The indentation is set to
2158 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2159 if omitted), otherwise it is set to the default indentation value.
2161 The first line of text following this macro is interpreted as a string
2162 to be printed flush-left, as it is appropriate for a label. It is not
2163 interpreted as part of a paragraph, so there is no attempt to fill the
2164 first line with text from the following input lines. Nevertheless, if
2165 the label is not as wide as the indentation, then the paragraph starts
2166 at the same line (but indented), continuing on the following lines.
2167 If the label is wider than the indentation, then the descriptive part
2168 of the paragraph begins on the line following the label, entirely
2169 indented. Note that neither font shape nor font size of the label is
2170 set to a default value; on the other hand, the rest of the text has
2171 default font settings.
2177 These macros are mutual aliases. Any of them causes a line break at
2178 the current position, followed by a vertical space downwards by the
2179 amount specified by the @code{PD} macro. The font size and shape are
2180 reset to the default value (10@dmn{pt} roman). Finally, the current
2181 left margin is restored.
2184 @Defmac {IP, [@Var{designator}] [@Var{nnn}]}
2185 Set up an indented paragraph, using @var{designator} as a tag to mark
2186 its beginning. The indentation is set to @var{nnn} if that argument
2187 is supplied (default unit is @samp{n}), otherwise the default
2188 indentation value is used. Font size and face of the paragraph (but
2189 not the designator) are reset to their default values. To start an
2190 indented paragraph with a particular indentation but without a
2191 designator, use @samp{""} (two double quotes) as the first argument of
2194 For example, to start a paragraph with bullets as the designator and
2195 4@dmn{en} indentation, write
2202 @cindex hanging indentation, in manual pages
2203 @Defmac {HP, [@Var{nnn}]}
2204 Set up a paragraph with hanging left indentation. The indentation is
2205 set to @var{nnn} if that argument is supplied (default unit is
2206 @samp{n}), otherwise the default indentation value is used. Font size
2207 and face are reset to their default values.
2210 @cindex left margin, how to move, in manual pages
2211 @Defmac {RS, [@Var{nnn}]}
2212 Move the left margin to the right by the value @var{nnn} if specified
2213 (default unit is @samp{n}); otherwise the default indentation value is
2214 used. Calls to the @code{RS} macro can be nested.
2217 @Defmac {RE, [@Var{nnn}]}
2218 Move the left margin back to level @var{nnn}; if no argument is given,
2219 it moves one level back. The first level (i.e., no call to @code{RS}
2220 yet) has number@w{ }1, and each call to @code{RS} increases the level
2232 To summarize, the following macros cause a line break with the insertion
2233 of vertical space (which amount can be changed with the @code{PD}
2234 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2235 @code{P}), @code{IP}, and @code{HP}.
2239 The macros @code{RS} and @code{RE} also cause a break but do not insert
2242 @c ---------------------------------------------------------------------
2244 @node Man font macros, Miscellaneous man macros, Man usage, man
2245 @subsection Macros to set fonts
2246 @cindex fonts in manual pages
2247 @cindex @code{man}, how to set fonts
2249 The standard font is roman; the default text size is 10@w{ }point.
2251 @Defmac {SM, [@Var{text}]}
2252 Set the text on the same line or the text on the next line in a font
2253 that is one point size smaller than the default font.
2256 @cindex boldface, in manual pages
2257 @Defmac {SB, [@Var{text}]}
2258 Set the text on the same line or the text on the next line in boldface
2259 font, one point size smaller than the default font.
2263 Set its arguments alternately in bold face and italic. Thus,
2266 .BI this "word and" that
2270 would set ``this'' and ``that'' in bold face, and ``word and'' in
2275 Set its arguments alternately in italic and bold face.
2279 Set its arguments alternately in roman and italic.
2283 Set its arguments alternately in italic and roman.
2287 Set its arguments alternately in bold face and roman.
2291 Set its arguments alternately in roman and bold face.
2294 @Defmac {R, [@Var{text}]}
2295 Set @var{text} in roman font. If no text is present on the line where
2296 the macro is called, then the text of the next line appears in roman.
2297 This is the default font to which text is returned at the end of
2298 processing of the other macros.
2301 @Defmac {B, [@Var{text}]}
2302 Set @var{text} in bold face. If no text is present on the line where
2303 the macro is called, then the text of the next line appears in bold
2307 @cindex italic, in manual pages
2308 @Defmac {I, [@Var{text}]}
2309 Set @var{text} in italic. If no text is present on the line where the
2310 macro is called, then the text of the next line appears in italic.
2313 @c ---------------------------------------------------------------------
2315 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2316 @subsection Miscellaneous macros
2319 @cindex @file{man}, default indentation
2320 @cindex default indentation, @file{man}
2321 The default indentation is 7.2@dmn{n} for all output devices except for
2322 @code{grohtml} which ignores indentation.
2325 @cindex tab stops, in manual pages
2327 Set tabs every 0.5@w{ }inches. Since this macro is always called
2328 during a @code{TH} request, it makes sense to call it only if the tab
2329 positions have been changed.
2332 @cindex empty space before a paragraph, in manual pages
2333 @Defmac {PD, [@Var{nnn}]}
2334 Adjust the empty space before a new paragraph (or section). The
2335 optional argument gives the amount of space (default unit is
2336 @samp{v}); without parameter, the value is reset to its default value
2337 (1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise).
2348 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2349 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2351 @c ---------------------------------------------------------------------
2353 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2354 @subsection Predefined strings
2356 The following strings are defined:
2359 Switch back to the default font size.
2363 The `registered' sign.
2367 The `trademark' sign.
2374 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2378 @c ---------------------------------------------------------------------
2380 @node Preprocessors in man pages, , Predefined man strings, man
2381 @subsection Preprocessors in @file{man} pages
2383 @cindex preprocessor, calling convention
2384 @cindex calling convention of preprocessors
2385 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2386 become common usage to make the first line of the man page look like
2393 @pindex geqn@r{, invocation in manual pages}
2394 @pindex grefer@r{, invocation in manual pages}
2395 @pindex gtbl@r{, invocation in manual pages}
2396 @pindex man@r{, invocation of preprocessors}
2398 Note the single space character after the double quote. @var{word}
2399 consists of letters for the needed preprocessors: @samp{e} for
2400 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2401 Modern implementations of the @code{man} program read this first line
2402 and automatically call the right preprocessor(s).
2405 @c =====================================================================
2407 @node mdoc, ms, man, Macro Packages
2408 @section @file{mdoc}
2411 @c XXX documentation
2414 @c =====================================================================
2416 @node ms, me, mdoc, Macro Packages
2420 @c XXX documentation
2423 @c =====================================================================
2425 @node me, mm, ms, Macro Packages
2429 @c XXX documentation
2432 @c =====================================================================
2434 @node mm, , me, Macro Packages
2438 @c XXX documentation
2442 @c =====================================================================
2443 @c =====================================================================
2445 @node gtroff Reference, Preprocessors, Macro Packages, Top
2446 @chapter @code{gtroff} Reference
2447 @cindex reference, @code{gtroff}
2448 @cindex @code{gtroff} reference
2450 This chapter covers @strong{all} of the facilities of @code{gtroff}.
2451 Users of macro packages may skip it if not interested in details.
2456 * Input Conventions::
2460 * Embedded Commands::
2462 * Manipulating Filling and Adjusting::
2463 * Manipulating Hyphenation::
2464 * Manipulating Spacing::
2466 * Character Translations::
2467 * Troff and Nroff Mode::
2474 * Conditionals and Loops::
2477 * Drawing Requests::
2481 * Suppressing output::
2483 * Postprocessor Access::
2485 * Gtroff Internals::
2487 * Implementation Differences::
2492 @c =====================================================================
2494 @node Text, Input Conventions, gtroff Reference, gtroff Reference
2496 @cindex text, @code{gtroff} processing
2498 @code{gtroff} input files contain text with control commands
2499 interspersed throughout. But, even without control codes, @code{gtroff}
2500 still does several things with the input text:
2504 filling and adjusting
2507 adding additional space after sentences
2513 inserting implicit line breaks
2517 * Filling and Adjusting::
2521 * Implicit Line Breaks::
2524 @c ---------------------------------------------------------------------
2526 @node Filling and Adjusting, Hyphenation, Text, Text
2527 @subsection Filling and Adjusting
2531 When @code{gtroff} reads text, it collects words from the input and fits
2532 as many of them together on one output line as it can. This is known as
2535 @cindex leading spaces
2536 @cindex spaces, leading and trailing
2537 @cindex extra spaces
2538 @cindex trailing spaces
2539 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
2540 it. This means it widens the spacing between words until the text
2541 reaches the right margin (in the default adjustment mode). Extra spaces
2542 between words are preserved, but spaces at the end of lines are ignored.
2543 Spaces at the front of a line cause a @dfn{break} (breaks are
2544 explained in @ref{Implicit Line Breaks})
2546 @xref{Manipulating Filling and Adjusting}.
2548 @c ---------------------------------------------------------------------
2550 @node Hyphenation, Sentences, Filling and Adjusting, Text
2551 @subsection Hyphenation
2554 Since the odds are not great for finding a set of words, for every
2555 output line, which fit nicely on a line without inserting excessive
2556 amounts of space between words, @code{gtroff} hyphenates words so
2557 that it can justify lines without inserting too much space between
2558 words. It uses an internal hyphenation algorithm (a simplified version
2559 of the algorithm used within @TeX{}) to indicate which words can be
2560 hyphenated and how to do so. When a word is hyphenated, the first part
2561 of the word is added to the current filled line being output (with
2562 an attached hyphen), and the other portion is added to the next
2565 @xref{Manipulating Hyphenation}.
2567 @c ---------------------------------------------------------------------
2569 @node Sentences, Tab Stops, Hyphenation, Text
2570 @subsection Sentences
2573 Although it is often debated, some typesetting rules say there should be
2574 different amounts of space after various punctuation marks. For
2575 example, the @cite{Chicago typsetting manual} says that a period at the
2576 end of a sentence should have twice as much space following it as would
2577 a comma or a period as part of an abbreviation.
2579 @c XXX exact citation of Chicago manual
2581 @cindex sentence space
2582 @cindex space between sentences
2583 @cindex french-spacing
2584 @code{gtroff} does this by flagging certain characters (normally
2585 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end of sentence} characters.
2586 When @code{gtroff} encounters one of these characters at the end of a
2587 line, it appends a normal space followed by a @dfn{sentence space} in
2588 the formatted output. (This justifies one of the conventions mentioned
2589 in @ref{Input Conventions}.)
2591 @cindex transparent characters
2592 @cindex character, transparent
2600 In addition, the following characters or glyphs are treated
2601 transparently while handling end of sentence characters: @samp{"},
2602 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}.
2604 See the @code{cflags} request in @ref{Using Symbols}, for more details.
2607 To prevent the insertion of extra space after an end of sentence
2608 character (at the end of a line), append @code{\&}.
2610 @c ---------------------------------------------------------------------
2612 @node Tab Stops, Implicit Line Breaks, Sentences, Text
2613 @subsection Tab Stops
2615 @cindex stops, tabulator
2616 @cindex tab character
2617 @cindex character, tabulator
2619 @cindex @acronym{EBCDIC} encoding
2620 @code{gtroff} translates @dfn{tabulator characters}, also called
2621 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
2622 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
2623 tabulator stop. These tab stops are initially located every half inch
2624 across the page. Using this, simple tables can be made easily.
2625 However, it can often be deceptive as the appearance (and width) of the
2626 text on a terminal and the results from @code{gtroff} can vary greatly.
2628 Also, a possible sticking point is that lines beginning with tab
2629 characters are still filled, again producing unexpected results.
2630 For example, the following input
2632 @multitable {12345678} {12345678} {12345678} {12345678}
2634 @tab 1 @tab 2 @tab 3
2642 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
2644 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
2647 @xref{Tabs and Fields}.
2649 @c ---------------------------------------------------------------------
2651 @node Implicit Line Breaks, , Tab Stops, Text
2652 @subsection Implicit Line Breaks
2653 @cindex implicit line breaks
2654 @cindex implicit breaks of lines
2655 @cindex line, implicit breaks
2656 @cindex break, implicit
2659 An important concept in @code{gtroff} is the @dfn{break}. When a break
2660 occurs, @code{gtroff} outputs the partially filled line
2661 (unjustified), and resumes collecting and filling text on the next output
2667 @cindex blank line macro
2669 There are several ways to cause a break in @code{gtroff}. A blank
2670 line not only causes a break, but it also outputs a one line vertical
2671 space (effectively a blank line). Note that this behaviour can be
2672 modified with the blank line macro request @code{blm}.
2678 A line that begins with a space causes a break and the space is
2679 output at the beginning of the next line. Note that this space isn't
2680 adjusted, even in fill mode.
2682 The end of file also causes a break -- otherwise the last line of
2683 the document may vanish!
2685 Certain requests also cause breaks, implicitly or explicitly. This is
2686 discussed in @ref{Manipulating Filling and Adjusting}.
2689 @c =====================================================================
2691 @node Input Conventions, Measurements, Text, gtroff Reference
2692 @section Input Conventions
2693 @cindex input conventions
2694 @cindex conventions for input
2696 Since @code{gtroff} does filling automatically, it is traditional in
2697 @code{groff} not to try and type things in as nicely formatted
2698 paragraphs. These are some conventions commonly used when typing
2703 Break lines after punctuation, particularly at the end of a sentence
2704 and in other logical places. Keep separate phrases on lines by
2705 themselves, as entire phrases are often added or deleted when editing.
2708 Try to keep lines less than 40-60@w{ }characters, to allow space for
2709 inserting more text.
2712 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
2713 don't try using spaces to get proper indentation).
2717 @c =====================================================================
2719 @node Measurements, Expressions, Input Conventions, gtroff Reference
2720 @section Measurements
2721 @cindex measurements
2723 @cindex units of measurement
2725 @cindex machine units
2726 @cindex measurement units
2727 @cindex @code{u} unit
2728 @cindex unit, @code{u}
2729 @code{gtroff} (like many other programs) requires numeric parameters to
2730 specify various measurements. Most numeric parameters@footnote{those
2731 that specify vertical or horizontal motion or a type size} may have a
2732 @dfn{measurement unit} attached. These units are specified as a single
2733 character which immediately follows the number or expression. Each of
2734 these units are understood, by @code{gtroff}, to be a multiple of its
2735 @dfn{basic unit}. So, whenever a different measurement unit is
2736 specified @code{gtroff} converts this into its @dfn{basic units}. This
2737 basic unit, represented by a @samp{u}, is a device dependent measurement
2738 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
2739 inch. The values may be given as fractional numbers; however,
2740 fractional basic units are always rounded to integers.
2742 Some of the measurement units are completely independent of any of the
2743 current settings (e.g.@: type size) of @code{gtroff}.
2748 @cindex @code{i} unit
2749 @cindex unit, @code{i}
2750 Inches. An antiquated measurement unit still in use in certain
2751 backwards countries with incredibly low-cost computer equipment. One
2752 inch is equal to@w{ }2.54@dmn{cm}.
2756 @cindex @code{c} unit
2757 @cindex unit, @code{c}
2758 Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
2762 @cindex @code{p} unit
2763 @cindex unit, @code{p}
2764 Points. This is a typesetter's measurement used for measure type size.
2765 It is 72@w{ }points to an inch.
2769 @cindex @code{P} unit
2770 @cindex unit, @code{P}
2771 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
2772 12@w{ }points to a pica).
2776 @cindex @code{s} unit
2777 @cindex unit, @code{s}
2778 @cindex @code{z} unit
2779 @cindex unit, @code{z}
2780 @xref{Fractional Type Sizes}, for a discussion of these units.
2783 The other measurements understood by @code{gtroff} depend on
2784 settings currently in effect in @code{gtroff}. These are very useful
2785 for specifying measurements which should look proper with any size of
2791 @cindex @code{m} unit
2792 @cindex unit, @code{m}
2793 Ems. This unit is equal to the current font size in points. So called
2794 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
2795 in the current font.
2799 @cindex @code{n} unit
2800 @cindex unit, @code{n}
2801 Ens. This is half of an em.
2804 @cindex vertical space
2805 @cindex space, vertical
2806 @cindex @code{v} unit
2807 @cindex unit, @code{v}
2808 Vertical space. This is equivalent to the current line spacing.
2809 @xref{Sizes}, for more information about this.
2812 @cindex @code{M} unit
2813 @cindex unit, @code{M}
2821 @c ---------------------------------------------------------------------
2823 @node Default Units, , Measurements, Measurements
2824 @subsection Default Units
2825 @cindex default units
2826 @cindex units, default
2828 Many requests take a default unit. While this can be helpful at times,
2829 it can cause strange errors in some expressions. For example, the line
2830 length request expects em units. Here are several attempts to get a
2831 line length of 3.5@w{ }inches and their results:
2838 7i/2u @result{} 3.5i
2842 Everything is converted to basic units first. In the above example it
2843 is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{
2844 }10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2
2845 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
2846 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
2849 @cindex measurements, specifying safely
2850 Thus, the safest way to specify measurements is to always
2851 attach a scaling indicator. If you want to multiply or divide by a
2852 certain scalar value, use @samp{u} as the unit for that value.
2855 @c =====================================================================
2857 @node Expressions, Identifiers, Measurements, gtroff Reference
2858 @section Expressions
2861 @code{gtroff} has most arithmetic operators common to other languages:
2863 @c XXX more details; examples
2867 @cindex arithmetic operators
2868 @cindex operators, arithmetic
2874 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
2875 (division), @samp{*} (multiplication), @samp{%} (modulo).
2877 @code{gtroff} only provides integer arithmetic. The internal type used
2878 for computing results is @samp{int}, which is usually a 32@dmn{bit}
2882 @cindex comparison operators
2883 @cindex operators, comparison
2890 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
2891 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
2892 (equal), @samp{==} (the same as @samp{=}).
2895 @cindex logical operators
2896 @cindex operators, logical
2899 Logical: @samp{&} (logical and), @samp{:} (logical or).
2902 @cindex unary operators
2903 @cindex operators, unary
2909 @cindex @code{if}, and the @samp{!} operator
2910 @cindex @code{while}, and the @samp{!} operator
2911 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
2912 (just for completeness; does nothing in expressions), @samp{!} (logical
2913 not; this works only within @code{if} and @code{while} requests). See
2914 below for the use of unary operators in motion requests.
2917 @cindex extremum operators
2918 @cindex operators, extremum
2921 Extrema: @samp{>?} (maximum), @samp{<?} (minimum). For example,
2922 @samp{5>?3} yields@w{ }@samp{5}.
2927 @cindex scaling operator
2928 @cindex operator, scaling
2929 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
2930 the default scaling indicator. If @var{c} is missing, ignore scaling
2931 indicators in the evaluation of @var{e}.
2935 @cindex order of evaluation in expressions
2936 @cindex expression, order of evaluation
2939 Parentheses may be used as in any other language. However, in
2940 @code{gtroff} they are necessary to ensure order of evaluation.
2941 @code{gtroff} has no operator precedence; expressions are evaluated left
2942 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
2943 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
2946 @opindex +@r{, and page motion}
2947 @opindex -@r{, and page motion}
2948 @opindex |@r{, and page motion}
2949 @cindex motion operators
2950 @cindex operators, motion
2951 For many requests which cause a motion on the page, the unary operators
2952 work differently. The @samp{+} and @samp{-} operators then indicate a
2953 motion relative to the current position (down or up, respectively), and
2954 the @samp{|} operator indicates an absolute position on the page or
2957 @samp{+} and @samp{-} are also treated differently by the following
2958 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
2959 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
2960 @code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus
2961 signs indicate increments and decrements.
2963 @c XXX add more xref
2964 @xref{Setting Registers}.
2966 @cindex space characters in expressions
2967 @cindex expressions and space characters
2968 Due to the way arguments are parsed, spaces are not allowed in
2969 expressions, unless the entire expression is surrounded by parentheses.
2971 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2974 @c =====================================================================
2976 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
2977 @section Identifiers
2980 Like any other language, @code{gtroff} has rules for properly formed
2981 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
2982 almost any printable character, with the exception of the following
2987 @cindex whitespace characters
2988 @cindex newline character
2989 @cindex character, whitespace
2990 Whitespace characters (spaces, tabs, and newlines).
2993 @cindex character, backspace
2994 @cindex backspace character
2995 @cindex @acronym{EBCDIC} encoding of backspace
2996 Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{
2997 }@code{0x16}) and character code @code{0x01}.
3000 @cindex invalid input characters
3001 @cindex input characters, invalid
3002 @cindex characters, invalid input
3004 The following input characters are invalid and are ignored if
3005 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
3006 warning message of type @samp{input} (see @ref{Debugging}, for more
3007 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
3008 @code{0x80}-@code{0x9F}.
3010 And here are the invalid input characters if @code{groff} runs on an
3011 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
3012 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
3013 @code{0x30}-@code{0x3F}.
3015 Currently, some of these reserved codepoints are used internally, thus
3016 making it non-trivial to extend @code{gtroff} to cover Unicode or other
3017 character sets and encodings which use characters of these ranges.
3019 Note that invalid characters are removed before parsing; an
3020 identifier @code{foo}, followed by an invalid character, followed by
3021 @code{bar} is treated as @code{foobar}.
3024 For example, any of the following is valid.
3036 Note that identifiers longer than two characters with a closing bracket
3037 (@samp{]}) in its name can't be accessed with escape sequences which
3038 expect an identifier as a parameter. For example, @samp{\[foo]]}
3039 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
3040 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
3044 @Defesc {\\A, ', ident, '}
3045 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
3046 expands to the character@w{ }1 or@w{ }0 according to whether its
3047 argument (usually delimited by quotes) is or is not acceptable as the
3048 name of a string, macro, diversion, number register, environment, or
3049 font. It returns@w{ }0 if no argument is given. This is useful for
3050 looking up user input in some sort of associative table.
3058 @xref{Escapes}, for details on parameter delimiting characters.
3060 @c XXX add xrefs above
3062 Identifiers in @code{gtroff} can be any length, but, in some contexts,
3063 @code{gtroff} needs to be told where identifiers end and text begins
3064 (and in different ways depending on their length):
3074 Two characters. Must be prefixed with @samp{(} in some situations.
3077 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
3078 and@w{ }@samp{]} in some situations. Any length identifier can be put
3082 @cindex undefined identifiers
3083 @cindex indentifiers, undefined
3084 Unlike many other programming languages, undefined identifiers are
3085 silently ignored or expanded to nothing.
3086 When @code{gtroff} finds an undefined identifier, it emits a
3091 If the identifier is a string, macro, or diversion,
3092 @code{gtroff} defines it as empty.
3095 If the identifier is a number register, @code{gtroff}
3096 defines it with a value of@w{ }0.
3101 @c XXX info about common identifier pool for strings and macros.
3103 @xref{Interpolating Registers}, and @ref{Strings}.
3106 @c =====================================================================
3108 @node Embedded Commands, Registers, Identifiers, gtroff Reference
3109 @section Embedded Commands
3110 @cindex embedded commands
3111 @cindex commands, embedded
3113 Most documents need more functionality beyond filling, adjusting and
3114 implicit line breaking. In order to gain further functionality,
3115 @code{gtroff} allows commands to be embedded into the text, in two ways.
3117 The first is a @dfn{request} which takes up an entire line, and does
3118 some large-scale operation (e.g.@: break lines, start new pages).
3120 The other is an @dfn{escape} which can be embedded anywhere in the text,
3121 or even as an argument to a request.
3122 @c XXX (Not always?)
3123 Escapes generally do more minor operations like sub- and superscripts,
3124 print a symbol, etc.
3132 @c ---------------------------------------------------------------------
3134 @node Requests, Macros, Embedded Commands, Embedded Commands
3135 @subsection Requests
3138 @cindex control character
3139 @cindex character, control
3140 @cindex no-break control character
3141 @cindex character, no-break control
3142 @cindex control character, no-break
3145 A request line begins with a control character, which is either a single
3146 quote (@samp{'}, the @dfn{no-break control character}) or a period
3147 (@samp{.}, the normal @dfn{control character}). These can be changed;
3148 see @ref{Character Translations}, for details. After this there may be
3149 optional tabs or spaces followed by an identifier which is the name of
3150 the request. This may be followed by any number of space-separated
3151 arguments (@emph{no} tabs here).
3153 @cindex structuring source code of documents or macro packages
3154 @cindex documents, structuring the source code
3155 @cindex macro packages, strucuring the source code
3156 Since a control character followed by whitespace only is ignored, it
3157 is common practice to use this feature for structuring the source code
3158 of documents or macro packages.
3172 @cindex blank line macro
3174 Another possibility is to use the blank line macro request @code{blm}
3175 by assigning an empty macro to it.
3180 .blm do-nothing \" activate blank line macro
3191 .blm \" deactivate blank line macro
3196 @cindex zero width space character
3197 @cindex character, zero width space
3198 @cindex space character, zero width
3200 @cindex @code{\&}, escaping control characters
3201 To begin a line with a control character without it being interpreted,
3202 precede it with @code{\&}. This represents a zero width space, which
3203 means it does not affect the output.
3205 In most cases the period is used as a control character. Several
3206 requests cause a break implicitly; using the single quote control
3207 character prevents this.
3210 * Request Arguments::
3213 @node Request Arguments, , Requests, Requests
3214 @subsubsection Request Arguments
3215 @cindex request arguments
3216 @cindex arguments to requests
3218 Arguments to requests (and macros) are processed much like the shell:
3219 The line is split into arguments according to spaces. An argument
3220 which is intended to contain spaces can either be enclosed in double
3221 quotes, or have the spaces @dfn{escaped} with backslashes.
3223 Here are a few examples:
3226 .uh The Mouse Problem
3227 .uh "The Mouse Problem"
3228 .uh The\ Mouse\ Problem
3234 The first line is the @code{uh} macro being called with 3 arguments,
3235 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
3236 same effect of calling the @code{uh} macro with one argument, @samp{The
3237 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
3238 is ``classical'' in the sense that it can be found in most @code{troff}
3239 documents. Nevertheless, it is not optimal in all situations, since
3240 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
3241 can't stretch. @code{gtroff} provides a different command @code{\~} to
3242 insert a stretchable, non-breaking space.}
3244 @cindex @code{"}, as a macro argument
3245 @cindex double quote, as a macro argument
3246 A double quote which isn't preceded by a space doesn't start a macro
3247 argument. If not closing a string, it is printed literally.
3252 .xxx a" "b c" "de"fg"
3256 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
3259 Duoble quotes in the @code{ds} request are handled differently.
3260 @xref{Strings}, for more details.
3262 @c ---------------------------------------------------------------------
3264 @node Macros, Escapes, Requests, Embedded Commands
3268 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
3269 which can be invoked by name. They are called in the same manner as
3270 requests -- arguments also may be passed in the same manner.
3272 @xref{Writing Macros}, and @ref{Request Arguments}.
3274 @c ---------------------------------------------------------------------
3276 @node Escapes, , Macros, Embedded Commands
3280 Escapes may occur anywhere in the input to @code{gtroff}. They usually
3281 begin with a backslash and are followed by a single character which
3282 indicates the function to be performed. The escape character can be
3283 changed; see @ref{Character Translations}.
3288 Escape sequences which require an identifier as a parameter accept three
3289 possible syntax forms.
3293 The next single character is the identifier.
3296 If this single character is an opening parenthesis, take the following
3297 two characters as the identifier. Note that there is no closing
3298 parenthesis after the identifier.
3301 If this single character is an opening bracket, take all characters
3302 until a closing bracket as the identifier.
3315 @cindex argument delimiting characters
3316 @cindex characters, argument delimiting
3317 @cindex delimiting characters for arguments
3318 Other escapes may require several arguments and/or some special format.
3319 In such cases the argument is traditionally enclosed in single quotes
3320 (and quotes are always used in this manual for the definitions of escape
3321 sequences). The enclosed text is then processed according to what that
3322 escape expects. Example:
3331 Note that the quote character can be replaced with any other character
3332 which does not occur in the argument (even a newline or a space
3333 character) in the following escapes: @code{\o}, @code{\b}, and
3334 @code{\X}. This makes e.g.
3343 @result{} A caf@'e in Paris
3347 possible, but it is better not to use this feature to avoid confusion.
3377 The following escapes sequences (which are handled similarly to
3378 characters since they don't take a parameter) are also allowed as
3379 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
3380 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
3381 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
3382 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
3383 @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't
3384 use these if possible.
3390 No newline characters as delimiters are allowed in the following
3391 escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}.
3404 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
3405 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
3406 @code{\x} can't use the following characters as delimiters:
3412 The digits @code{0}-@code{9}.
3429 The (single-character) operators @samp{+-/*%<>=&:().}.
3432 @cindex space character
3433 @cindex character, space
3434 @cindex tab character
3435 @cindex character, tab
3436 @cindex newline character
3437 @cindex character, newline
3438 The space, tab, and newline characters.
3454 All escape sequences except @code{\%}, @code{\@{}, @code{\@}},
3455 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
3456 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
3462 To have a backslash (actually, the current escape character) appear in the
3463 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
3464 These are very similar, and only differ with respect to being used in
3465 macros or diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for
3468 @c XXX explanation of \E
3470 @xref{Identifiers}, and @ref{Character Translations}.
3476 @node Comments, , Escapes, Escapes
3477 @subsubsection Comments
3480 Probably one of the most@footnote{Unfortunately, this is a lie. But
3481 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
3482 common forms of escapes is the comment.
3485 Start a comment. Everything to the end of the input line is ignored.
3487 This may sound simple, but it can be tricky to keep the comments from
3488 interfering with the appearance of the final output.
3492 If the escape is to the right of some text or a request, that portion
3493 of the line is ignored, but the space leading up to it is noticed by
3494 @code{gtroff}. This only affects the @code{.ds} and @code{.as}
3497 @cindex tabs before comments
3498 @cindex comments, lining up with tabs
3499 One possibly irritating idiosyncracy is that tabs must not be used to
3500 line up comments. Tabs are not treated as white space between the
3501 request and macro arguments.
3503 @cindex undefined request
3504 @cindex request, undefined
3505 A comment on a line by itself is treated as a blank line, because
3506 after eliminating the comment, that is all that remains:
3523 To avoid this, it is common to start the line with @code{.\"} which
3524 causes the line to be treated as an undefined request and thus ignored
3528 Another commenting scheme seen sometimes is three consecutive single
3529 quotes (@code{'''}) at the beginning of a line. This works, but
3530 @code{gtroff} gives a warning about an undefined macro (namely
3531 @code{''}), which is harmless, but irritating.
3535 To avoid all this, @code{gtroff} has a new comment mechanism using the
3536 @code{\#} escape. This escape works the same as @code{\"} except that
3537 the newline is also ignored:
3557 Ignore all input until @code{gtroff} encounters the macro named
3558 @code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not
3559 specified). This is useful for commenting out large blocks of text:
3564 This is part of a large block
3565 of text that has been
3566 temporarily(?) commented out.
3568 We can restore it simply by removing
3569 the .ig request and the ".." at the
3572 More text text text...
3579 text text text@dots{} More text text text@dots{}
3583 Note that the commented-out block of text does not
3586 The input is read in copy-mode; auto-incremented registers @emph{are}
3587 affected (@pxref{Auto-increment}).
3591 @c =====================================================================
3593 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
3597 Numeric variables in @code{gtroff} are called @dfn{registers}. There
3598 are a number of built-in registers, supplying anything from the date to
3599 details of formatting parameters.
3601 @xref{Identifiers}, for details on register identifiers.
3604 * Setting Registers::
3605 * Interpolating Registers::
3607 * Assigning Formats::
3608 * Built-in Registers::
3611 @c ---------------------------------------------------------------------
3613 @node Setting Registers, Interpolating Registers, Registers, Registers
3614 @subsection Setting Registers
3615 @cindex setting registers
3616 @cindex registers, setting
3618 Define or set registers using the @code{nr} request or the
3621 @Defreq {nr, ident value}
3622 @Defescx {\\R, ', ident value, '}
3623 Set number register @var{ident} to @var{value}. If @var{ident}
3624 doesn't exist, @code{gtroff} creates it.
3626 The argument to @code{\R} usually has to be enclosed in quotes.
3627 @xref{Escapes}, for details on parameter delimiting characters.
3630 For example, the following two lines are equivalent:
3637 Both @code{nr} and @code{\R} have two additional special forms to
3638 increment or decrement a register.
3640 @Defreq {nr, ident @t{+}@Var{value}}
3641 @Defreqx {nr, ident @t{-}@Var{value}}
3642 @Defescx {\\R, ', ident @t{+}@Var{value}, '}
3643 @Defescx {\\R, ', ident @t{-}@Var{value}, '}
3644 Increment (decrement) register @var{ident} by @var{value}.
3653 @cindex negating register values
3654 To assign the negated value of a register to another register, some care
3655 must be taken to get the desired result:
3669 The surrounding parentheses prevent the interpretation of the minus sign
3670 as a decrementing operator. An alternative is to start the assignment
3686 Remove number register @var{ident}. If @var{ident} doesn't exist, the
3690 @Defreq {rnn, ident1 ident2}
3691 Rename number register @var{ident1} to @var{ident2}. If either
3692 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
3695 @Defreq {aln, ident1 ident2}
3696 Create an alias @var{ident1} for a number register @var{ident2}. The
3697 new name and the old name are exactly equivalent. If @var{ident1} is
3698 undefined, a warning of type @samp{reg} is generated, and the request
3699 is ignored. @xref{Debugging}, for information about warnings.
3702 @c ---------------------------------------------------------------------
3704 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
3705 @subsection Interpolating Registers
3706 @cindex interpolating registers
3707 @cindex registers, interpolating
3709 Numeric registers can be accessed via the @code{\n} escape.
3711 @cindex nested assignments
3712 @cindex assignments, nested
3713 @cindex indirect assignments
3714 @cindex assignments, indirect
3715 @Defesc {\\n, , i, }
3716 @Defescx {\\n, @lparen{}, id, }
3717 @Defescx {\\n, @lbrack{}, ident, @rbrack}
3718 Interpolate number register with name @var{ident} (one-character name
3719 @var{i}, two-character name @var{id}). This means that the value of
3720 the register is expanded in-place while @code{gtroff} is parsing the
3721 input line. Nested assignments (also called indirect assignments) are
3743 @c ---------------------------------------------------------------------
3745 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
3746 @subsection Auto-increment
3747 @cindex auto-increment
3748 @cindex increment, automatic
3750 Number registers can also be auto-incremented and auto-decremented.
3751 The increment or decrement value can be specified with a third
3752 argument to the @code{nr} request or @code{\R} escape.
3755 @Defreq {nr, ident value incr}
3756 Set number register @var{ident} to @var{value}; the increment for
3757 auto-incrementing is set to @var{incr}. Note that the @code{\R}
3758 escape doesn't support this notation.
3761 To activate auto-incrementing, the escape @code{\n} has a special
3764 @Defesc {\\n, +, i, }
3765 @Defescx {\\n, -, i, }
3766 @Defescx {\\n, @lparen{}+, id, }
3767 @Defescx {\\n, @lparen{}-, id, }
3768 @Defescx {\\n, +@lparen{}, id, }
3769 @Defescx {\\n, -@lparen{}, id, }
3770 @Defescx {\\n, @lbrack{}+, ident, @rbrack{}}
3771 @Defescx {\\n, @lbrack{}-, ident, @rbrack{}}
3772 @Defescx {\\n, +@lbrack{}, ident, @rbrack{}}
3773 @Defescx {\\n, -@lbrack{}, ident, @rbrack{}}
3774 Before interpolating, increment or decrement @var{ident}
3775 (one-character name @var{i}, two-character name @var{id}) by the
3776 auto-increment value as specified with the @code{nr} request (or the
3777 @code{\R} escape). If no auto-increment value has been specified,
3778 these syntax forms are identical to @code{\n}.
3787 \n+a, \n+a, \n+a, \n+a, \n+a
3789 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
3791 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
3799 -5, -10, -15, -20, -25
3803 @cindex increment value without changing the register
3804 To change the increment value without changing the value of a register
3805 (@var{a} in the example), the following can be used:
3811 @c ---------------------------------------------------------------------
3813 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
3814 @subsection Assigning Formats
3815 @cindex assigning formats
3816 @cindex formats, assigning
3818 When a register is used in the text of an input file (as opposed to
3819 part of an expression), it is textually replaced (or interpolated)
3820 with a representation of that number. This output format can be
3821 changed to a variety of formats (numbers, Roman numerals, etc.). This
3822 is done using the @code{af} request.
3824 @Defreq {af, ident format}
3825 Change the output format of a number register. The first argument
3826 @var{ident} is the name of the number register to be changed, and the
3827 second argument @var{format} is the output format. The following
3828 output formats are available:
3832 Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{
3836 Decimal numbers with as many digits as specified. So, @samp{00} would
3837 result in printing numbers as 01, 02, 03,@w{ }@enddots{}
3839 In fact, any digit instead of zero will do; @code{gtroff} only counts
3840 how many digits are specified. As a consequence, @code{af}'s default
3841 format @samp{1} could be specified as @samp{0} also (and exactly this is
3842 returned by the @code{\g} escape, see below).
3845 @cindex Roman numerals
3846 @cindex numerals, Roman
3847 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{}
3850 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{}
3853 Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{}
3856 Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{}
3859 Omitting the number register format causes a warning of type
3860 @samp{missing}. @xref{Debugging}, for more details. Specifying a
3861 nonexistent format causes an error.
3863 The following example produces @samp{10, X, j, 010}:
3867 .af a 1 \" the default format
3877 @cindex Roman numerals, maximum and minimum
3878 @cindex maximum values of Roman numerals
3879 @cindex minimum values of Roman numerals
3880 The largest number representable for the @samp{i} and @samp{I} formats
3881 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
3882 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
3883 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
3884 thousand and Roman numeral ten thousand (Unicode code points
3885 @code{U+2182} and @code{U+2181}, respectively) are not available.
3887 If @var{ident} doesn't exist, it is created.
3889 @cindex read-only register, changing format
3890 @cindex changing format, read-only register
3891 Changing the output format of a read-only register causes an error. It
3892 is necessary to first copy the register's value to a writeable register,
3893 then apply the @code{af} request to this other register.
3896 @cindex format of register
3897 @cindex register, format
3898 @Defesc {\\g, , i, }
3899 @Defescx {\\g, @lparen{}, id, }
3900 @Defescx {\\g, @lbrack{}, ident, @rbrack{}}
3901 Return the current format of the specified register @var{ident}
3902 (one-character name @var{i}, two-character name @var{id}). For
3903 example, @samp{\ga} after the previous example would produce the
3904 string @samp{000}. If the register hasn't been defined yet, nothing
3908 @c ---------------------------------------------------------------------
3910 @node Built-in Registers, , Assigning Formats, Registers
3911 @subsection Built-in Registers
3912 @cindex built-in registers
3913 @cindex registers, built-in
3915 The following lists some built-in registers which are not described
3916 elsewhere in this manual. Any register which begins with a @samp{.} is
3917 read-only. A complete listing of all built-in registers can be found in
3918 @ref{Register Index}.
3922 @cindex horizontal resolution register
3923 @cindex resolution, horizontal, register
3925 Horizontal resolution in basic units.
3928 @cindex vertical resolution register
3929 @cindex resolution, vertical, register
3931 Vertical resolution in basic units.
3934 @cindex day of the week register
3935 @cindex date, day of the week register
3937 Day of the week (1-7).
3940 @cindex day of the month register
3941 @cindex date, day of the month register
3943 Day of the month (1-31).
3946 @cindex month of the year register
3947 @cindex date, month of the year register
3949 Current month (1-12).
3952 @cindex date, year register
3953 @cindex year, current, register
3959 The current year minus@w{ }1900. Unfortunately, the documentation of
3960 @acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
3961 incorrectly claimed that @code{yr} contains the last two digits of the
3962 year. That claim has never been true of either traditional @code{troff}
3963 or GNU @code{troff}. Old @code{troff} input that looks like this:
3966 '\" The following line stopped working after 1999
3967 This document was formatted in 19\n(yr.
3971 can be corrected as follows:
3974 This document was formatted in \n[year].
3978 or, to be portable to older @code{troff} versions, as follows:
3982 This document was formatted in \n(y4.
3989 @cindex input line number register
3990 @cindex line number, input, register
3991 The current @emph{input} line number. Register @samp{.c} is read-only,
3992 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
3993 affecting both @samp{.c} and @samp{c.}.
3998 @cindex output line number register
3999 @cindex line number, output, register
4000 The current @emph{output} line number after a call to the @code{nm}
4001 request to activate line numbering.
4003 @xref{Miscellaneous}, for more information about line numbering.
4007 @cindex major version number register
4008 @cindex version number, major, register
4009 The major version number. For example, if the version number is@w{
4010 }1.03 then @code{.x} contains@w{ }@samp{1}.
4014 @cindex minor version number register
4015 @cindex version number, minor, register
4016 The minor version number. For example, if the version number is@w{
4017 }1.03 then @code{.y} contains@w{ }@samp{03}.
4021 @cindex revision number register
4022 The revision number of @code{groff}.
4026 @cindex @code{gtroff} identification register
4027 @cindex GNU-specific register
4028 Always@w{ }1. Macros should use this to determine whether they are
4029 running under GNU @code{troff}.
4033 @cindex @acronym{ASCII} approximation output register
4034 If the command line option @option{-a} is used to produce an
4035 @acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
4036 otherwise. @xref{Groff Options}.
4040 This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current
4041 page is actually being printed, i.e., if the @option{-o} option is being
4042 used to only print selected pages. @xref{Groff Options}, for more
4047 If @code{gtroff} is called with the @option{-T} command line option, the
4048 number register @code{.T} is set to@w{ }1, and zero otherwise.
4049 @xref{Groff Options}.
4052 @cindex output device register
4053 Additionally, @code{gtroff} predefines a single read-write string
4054 register @code{.T} which contains the current output device (for
4055 example, @samp{latin1} or @samp{ps}).
4059 @c =====================================================================
4061 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
4062 @section Manipulating Filling and Adjusting
4063 @cindex manipulating filling and adjusting
4064 @cindex filling and adjusting, manipulating
4065 @cindex adjusting and filling, manipulating
4066 @cindex justifying text
4067 @cindex text, justifying
4082 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
4083 Breaks}. The @code{br} request likewise causes a break. Several
4084 other requests also cause breaks, but implicitly. These are
4085 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
4086 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
4089 Break the current line, i.e., the input collected so far is emitted
4092 If the no-break control character is used, @code{gtroff} suppresses
4103 Initially, @code{gtroff} fills and adjusts text to both margins.
4104 Filling can be disabled via the @code{nf} request and re-enabled with
4105 the @code{fi} request.
4111 Activate fill mode (which is the default). This request implicitly
4112 enables adjusting; it also inserts a break in the text currently being
4113 filled. The read-only number register @code{.u} is set to@w{ }1.
4115 The fill mode status is associated with the current environment
4116 (@pxref{Environments}).
4119 @cindex no-fill mode
4120 @cindex mode, no-fill
4122 Activate no-fill mode. Input lines are output as-is, retaining line
4123 breaks and ignoring the current line length. This command implicitly
4124 disables adjusting; it also causes a break. The number register
4125 @code{.u} is set to@w{ }0.
4127 The fill mode status is associated with the current environment
4128 (@pxref{Environments}).
4131 @Defreq {ad, [@Var{mode}]}
4135 Activation and deactivation of adjusting is done implicitly with
4136 calls to the @code{fi} or @code{nf} requests.
4138 @var{mode} can have one of the following values:
4142 @cindex ragged-right
4143 Adjust text to the left margin. This produces what is traditionally
4144 called ragged-right text.
4148 Adjust text to the right margin, producing ragged-left text.
4151 @cindex centered text
4153 Center filled text. This is different to the @code{ce} request which
4154 only centers text without filling.
4158 Justify to both margins. This is the default used by @code{gtroff}.
4161 With no argument, @code{gtroff} adjusts lines in the same way it did
4162 before adjusting was deactivated (with a call to @code{na}, for
4173 .ad \" back to centering
4177 @cindex current adjustment mode register
4178 The current adjustment mode is available in the read-only number
4179 register @code{.j}; it can be stored and subsequently used to set
4182 The adjustment mode status is associated with the current environment
4183 (@pxref{Environments}).
4187 Disable adjusting. This request won't change the current adjustment
4188 mode: A subsequent call to @code{ad} uses the previous adjustment
4191 The adjustment mode status is associated with the current environment
4192 (@pxref{Environments}).
4196 Adjust the current line and cause a break.
4198 In most cases this produces very ugly results, since @code{gtroff}
4199 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
4200 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
4204 This is an uninteresting sentence.
4205 This is an uninteresting sentence.\p
4206 This is an uninteresting sentence.
4213 This is an uninteresting sentence. This is an
4214 uninteresting sentence.
4215 This is an uninteresting sentence.
4219 @cindex word space size
4220 @cindex size of word space
4221 @cindex space between words
4222 @cindex sentence space size
4223 @cindex size of sentence space
4224 @cindex space between sentences
4225 @Defreq {ss, word_space_size [@Var{sentence_space_size}]}
4228 Change the minimum size of a space between filled words. It takes its
4229 units as one twelfth of the space width parameter for the current
4230 font. Initially both the @var{word_space_size} and
4231 @var{sentence_space_size} are@w{ }12.
4235 If two arguments are given to the @code{ss} request, the second
4236 argument sets the sentence space size. If the second argument is not
4237 given, sentence space size is set to @var{word_space_size}. The
4238 sentence space size is used in two circumstances: If the end of a
4239 sentence occurs at the end of a line in fill mode, then both an
4240 inter-word space and a sentence space are added; if two spaces follow
4241 the end of a sentence in the middle of a line, then the second space
4242 is a sentence space. If a second argument is never given to the
4243 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
4244 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
4245 in @acronym{UNIX} @code{troff}, a sentence should always be followed
4246 by either a newline or two spaces.
4248 The read-only number registers @code{.ss} and @code{.sss} hold the
4249 values of the parameters set by the first and second arguments of the
4252 The word space and sentence space values are associated with the current
4253 environment (@pxref{Environments}).
4255 Contrary to traditional Unix @code{troff}, this request is @emph{not}
4256 ignored if a tty output device is used; the given values are then
4257 rounded down to a multiple of@w{ }12.
4259 @c XXX xref implementation differences
4261 The request is ignored if there is no parameter.
4264 @cindex centering lines
4265 @cindex lines, centering
4266 @Defreq {ce, [@Var{nnn}]}
4268 Center text. While the @w{@samp{.ad c}} request also centers text,
4269 it fills the text as well. @code{ce} does not fill the
4270 text it affects. This request causes a break.
4272 The following example demonstrates the differences.
4278 This is a small text fragment which shows the differences
4279 between the `.ce' and the `.ad c' request.
4283 This is a small text fragment which shows the differences
4284 between the `.ce' and the `.ad c' request.
4288 And here the result:
4291 This is a small text fragment which
4292 shows the differences
4293 between the `.ce' and the `.ad c' request.
4295 This is a small text fragment which
4296 shows the differences between the `.ce'
4297 and the `.ad c' request.
4300 With no arguments, @code{ce} centers the next line of text. @var{nnn}
4301 specifies the number of lines to be centered. If the argument is zero
4302 or negative, centering is disabled.
4307 The basic length for centering text is the line length (as set with the
4308 @code{ll} request) minus the indentation (as set with the @code{in}
4309 request). Temporary indentation is ignored.
4311 As can be seen in the previous example, it is a common idiom to turn
4312 on centering for a large number of lines, and to turn off centering
4313 after text to be centered. This is useful for any request which takes
4314 a number of lines as an argument.
4316 The @code{.ce} read-only number register contains the number of lines
4317 remaining to be centered, as set by the @code{ce} request.
4320 @cindex justifying text
4321 @cindex text, justifying
4322 @cindex right-justifying
4323 @Defreq {rj, [@Var{nnn}]}
4325 Justify unfilled text to the right margin. Arguments are identical to
4326 the @code{ce} request. The @code{.rj} read-only number register is
4327 the number of lines to be right-justified as set by the @code{rj}
4328 request. This request causes a break.
4332 @c =====================================================================
4334 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
4335 @section Manipulating Hyphenation
4336 @cindex manipulating hyphenation
4337 @cindex hyphenation, manipulating
4339 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
4340 There are a number of ways to influence hyphenation.
4342 @Defreq {hy, [@Var{mode}]}
4344 Enable hyphenation. The request has an optional numeric argument,
4345 @var{mode}, to restrict hyphenation if necessary:
4349 The default argument if @var{mode} is omitted. Hyphenate without
4350 restrictions. This is also the start-up value of @code{gtroff}.
4353 Do not hyphenate the last word on a page or column.
4356 Do not hyphenate the last two characters of a word.
4359 Do not hyphenate the first two characters of a word.
4362 Values in the previous table are additive. For example, the value@w{
4363 }12 causes @code{gtroff} to neither hyphenate the last two nor the first
4364 two characters of a word.
4366 @cindex hyphenation restrictions register
4367 The current hyphenation restrictions can be found in the read-only
4368 number register @samp{.hy}.
4370 The hyphenation mode is associated with the current environment
4371 (@pxref{Environments}).
4375 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
4376 that the hyphenation mode of the last call to @code{hy} is not
4379 The hyphenation mode is associated with the current environment
4380 (@pxref{Environments}).
4384 @cindex explicit hyphens
4385 @cindex hyphen, explicit
4386 @cindex consecutive hyphenated lines
4387 @cindex lines, consecutive hyphenated
4388 @cindex hyphenated lines, consecutive
4389 @Defreq {hlm, [@Var{nnn}]}
4392 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
4393 If this number is negative, there is no maximum. The default value
4394 is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated
4395 with the current environment (@pxref{Environments}). Only lines
4396 output from a given environment count towards the maximum associated
4397 with that environment. Hyphens resulting from @code{\%} are counted;
4398 explicit hyphens are not.
4400 The current setting of @code{hlm} is available in the @code{.hlm}
4401 read-only number register. Also the number of immediately preceding
4402 consecutive hyphenated lines are available in the read-only number
4403 register @samp{.hlc}.
4406 @Defreq {hw, word1 word2 @dots{}}
4407 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
4408 words must be given with hyphens at the hyphenation points. For
4416 Besides the space character, any character whose hyphenation code value
4417 is zero can be used to separate the arguments of @code{hw} (see the
4418 documentation for the @code{hcode} request below for more information).
4419 In addition, this request can be used more than once.
4421 Hyphenation exceptions specified with the @code{hw} request are
4422 associated with the current hyphenation language; it causes an error
4423 if there is no current hyphenation language.
4425 This request is ignored if there is no parameter.
4427 In old versions of @code{troff} there was a limited amount of space to
4428 store such information; fortunately, with @code{gtroff}, this is no
4429 longer a restriction.
4432 @cindex hyphenation character
4433 @cindex character, hyphenation
4434 @cindex disabling hyphenation
4435 @cindex hyphenation, disabling
4437 To tell @code{gtroff} how to hyphenate words on the fly, use the
4438 @code{\%} escape, also known as the @dfn{hyphenation character}.
4439 Preceding a word with this character prevents it from being
4440 hyphenated; putting it inside a word indicates to @code{gtroff} that
4441 the word may be hyphenated at that point. Note that this mechanism
4442 only affects that one occurrence of the word; to change the
4443 hyphenation of a word for the entire document, use the @code{hw}
4447 @Defreq {hc, [@Var{char}]}
4448 Change the hyphenation character to @var{char}. This character then
4449 works the same as the @code{\%} escape, and thus, no longer appears in
4450 the output. Without an argument, @code{hc} resets the hyphenation
4451 character to be @code{\%} (the default) only.
4453 The hyphenation character is associated with the current environment
4454 (@pxref{Environments}).
4457 @cindex hyphenation patterns
4458 @cindex patterns for hyphenation
4459 @Defreq {hpf, pattern_file}
4460 Read in a file of hyphenation patterns. This file is searched for in
4461 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
4462 searched for if the @option{-m@var{name}} option is specified.
4464 It should have the same format as the argument to the @code{\patterns}
4465 primitive in @TeX{} (without using @TeX{}'s macro expansion); the
4466 letters appearing in this file are interpreted as hyphenation codes. A
4467 @samp{%} character in the patterns file introduces a comment that
4468 continues to the end of the line.
4470 If no @code{hpf} request is specified (either in the document or in a
4471 macro package), @code{gtroff} won't hyphenate at all.
4477 The set of hyphenation patterns is associated with the current language
4478 set by the @code{hla} request. The @code{hpf} request is usually
4479 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
4480 @file{troffrc} loads hyphenation patterns for American English (in file
4483 Invoking @code{hpf} causes an error if there is no current hyphenation
4487 @cindex hyphenation code
4488 @cindex code, hyphenation
4489 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
4490 Set the hyphenation code of character @var{c1} to @var{code1}, that of
4491 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
4492 input character (not a special character) other than a digit or a
4493 space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
4494 hyphenation set to itself, and each upper-case letter
4495 (@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
4498 This request is ignored if it has no parameter.
4501 @cindex hyphenation margin
4502 @cindex margin for hyphenation
4504 @Defreq {hym, [@Var{length}]}
4506 Set the (right) hyphenation margin to @var{length}. If the current
4507 adjustment mode is not @samp{b} or@w{ }@samp{n}, the line is not
4508 hyphenated if it is shorter than @var{length}. Without an argument,
4509 the hyphenation margin is reset to its default value, which is@w{ }0.
4510 The default scaling indicator for this request is@w{ }@code{m}. The
4511 hyphenation margin is associated with the current environment
4512 (@pxref{Environments}).
4514 A negative argument resets the hyphenation margin to zero, emitting
4515 a warning of type @samp{range}.
4517 @cindex current hyphenation margin register
4518 The current hyphenation margin is available in the @code{.hym} read-only
4522 @cindex hyphenation space
4524 @Defreq {hys, [@Var{hyphenation_space}]}
4526 Set the hyphenation space to @var{hyphenation_space}. If the current
4527 adjustment mode is @samp{b} or@w{ }@samp{n}, don't hyphenate the line
4528 if it can be justified by adding no more than @var{hyphenation_space}
4529 extra space to each word space. Without argument, the hyphenation
4530 space is set to its default value, which is@w{ }0. The default
4531 scaling indicator for this request is@w{ }@code{m}. The hyphenation
4532 space is associated with the current environment
4533 (@pxref{Environments}).
4535 A negative argument resets the hyphenation space to zero, emitting a
4536 warning of type @samp{range}.
4538 @cindex current hyphenation space register
4539 The current hyphenation space is available in the @code{.hys} read-only
4543 @cindex soft hyphen character
4544 @cindex character, soft hyphen
4548 @Defreq {shc, [@Var{char}]}
4549 Set the soft hyphen character to @var{char}. If the argument is
4550 omitted, the soft hyphen character is set to the default character
4551 @code{\(hy} (this is the start-up value of @code{gtroff} also). The
4552 soft hyphen character is the character that is inserted when a word is
4553 hyphenated at a line break. If the soft hyphen character does not
4554 exist in the font of the character immediately preceding a potential
4555 break point, then the line is not broken at that point. Neither
4556 definitions (specified with the @code{char} request) nor translations
4557 (specified with the @code{tr} request) are considered when finding the
4558 soft hyphen character.
4565 @Defreq {hla, language}
4567 Set the current hyphenation language to the string @var{language}.
4568 Hyphenation exceptions specified with the @code{hw} request and
4569 hyphenation patterns specified with the @code{hpf} request are both
4570 associated with the current hyphenation language. The @code{hla}
4571 request is usually invoked by the @file{troffrc} or the
4572 @file{troffrc-end} files; @file{troffrc} sets the default language to
4575 @cindex current hyphenation language register
4576 The current hyphenation language is available as a string in the
4577 read-only number register @samp{.hla}.
4580 .ds curr_language \n[.hla]
4587 @c =====================================================================
4589 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
4590 @section Manipulating Spacing
4591 @cindex manipulating spacing
4592 @cindex spacing, manipulating
4594 @Defreq {sp, [@Var{distance}]}
4595 Space downwards @var{distance}. With no argument it advances 1@w{
4596 }line. A negative argument causes @code{gtroff} to move up the page
4597 the specified distance. If the argument is preceded by a @samp{|}
4598 then @code{gtroff} moves that distance from the top of the page. This
4599 request causes a line break. The default scaling indicator is@w{
4603 @cindex double-spacing
4604 @Defreq {ls, [@Var{nnn}]}
4606 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
4607 With no argument, @code{gtroff} uses the previous value before the
4608 last @code{ls} call.
4611 .ls 2 \" This causes double-spaced output
4612 .ls 3 \" This causes triple-spaced output
4613 .ls \" Again double spaced
4616 The line spacing is associated with the current environment
4617 (@pxref{Environments}).
4619 @cindex current line spacing register
4620 The read-only number register @code{.L} contains the current line
4624 @c XXX document \n[nl]
4625 @c XXX document \n[nl] == -1 if vertical position is zero
4627 @Defesc {\\x, ', spacing, '}
4629 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
4630 to allow space for a tall construct (like an equation). The @code{\x}
4631 escape does this. The escape is given a numerical argument, usually
4632 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
4633 is@w{ }@code{v}. If this number is positive extra vertical space is
4634 inserted below the current line. A negative number adds space above.
4635 If this escape is used multiple times on the same line, the maximum of
4638 @xref{Escapes}, for details on parameter delimiting characters.
4640 @cindex extra vertical line space register
4641 The @code{.a} read-only number register contains the most recent
4642 (nonnegative) extra vertical line space.
4647 ... example of inline equation ...
4653 @cindex no-space mode
4654 @cindex mode, no-space
4655 @cindex blank lines, disabling
4656 @cindex lines, blank, disabling
4659 Enable @dfn{no-space mode}. In this mode, spacing (either via
4660 @code{sp} or via blank lines) is disabled. The @code{bp} request to
4661 advance to the next page is also disabled, except if it is accompanied
4662 by a page number (see @ref{Page Control}, for more information). This
4663 mode ends when actual text is output or the @code{rs} request is
4664 encountered. The read-only number register @code{.ns} is set to@w{ }1.
4666 This request is useful for macros which want to avoid that subsequent
4667 macros inadvertently insert some vertical space before the text starts
4668 (for example, to set up the first paragraph after a section header).
4674 Disable no-space mode.
4680 @c =====================================================================
4682 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
4683 @section Tabs and Fields
4684 @cindex tabs and fields
4685 @cindex fields and tabs
4687 @cindex @acronym{EBCDIC} encoding of a tab
4688 A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
4689 }5) causes a horizontal movement to the next tab stop (much
4690 like it did on a typewriter).
4693 This escape is a non-interpreted tab character. In copy mode
4694 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
4697 @Defreq {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
4699 Change tab stop positions. This request takes a series of tab
4700 specifiers as arguments (optionally divided into two groups with the
4701 letter @samp{T}) which indicate where each tab stop is to be
4702 (overriding any previous settings).
4704 Tab stops can be specified absolutely, i.e., as the distance from the
4705 left margin. For example, the following sets 6@w{ }tab stops every
4709 .ta 1i 2i 3i 4i 5i 6i
4712 Tab stops can also be specified using a leading @samp{+}
4713 which means that the specified tab stop is set relative to
4714 the previous tab stop. For example, the following is equivalent to the
4718 .ta 1i +1i +1i +1i +1i +1i
4721 @code{gtroff} supports an extended syntax to specify repeat values after
4722 the @samp{T} mark (these values are always taken as relative) -- this is
4723 the usual way to specify tabs set at equal intervals. The following is,
4724 yet again, the same as the previous examples. It does even more since
4725 it defines an infinite number of tab stops separated by one inch.
4731 Now we are ready to interpret the full syntax given at the beginning:
4732 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
4733 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
4734 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
4735 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
4737 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
4738 20c 23c 28c 30c @dots{}}.
4740 The material in each tab column (i.e., the column between two tab stops)
4741 may be justified to the right or left or centered in the column. This
4742 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
4743 specifier. The default justification is @samp{L}. Example:
4753 The default unit of the @code{ta} request is @samp{m}.
4756 A tab stop is converted into a non-breakable horizontal movement which
4757 can be neither stretched nor squeezed. For example,
4766 creates a single line which is a bit longer than 10@w{ }inches (a string
4767 is used to show exactly where the tab characters are). Now consider the
4777 @code{gtroff} first converts the tab stops of the line into unbreakable
4778 horizontal movements, then splits the line after the second @samp{b}
4779 (assuming a sufficiently short line length). Usually, this isn't what
4783 Superfluous tabs (i.e., tab characters which do not correspond to a tab
4784 stop) are ignored except the first one which delimits the characters
4785 belonging to the last tab stop for right-justifying or centering.
4786 Consider the following example
4790 .ds ZZ foo\tbar\tfoobar
4791 .ds ZZZ foo\tbar\tfoo\tbar
4802 which produces the following output:
4811 The first line right-justifies the second `foo' relative to the tab
4812 stop. The second line right-justifies `foobar'. The third line finally
4813 right-justifies only `foo' because of the additional tab character which
4814 marks the end of the string belonging to the last defined tab stop.
4817 Tab stops are associated with the current environment
4818 (@pxref{Environments}).
4821 Calling @code{ta} without an argument removes all tab stops.
4824 @cindex tab stops, for tty output devices
4825 The start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. This value
4826 is used even for tty output devices (contrary to @acronym{UNIX}
4827 @code{nroff} which has tab stops preset every 0.8@dmn{i}).
4829 @c XXX xref implementation differences
4832 @cindex current tab settings register
4833 The read-only number register @code{.tabs} contains a string
4834 representation of the current tab settings suitable for use as an
4835 argument to the @code{ta} request.
4838 .ds tab-string \n[.tabs]
4844 @cindex tab repetition character
4845 @cindex character, tab repetition
4846 @Defreq {tc, [@Var{fill-char}]}
4847 Normally @code{gtroff} fills the space to the next tab stop with
4848 whitespace. This can be changed with the @code{tc} request. With no
4849 argument @code{gtroff} reverts to using whitespace, which is the
4850 default. The value of this @dfn{tab repetition} character is
4851 associated with the current environment (@pxref{Environments}).
4859 @c ---------------------------------------------------------------------
4861 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
4865 Sometimes it may may be desirable to use the @code{tc} request to fill a
4866 particular tab stop with a given character (for example dots in a table
4867 of contents), but also normal tab stops on the rest of the line. For
4868 this @code{gtroff} provides an alternate tab mechanism, called
4869 @dfn{leaders} which does just that.
4871 @cindex leader character
4872 A leader character (character code@w{ }1) behaves similarly to a tab
4873 character: It moves to the next tab stop. The only difference is that
4874 for this movement, the fill character defaults to a period character and
4878 This escape is a non-interpreted leader character. In copy mode
4879 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
4883 @cindex leader repetition character
4884 @cindex character, leader repetition
4885 @Defreq {lc, [@Var{fill-char}]}
4886 Declare the leader character. Without an argument, leaders act the
4887 same as tabs (i.e., using whitespace for filling). @code{gtroff}'s
4888 start-up value is @samp{.}. The value of this @dfn{leader repetition}
4889 character is associated with the current environment
4890 (@pxref{Environments}).
4893 @cindex table of contents
4894 @cindex contents, table of
4895 For a table of contents, to name an example, tab stops may be defined so
4896 that the section number is one tab stop, the title is the second with
4897 the remaining space being filled with a line of dots, and then the page
4898 number slightly separated from the dots.
4901 .ds entry 1.1\tFoo\a\t12
4911 1.1 Foo.......................................... 12
4914 @c ---------------------------------------------------------------------
4916 @node Fields, , Leaders, Tabs and Fields
4920 @cindex field delimiting character
4921 @cindex delimiting character for fields
4922 @cindex character, field delimiting
4923 @cindex field padding character
4924 @cindex padding character for fields
4925 @cindex character, field padding
4926 @dfn{Fields} are a more general way of laying out tabular data. A field
4927 is defined as the data between a pair of @dfn{delimiting characters}.
4928 It contains substrings which are separated by @dfn{padding characters}.
4929 The width of a field is the distance on the @emph{input} line from the
4930 position where the field starts to the next tab stop. A padding
4931 character inserts stretchable space similar to @TeX{}'s @code{\hss}
4932 command (thus it can even be negative) to make the sum of all substring
4933 lengths plus the stretchable space equal to the field width. If more
4934 than one padding character is inserted, the available space is evenly
4935 distributed among them.
4937 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
4938 Define a delimiting and a padding character for fields. If the latter
4939 is missing, the padding character defaults to a space character. If
4940 there is no argument at all, the field mechanism is disabled (which is
4941 the default). Note that contrary to e.g.@: the tab repetition
4942 character, delimiting and padding characters are not associated to the
4943 current environment (@pxref{Environments}).
4956 and here the result:
4965 @c =====================================================================
4967 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
4968 @section Character Translations
4969 @cindex character translations
4970 @cindex translations of characters
4974 @cindex control character
4975 @cindex character, control
4976 @cindex no-break control character
4977 @cindex character, no-break control
4978 @cindex control character, no-break
4979 The control character (@samp{.}) and the no-break control character
4980 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
4983 @Defreq {cc, [@Var{c}]}
4984 Set the control character to @var{c}. With no argument the default
4985 control character @samp{.} is restored. The value of the control
4986 character is associated with the current environment
4987 (@pxref{Environments}).
4990 @Defreq {c2, [@Var{c}]}
4991 Set the no-break control character to @var{c}. With no argument the
4992 default control character @samp{'} is restored. The value of the
4993 no-break control character is associated with the current environment
4994 (@pxref{Environments}).
4999 Disable the escape mechanism completely. After executing this
5000 request, the backslash character @samp{\} no longer starts an escape
5003 This request can be very helpful in writing macros since it is not
5004 necessary then to double the escape character. Here an example:
5007 .\" This is a simplified version of the
5008 .\" .BR request from the man macro package
5012 . while (\n[.$] >= 2) \@{\
5013 . as result \fB\$1\fR\$2
5016 . if \n[.$] .as result \fB\$1
5024 @cindex escape character
5025 @cindex character, escape
5026 @Defreq {ec, [@Var{c}]}
5027 Set the escape character to @var{c}. With no argument the default
5028 escape character @samp{\} is restored. It can be also used to
5029 re-enable the escape mechanism after an @code{eo} request.
5031 Note that changing the escape character globally will likely break
5032 macro packages since @code{gtroff} has no mechanism (like @TeX{}) to
5033 `intern' macros, i.e., to convert a macro definition into an internal
5034 form which is independent of its representation. If a macro is
5035 called, it is executed literally.
5039 This escape sequence prints the current escape character (which is the
5040 backslash character @samp{\} by default).
5043 A @dfn{translation} is a mapping of an input character to an output
5044 character. The default mappings are given in the font definition files
5045 for the specific output device (@pxref{Font Files}); all mappings (both
5046 with @code{tr} and in the font definition files) occur at output time,
5047 i.e., the input character gets assigned the metric information of the
5048 mapped output character.
5050 @Defreq {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
5051 Translate character @var{a} to @var{b}, character @var{c} to @var{d},
5052 etc. If there is an odd number of arguments, the last one is
5053 translated to the space character.
5068 @cindex special character
5069 @cindex character, special
5070 @cindex numbered character
5071 @cindex character, numbered
5072 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
5073 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
5074 characters defined with the @code{char} request, and numbered characters
5075 (@code{\N'@var{xxx}'}) can be translated also.
5079 The @code{\e} escape can be translated also.
5084 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
5085 @code{\%} and @code{\~} can't be mapped onto another character).
5088 @cindex backspace character
5089 @cindex character, backspace
5090 @cindex leader character
5091 @cindex character, leader
5092 @cindex newline character
5093 @cindex character, newline
5094 @cindex tab character
5095 @cindex character, tab
5098 The following characters can't be translated: space (with one exception,
5099 see below), backspace, newline, leader (and @code{\a}), tab (and
5104 Translations are not considered for finding the soft hyphen character
5105 set with the @code{shc} request.
5109 The character pair @samp{@var{c}\&} (this is an arbitrary character@w{
5110 }@var{c} followed by the zero width space character) maps this
5111 character to nothing.
5120 It is even possible to map the space character to nothing:
5129 As shown in the example, the space character can't be the first
5130 character pair as an argument of @code{tr}. Additionally, it is not
5131 possible to map the space character to any other character; requests
5132 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
5134 If justification is active, lines are justified in spite of the
5135 `empty' space character (but there is no minimal distance, i.e.@: the
5136 space character, between words).
5139 After an output character has been constructed (this happens at the
5140 moment immediately before the character is appended to an output
5141 character list, either by direct output, in a macro, diversion, or
5142 string), it is no longer affected by @code{tr}.
5147 Without an argument, the @code{tr} request is ignored.
5152 @cindex @code{\!}, and @code{trnt}
5153 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
5154 @code{trnt} is the same as the @code{tr} request except that the
5155 translations do not apply to text that is transparently throughput
5156 into a diversion with @code{\!}. @xref{Diversions}, for more
5170 prints @samp{b} to the standard error stream; if @code{trnt} is used
5171 instead of @code{tr} it prints @samp{a}.
5175 @c =====================================================================
5177 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
5178 @section Troff and Nroff Mode
5184 Originally, @code{nroff} and @code{troff} were two separate programs,
5185 the former for tty output, the latter for everything else. With GNU
5186 @code{troff}, both programs are merged into one executable, sending
5187 its output to a device driver (@code{grotty} for tty devices,
5188 @code{grops} for @sc{PostScript}, etc.) which interprets the
5189 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
5190 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
5191 since the differences are hardcoded. For GNU @code{troff}, this
5192 distinction is not appropriate because @code{gtroff} simply takes the
5193 information given in the font files for a particular device without
5194 handling requests specially if a tty output device is used.
5196 Usually, a macro package can be used with all output devices.
5197 Nevertheless, it is sometimes necessary to make a distinction between
5198 tty and non-tty devices: @code{gtroff} provides two built-in
5199 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
5200 @code{while} requests to decide whether @code{gtroff} shall behave
5201 like @code{nroff} or like @code{troff}.
5206 Make the @samp{t} built-in condition true (and the @samp{n} built-in
5207 condition false) for @code{if}, @code{ie}, and @code{while}
5208 conditional requests. This is the default if @code{gtroff}
5209 (@emph{not} @code{groff}) is started with the @option{-R} switch to
5210 avoid loading of the start-up files @file{troffrc} and
5211 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
5212 mode if the output device is not a tty (e.g.@: `ps').
5217 Make the @samp{n} built-in condition true (and the @samp{t} built-in
5218 condition false) for @code{if}, @code{ie}, and @code{while}
5219 conditional requests. This is the default if @code{gtroff} uses a tty
5220 output device; the code for switching to nroff mode is in the file
5221 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
5224 @xref{Conditionals and Loops}, for more details on built-in
5227 @c XXX move the following to grotty section
5231 @cindex ISO 6249 SGR
5232 @cindex terminal control sequences
5233 @cindex control sequences, for terminals
5234 For tty output devices, underlining is done by emitting sequences of
5235 @samp{_} and @samp{\b} (the backspace character) before the actual
5236 character. Literally, this is printing an underline character, then
5237 moving back one character position, and printing the actual character
5238 at the same position as the underline character (similar to a
5239 typewriter). Usually, a modern terminal can't interpret this (and the
5240 original Teletype machines for which this sequence was appropriate are
5241 no longer in use). You need a pager program like @code{less} which
5242 translates this into ISO 6429 SGR sequences to control terminals.
5244 @c =====================================================================
5246 @node Line Layout, Page Layout, Troff and Nroff Mode, gtroff Reference
5247 @section Line Layout
5249 @cindex layout, line
5251 @cindex dimensions, line
5252 @cindex line dimensions
5253 The following drawing shows the dimensions which @code{gtroff} uses for
5254 placing a line of output onto the page. They are labeled with the
5255 request which manipulates each dimension.
5259 |<-----------ll------------>|
5260 +----+----+----------------------+----+
5262 +----+----+----------------------+----+
5264 |<--------paper width---------------->|
5268 These dimensions are:
5273 @cindex margin, left
5275 @cindex offset, page
5276 @dfn{Page offset} -- this is the leftmost position of text on the final
5277 output, defining the @dfn{left margin}.
5281 @cindex line indentation
5282 @dfn{Indentation} -- this is the distance from the left margin where
5287 @cindex length of line
5288 @dfn{Line length} -- this is the distance from the left margin to right
5292 @c XXX improve example
5297 A bunch of really boring text which should
5298 be indented from both margins.
5299 Replace me with a better (and more) example!
5305 @Defreq {po, [@Var{offset}]}
5306 @Defreqx {po, @t{+}@Var{offset}}
5307 @Defreqx {po, @t{-}@Var{offset}}
5309 Set horizontal page offset to @var{offset} (or increment or decrement
5310 the current value by @var{offset}). Note that this request does not
5311 cause a break, so changing the page offset in the middle of text being
5312 filled may not yield the expected result. The initial value is
5313 1@dmn{i}. For tty output devices, it is set to 0 in the startup file
5314 @file{troffrc}; the default scaling indicator is@w{ }@code{m} (and
5315 not@w{ }@code{v} as incorrectly documented in the original
5316 @acronym{UNIX} troff manual).
5318 The current page offset can be found in the read-only number register
5321 If @code{po} is called without an argument, the page offset is reset to
5322 the previous value before the last call to @code{po}.
5337 @Defreq {in, [@Var{indent}]}
5338 @Defreqx {in, @t{+}@Var{indent}}
5339 @Defreqx {in, @t{-}@Var{indent}}
5341 Set indentation to @var{indent} (or increment or decrement the
5342 current value by @var{indent}). This request causes a break.
5343 Initially, there is no indentation.
5345 If @code{in} is called without an argument, the indentation is reset to
5346 the previous value before the last call to @code{in}. The default
5347 scaling indicator is@w{ }@code{m}.
5349 The indentation is associated with the current environment.
5351 If a negative indentation value is specified (which is not allowed),
5352 @code{gtroff} emits a warning of type @samp{range} and sets the
5353 indentation to zero.
5355 The effect of @code{in} is delayed until a partially collected line (if
5356 it exists) is output. A temporary indent value is reset to zero also.
5358 The current indentation (as set by @code{in}) can be found in the
5359 read-only number register @samp{.i}.
5362 @Defreq {ti, offset}
5363 @Defreqx {ti, @t{+}@Var{offset}}
5364 @Defreqx {ti, @t{-}@Var{offset}}
5366 Temporarily indent the next output line by @var{offset}. If an
5367 increment or decrement value is specified, adjust the temporary
5368 indentation relative to the value set by the @code{in} request.
5370 This request causes a break; its value is associated with the current
5371 environment. The default scaling indicator is@w{ }@code{m}. A call
5372 of @code{ti} without an argument is ignored.
5374 If the total indentation value is negative (which is not allowed),
5375 @code{gtroff} emits a warning of type @samp{range} and sets the
5376 temporary indentation to zero. `Total indentation' is either
5377 @var{offset} if specified as an absolute value, or the temporary plus
5378 normal indentation, if @var{offset} is given as a relative value.
5380 The effect of @code{ti} is delayed until a partially collected line (if
5381 it exists) is output.
5383 The read-only number register @code{.in} is the indentation that applies
5384 to the current output line.
5386 The difference between @code{.i} and @code{.in} is that the latter takes
5387 into account whether a partially collected line still uses the old
5388 indentation value or a temporary indentation value is active.
5391 @Defreq {ll, [@Var{length}]}
5392 @Defreqx {ll, @t{+}@Var{length}}
5393 @Defreqx {ll, @t{-}@Var{length}}
5396 Set the line length to @var{length} (or increment or decrement the
5397 current value by @var{length}). Initially, the line length is set to
5398 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
5399 collected line (if it exists) is output. The default scaling
5400 indicator is@w{ }@code{m}.
5402 If @code{ll} is called without an argument, the line length is reset to
5403 the previous value before the last call to @code{ll}. If a negative
5404 line length is specified (which is not allowed), @code{gtroff} emits a
5405 warning of type @samp{range} and sets the line length to zero.
5407 The line length is associated with the current environment.
5409 @cindex current line length register
5410 The current line length (as set by @code{ll}) can be found in the
5411 read-only number register @samp{.l}. The read-only number register
5412 @code{.ll} is the line length that applies to the current output line.
5414 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
5415 and @code{.ll} is that the latter takes into account whether a partially
5416 collected line still uses the old line length value.
5420 @c =====================================================================
5422 @node Page Layout, Page Control, Line Layout, gtroff Reference
5423 @section Page Layout
5425 @cindex layout, page
5427 @code{gtroff} provides some very primitive operations for controlling
5431 @cindex length of page
5432 @Defreq {pl, [@Var{length}]}
5433 @Defreqx {pl, @t{+}@Var{length}}
5434 @Defreqx {pl, @t{-}@Var{length}}
5436 Set the @dfn{page length} to @var{length} (or increment or decrement
5437 the current value by @var{length}). This is the length of the
5438 physical output page. The default scaling indicator is@w{ }@code{v}.
5440 @cindex current page length register
5441 The current setting can be found in the read-only number register
5446 @cindex bottom margin
5447 @cindex margin, bottom
5448 Note that this only specifies the size of the page, not the top and
5449 bottom margins. Those are not set by @code{gtroff} directly.
5450 @xref{Traps}, for further information on how to do this.
5452 Negative @code{pl} values are possible also, but not very useful: No
5453 trap is sprung, and each line is output on a single page (thus
5454 suppressing all vertical spacing).
5456 If no argument or an invalid argument is given, @code{pl} sets the page
5457 length to 11@dmn{i}.
5463 @code{gtroff} provides several operations which help in setting up top
5464 and bottom titles (or headers and footers).
5467 @cindex three-part title
5468 @cindex page number character
5469 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
5470 Print a @dfn{title line}. It consists of three parts: a left
5471 justified portion, a centered portion, and a right justified portion.
5472 The argument separator @samp{'} can be replaced with any character not
5473 occurring in the title line. The @samp{%} character is replaced with
5474 the current page number. This character can be changed with the
5475 @code{pc} request (see below).
5477 Without argument, @code{tl} is ignored.
5483 A title line is not restricted to the top or bottom of a page.
5486 @code{tl} prints the title line immediately, ignoring a partially filled
5487 line (which stays untouched).
5490 It is not an error to omit closing delimiters. For example,
5491 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
5492 title line with the left justified word @samp{foo}; the centered and
5493 right justfied parts are empty.
5496 Any modifications to the current environment within @code{tl} (e.g.@:
5497 changing the font or font size) are undone after processing @code{tl}.
5500 @code{tl} accepts the same parameter delimiting characters as the
5501 @code{\A} escape; see @ref{Escapes}.
5505 @cindex length of title line
5506 @cindex title line, length
5507 @cindex current title line length register
5508 @Defreq {lt, [@Var{length}]}
5509 @Defreqx {lt, @t{+}@Var{length}}
5510 @Defreqx {lt, @t{-}@Var{length}}
5512 The title line is printed using its own line length, which is
5513 specified (or incremented or decremented) with the @code{lt} request.
5514 Initially, the title line length is set to 6.5@dmn{i}. If a negative
5515 line length is specified (which is not allowed), @code{gtroff} emits a
5516 warning of type @samp{range} and sets the title line length to zero.
5517 The default scaling indicator is@w{ }@code{m}. If @code{lt} is called
5518 without an argument, the title length is reset to the previous value
5519 before the last call to @code{lt}.
5521 The current setting of this is available in the @code{.lt} read-only
5522 number register; it is associated with the current environment
5523 (@pxref{Environments}).
5528 @cindex number, page
5530 @Defreqx {pn, @t{+}@Var{page}}
5531 @Defreqx {pn, @t{-}@Var{page}}
5533 Change (increase or decrease) the page number of the @emph{next} page.
5534 The only argument is the page number; the request is ignored without a
5537 The read-only number register @code{.pn} contains the number of the next
5538 page: either the value set by a @code{pn} request, or the number of the
5539 current page plus@w{ }1.
5542 @cindex current page number register
5544 A read-write register holding the current page number.
5547 @cindex changing the page number character
5548 @cindex page number character, changing
5550 @Defreq {pc, [@Var{char}]}
5551 Change the page number character (used by the @code{tl} request) to a
5552 different character. With no argument, this mechanism is disabled.
5553 Note that this doesn't affect the number register @code{%}.
5559 @c =====================================================================
5561 @node Page Control, Fonts, Page Layout, gtroff Reference
5562 @section Page Control
5563 @cindex page control
5564 @cindex control, page
5568 @Defreq {bp, [@Var{page}]}
5569 @Defreqx {bp, @t{+}@Var{page}}
5570 @Defreqx {bp, @t{-}@Var{page}}
5571 Stop processing the current page and move to the next page. This
5572 request causes a break. It can also take an argument to set
5573 (increase, decrease) the page number of the next page. The only
5574 difference between @code{bp} and @code{pn} is that @code{pn} does not
5575 cause a break or actually eject a page.
5578 .de newpage \" define macro
5580 'sp .5i \" vertical space
5581 .tl 'left top'center top'right top' \" title
5582 'sp .3i \" vertical space
5586 @cindex top-level diversion
5587 @cindex diversion, top-level
5588 @code{bp} has no effect if not called within the top-level diversion
5589 (@pxref{Diversions}).
5593 @Defreq {ne, [@Var{space}]}
5594 It is often necessary to force a certain amount of space before a new
5595 page occurs. This is most useful to make sure that there is not a
5596 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
5597 request ensures that there is a certain distance, specified by the
5598 first argument, before the next page is triggered (see @ref{Traps},
5599 for further information). The default unit for @code{ne} is @samp{v};
5600 the default value of @var{space} is@w{ }1@dmn{v} if no argument is
5603 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
5604 do the following before each paragraph:
5614 @Defreq {sv, [@Var{space}]}
5615 @code{sv} is similar to the @code{ne} request; it reserves the
5616 specified amount of vertical space. If the desired amount of space
5617 exists before the next trap (bottom page boundary), the space is
5618 output immediately (ignoring a partial filled line which stays
5619 untouched). If there is not enough space, it is stored for later
5620 output via the @code{os} request. The default value is@w{ }1@dmn{v}
5621 if no argument is given; the default unit is @samp{v}.
5625 @c =====================================================================
5627 @node Fonts, Sizes, Page Control, gtroff Reference
5631 @code{gtroff} can switch fonts at any point in the text.
5633 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
5634 These are Times Roman, Italic, Bold, and Bold Italic. For non-tty
5635 devices, there is also at least one symbol font which contains various
5636 special symbols (Greek, mathematics).
5644 * Artificial Fonts::
5645 * Ligatures and Kerning::
5648 @c ---------------------------------------------------------------------
5650 @node Changing Fonts, Font Families, Fonts, Fonts
5651 @subsection Changing Fonts
5652 @cindex changing fonts
5653 @cindex fonts, changing
5660 @Defreq {ft, [@Var{font}]}
5661 @Defescx {\\f, , f, }
5662 @Defescx {\\f, @lparen{}, fn, }
5663 @Defescx {\\f, @lbrack{}, font, @rbrack}
5664 The @code{ft} request and the @code{\f} escape change the current font
5665 to @var{font} (one-character name @var{f}, two-character name
5668 If @var{font} is a style name (as set with the @code{sty} request or
5669 with the @code{styles} command in the @file{DESC} file), use it within
5670 the current font family (as set with the @code{fam} request or with
5671 the @code{family} command in the @file{DESC} file).
5673 @cindex previous font
5674 @cindex font, previous
5675 With no argument or using @samp{P} as an argument, @code{.ft} switches
5676 to the previous font. Use @code{\fP} or @code{\f[P]} to do this with
5679 Fonts are generally specified as upper-case strings, which are usually
5680 1@w{ }to 4 characters representing an abbreviation or acronym of the
5681 font name. This is no limitation, just a convention.
5683 The example below produces two identical lines.
5692 eggs, bacon, \fBspam\fP and sausage.
5695 @xref{Font Positions}, for an alternative syntax.
5708 @Defreq {ftr, f [@Var{g}]}
5709 Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named
5710 @var{f} is referred to in a @code{\f} escape sequence, or in the
5711 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
5712 @code{special}, @code{fspecial}, @code{fp}, or @code{code} requests,
5713 font@w{ }@var{g} is used. If @var{g} is missing or equal to @var{f}
5714 the translation is undone.
5717 @c ---------------------------------------------------------------------
5719 @node Font Families, Font Positions, Changing Fonts, Fonts
5720 @subsection Font Families
5721 @cindex font families
5722 @cindex families, font
5724 @cindex styles, font
5726 Due to the variety of fonts available, @code{gtroff} has added the
5727 concept of @dfn{font families} and @dfn{font styles}. The fonts are
5728 specified as the concatenation of the font family and style. Specifying
5729 a font without the family part causes @code{gtroff} to use that style of
5732 @cindex postscript fonts
5733 @cindex fonts, postscript
5734 Currently, only @sc{PostScript} fonts are set up to this mechanism.
5735 By default, @code{gtroff} uses the Times family with the four styles
5736 @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
5738 This way, it is possible to use the basic four fonts and to select a
5739 different font family on the command line (@pxref{Groff Options}).
5741 @Defreq {fam, [@Var{family}]}
5743 Switch font family to @var{family}. If no argument is given, switch
5744 back to the previous font family. The current font family is available
5745 in the read-only number register @samp{.fam} (this is a string-valued
5746 register); it is associated with the current environment.
5750 .fam H \" helvetica family
5751 spam, \" used font is family H + style R = HR
5752 .ft B \" family H + style B = font HB
5754 .fam T \" times family
5755 spam, \" used font is family T + style B = TB
5756 .ft AR \" font AR (not a style)
5758 .ft R \" family T + style R = font TR
5768 @Defreq {sty, n style}
5769 Associate @var{style} with font position@w{ }@var{n}. A font position
5770 can be associated either with a font or with a style. The current
5771 font is the index of a font position and so is also either a font or a
5772 style. When it is a style, the font that is actually used is the font
5773 the name of which is the concatenation of the name of the current
5774 family and the name of the current style. For example, if the current
5775 font is@w{ }1 and font position@w{ }1 is associated with style@w{
5776 }@samp{R} and the current font family is@w{ }@samp{T}, then font
5777 @samp{TR} will be used. If the current font is not a style, then the
5778 current family is ignored. When the requests @code{cs}, @code{bd},
5779 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, then
5780 they will instead be applied to the member of the current family
5781 corresponding to that style.
5783 @var{n} must be a non-negative integer value.
5787 The default family can be set with the @option{-f} option
5788 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
5789 file controls which font positions (if any) are initially associated
5790 with styles rather than fonts. For example, the default setting for
5791 @sc{PostScript} fonts
5807 @code{.fam} always checks whether the current font position is valid;
5808 this can give surprising results if the current font position is
5809 associated with a style.
5811 In the following example, we want to access the @sc{PostScript} font
5812 @code{FooBar} from the font family @code{Foo}:
5817 @result{} warning: can't find font `FooR'
5821 The default font position at start-up is@w{ }1; for the
5822 @sc{PostScript} device, this is associated with style @samp{R}, so
5823 @code{gtroff} tries to open @code{FooR}.
5825 A solution to this problem is to use a dummy font like the following:
5828 .fp 0 dummy TR \" set up dummy font at position 0
5829 .sty \n[.fp] Bar \" register style `Bar'
5830 .ft 0 \" switch to font at position 0
5831 .fam Foo \" activate family `Foo'
5832 .ft Bar \" switch to font `FooBar'
5835 @xref{Font Positions}.
5838 @c ---------------------------------------------------------------------
5840 @node Font Positions, Using Symbols, Font Families, Fonts
5841 @subsection Font Positions
5842 @cindex font positions
5843 @cindex positions, font
5845 For the sake of old phototypesetters and compatibility with old versions
5846 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
5847 on which various fonts are mounted.
5849 @Defreq {fp, pos font [@Var{external-name}]}
5852 Mount font @var{font} at position @var{pos} (which must be a
5853 non-negative integer). This numeric position can then be referred to
5854 with font changing commands. When @code{gtroff} starts it is using
5855 font position@w{ }1 (which must exist; position@w{ }0 is unused
5856 usually at start-up).
5858 @cindex current font position register
5859 The current font in use, as a font position, is available in the
5860 read-only number register @samp{.f}. This can be useful to remember the
5861 current font for later recall. It is associated with the current
5862 environment (@pxref{Environments}).
5865 .nr save-font \n[.f]
5867 ... text text text ...
5871 @cindex next free font position register
5872 The number of the next free font position is available in the read-only
5873 number register @samp{.fp}. This is useful when mounting a new font,
5877 .fp \n[.fp] NEATOFONT
5880 @pindex DESC@r{, and font mounting}
5881 Fonts not listed in the @file{DESC} file are automatically mounted on
5882 the next available font position when they are referenced. If a font
5883 is to be mounted explicitly with the @code{fp} request on an unused
5884 font position, it should be mounted on the first unused font position,
5885 which can be found in the @code{.fp} register. Although @code{gtroff}
5886 does not enforce this strictly, it is not allowed to mount a font at a
5887 position whose number is much greater (approx.@: 1000 positions) than
5888 that of any currently used position.
5890 The @code{fp} request has an optional third argument. This argument
5891 gives the external name of the font, which is used for finding the font
5892 description file. The second argument gives the internal name of the
5893 font which is used to refer to the font in @code{gtroff} after it has
5894 been mounted. If there is no third argument then the internal name is
5895 used as the external name. This feature makes it possible to use
5896 fonts with long names in compatibility mode.
5899 Both the @code{ft} request and the @code{\f} escape have alternative
5900 syntax forms to access font positions.
5908 @Defescx {\\f, , n, }
5909 @Defescx {\\f, @lparen{}, nn, }
5910 @Defescx {\\f, @lbrack{}, nnn, @rbrack}
5911 Change the current font position to @var{nnn} (one-digit position
5912 @var{n}, two-digit position @var{nn}), which must be a non-negative
5915 If @var{nnn} is associated with a style (as set with the @code{sty}
5916 request or with the @code{styles} command in the @file{DESC} file), use
5917 it within the current font family (as set with the @code{fam} request or
5918 with the @code{family} command in the @file{DESC} file).
5924 .ft \" switch back to font 1
5928 this is font 1 again
5931 @xref{Changing Fonts}, for the standard syntax form.
5934 @c ---------------------------------------------------------------------
5936 @node Using Symbols, Special Fonts, Font Positions, Fonts
5937 @subsection Using Symbols
5938 @cindex using symbols
5939 @cindex symbols, using
5944 A @dfn{glyph} is a graphical representation of a @dfn{character}.
5945 While a character is an abstract entity containing semantic
5946 information, a glyph is something which can be actually seen on screen
5947 or paper. It is possible that a character has multiple glyph
5948 representation forms (for example, the character `A' can be either
5949 written in a roman or an italic font, yielding two different glyphs);
5950 sometimes more than one character maps to a single glyph (this is a
5951 @dfn{ligature} -- the most common is `fi').
5955 Please note that currently the distinction between glyphs and
5956 characters in this reference is not clearly carried out. This will be
5957 improved eventually in the next revision.
5960 @cindex special fonts
5964 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
5965 glyph names of a particular font are defined in its font file. If the
5966 user requests a glyph not available in this font, @code{gtroff} looks
5967 up an ordered list of @dfn{special fonts}. By default, the
5968 @sc{PostScript} output device supports the two special fonts @samp{SS}
5969 (slanted symbols) and @samp{S} (symbols) (the former is looked up
5970 before the latter). Other output devices use different names for
5971 special fonts. Fonts mounted with the @code{fonts} keyword in the
5972 @file{DESC} file are globally available. To install additional
5973 special fonts locally (i.e.@: for a particular font), use the
5974 @code{fspecial} request.
5976 @xref{Font Files}, and @ref{Special Fonts}, for more details.
5978 @Defesc {\\, @lparen{}, nm, }
5979 @Defescx {\\, @lbrack{}, name, @rbrack}
5980 Insert a symbol @var{name} (two-character name @var{nm}). There is no
5981 special syntax for one-character names -- the natural form
5982 @samp{\@var{n}} would collide with escapes.
5984 If @var{name} is undefined, a warning of type @samp{char} is generated,
5985 and the escape is ignored. @xref{Debugging}, for information about
5988 The list of available symbols is device dependent; see @ref{Glyph Name
5989 Index} for some of them discussed in this reference.
5991 @c XXX list of common symbols
5994 @Defesc {\\C, ', xxx, '}
5995 Typeset the character named @var{xxx}. Normally it is more convenient
5996 to use @code{\[@var{xxx}]}, but @code{\C} has the advantage that it is
5997 compatible with newer versions of @code{ditroff} and is available in
6003 @Defesc {\\N, ', n, '}
6004 Typeset the character with code@w{ }@var{n} in the current font (this
6005 is @strong{not} the input character code). @var{n} can be any
6006 integer. Most devices only have characters with codes between 0
6007 and@w{ }255; the Unicode output device uses codes in the range
6008 0--65535. If the current font does not contain a character with that
6009 code, special fonts are @emph{not} searched. The @code{\N} escape
6010 sequence can be conveniently used in conjunction with the @code{char}
6014 .char \[phone] \f[ZD]\N'37'
6019 @cindex unnamed characters
6020 @cindex characters, unnamed
6021 The code of each character is given in the fourth column in the font
6022 description file after the @code{charset} command. It is possible to
6023 include unnamed characters in the font description file by using a
6024 name of @samp{---}; the @code{\N} escape sequence is the only way to
6028 @c XXX should be `glyph', not `character'
6030 @cindex character properties
6031 @cindex properties of characters
6032 @Defreq {cflags, n c1 c2 @dots{}}
6033 Each character has certain properties associated with it. These
6034 properties can be modified with the @code{cflags} request. The first
6035 argument is the the sum of the desired flags and the remaining
6036 arguments are the characters to have those properties. It is possible
6037 to omit the spaces between the characters.
6041 @cindex end of sentence characters
6042 @cindex characters, end of sentence
6043 the character ends sentences (initially characters @samp{.?!} have this
6047 @cindex hyphenating characters
6048 @cindex characters, hyphenation
6049 lines can be broken before the character (initially no characters have
6055 lines can be broken after the character (initially the characters
6056 @samp{-\(hy\(em} have this property)
6059 @cindex overlapping characters
6060 @cindex characters, overlapping
6064 the character overlaps horizontally (initially the characters
6065 @samp{\(ul\(rn\(ru} have this property)
6069 the character overlaps vertically (initially character @samp{\(br} has
6073 @cindex transparent characters
6074 @cindex character, transparent
6082 an end of sentence character followed by any number of characters with
6083 this property is treated as the end of a sentence if followed by a
6084 newline or two spaces; in other words the character is
6085 @dfn{transparent} for the purposes of end of sentence recognition --
6086 this is the same as having a zero space factor in @TeX{} (initially
6087 characters @samp{"')]*\(dg\(rq} have this property).
6091 @cindex defining characters
6092 @cindex characters, defining
6093 @cindex creating new characters
6094 @cindex escape character
6095 @cindex character, escape
6105 @Defreq {char, c [@Var{string}]}
6106 Define a new character@w{ }@var{c} to be @var{string} (which can be
6107 empty). Every time character@w{ }@var{c} needs to be printed,
6108 @var{string} is processed in a temporary environment and the result is
6109 wrapped up into a single object. Compatibility mode is turned off and
6110 the escape character is set to @samp{\} while @var{string} is being
6111 processed. Any emboldening, constant spacing or track kerning is
6112 applied to this object rather than to individual characters in
6113 @var{string}. A character defined by this request can be used just
6114 like a normal character provided by the output device. In particular,
6115 other characters can be translated to it with the @code{tr} request;
6116 it can be made the leader character by the @code{lc} request; repeated
6117 patterns can be drawn with the character using the @code{\l} and
6118 @code{\L} escape sequences; words containing the character can be
6119 hyphenated correctly, if the @code{hcode} request is used to give the
6120 character a hyphenation code. There is a special anti-recursion
6121 feature: Use of character within the character's definition is handled
6122 like normal characters not defined with @code{char}.
6125 @cindex removing character definition
6126 @cindex character, removing definition
6127 @Defreq {rchar, c1 c2 @dots{}}
6128 Remove the definitions of characters @var{c1}, @var{c2},@w{
6129 }@enddots{} This undoes the effect of a @code{char} request.
6131 It is possible to omit the whitespace between arguments.
6134 @xref{Special Characters}.
6136 @c ---------------------------------------------------------------------
6138 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts
6139 @subsection Special Fonts
6140 @cindex special fonts
6141 @cindex fonts, special
6147 @c ---------------------------------------------------------------------
6149 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts
6150 @subsection Artificial Fonts
6151 @cindex artificial fonts
6152 @cindex fonts, artificial
6154 There are a number of requests for artificially creating fonts. These
6155 are largely vestiges of the days when output devices did not have a
6156 wide variety of fonts, and when @code{nroff} and @code{troff} were
6157 separate programs. These are no longer necessary in GNU
6158 @code{troff}. Nevertheless, they are supported.
6161 @Defreq {ul, [@Var{lines}]}
6162 The @code{ul} request normally underlines subsequent lines if a tty
6163 output device is used. Otherwise, the lines are printed in italics
6164 (only the term `underlined' is used in the following). The single
6165 argument is the number of input lines to be underlined; with no
6166 argument, the next line is underlined. If @var{lines} is zero or
6167 negative, stop the effects of @code{ul} (if it was active). Requests
6168 and empty lines do not count for computing the number of underlined
6169 input lines, even if they produce some output like @code{tl}. Lines
6170 inserted by macros (e.g.@: invoked by a trap) do count.
6172 At the beginning of @code{ul}, the current font is stored and the
6173 underline font is activated. Within the span of a @code{ul} request,
6174 it is possible to change fonts, but after the last line affected by
6175 @code{ul} the saved font is restored.
6177 @cindex underline font
6178 @cindex font, for underlining
6180 This command is associated with the current environment. The
6181 underline font can be changed with the @code{uf} request.
6183 @c XXX @xref should be changed to grotty
6185 @xref{Troff and Nroff Mode}, for a discussion how underlining is
6186 implemented in for tty output devices, and which problems can arise.
6188 The @code{ul} request does not underline spaces.
6191 @cindex continuous underlining
6192 @cindex underlining, continuous
6193 @Defreq {cu, [@Var{lines}]}
6194 The @code{cu} request is similar to @code{ul} but underlines spaces as
6195 well (if a tty output device is used).
6198 @cindex underline font
6199 @cindex font for underlining
6203 Set the underline font (globally) used by @code{ul} and @code{cu}. By
6204 default, this is the font at position@w{ }2. @var{font} can be either
6205 a non-negative font position or the name of a font.
6208 @cindex imitating bold face
6209 @cindex bold face, imitating
6210 @Defreq {bd, font [@Var{offset}]}
6211 @Defreqx {bd, font1 font2 [@Var{offset}]}
6213 Artificially create a bold font by printing each character twice,
6216 Two syntax forms are available.
6220 Imitate a bold font unconditionally. The first argument specifies the
6221 font to embolden, and the second is the number of basic units, minus
6222 one, by which the two characters is offset. If the second argument is
6223 missing, emboldening is turned off.
6225 @var{font} can be either a non-negative font position or the name of a
6228 @var{offset} is available in the @code{.b} read-only register if a
6229 special font is active; in the @code{bd} request, its default unit is
6234 @cindex embolding of special fonts
6235 @cindex special fonts, emboldening
6237 Imitate a bold form conditionally. Embolden @var{font1} by
6238 @var{offset} only if font @var{font2} is the current font. This
6239 command can be issued repeatedly to set up different emboldening
6240 values for different current fonts. If the second argument is
6241 missing, emboldening is turned off for this particular current font.
6243 This affects special fonts only (either set up with the @code{special}
6244 command in font files or with the @code{fspecial} request).
6248 @cindex constant character space mode
6249 @cindex mode for constant character space
6250 @cindex character, constant space
6252 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
6253 Switch to and from constant character space mode. If activated, the
6254 width of every character is @math{@var{width}/36} ems. The em size is
6255 given absolutely by @var{em-size}; if this argument is missing, the em
6256 value is taken from the current font size (as set with the @code{ps}
6257 request) when the font is effectively in use. Without second and
6258 third argument, constant character space mode is deactivated.
6260 Default unit for @var{em-size} is @samp{z}; @var{width} is an integer.
6263 @c ---------------------------------------------------------------------
6265 @node Ligatures and Kerning, , Artificial Fonts, Fonts
6266 @subsection Ligatures and Kerning
6267 @cindex ligatures and kerning
6268 @cindex kerning and ligatures
6270 Ligatures are groups of characters that are run together. For
6271 example, the letters `f' and `i' can form a ligature `fi' as in the
6272 word `file'. This produces a cleaner look (albeit subtle) to the
6273 printed output. Usually, ligatures are not available in fonts for tty
6276 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
6277 typesetter that was the target of AT&T @code{troff} also supported
6278 `ff', `ffi', and `ffl' ligatures. Advanced typesetters or `expert'
6279 fonts may include ligatures for `ft' and `ct', although GNU
6280 @code{troff} does not support these (yet).
6282 @cindex ligatures enabled register
6283 @Defreq {lg, [@Var{flag}]}
6285 The ligature mechanism can be switched on or off with the @code{lg}
6286 request; if the parameter is non-zero or missing, ligatures are
6287 enabled, otherwise disabled. Default is on. The current ligature
6288 mode can be found in the read-only number register @code{.lg} (set to
6289 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise).
6291 Setting the ligature mode to@w{ }2 enables the two-character ligatures
6292 (fi, fl, and ff) and disables the three-character ligatures (ffi and
6296 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
6297 modifies the distance between a character pair to improve readability.
6298 In most cases (but not always) the distance is decreased.
6300 For example, compare the combination of the letters `V' and `A'. With
6301 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
6303 Typewriter-like fonts and fonts for terminals where all characters
6304 have the same width don't use kerning.
6306 @cindex kerning enabled register
6307 @Defreq {kern, [@Var{flag}]}
6309 Kerning can be activated with the @code{kern} request. If the
6310 parameter is non-zero or missing, enable pairwise kerning, otherwise
6311 disable it. The read-only number register @code{.kern} is set to@w{
6312 }1 if pairwise kerning is enabled, 0@w{ }otherwise.
6314 @cindex zero width space character
6315 @cindex character, zero width space
6316 @cindex space character, zero width
6317 If the font description file contains pairwise kerning information,
6318 characters from that font are kerned. Kerning between two characters
6319 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
6321 @xref{Font File Format}.
6324 @cindex track kerning
6325 @cindex kerning, track
6326 @dfn{Track kerning} expands or reduces the space between characters.
6327 This can be handy, for example, if you need to squeeze a long word
6328 onto a single line or spread some text to fill a narrow column. It
6329 must be used with great care since it is usually considered bad
6330 typography if the reader notices the effect.
6332 @Defreq {tkf, f s1 n1 s2 n2}
6333 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
6334 }@var{f} the width of every character is increased by an amount
6335 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
6336 the current point size is less than or equal to @var{s1} the width is
6337 increased by @var{n1}; if it is greater than or equal to @var{s2} the
6338 width is increased by @var{n2}; if the point size is greater than or
6339 equal to @var{s1} and less than or equal to @var{s2} the increase in
6340 width is a linear function of the point size.
6342 The default unit is @samp{z} for @var{s1} and @var{s2}, @samp{p} for
6343 @var{n1} and @var{n2}.
6346 Sometimes, when typesetting letters of different fonts, more or less
6347 space at such boundaries are needed. There are two escapes to help
6350 @cindex italic correction
6351 @cindex correction, italic
6352 @cindex correction between italic and roman character
6353 @cindex roman character, correction after italic character
6354 @cindex italic character, correction before roman character
6356 Increase the width of the preceding character so that the spacing
6357 between that character and the following character is correct if the
6358 following character is a roman character. For example, if an
6359 italic@w{ }@code{f} is immediately followed by a roman right
6360 parenthesis, then in many fonts the top right portion of the @code{f}
6361 overlaps the top left of the right parenthesis. Use this escape
6362 sequence whenever an italic character is immediately followed by a
6363 roman character without any intervening space. This small amount of
6364 space is also called @dfn{italic correction}.
6370 @result{} {@it f}@r{)}
6372 @result{} @i{f}@r{)}
6378 @cindex left italic correction
6379 @cindex correction, left italic
6380 @cindex roman character, correction before italic character
6381 @cindex italic character, correction after roman character
6382 @Defesc {\\\,, , , }
6383 Modify the spacing of the following character so that the spacing
6384 between that character and the preceding character is correct if the
6385 preceding character is a roman character. Use this escape sequence
6386 whenever a roman character is immediately followed by an italic
6387 character without any intervening space. In analogy to above, this
6388 space could be called @dfn{left italic correction}, but this term
6395 @result{} @r{q}@i{f}
6397 @result{} @r{q}@math{@ptexcomma}@i{f}
6404 Insert a zero-width character, which is invisible. Its intended use
6405 is to stop interaction of a character with its surrounding.
6409 It prevents the insertion of extra space after an end of sentence
6415 @result{} Test. Test.
6418 @result{} Test. Test.
6422 It prevents interpretation of a control character at the beginning of
6427 @result{} warning: `Test' not defined
6433 It prevents kerning between two characters.
6441 @result{} @r{V@w{}A}
6447 It is needed to map an arbitrary character to nothing in the @code{tr}
6448 request (@pxref{Character Translations}).
6453 @c =====================================================================
6455 @node Sizes, Strings, Fonts, gtroff Reference
6461 @cindex size of type
6462 @cindex vertical spacing
6463 @cindex spacing, vertical
6464 @code{gtroff} uses two dimensions with each line of text, type size
6465 and vertical spacing. The @dfn{type size} is approximately the height
6466 of the tallest character.@footnote{This is usually the parenthesis.
6467 Note that in most cases the real dimensions of the glyphs in a font
6468 are @emph{not} related to its type size! For example, the standard
6469 @sc{PostScript} font families `Times Roman', `Helvetica', and
6470 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
6471 output, the size of `Helvetica' has to be reduced by one point, and
6472 the size of `Courier' must be increased by one point.} @dfn{Vertical
6473 spacing} is the amount of space @code{gtroff} allows for a line of
6474 text; normally, this is about 20%@w{ }larger than the current type
6475 size. Ratios smaller than this can result in hard-to-read text;
6476 larger than this, it spreads the text out more vertically (useful for
6477 term papers). By default, @code{gtroff} uses 10@w{ }point type on
6478 12@w{ }point spacing.
6481 The difference between type size and vertical spacing is known, by
6482 typesetters, as @dfn{leading}.
6485 * Changing Type Sizes::
6486 * Fractional Type Sizes::
6489 @c ---------------------------------------------------------------------
6491 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
6492 @subsection Changing Type Sizes
6493 @cindex changing type sizes
6494 @cindex type sizes, changing
6496 @Defreq {ps, [@Var{size}]}
6497 @Defreqx {ps, @t{+}@Var{size}}
6498 @Defreqx {ps, @t{-}@Var{size}}
6499 @Defescx {\\s, , size, }
6501 Use the @code{ps} request or the @code{\s} escape to change (increase,
6502 decrease) the type size (in points). Specify @var{size} as either an
6503 absolute point size, or as a relative change from the current size.
6504 The size@w{ }0, or no argument, goes back to the previous size.
6506 Default unit of @code{size} is @samp{z}. If @code{size} is zero or
6507 negative, it is set to 1@dmn{u}.
6509 The read-only number register @code{.s} returns the point size in
6510 points as a decimal fraction. This is a string. To get the point
6511 size in scaled points, use the @code{.ps} register instead.
6513 @code{.s} is associated with the current environment
6514 (@pxref{Environments}).
6521 wink, wink, \s+2nudge, nudge,\s+8 say no more!
6525 The @code{\s} escape may be called in a variety of ways. Much like
6526 other escapes there must be a way to determine where the argument ends
6527 and the text begins. Any of the following forms are valid:
6531 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either
6532 0 or in the range 4 to@w{ }39.
6536 Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{
6537 }must be exactly one digit.
6540 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly
6547 Increase or decrease the point size by @var{nn}@w{ }points. @var{nn}
6548 must be exactly two digits.
6551 @xref{Fractional Type Sizes}, for yet another syntactical form of
6552 using the @code{\s} escape.
6554 Some devices may only have certain permissible sizes, in which case
6555 @code{gtroff} rounds to the nearest permissible size.
6558 @cindex current type size register
6559 @cindex current vertical spacing register
6560 @Defreq {vs, [@Var{space}]}
6561 @Defreqx {vs, @t{+}@Var{space}}
6562 @Defreqx {vs, @t{-}@Var{space}}
6564 Change (increase, decrease) the vertical spacing by @var{space}. The
6565 default unit is @samp{p}.
6567 If @code{vs} is called without an argument, the vertical spacing is
6568 reset to the previous value before the last call to @code{vs}.
6571 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
6572 zero or negative; the vertical spacing is then set to the vertical
6573 resolution (as given in the @code{.V} register).
6575 The read-only number register @code{.v} contains the current vertical
6576 spacing; it is associated with the current environment
6577 (@pxref{Environments}).
6584 ... .sz macro example?? ...
6588 @c ---------------------------------------------------------------------
6590 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
6591 @subsection Fractional Type Sizes
6592 @cindex fractional type sizes
6593 @cindex type sizes, fractional
6595 @cindex @code{s} unit
6596 @cindex unit, @code{s}
6597 @cindex @code{z} unit
6598 @cindex unit, @code{z}
6604 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
6605 where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by
6606 default). There is a new scale indicator @samp{z} which has the
6607 effect of multiplying by @var{sizescale}. Requests and escape
6608 sequences in @code{gtroff} interpret arguments that represent a point
6609 size as being in units of scaled points, but they evaluate each such
6610 argument using a default scale indicator of @samp{z}. Arguments
6611 treated in this way are the argument to the @code{ps} request, the
6612 third argument to the @code{cs} request, the second and fourth
6613 arguments to the @code{tkf} request, the argument to the @code{\H}
6614 escape sequence, and those variants of the @code{\s} escape sequence
6615 that take a numeric expression as their argument (see below).
6617 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
6618 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
6619 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
6620 10250@w{ }scaled points, which is equal to 10.25@w{ }points.
6622 @code{gtroff} disallows the use of the @samp{z} scale indicator in
6623 instances where it would make no sense, such as a numeric
6624 expression whose default scale indicator was neither @samp{u} nor
6625 @samp{z}. Similarly it would make
6626 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
6627 numeric expression whose default scale indicator was @samp{z}, and so
6628 @code{gtroff} disallows this as well.
6630 There is also new scale indicator @samp{s} which multiplies by the
6631 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
6632 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
6637 A read-only number register returning the point size in scaled points.
6639 @code{.ps} is associated with the current environment
6640 (@pxref{Environments}).
6643 @cindex last-requested point size register
6644 @cindex point size, last-requested
6649 The last-requested point size in scaled points is contained in the
6650 @code{.psr} read-only number register. The last requested point size
6651 in points as a decimal fraction can be found in @code{.sr}. This is a
6652 string-valued read-only number register.
6654 Note that the requested point sizes are device-independent, whereas
6655 the values returned by the @code{.ps} and @code{.s} registers are not.
6656 For example, if a point size of 11@dmn{pt} is requested for a DVI
6657 device, 10.95@dmn{pt} are actually used (as specified in the
6660 Both registers are associated with the current environment
6661 (@pxref{Environments}).
6664 The @code{\s} escape has the following syntax for working with
6665 fractional type sizes:
6670 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
6671 expression with a default scale indicator of @samp{z}.
6681 Increase or or decrease the point size by @var{n} scaled points;
6682 @var{n} is a numeric expression with a default scale indicator of
6689 @c =====================================================================
6691 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
6695 @code{gtroff} has string variables, which are entirely for user
6696 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
6697 even this is a read-write string variable).
6699 @cindex string interpolation
6700 @cindex string expansion
6701 @cindex interpolation of strings
6702 @cindex expansion of strings
6703 @Defreq {ds, name [@Var{string}]}
6704 @Defescx {\\*, , n, }
6705 @Defescx {\\*, @lparen{}, nm, }
6706 @Defescx {\\*, @lbrack{}, name, @rbrack{}}
6707 Define and access a string variable @var{name} (one-character name
6708 @var{n}, two-character name @var{nm}). If @var{name} already exists,
6709 @code{ds} overwrites the previous definition.
6714 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
6716 The \*(UX Operating System
6719 The @code{\*} escape @dfn{interpolates} (expands in-place) a
6720 previously-defined string variable. To be more precise, the stored
6721 string is pushed onto the input stack which is then parsed by
6722 @code{gtroff}. Similar to number registers, it is possible to nest
6723 strings, i.e. a string variables can be called within string
6726 If the string named by the @code{\*} does not exist, it is defined as
6727 empty, and a warning of type @samp{mac} is emitted (see
6728 @ref{Debugging}, for more details).
6730 @cindex comments, with @code{ds}
6731 @strong{Caution:} Unlike other requests, the second argument to the
6732 @code{ds} request takes up the entire line including trailing spaces.
6733 This means that comments on a line with such a request can introduce
6734 unwanted space into a string.
6737 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
6741 Instead the comment should be put on another line or have the comment
6742 escape adjacent with the end of the string.
6745 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
6748 @cindex trailing quotes
6749 @cindex quotes, trailing
6750 @cindex leading spaces with @code{ds}
6751 @cindex spaces with @code{ds}
6752 To produce leading space the string can be started with a double
6753 quote. No trailing quote is needed; in fact, any trailing quote is
6754 included in your string.
6757 .ds sign " Yours in a white wine sauce,
6761 @cindex multi-line strings
6762 @cindex strings, multi-line
6763 @cindex newline character in strings, escaping
6764 @cindex escaping newline characters in strings
6765 Strings are not limited to a single line of text. A string can span
6766 several lines by escaping the newlines with a backslash. The
6767 resulting string is stored @emph{without} the newlines.
6770 .ds foo lots and lots \
6771 of text are on these \
6775 It is not possible to have real newlines in a string.
6777 @cindex name space of macros and strings
6778 @cindex macros, shared name space with strings
6779 @cindex strings, shared name space with macros
6780 Strings, macros, and diversions (and boxes) share the same name space.
6781 Internally, even the same mechanism is used to store them. This has
6782 some interesting consequences. For example, it is possible to call a
6783 macro with string syntax and vice versa.
6790 @result{} This is a funny test.
6792 .ds yyy a funny test
6795 @result{} This is a funny test.
6798 Diversions and boxes can be also called with string syntax. It is not
6799 possible to pass arguments to a macro if called with @code{\*}.
6801 Another consequence is that you can copy one-line diversions or boxes
6809 .ds yyy This is \*[xxx]\c
6811 @result{} @r{This is a }@i{test}.
6815 As the previous example shows, it is possible to store formatted
6816 output in strings. The @code{\c} escape prevents the insertion of an
6817 additional blank line in the output.
6819 Copying diversions longer than a single output line produces
6829 .ds yyy This is \*[xxx]\c
6831 @result{} test This is a funny.
6834 Usually, it is not predictable whether a diversion contains one or
6835 more output lines, so this mechanism should be avoided. With
6836 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
6837 final newline from a diversion. Another disadvantage is that the
6838 spaces in the copied string are already formatted, making them
6839 unstretchable. This can cause ugly results.
6843 A clean solution to this problem is available in GNU @code{troff},
6844 using the requests @code{chop} to remove the final newline of a
6845 diversion, and @code{unformat} to make the horizontal spaces
6858 @result{} This is a funny test.
6861 @xref{Gtroff Internals}, for more information.
6864 @cindex appending to strings
6865 @cindex strings, appending
6866 @Defreq {as, name [@Var{string}]}
6867 The @code{as} request is similar to @code{ds} but appends @var{string}
6868 to the string stored as @var{name} instead of redefining it. If
6869 @var{name} doesn't exist yet, it is created.
6872 .as sign " with shallots, onions and garlic,
6876 Rudimentary string manipulation routines are given with the next two
6880 @Defreq {substring, str n1 [@Var{n2}]}
6881 Replace the string in register@w{ }@var{str} with the substring
6882 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
6883 in the string has index one. If @var{n2} is omitted, it is taken to
6884 be equal to the string's length. If the index value @var{n1} or
6885 @var{n2} is negative or zero, it is counted from the end of the
6886 string, going backwards: The last character has index@w{ }0, the
6887 character before the last character has index@w{ }@minus{}1, etc.
6897 @cindex length of a string
6898 @cindex string, length of
6899 @Defreq {length, reg str}
6900 Compute the length of @var{str} and returns it in the number
6901 register@w{ }@var{reg}. If @var{reg} doesn't exist, it is created.
6911 @cindex rename request
6912 @cindex rename macro
6913 @cindex rename string
6915 Rename the request, macro, or string @var{xx} to @var{yy}.
6918 @cindex remove request
6919 @cindex remove macro
6920 @cindex remove string
6922 Remove the request, macro, or string @var{xx}. @code{gtroff} treats
6923 subsequent invocations as if the object had never been defined.
6927 @Defreq {als, new old}
6928 Create an alias named @var{new} for the request, string, macro, or
6929 diversion object named @var{old}. The new name and the old name are
6930 exactly equivalent (it is similar to a hard rather than a soft
6931 link). If @var{old} is undefined, @code{gtroff} generates a warning of
6932 type @samp{mac} and ignores the request.
6936 Remove (chop) the last character from the macro, string, or diversion
6937 named @var{xx}. This is useful for removing the newline from the end
6938 of diversions that are to be interpolated as strings. This command
6939 can be used repeatedly; see @ref{Gtroff Internals}, for details on
6940 nodes inserted by @code{gtroff} automatically.
6943 @xref{Identifiers}, and @ref{Comments}.
6946 @c =====================================================================
6948 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
6949 @section Conditionals and Loops
6950 @cindex conditionals and loops
6951 @cindex loops and conditionals
6954 * Operators in Conditionals::
6959 @c ---------------------------------------------------------------------
6961 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
6962 @subsection Operators in Conditionals
6966 @cindex @code{if}, operators to use with it
6967 @cindex @code{while}, operators to use with it
6968 In @code{if} and @code{while} requests, there are several more
6969 operators available:
6974 True if the current page is even or odd numbered (respectively).
6978 True if the document is being processed in nroff mode (i.e., the
6979 @code{.nroff} command has been issued).
6983 True if the document is being processed in troff mode (i.e., the
6984 @code{.troff} command has been issued).
6989 @item '@var{xxx}'@var{yyy}'
6990 True if the string @var{xxx} is equal to the string @var{yyy}. Other
6991 characters can be used in place of the single quotes; the same set of
6992 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
6993 @code{gtroff} formats the strings before being compared:
7004 The resulting motions, character sizes, and fonts have to
7005 match,@footnote{The created output nodes must be identical.
7006 @xref{Gtroff Internals}.} and not the individual motion, size, and
7007 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
7008 both result in a roman @samp{|} character with the same point size and
7009 at the same location on the page, so the strings are equal. If
7010 @samp{.ft@w{ }I} had been added before the @samp{.ie}, the result
7011 would be ``false'' because (the first) @samp{|} produces an italic
7012 @samp{|} rather than a roman one.
7015 True if there is a number register named @var{xxx}.
7018 True if there is a string, macro, diversion, or request named @var{xxx}.
7022 True if there is a character @var{ch} available; @var{ch} is either an
7023 @acronym{ASCII} character or a special character (@code{\(@var{ch}} or
7024 @code{\[@var{ch}]}); the condition is also true if @var{ch} has been
7025 defined by the @code{char} request.
7028 Note that these operators can't be combined with other operators like
7029 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
7030 between the exclamation mark and the operator) can be used to negate
7042 A whitespace after @samp{!} always evaluates to zero (this bizarre
7043 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
7051 @result{} r xxx true
7054 It is possible to omit the whitespace before the argument to the
7055 @samp{r}, @samp{d}, and @samp{c} operators.
7059 @c ---------------------------------------------------------------------
7061 @node if-else, while, Operators in Conditionals, Conditionals and Loops
7065 @code{gtroff} has if-then-else constructs like other languages, although
7066 the formatting can be painful.
7068 @Defreq {if, expr anything}
7069 Evaluate the expression @var{expr}, and executes @var{anything} (the
7070 remainder of the line) if @var{expr} evaluates to non-zero (true).
7071 @var{anything} is interpreted as though it was on a line by itself
7072 (except that leading spaces are swallowed). @xref{Expressions}, for
7078 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
7085 @Defreq {ie, expr anything}
7086 @Defreqx {el, anything}
7087 Use the @code{ie} and @code{el} requests to write an if-then-else.
7088 The first request is the `if' part and the latter is the `else' part.
7091 .ie n .ls 2 \" double spacing in nroff
7092 .el .ls 1 \" single spacing in troff
7096 @c this is a bug in makeinfo: you can't have `@{' as an argument
7101 @c @Defesc {\\@@@{, , , }
7102 @c @Defescx {\\@@@}, , , }
7103 In many cases, an if (or if-else) construct needs to execute more than
7104 one request. This can be done using the @code{\@{} and @code{\@}}
7105 escapes. The following example shows the possible ways to use these
7106 escapes (note the position of the opening and closing braces).
7122 @c ---------------------------------------------------------------------
7124 @node while, , if-else, Conditionals and Loops
7128 @code{gtroff} provides a looping construct using the @code{while}
7129 request, which is used much like the @code{if} (and related) requests.
7131 @Defreq {while, expr anything}
7132 Evaluate the expression @var{expr}, and repeatedly execute
7133 @var{anything} (the remainder of the line) until @var{expr} evaluates
7138 .while (\na < 9) \@{\
7142 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
7150 The body of a @code{while} request is treated like the body of a
7151 @code{de} request: @code{gtroff} temporarily stores it in a macro
7152 which is deleted after the loop has been exited. It can considerably
7153 slow down a macro if the body of the @code{while} request (within the
7154 macro) is large. Each time the macro is executed, the @code{while}
7155 body is parsed and stored again as a temporary macro.
7160 . while (\\n[num] > 0) \@{\
7161 . \" many lines of code
7167 @cindex recursive macros
7168 @cindex macros, recursive
7170 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
7171 doesn't have the @code{while} request) is to use a recursive macro
7172 instead which is parsed only once during its definition.
7176 . if (\\n[num] > 0) \@{\
7177 . \" many lines of code
7190 Note that the number of available recursion levels is set to@w{ }1000
7191 (this is a compile-time constant value of @code{gtroff}).
7194 The closing brace of a @code{while} body must end a line.
7199 . while (\n[a] < 10) \@{\
7202 @result{} unbalanced \@{ \@}
7208 @cindex @code{break}, in a @code{while} loop
7209 @cindex @code{continue}, in a @code{while} loop
7211 Break out of a @code{while} loop. Be sure not to confuse this with
7212 the @code{br} request (causing a line break).
7215 @Defreq {continue, }
7216 Finishes the current iteration of a @code{while} loop, immediately
7217 restarting the next iteration.
7223 @c =====================================================================
7225 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
7226 @section Writing Macros
7227 @cindex writing macros
7228 @cindex macros, writing
7230 A @dfn{macro} is a collection of text and embedded commands which can
7231 be invoked multiple times. Use macros to define common operations.
7233 @Defreq {de, name [@Var{end}]}
7234 Define a new macro named @var{name}. @code{gtroff} copies subsequent
7235 lines (starting with the next one) into an internal buffer until it
7236 encounters the line @samp{..} (two dots). The optional second
7237 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
7239 Note that no leading whitespace is allowed in the line containing the
7240 ending token (either @samp{..} or the macro @samp{.@var{end}}).
7242 Here a small example macro called @samp{P} which causes a break and
7243 inserts some vertical space. It could be used to separate paragraphs.
7252 @c XXX add info about macro definitions in macros.
7254 @c XXX give example for end macro.
7256 @c XXX add info about indirect macro calls:
7262 @c test \*[xxx] test
7263 @c => test from yyy test
7265 @c XXX info about common identifier pool for strings, macros, and
7269 @cindex appending, to a macro
7271 Works similarly to @code{de} except it appends onto the macro named
7272 @var{xx}. So, to make the previously defined @samp{P} macro actually
7273 do indented instead of block paragraphs, add the necessary code to the
7274 existing macro like this:
7284 @Defreq {als, new old}
7285 Create an alias named @var{new} for the request, string, macro, or
7286 diversion object named @var{old}. The new name and the old name are
7287 exactly equivalent (it is similar to a hard rather than a soft
7288 link). If @var{old} is undefined, @code{gtroff} generates a warning of
7289 type @samp{mac} and ignores the request.
7291 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds},
7292 and @code{as} requests only create a new object if the name
7293 of the macro, diversion or string diversion is currently
7294 undefined or if it is defined to be a request; normally
7295 they modify the value of an existing object.
7303 @c ---------------------------------------------------------------------
7305 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
7306 @subsection Copy-in Mode
7307 @cindex copy-in mode
7308 @cindex mode, copy-in
7315 @cindex @code{\n}, when reading text for a macro
7316 @cindex @code{\$}, when reading text for a macro
7317 @cindex @code{\*}, when reading text for a macro
7318 @cindex @code{\\}, when reading text for a macro
7319 @cindex \@key{RET}, when reading text for a macro
7320 When @code{gtroff} reads in the text for a macro or diversion, it copies
7321 the text (including request lines, but excluding escapes) into an
7322 internal buffer. Escapes are converted into an internal form,
7323 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
7324 @code{\@key{RET}} which are evaluated and inserted into the text where
7325 the escape was located. This is known as @dfn{copy-in} mode or
7328 What this means is that you can specify when these escapes are to be
7329 evaluated (either at copy-in time or at the time of use) by insulating
7330 the escapes with an extra backslash. Compare this to the @code{\def}
7331 and @code{\edef} commands in @TeX{}.
7333 The following example prints the numbers 20 and@w{ }10:
7345 @c ---------------------------------------------------------------------
7347 @node Parameters, , Copy-in Mode, Writing Macros
7348 @subsection Parameters
7352 The arguments to a macro can be examined using a variety of escapes.
7353 The number of arguments is available in the @code{.$} number register.
7354 Any individual argument can be retrieved with one of the following
7357 @cindex copy-in mode, and macro arguments
7358 @Defesc {\\$, n, , }
7359 @Defescx {\\$, @lparen{}, nn, }
7360 @Defescx {\\$, @lbrack{}, nnn, @rbrack{}}
7361 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
7362 @code{\$[@var{nnn}]} retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or
7363 @var{nnn}@dmn{th} argument. As usual, the first form only accepts a
7364 single number (larger than zero), the second a two-digit number (larger
7365 or equal to@w{ }10), and the third any positive integer value (larger
7366 than zero). Macros can have an unlimited number of arguments. Note
7367 that due to copy-in mode, use two backslashes on these in actual use to
7368 prevent interpolation until the macro is actually invoked.
7371 @Defreq {shift, [@Var{n}]}
7372 Shifts the arguments 1@w{ }position, or as
7373 many positions as specified by its argument. After executing this
7374 request, argument@w{ }@var{i} becomes argument @var{i}-@var{n};
7375 arguments 1 to@w{ }@var{n} are no longer available. Shifting by
7376 negative amounts is currently undefined.
7379 @Defesc {\\$*, , , }
7380 @Defescx {\\$@@, , , }
7381 In some cases it is convenient to use all of the arguments at once (for
7382 example, to pass the arguments along to another macro). The @code{\$*}
7383 escape concatenates all the arguments separated by spaces. A
7384 similar escape is @code{\$@@}, which concatenates all the
7385 arguments with each surrounded by double quotes, and separated by
7390 @cindex @code{als}, use with @code{\$0}
7391 @Defesc {\\$0, , , }
7392 The name used to invoke the current macro.
7393 The @code{als} request can make a macro have more than one name.
7397 .ie \\n(.$=1 .ds Vl Pre-Release Version
7398 .el .ds Vl Version \\$3, \\$4.
7403 This would be called as
7406 .vl $Id: groff.texinfo,v 1.77 2001/05/07 13:36:24 wlemb Exp $
7410 @xref{Request Arguments}.
7413 @c =====================================================================
7415 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
7416 @section Page Motions
7417 @cindex page motions
7418 @cindex motions, page
7420 @cindex @code{sp}, as vertical page motion
7421 @Defreq {sp, [@Var{len}]}
7422 Motions up and down the page can be done with the @code{sp} request.
7423 However, this causes a break so that the actual effect is to move to the
7424 left margin and then to the specified location.
7427 @Defreq {mk, [@Var{reg}]}
7429 The request @code{mk} can be used to mark a location on a page, for
7430 movement to later. This request takes a register name as an argument in
7431 which to store the current page location. With no argument it
7432 stores the location in an internal register. The results of this can be
7433 used later by the @code{rt} or the @code{sp} request. The @code{rt}
7434 request returns @emph{upwards} to the location given in the register
7435 name given as an argument; with no argument it returns to the
7436 location marked with the @code{mk} request.
7441 ... dual column example ...
7446 The following escapes give fine control of movements about the page.
7448 @cindex vertical motion
7449 @cindex motion, vertical
7450 @Defesc {\\v, ', e, '}
7451 The @code{\v'@var{e}'} escape enables arbitrary vertical motion from the
7452 current location on the page. The argument@w{ }@var{e} specifies the
7453 distance to move; positive is downwards and negative upwards. The
7454 default unit for this escape @samp{v}. Beware, however, that
7455 @code{gtroff} continues text processing at the point where the motion
7456 ends, so you should always balance motions to avoid interference with
7460 There are some special case escapes for vertical motion.
7464 move upwards@w{ }1@dmn{v}.
7467 move upwards@w{ }.5@dmn{v}.
7470 move down@w{ }.5@dmn{v}.
7473 @cindex inserting horizontal space
7474 @cindex horizontal space
7475 @cindex space, horizontal
7476 @Defesc {\\h, ', e, '}
7477 The @code{\h'@var{e}'} escape provides horizontal motions. The
7478 expression@w{ }@var{e} indicates how far to move: positive is rightwards
7479 and negative leftwards.
7480 @c XXX Is there a default unit for this?
7483 There are a number of special case escapes for horizontal motion:
7487 An unbreakable and unpaddable (i.e.@: not expanded during filling)
7488 space. (Note: This is a backslash followed by a space.)
7491 An unbreakable space that stretches like a normal inter-word space
7492 when a line is adjusted.
7495 A 1/6@dmn{th} em space. Ignored for tty output devices (rounded to
7499 A 1/12@dmn{th} em space. Ignored for tty output devices (rounded to
7503 A space the size of a digit.
7506 @cindex zero width space character
7507 @cindex character, zero width space
7508 @cindex space character, zero width
7512 Like @code{\&} except that it behaves like a character declared with the
7513 @code{cflags} request to be transparent for the purposes of end of
7514 sentence recognition.
7517 The following string sets the @TeX{} logo:
7520 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
7523 @cindex width escape
7524 @cindex escape, width
7525 @Defesc {\\w, ', text, '}
7526 Used as @code{\w'@var{text}'},
7527 returns the width of the specified @var{text} in basic units.
7528 This allows horizontal movement based on the width of some
7529 arbitrary text (e.g.@: given as an argument to a macro).
7535 ... strlen example ...
7539 Font changes may occur in @var{text} which don't affect current
7542 After use, @code{\w} sets several registers:
7549 The highest and lowest point, respectively, in @var{text}.
7555 Like the @code{st} and @code{sb} registers, but takes account of the
7556 heights and depths of characters.
7560 Defines the kinds of characters occurring in @var{text}:
7564 only short characters, no descenders or tall characters.
7567 at least one descender.
7570 at least one tall character.
7573 at least one each of a descender and a tall character.
7578 The amount of horizontal space (possibly negative) that should be added
7579 to the last character before a subscript.
7583 How far to right of the center of the last character in the @code{\w}
7584 argument, the center of an accent from a roman font should be placed
7585 over that character.
7589 @Defesc {\\k, ', x, '}
7590 Stores the current horizontal position in register @var{x}.
7591 Use this, for example, to return to the beginning of a string
7592 for highlighting or other decoration.
7596 A read-only number register containing the current horizontal output
7600 @c XXX documentation
7603 @c =====================================================================
7605 @node Drawing Requests, Traps, Page Motions, gtroff Reference
7606 @section Drawing Requests
7607 @cindex drawing requests
7608 @cindex requests for drawing
7610 @code{gtroff} provides a number of ways to draw lines and other figures
7611 on the page. Used in combination with the page motion commands (see
7612 @ref{Page Motions}, for more info), a wide variety of figures can be
7613 drawn. However, for complex drawings these operations can be quite
7614 cumbersome, and it may be wise to use graphic preprocessors like
7615 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
7618 All drawing is done via escapes.
7620 @cindex drawing horizontal lines
7621 @cindex horizontal line, drawing
7622 @cindex line, horizontal, drawing
7623 @Defesc {\\l, ', l c, '}
7624 Draws a line rightwards from the current
7625 location. The full syntax for this escape is:
7632 where @var{l} is the length of the line to be drawn, starting at the
7633 current location; positive numbers draw to the right, and negative
7634 numbers draw towards the left. This can also be specified absolutely
7635 (i.e.@: with a leading @samp{|}) which draws back to the beginning
7638 @cindex underscore character
7639 @cindex character, underscore
7640 @cindex line drawing character
7641 @cindex character for line drawing
7642 The optional second parameter @var{c} is a character to draw the line
7643 with. If this second argument is not specified, @code{gtroff} uses
7644 the underscore character.
7646 @cindex zero width space character
7647 @cindex character, zero width space
7648 @cindex space character, zero width
7650 To separate the two arguments (to prevent @code{gtroff} from
7651 interpreting a drawing character as a scaling indicator) use @code{\&}.
7653 Here a small useful example:
7657 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
7663 Note that this works by outputting a box rule (a vertical line), then
7664 the text given as an argument and then another box rule. Then the line
7665 drawing escapes both draw from the current location to the beginning of
7666 the @emph{input} line.
7669 @cindex drawing vertical lines
7670 @cindex vertical line drawing
7671 @cindex line, vertical, drawing
7672 @cindex line drawing character
7673 @cindex character for line drawing
7674 @cindex box rule character
7675 @cindex character, box rule
7676 @Defesc {\\L, ', l c, '}
7677 Draws vertical lines. Its parameters are
7678 similar to the @code{\l} escape. The
7679 movement is downwards for positive values,
7680 and upwards for negative values. The
7681 default character is the box rule character. As with the vertical
7682 motion escapes, text processing blindly continues where the line
7694 @Defesc {\\D, ', command arg @dots{}, '}
7695 The @code{\D} escape provides a variety of drawing functions.
7696 While the previous escapes work on a character device, these
7700 @item \D'l @var{dx} @var{dy}'
7701 Draw a line from the current location to the relative point specified by
7702 (@var{dx},@var{dy}).
7708 ...revised box macro...
7713 @cindex circle drawing
7714 @cindex drawing a circle
7715 Draw a circle with a diameter of @var{d} with the leftmost point at the
7719 Draw a solid circle with the same parameters as an outlined circle.
7721 @item \D'e @var{dx} @var{dy}'
7722 @cindex drawing an ellipse
7723 @cindex ellipse drawing
7724 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
7725 diameter of @var{dy} with the leftmost point at the current position.
7727 @item \D'E @var{dx} @var{dy}'
7728 Draw a solid ellipse with the same parameters as an outlined ellipse.
7730 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
7732 @cindex drawing an arc
7733 Draw an arc clockwise from the current location through the two
7734 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
7736 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
7737 @cindex drawing a spline
7738 @cindex spline drawing
7739 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
7740 then to (@var{dx2},@var{dy2}), and so on.
7743 @cindex gray shading
7745 @cindex shades for filling objects
7746 Set the shade of gray to be used for filling solid objects to@w{
7747 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
7748 corresponds solid white and 1000 to solid black, and values in between
7749 correspond to intermediate shades of gray. This applies only to solid
7750 circles, solid ellipses and solid polygons. By default, a level of@w{
7753 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
7754 @cindex drawing a polygon
7755 @cindex polygon drawing
7756 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
7757 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
7758 are exhausted, a line is drawn back to the starting point.
7764 ... box example (yes, again)...
7768 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
7769 Draw a solid polygon with the same parameters as an outlined polygon.
7775 ... shaded box example ...
7780 @cindex line thickness
7781 @cindex thickness of lines
7782 Set the current line thickness to @var{n} machine units. A value of
7783 zero selects the smallest available line thickness. A negative value
7784 makes the line thickness proportional to the current point size (this is
7785 the default behaviour of @code{ditroff}).
7789 @cindex pile, character
7790 @cindex character pile
7791 @Defesc {\\b, ', string, '}
7792 @dfn{Piles} a sequence of characters
7793 vertically, and centers it vertically on the current line. Use it
7794 to build large brackets and braces.
7797 \b'\(lt\(bv\(lk\(bv\(lb'
7801 @xref{Drawing Functions}.
7804 @c =====================================================================
7806 @node Traps, Diversions, Drawing Requests, gtroff Reference
7810 @dfn{Traps} are locations, which, when reached, call a specified
7811 macro. These traps can occur at a given location on the page, at a
7812 given location in the current diversion, after a certain number of input
7813 lines or at the end of input.
7816 * Page Location Traps::
7818 * Input Line Traps::
7819 * End-of-input Traps::
7822 @c ---------------------------------------------------------------------
7824 @node Page Location Traps, Diversion Traps, Traps, Traps
7825 @subsection Page Location Traps
7826 @cindex page location traps
7827 @cindex traps, page location
7829 @dfn{Page location traps} perform an action when @code{gtroff}
7830 reaches a certain vertical location on the page. Page location
7831 traps have a variety of purposes, including:
7835 setting headers and footers
7838 setting body text in multiple columns
7844 @cindex vertical position trap enable register
7847 Enables vertical position traps if @var{flag} is non-zero, or disables
7848 them otherwise. Vertical position traps are traps set by the @code{wh}
7849 or @code{dt} requests. Traps set by the @code{it} request are not
7850 vertical position traps. The parameter that controls whether vertical
7851 position traps are enabled is global. Initially vertical position traps
7852 are enabled. The current setting of this is available in the
7853 @code{.vpt} read-only number register.
7856 @Defreq {wh, dist macro}
7857 Sets a page location trap. Positive values for @var{dist} set
7858 the trap relative to the top of the page; negative values set
7859 the trap relative to the bottom of the page.
7861 @var{macro} is the name of the macro to execute when the
7864 @cindex page headers
7865 @cindex page footers
7868 The following is a simple example of how many macro packages
7869 set headers and footers.
7872 .de hd \" Page header
7877 .de fo \" Page footer
7882 .wh 0 hd \" trap at top of the page
7883 .wh -1i fo \" trap one inch from bottom
7887 @cindex distance to next trap
7888 @cindex trap, distance
7890 A read-only number register holding the distance to the next trap.
7893 @cindex changing trap location
7894 @cindex trap, changing location
7895 @Defreq {ch, dist macro}
7896 Changes the location of a trap.
7897 The first argument is the name of the macro to be invoked at
7898 the trap, and the second argument is the new location for the trap
7899 (note that the parameters are specified the opposite of the @code{.wh} request).
7900 This is useful for building up footnotes in a diversion to allow more
7901 space at the bottom of the page for them.
7907 ... (simplified) footnote example ...
7913 The read-only number register @code{.ne} contains the amount of space
7914 that was needed in the last @code{ne} request that caused a trap to be
7915 sprung. Useful in conjunction with the @code{.trunc} register.
7916 @xref{Page Control}, for more information.
7920 @cindex @code{ne}, and the @code{.trunc} register
7922 A read-only register containing the amount of vertical space truncated
7923 by the most recently sprung vertical position trap, or, if the trap was
7924 sprung by an @code{ne} request, minus the amount of vertical motion
7925 produced by the @code{ne} request. In other words, at the point a trap
7926 is sprung, it represents the difference of what the vertical position
7927 would have been but for the trap, and what the vertical position
7931 @c ---------------------------------------------------------------------
7933 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
7934 @subsection Diversion Traps
7935 @cindex diversion traps
7936 @cindex traps, diversion
7939 @cindex @code{.t}, and diversions
7940 @Defreq {dt, dist macro}
7941 Sets a trap @emph{within} a diversion.
7942 @var{dist} is the first argument is the location of the trap
7943 (identical to the @code{.wh} request)
7944 and @var{macro} is the name of the macro to be invoked. The
7945 number register @code{.t} still works within diversions.
7946 @xref{Diversions}, for more information.
7949 @c ---------------------------------------------------------------------
7951 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
7952 @subsection Input Line Traps
7953 @cindex input line traps
7954 @cindex traps, input line
7956 @Defreq {it, n macro}
7957 Sets an input line trap.
7958 @var{n} is the number of lines of input which may be read before
7959 @dfn{springing} the trap, @var{macro} is the macro to be invoked.
7960 Request lines are not counted as input lines.
7962 For example, one possible use is to have a macro which prints the
7963 next @var{n}@w{ }lines in a bold font.
7976 @c ---------------------------------------------------------------------
7978 @node End-of-input Traps, , Input Line Traps, Traps
7979 @subsection End-of-input Traps
7980 @cindex end-of-input traps
7981 @cindex traps, end-of-input
7984 Sets a trap at the end of input. The @var{macro}
7985 specified is executed after the last line of the
7986 input file has been processed.
7988 For example, if the document had to have a section at the bottom of the
7989 last page for someone to approve it, the @code{em} request could be
8008 @c =====================================================================
8010 @node Diversions, Environments, Traps, gtroff Reference
8014 In @code{gtroff} it is possible to @dfn{divert} text into a named
8015 storage area. Due to the similarity to defining macros it is sometimes
8016 said to be stored in a macro. This is used for saving text for output
8017 at a later time, which is useful for keeping blocks of text on the same
8018 page, footnotes, tables of contents and indices.
8020 @c XXX describe top-level diversion
8021 @c XXX index entry for top-level diversion
8024 @Defreqx {da, macro}
8025 Begins a diversion. Like the @code{de}
8026 request, it takes an argument of a macro name to divert subsequent text
8027 into. The @code{da} macro appends to an existing diversion.
8029 @code{di} or @code{da} without an argument ends the diversion.
8035 ... end-note example ...
8042 @cindex nested diversions
8043 @cindex diversion, nested
8046 Diversions may be nested. The read-only number register @code{.z}
8047 contains the name of the current diversion (this is a string-valued
8048 register). The read-only number register @code{.d} contains the current
8049 vertical place in the diversion. If not in a diversion it is the same
8050 as the register @code{nl}.
8056 The @dfn{high-water mark} on the current page. It corresponds to the
8057 text baseline of the lowest line on the page. This is a read-only
8063 After completing a diversion, the read-write number registers @code{dn}
8064 and @code{dl} contain the vertical and horizontal size of the diversion.
8068 .\" Center text both horizontally & vertically
8079 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
8095 @cindex transparent output
8096 @cindex output, transparent
8098 @Defescx {\\?, , @Var{anything}, \\?}
8099 Prevents requests, macros and escapes from being
8100 interpreted when read into a diversion. This takes the given text
8101 and @dfn{transparently} embeds it into the diversion. This is useful for
8102 macros which shouldn't be invoked until the diverted text is actually
8105 @c XXX anything is read in copy mode. (what about \! ??)
8107 The @code{\!} escape transparently embeds text up to
8108 and including the end of the line.
8109 The @code{\?} escape transparently embeds text until the next
8110 occurrence of the @code{\?} escape. For example:
8117 @var{anything} may not contain newlines; use @code{\!} to embed
8118 newlines in a diversion. The escape sequence @code{\?} is also
8119 recognized in copy mode and turned into a single internal code; it is
8120 this code that terminates anything. Thus the following example
8127 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
8142 @cindex unformatting diversions
8143 @cindex diversion, unformatting
8144 @Defreq {asciify, div}
8145 @dfn{Unformats} the diversion specified by @var{div}
8146 in such a way that @acronym{ASCII} and space characters that
8147 were formatted and diverted are treated like ordinary input
8148 characters when the diversion is reread. It can be also used for gross
8149 hacks; for example, the following sets register @code{n} to@w{ }1.
8162 @xref{Copy-in Mode}.
8166 @c =====================================================================
8168 @node Environments, Suppressing output, Diversions, gtroff Reference
8169 @section Environments
8170 @cindex environments
8172 It happens frequently that some text should be printed in a certain
8173 format regardless of what may be in effect at the time, for example, in
8174 a trap invoked macro to print headers and footers. To solve this
8175 @code{gtroff} processes text in @dfn{environments}. An
8176 environment contains most of the parameters that control text
8177 processing. It is possible to switch amongst these environments; by
8178 default @code{gtroff} processes text in environment@w{ }0. The
8179 following is the information kept in an environment.
8183 font parameters (size, family, style, character height and slant, space
8184 and sentence space size)
8187 page parameters (line length, title length, vertical spacing,
8188 line spacing, indentation, line numbering, hyphenation data)
8191 fill and adjust mode
8194 tab stops, tab and leader characters, escape character, no-break and
8195 hyphen indicators, margin character data
8198 partially collected lines
8201 These environments may be given arbitrary names (see @ref{Identifiers},
8202 for more info). Old versions of @code{troff} only had environments
8203 named @samp{0}, @samp{1} and@w{ }@samp{2}.
8205 @cindex switch environments
8206 @cindex current environment number/name register
8209 Switches to another environment. The argument @var{env} is the name of
8210 the environment to switch to. With no argument, @code{gtroff} switches
8211 back to the previous environment. There is no limit on the number of
8212 named environments; they are created the first time that they are
8213 referenced. The @code{.ev} read-only register contains the name or
8214 number of the current environment. This is a string-valued register.
8216 Note that a call to @code{ev} (with argument) pushes the previously
8217 active environment onto a stack. If, say, environments @samp{foo},
8218 @samp{bar}, and @samp{zap} are called (in that order), the first
8219 @code{ev} request without parameter switches back to environment
8220 @samp{bar} (which is popped off the stack), and a second call
8221 switches back to environment @samp{foo}.
8227 ... page break macro, revised ...
8244 \(dg Note the large, friendly letters.
8249 @cindex copy environment
8251 Copies the environment @var{env} into the current environment.
8255 @c =====================================================================
8257 @node Suppressing output, I/O, Environments, gtroff Reference
8258 @section Suppressing output
8259 @cindex suppressing output
8261 @Defesc {\\O, , num, }
8262 Disables or enables output depending on the value of @var{num}:
8266 Disable any ditroff glyphs from being emitted to the device driver.
8269 Enable output of glyphs.
8276 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
8277 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
8278 @xref{Register Index}. These four registers mark the top left and
8279 bottom right hand corners of a box which encompasses all written glyphs.
8281 The following two forms of @code{\O} are specific to @code{grohtml}.
8285 Disable any ditroff glyphs from being emitted to the device driver. Also
8286 write out to @code{stderr} the page number and four registers encompassing
8287 the glyphs previously written since the last call to @code{\O}.
8290 Enable output of glyphs (the default). Also write out to @code{stderr}
8291 the page number and four registers encompassing the glyphs previously
8292 written since the last call to @code{\O}.
8297 @c =====================================================================
8299 @node I/O, Postprocessor Access, Suppressing output, gtroff Reference
8302 @cindex input and output requests
8303 @cindex requests for input and output
8304 @cindex output and input requests
8306 @code{gtroff} has several requests for including files:
8308 @cindex including a file
8309 @cindex file inclusion
8311 Reads in the specified @var{file} and
8312 includes it in place of the @code{so} request. This is quite useful for
8313 large documents, e.g.@: keeping each chapter in a separate file.
8314 @xref{gsoelim}, for more information.
8318 Identical to the @code{so} request except that @code{gtroff}
8319 searches for the specified
8320 @var{file} in the same directories as macro files for the
8321 the @option{-m} command line option. If the file name to be included
8322 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
8323 to include @file{tmac.@var{name}} and vice versa.
8326 @cindex transparent output
8327 @cindex output, transparent
8329 @Defreqx {trf, file}
8330 Transparently outputs the contents of @var{file}. Each line is output
8331 as it were preceded by @code{\!}; however, the lines are not subject to
8332 copy mode interpretation. If the file does not end with a newline, then
8333 a newline is added. For example, to define a macro@w{ }@code{x}
8334 containing the contents of file@w{ }@file{f}, use
8342 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
8343 embeds an object in the diversion which, when reread, causes the
8344 contents of @var{filename} to be transparently copied through to the
8347 In @acronym{UNIX} @code{troff}, the contents of @var{filename}
8348 is immediately copied through to the output regardless of whether there
8349 is a current diversion; this behaviour is so anomalous that it must be
8350 considered a bug. This request causes a line break.
8353 With @code{trf}, unlike @code{cf}, the file cannot contain characters
8354 such as NUL that are not valid @code{gtroff} input characters
8355 (@pxref{Identifiers}). This request causes a line break.
8359 Forces @code{gtroff} to continue processing of
8360 the file specified as an argument.
8364 The @code{rd} request reads from standard input, and includes what is
8365 read as though it were part of the input file. Text is read until a
8366 blank line is encountered.
8369 @cindex form letters
8370 @cindex letters, form
8371 Using the @code{nx} and @code{rd} requests,
8372 it is easy to set up form letters. The form
8373 letter template is constructed like this:
8391 When this is run, the following file should be redirected in. Note that
8392 requests included in this file are executed as though they were part of
8393 the form letter. The last block of input is the @code{ex} requests
8394 which tells groff to stop processing. If this was not there, groff
8395 would not know when to stop.
8399 708 NW 19th Av., #202
8414 Pipes the output of @code{gtroff} to the shell command(s)
8415 specified by @var{pipe}. This request must occur before
8416 @code{gtroff} has a chance to print anything.
8421 In @dfn{unsafe} mode, executes the shell command(s) specified by
8422 @var{cmds}. The output is not saved anyplace, so it is up to the user
8425 @c XXX add info about safer and unsafe mode
8427 For example, the following example introduces the current time
8430 @cindex time, current
8431 @cindex current time
8434 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
8435 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
8442 Note that this works by having the @code{perl} script (run by @code{sy})
8443 print out the @code{nr} requests which set the number registers
8444 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
8445 the @code{so} request.
8447 @cindex @code{system()} return value register
8448 The @code{systat} read-write number register contains the return value
8449 of the @code{system()} function executed by the last @code{sy} request.
8452 @Defreq {open, stream file}
8453 @Defreqx {opena, stream file}
8454 Opens the specified @var{file} for writing and
8455 associates the specified @var{stream} with it.
8457 The @code{opena} is like @code{open}, but if the file exists, append to
8458 it instead of truncating it.
8461 @cindex copy-in mode, and @code{write} requests
8462 @cindex mode, copy-in, and @code{write} requests
8463 @Defreq {write, stream data}
8464 Writes to the file associated with the specified @var{stream}.
8465 The stream must previously have
8466 been the subject of an open request. The remainder of the line is
8467 interpreted as the @code{ds} request reads its second argument: A
8468 leading @samp{"} is stripped, and it is read in copy-in mode.
8471 @Defreq {close, stream}
8472 Closes the specified @var{stream};
8473 the stream is no longer an acceptable argument to the
8474 @code{write} request.
8480 ... example of open write &c...
8485 @Defesc {\\V, ', xxx, '}
8486 Interpolates the contents of the specified
8487 environment variable, as returned by the function @code{getenv}.
8488 Specify the argument to @code{\V} as an identifier, i.e.@:
8489 @samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V}
8490 is interpreted in copy-in mode.
8494 @c =====================================================================
8496 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
8497 @section Postprocessor Access
8498 @cindex postprocessor access
8499 @cindex access of postprocessor
8501 There are two escapes which give information directly to the
8502 postprocessor. This is particularly useful for embedding
8503 @sc{PostScript} into the final document.
8505 @Defesc {\\X, ', xxx, '}
8506 Embeds its argument into the @code{gtroff}
8507 output preceded with @w{@samp{x X}}.
8510 @Defesc {\\Y, ', xxx, '}
8511 The @code{\Y} escape is called with an identifier (i.e.@:
8512 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
8513 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
8514 contents of the string or macro @var{xxx} are not interpreted; also it
8515 is permitted for @var{xxx} to have been defined as a macro and thus
8516 contain newlines (it is not permitted for the argument to @code{\X} to
8517 contain newlines). The inclusion of newlines requires an extension to
8518 the @acronym{UNIX} @code{troff} output format, and confuses drivers
8519 that do not know about this extension.
8522 @xref{Output Devices}.
8525 @c =====================================================================
8527 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
8528 @section Miscellaneous
8529 @cindex miscellaneous
8531 This section documents parts of @code{gtroff} which cannot (yet) be
8532 categorized elsewhere in this manual.
8534 @cindex line numbers
8535 @cindex numbers, line
8536 @Defreq {nm, start inc space indent}
8537 Prints line numbers in the left margin.
8538 @var{start} is the line number of the @emph{next}
8539 output line; this defaults to@w{ }1. @var{inc} indicates on
8540 which lines numbers are printed, i.e.@: 5 means put line numbers on
8541 every 5@w{ }lines; this defaults to@w{ }1. @var{space} is the
8542 space to be left between the number and the text; this defaults to@w{
8543 }1. The fourth argument is the indentation of the line numbers.
8544 Without arguments, line numbers are turned off.
8547 @c XXX xref ln register
8549 @Defreq {nn, [@Var{skip}]}
8550 Temporarily turns off line numbering. The
8551 argument is the number of lines not to be numbered; this defaults
8554 @c XXX (does this disable incrementing or display?)
8560 ... line numbering example ...
8565 @cindex margin characters
8566 @cindex characters for margins
8567 @Defreq {mc, char dist}
8568 Prints margin characters to the right of the text.
8569 The first argument is the character to be
8570 printed, and the second argument is the distance away from the main body
8571 text. With no arguments the margin characters are turned off. If this
8572 occurs before a break, no margin character is printed.
8576 This is quite useful for indicating text that has changed, and, in fact,
8577 there are programs available for doing this (they are called
8578 @code{nrchbar} and @code{changebar} and can be found in any
8579 @samp{comp.sources.unix} archive.
8585 ... margin char example ...
8591 @cindex multi-file documents
8592 @cindex documents, multi-file
8593 @Defreq {lf, line filename}
8595 documents which are split into many files, then put together
8596 with @code{soelim} and other preprocessors. The second argument is the
8597 name of the file and the first argument is the input line number in
8598 that file. This way @code{gtroff} can produce error messages which are
8599 intelligible to the user.
8605 ... example of soelim'ed doc ...
8611 @c =====================================================================
8613 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
8614 @section @code{gtroff} Internals
8617 @cindex token, input
8619 @cindex node, output
8620 @code{gtroff} processes input in three steps. One or more input
8621 characters are converted to an @dfn{input token}. Then, one or more
8622 input tokens are converted to an @dfn{output node}. Finally, output
8623 nodes are converted to the intermediate output language understood by
8626 For example, the input string @samp{fi\[:u]} is converted in a
8627 character token @samp{f}, a character token @samp{i}, and a special
8628 token @samp{:u} (representing u@w{ }umlaut). Later on, the character
8629 tokens @samp{f} and @samp{i} are merged to a single output node
8630 representing the ligature glyph @samp{fi}; the same happens with
8631 @samp{:u}. All output glyph nodes are `processed' which means that
8632 they are invariably associated with a given font, font size, advance
8633 width, etc. During the formatting process, @code{gtroff} itself adds
8634 various nodes to control the data flow.
8636 Macros, diversions, and strings collect elements in two chained lists:
8637 a list of input tokens which have been passed unprocessed, and a list
8638 of output nodes. Consider the following the diversion.
8650 It contains these elements.
8652 @multitable {@i{vertical size node}} {token list} {element number}
8653 @item node list @tab token list @tab element number
8655 @item @i{line start node} @tab --- @tab 1
8656 @item @i{glyph node @code{a}} @tab --- @tab 2
8657 @item @i{word space node} @tab --- @tab 3
8658 @item --- @tab @code{b} @tab 4
8659 @item --- @tab @code{\n} @tab 5
8660 @item @i{glyph node @code{c}} @tab --- @tab 6
8661 @item @i{vertical size node} @tab --- @tab 7
8662 @item @i{vertical size node} @tab --- @tab 8
8663 @item --- @tab @code{\n} @tab 9
8669 Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two
8670 (which are always present) specify the vertical extent of the last
8671 line, possibly modified by @code{\v}. The @code{br} request finishes
8672 the current partial line, inserting a newline input token which is
8673 subsequently converted to a space when the diversion is reread. Note
8674 that the word space node has a fixed width which isn't stretchable
8675 anymore. To convert horizontal space nodes back to input tokens, use
8676 the @code{unformat} request.
8678 Macros only contain elements in the token list (and the node list is
8679 empty); diversions and strings can contain elements in both lists.
8682 @c =====================================================================
8684 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
8688 @code{gtroff} is not easy to debug, but there are some useful features
8689 and strategies for debugging.
8691 @Defreq {tm, string}
8692 Sends the @var{string} to the standard error stream;
8693 this is very useful for printing debugging output among other things.
8697 @Defreq {ab, [@Var{string}]}
8698 Similar to the @code{tm} request, except that
8699 it causes @code{gtroff} to stop processing. With no argument it
8700 prints @samp{User Abort}.
8703 @cindex @code{ex}, use in debugging
8706 The @code{ex} request also causes @code{gtroff} to stop processing
8707 if encountered at the topmost level; see also @ref{I/O}.
8710 When doing something involved it is useful to leave the debugging
8711 statements in the code and have them turned on by a command line flag.
8714 .if \n(DB .tm debugging output
8718 To activate these statements say
8724 @c XXX .tm1, .tmc requests
8726 If it is known in advance that there will be many errors and no useful
8727 output, @code{gtroff} can be forced to suppress formatted output with
8728 the @option{-z} flag.
8730 @cindex dumping symbol table
8731 @cindex symbol table, dumping
8733 The @code{pm} request prints out the entire symbol table on @code{stderr}.
8736 @cindex dumping number registers
8737 @cindex number registers, dumping
8739 Prints the names and contents of all
8740 currently defined number registers on @code{stderr}.
8743 @cindex dumping traps
8744 @cindex traps, dumping
8746 Prints the names and positions of all traps
8747 (not including input line traps and diversion traps) on @code{stderr}.
8748 Empty slots in the page trap list are printed as well, because they can
8749 affect the priority of subsequently planted traps.
8752 @cindex flush output
8753 @cindex output, flush
8754 @cindex interactive use of @code{gtroff}
8755 @cindex @code{gtroff}, interactive use
8757 Instructs @code{gtroff} to flush its output
8758 immediately. The intent is for interactive use.
8759 @code{gtroff}; there is little other use for it. This
8760 request causes a line break.
8763 @cindex backtrace of input stack
8764 @cindex input stack, backtrace
8765 @Defreq {backtrace, }
8766 The @code{backtrace} request prints a backtrace of the input stack
8767 to the standard error stream.
8771 @code{gtroff} has command line options for printing out more warnings
8772 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
8773 or an error occurs. The most verbose level of warnings is @option{-ww}.
8775 @cindex level of warnings
8776 @cindex warnings, level
8777 @Defreq {warn, [@Var{flags}]}
8779 Controls the level of warnings checked for. The @var{flags} are the sum
8780 of the numbers associated with each warning that is to be enabled; all
8781 other warnings are disabled. The number associated with each warning is
8782 listed below. For example, @w{@code{.warn 0}} disables all warnings,
8783 and @w{@code{.warn 1}} disables all warnings except that about missing
8784 characters. If an argument is not given, all warnings are enabled.
8786 The read-only number register @code{.warn} contains the current warning
8794 @c ---------------------------------------------------------------------
8796 @node Warnings, , Debugging, Debugging
8797 @subsection Warnings
8800 The warnings that can be given to @code{gtroff} are divided into the
8801 following categories. The name associated with each warning is used by
8802 the @option{-w} and @option{-W} options; the number is used by the
8803 @code{warn} request and by the @code{.warn} register.
8808 Non-existent characters. This is enabled by default.
8812 Invalid numeric expressions. This is enabled by default.
8819 In fill mode, lines which could not be broken so that their length was
8820 less than the line length. This is enabled by default.
8824 Missing or mismatched closing delimiters.
8830 Use of the @code{el} request with no matching @code{ie} request.
8835 Meaningless scaling indicators.
8839 Out of range arguments.
8843 Dubious syntax in numeric expressions.
8849 @cindex @code{di}, debugging
8850 @cindex @code{da}, debugging
8851 Use of @code{di} or @code{da} without an argument when there is no
8857 @c XXX more index entries
8858 Use of undefined strings, macros and diversions. When an undefined
8859 string, macro or diversion is used, that string is automatically defined
8860 as empty. So, in most cases, at most one warning is given for each
8866 @c XXX more index entries
8867 Use of undefined number registers. When an undefined number register is
8868 used, that register is automatically defined to have a value of@w{ }0.
8869 A definition is automatically made with a value of@w{ }0. So, in most
8870 cases, at most one warning is given for use of a particular name.
8874 Use of a tab character where a number was expected.
8879 @cindex @code{\@}}, debugging
8880 Use of @code{\@}} where a number was expected.
8884 Requests that are missing non-optional arguments.
8888 Illegal input characters.
8892 Unrecognized escape sequences. When an unrecognized escape sequence is
8893 encountered, the escape character is ignored.
8897 @cindex compatibility mode
8898 Missing space between a request or macro and its argument. This warning
8899 is given when an undefined name longer than two characters is
8900 encountered, and the first two characters of the name make a defined
8901 name. The request or macro is not invoked. When this warning is
8902 given, no macro is automatically defined. This is enabled by default.
8903 This warning never occurs in compatibility mode.
8907 Non-existent fonts. This is enabled by default.
8910 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
8911 intended that this covers all warnings that are useful with traditional
8919 @c =====================================================================
8921 @node Implementation Differences, Summary, Debugging, gtroff Reference
8922 @section Implementation Differences
8923 @cindex implementation differences
8924 @cindex differences in implementation
8925 @cindex incompatibilities with Unix @code{troff}
8926 @cindex compatibility mode
8927 @cindex mode, compatibility
8929 GNU @code{troff} has a number of features which cause incompatibilities
8930 with documents written with old versions of @code{troff}.
8934 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
8943 @cindex @code{\*}, incompatibilities with Unix @code{troff}
8944 @cindex @code{\n}, incompatibilities with Unix @code{troff}
8948 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
8949 @code{troff} interprets this as a call of a macro named
8950 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
8951 @code{\*[} or @code{\n[} as references to a string or number register
8952 called @samp{[}. In GNU @code{troff}, however, this is normally
8953 interpreted as the start of a long name. In compatibility mode GNU
8954 @code{troff} interprets long names in the traditional way
8955 (which means that they are not recognized as names).
8956 Compatibility mode can be turned on with the @option{-C} command line
8957 option, and turned on or off with the @code{cp} request. The number
8958 register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{
8975 GNU @code{troff} does not allow the use of the escape sequences
8976 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
8977 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
8978 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
8979 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
8980 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
8981 avoiding use of these escape sequences in names.
8983 @cindex fractional point sizes
8984 @cindex point sizes, fractional
8986 @cindex @code{ps}, incompatibilities with Unix @code{troff}
8987 Fractional point sizes cause one noteworthy incompatibility. In
8988 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
8996 sets the point size to 10@w{ }points, whereas in GNU @code{troff} it
8997 sets the point size to 10@w{ }scaled points. @xref{Fractional Type
8998 Sizes}, for more information.
9005 @cindex @code{bd}, incompatibilities with Unix @code{troff}
9006 @cindex @code{cs}, incompatibilities with Unix @code{troff}
9007 @cindex @code{tkf}, incompatibilities with Unix @code{troff}
9008 @cindex @code{tr}, incompatibilities with Unix @code{troff}
9009 @cindex @code{fp}, incompatibilities with Unix @code{troff}
9010 @cindex input and output characters, compatibility with Unix
9011 @cindex output characters, compatibility with Unix
9012 @cindex characters, input and output, compatibility with Unix
9013 In GNU @code{troff} there is a fundamental difference between
9014 unformatted, input characters, and formatted, output characters.
9015 Everything that affects how an output character is output is stored
9016 with the character; once an output character has been constructed it is
9017 unaffected by any subsequent requests that are executed, including
9018 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
9019 Normally output characters are constructed from input characters at the
9020 moment immediately before the character is added to the current output
9021 line. Macros, diversions and strings are all, in fact, the same type of
9022 object; they contain lists of input characters and output characters in
9023 any combination. An output character does not behave like an input
9024 character for the purposes of macro processing; it does not inherit any
9025 of the special properties that the input character from which it was
9026 constructed might have had. For example,
9039 @cindex @code{\e}, incompatibilities with Unix @code{troff}
9040 @cindex @code{\!}, incompatibilities with Unix @code{troff}
9041 @cindex @code{\?}, incompatibilities with Unix @code{troff}
9042 @cindex transparent output, incompatibilities with Unix @code{troff}
9043 @cindex output, transparent, incompatibilities with Unix @code{troff}
9045 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
9046 is turned into one output backslash and the resulting output backslashes
9047 are not interpreted as escape characters when they are reread.
9048 @acronym{UNIX} @code{troff} would interpret them as escape characters
9049 when they were reread and would end up printing one @samp{\}. The
9050 correct way to obtain a printable backslash is to use the @code{\e}
9051 escape sequence: This always prints a single instance of the current
9052 escape character, regardless of whether or not it is used in a
9053 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
9054 @code{troff}. To store, for some reason, an escape sequence in a
9055 diversion that will be interpreted when the diversion is reread, either
9056 use the traditional @code{\!} transparent output facility, or, if this
9057 is unsuitable, the new @code{\?} escape sequence.
9059 @c XXX .tl compatibility mode -> input stack level
9060 @c XXX .if compatibility mode -> input stack level
9062 @xref{Diversions}, for more information.
9065 @c =====================================================================
9067 @node Summary, , Implementation Differences, gtroff Reference
9071 @c XXX documentation
9075 @c =====================================================================
9076 @c =====================================================================
9078 @node Preprocessors, Output Devices, gtroff Reference, Top
9079 @chapter Preprocessors
9080 @cindex preprocessors
9082 This chapter describes all preprocessors that come with @code{groff} or
9083 which are freely available.
9096 @c =====================================================================
9098 @node geqn, gtbl, Preprocessors, Preprocessors
9099 @section @code{geqn}
9109 @c ---------------------------------------------------------------------
9111 @node Invoking geqn, , geqn, geqn
9112 @subsection Invoking @code{geqn}
9113 @cindex invoking @code{geqn}
9114 @cindex @code{geqn}, invoking
9119 @c =====================================================================
9121 @node gtbl, gpic, geqn, Preprocessors
9122 @section @code{gtbl}
9132 @c ---------------------------------------------------------------------
9134 @node Invoking gtbl, , gtbl, gtbl
9135 @subsection Invoking @code{gtbl}
9136 @cindex invoking @code{gtbl}
9137 @cindex @code{gtbl}, invoking
9142 @c =====================================================================
9144 @node gpic, ggrn, gtbl, Preprocessors
9145 @section @code{gpic}
9155 @c ---------------------------------------------------------------------
9157 @node Invoking gpic, , gpic, gpic
9158 @subsection Invoking @code{gpic}
9159 @cindex invoking @code{gpic}
9160 @cindex @code{gpic}, invoking
9165 @c =====================================================================
9167 @node ggrn, grap, gpic, Preprocessors
9168 @section @code{ggrn}
9178 @c ---------------------------------------------------------------------
9180 @node Invoking ggrn, , ggrn, ggrn
9181 @subsection Invoking @code{ggrn}
9182 @cindex invoking @code{ggrn}
9183 @cindex @code{ggrn}, invoking
9188 @c =====================================================================
9190 @node grap, grefer, ggrn, Preprocessors
9191 @section @code{grap}
9194 A free implementation of @code{grap}, written by Ted Faber,
9195 is available as an extra package from the following address:
9198 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
9202 @c =====================================================================
9204 @node grefer, gsoelim, grap, Preprocessors
9205 @section @code{grefer}
9206 @cindex @code{refer}
9207 @cindex @code{grefer}
9215 @c ---------------------------------------------------------------------
9217 @node Invoking grefer, , grefer, grefer
9218 @subsection Invoking @code{grefer}
9219 @cindex invoking @code{grefer}
9220 @cindex @code{grefer}, invoking
9225 @c =====================================================================
9227 @node gsoelim, , grefer, Preprocessors
9228 @section @code{gsoelim}
9229 @cindex @code{soelim}
9230 @cindex @code{gsoelim}
9235 * Invoking gsoelim::
9238 @c ---------------------------------------------------------------------
9240 @node Invoking gsoelim, , gsoelim, gsoelim
9241 @subsection Invoking @code{gsoelim}
9242 @cindex invoking @code{gsoelim}
9243 @cindex @code{gsoelim}, invoking
9249 @c =====================================================================
9250 @c =====================================================================
9252 @node Output Devices, File formats, Preprocessors, Top
9253 @chapter Output Devices
9254 @cindex output devices
9255 @cindex devices for output
9260 * Special Characters::
9271 @c =====================================================================
9273 @node Special Characters, grotty, Output Devices, Output Devices
9274 @section Special Characters
9275 @cindex special characters
9276 @cindex characters, special
9283 @c =====================================================================
9285 @node grotty, grops, Special Characters, Output Devices
9286 @section @code{grotty}
9287 @cindex @code{grotty}
9295 @c ---------------------------------------------------------------------
9297 @node Invoking grotty, , grotty, grotty
9298 @subsection Invoking @code{grotty}
9299 @cindex invoking @code{grotty}
9300 @cindex @code{grotty}, invoking
9305 @c =====================================================================
9307 @node grops, grodvi, grotty, Output Devices
9308 @section @code{grops}
9309 @cindex @code{grops}
9315 * Embedding PostScript::
9318 @c ---------------------------------------------------------------------
9320 @node Invoking grops, Embedding PostScript, grops, grops
9321 @subsection Invoking @code{grops}
9322 @cindex invoking @code{grops}
9323 @cindex @code{grops}, invoking
9327 @c ---------------------------------------------------------------------
9329 @node Embedding PostScript, , Invoking grops, grops
9330 @subsection Embedding @sc{PostScript}
9331 @cindex embedding postscript
9332 @cindex postscript, embedding
9337 @c =====================================================================
9339 @node grodvi, grolj4, grops, Output Devices
9340 @section @code{grodvi}
9341 @cindex @code{grodvi}
9349 @c ---------------------------------------------------------------------
9351 @node Invoking grodvi, , grodvi, grodvi
9352 @subsection Invoking @code{grodvi}
9353 @cindex invoking @code{grodvi}
9354 @cindex @code{grodvi}, invoking
9359 @c =====================================================================
9361 @node grolj4, grolbp, grodvi, Output Devices
9362 @section @code{grolj4}
9363 @cindex @code{grolj4}
9371 @c ---------------------------------------------------------------------
9373 @node Invoking grolj4, , grolj4, grolj4
9374 @subsection Invoking @code{grolj4}
9375 @cindex invoking @code{grolj4}
9376 @cindex @code{grolj4}, invoking
9381 @c =====================================================================
9383 @node grolbp, grohtml, grolj4, Output Devices
9384 @section @code{grolbp}
9385 @cindex @code{grolbp}
9393 @c ---------------------------------------------------------------------
9395 @node Invoking grolbp, , grolbp, grolbp
9396 @subsection Invoking @code{grolbp}
9397 @cindex invoking @code{grolbp}
9398 @cindex @code{grolbp}, invoking
9403 @c =====================================================================
9405 @node grohtml, gxditview, grolbp, Output Devices
9406 @section @code{grohtml}
9407 @cindex @code{grohtml}
9412 * Invoking grohtml::
9415 @c ---------------------------------------------------------------------
9417 @node Invoking grohtml, , grohtml, grohtml
9418 @subsection Invoking @code{grohtml}
9419 @cindex invoking @code{grohtml}
9420 @cindex @code{grohtml}, invoking
9425 @c =====================================================================
9427 @node gxditview, , grohtml, Output Devices
9428 @section @code{gxditview}
9429 @cindex @code{gxditview}
9434 * Invoking gxditview::
9437 @c ---------------------------------------------------------------------
9439 @node Invoking gxditview, , gxditview, gxditview
9440 @subsection Invoking @code{gxditview}
9441 @cindex invoking @code{gxditview}
9442 @cindex @code{gxditview}, invoking
9449 @c =====================================================================
9450 @c =====================================================================
9452 @node File formats, Installation, Output Devices, Top
9453 @chapter File formats
9454 @cindex file formats
9455 @cindex formats, file
9465 @c =====================================================================
9467 @node gtroff Output, Font Files, File formats, File formats
9468 @section @code{gtroff} Output
9469 @cindex @code{gtroff} output
9470 @cindex output, @code{gtroff}
9472 This section describes the format output of GNU @code{troff}. The
9473 output format used by GNU @code{troff} is very similar -- but
9474 not identical -- to that used by
9475 @acronym{UNIX} device-independent @code{troff} (@code{ditroff}).
9480 * Drawing Functions::
9481 * Line Continuation::
9484 @c ---------------------------------------------------------------------
9486 @node Output Format, Device Control, gtroff Output, gtroff Output
9487 @subsection Output Format
9488 @cindex output format
9489 @cindex format of output
9492 @cindex input, 8-bit
9493 The output format is text based, as opposed to a binary format (like
9494 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
9495 characters can have the eighth bit set, as can the names of fonts and
9498 The output format consists of single command characters with attached
9499 parameters which are separated from subsequent text by whitespace or a
9502 The names of characters and fonts can be of arbitrary length; drivers
9503 should not assume that they are only two characters long (as
9504 @code{ditroff} does).
9506 When a character is to be printed, that character is always in the
9507 current font. Unlike @code{ditroff}, it is not necessary for drivers to
9508 search special fonts to find a character.
9529 @item @var{nn}@var{c}
9533 @var{xxx} is any sequence of characters terminated by a space or a
9534 newline; the first character should be printed at the current position,
9535 the the current horizontal position should be increased by the width of
9536 the first character, and so on for each character. The width of the
9537 character is that given in the font file, appropriately scaled for the
9538 current point size, and rounded so that it is a multiple of the
9539 horizontal resolution. Special characters cannot be printed using this
9543 @pindex DESC@r{, and @code{tcommand}}
9544 This command is only allowed if the @samp{tcommand} line is present in
9545 the @file{DESC} file.
9547 @item u@var{n} @var{xxx}
9548 This is same as the @samp{t} command except that after printing each
9549 character, the current horizontal position is increased by the sum of
9550 the width of that character and@w{ }@var{n}.
9552 This command is only allowed if the @samp{tcommand} line is present in
9553 the @file{DESC} file.
9555 @item n@var{a}@var{b}
9563 @pindex DESC@r{, and @code{sizescale}}
9564 The argument to the @samp{s} command is in scaled points (units of
9565 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
9566 command in the @file{DESC} file).
9573 @item D@var{c} @var{x}@dots{}\n
9577 @c ---------------------------------------------------------------------
9579 @node Device Control, Drawing Functions, Output Format, gtroff Output
9580 @subsection Device Control
9581 @cindex device control
9582 @cindex control of devices
9584 The @samp{x} command is normally followed by a letter or word indicating
9585 the function to perform, followed by white space separated arguments.
9587 The first argument can be abbreviated to the first letter.
9596 @item x res @var{n} @var{h} @var{v}
9601 The argument to the @w{@samp{x Height}} command is also in scaled
9605 The first three output commands are guaranteed to be:
9614 For example, the input
9617 crunchy \fH\s+2frog\s0\fP!?
9627 ... sample output here ...
9631 @c ---------------------------------------------------------------------
9633 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
9634 @subsection Drawing Functions
9635 @cindex drawing functions
9636 @cindex functions for drawing
9639 The @samp{D} drawing command has been extended. These extensions are
9640 used by GNU @code{pic} only if the @option{-x} option is given.
9642 @xref{Drawing Requests}.
9647 Set the shade of gray to be used for filling solid objects to@w{
9648 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
9649 corresponds solid white and 1000 to solid black, and values in between
9650 correspond to intermediate shades of gray. This applies only to solid
9651 circles, solid ellipses and solid polygons. By default, a level of@w{
9652 }1000 is used. Whatever color a solid object has, it should
9653 completely obscure everything beneath it. A value greater than@w{ }1000
9654 or less than@w{ }0 can also be used: this means fill with the shade of
9655 gray that is currently being used for lines and text. Normally this
9656 is black, but some drivers may provide a way of changing this.
9659 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
9660 point at the current position.
9662 @item DE @var{dx} @var{dy}
9663 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
9664 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
9667 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
9668 Draw a polygon with automatic closure. The first vertex is at the
9669 current position, the second vertex at an offset (@var{dx1},@var{dy1})
9670 from the current position, the second vertex at an offset
9671 (@var{dx2},@var{dy2}) from the first vertex, and so on up to the
9672 @var{n}@dmn{th} vertex. At the moment, GNU @code{pic} only uses this
9673 command to generate triangles and rectangles.
9675 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
9676 Like @code{Dp} but draw a solid rather than outlined polygon.
9679 @cindex line thickness
9680 @cindex thickness of lines
9681 Set the current line thickness to @var{n}@w{ }machine units.
9682 Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness
9683 proportional to the current point size; drivers should continue to do
9684 this if no @code{Dt} command has been given, or if a @code{Dt} command
9685 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
9686 }@var{n} selects the smallest available line thickness.
9690 A difficulty arises in how the current position should be changed after
9691 the execution of these commands. This is not of great importance since
9692 the code generated by GNU @code{pic} does not depend on this. Given a
9693 drawing command of the form
9696 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
9703 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
9704 @samp{~}, @acronym{UNIX} @code{troff} treats each x@w{ }value
9705 as a horizontal quantity, and each y@w{ }value as a vertical
9706 quantity; it assumes that the width of the drawn object is the sum of
9707 all x@w{ }values, and that the height is the sum of all y@w{ }values.
9708 (The assumption about the height can be seen by examining the @code{st}
9709 and @code{sb} registers after using such a @code{D}@w{ }command in a
9710 @code{\w} escape sequence.) This rule also holds for all the original
9711 drawing commands with the exception of @code{De}. For the sake of
9712 compatibility GNU @code{troff} also follows this rule, even though it
9713 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
9714 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
9715 @code{D}@w{ }command of the form
9718 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
9722 the current position should be increased horizontally by the sum of all
9723 x@w{ }values and vertically by the sum of all y@w{ }values.
9725 @c ---------------------------------------------------------------------
9727 @node Line Continuation, , Drawing Functions, gtroff Output
9728 @subsection Line Continuation
9729 @cindex line continuation in output commands
9730 @cindex output commands, line continuation
9732 There is a continuation convention which permits the argument to the
9733 @w{@samp{x X}} command to contain newlines: When outputting the argument
9734 to the @w{@samp{x X}} command, GNU @code{troff} follows each newline
9735 in the argument with a @samp{+} character (as usual, it terminates
9736 the entire argument with a newline); thus if the line after the line
9737 containing the @w{@samp{x X}} command starts with @samp{+}, then the
9738 newline ending the line containing the @w{@samp{x X}} command should be
9739 treated as part of the argument to the @w{@samp{x X}} command, the
9740 @samp{+} should be ignored, and the part of the line following the
9741 @samp{+} should be treated like the part of the line following the
9742 @w{@samp{x X}} command.
9745 @c =====================================================================
9747 @node Font Files, , gtroff Output, File formats
9752 The @code{gtroff} font format is roughly a superset of the
9753 @code{ditroff} font format. Unlike the @code{ditroff} font format,
9754 there is no associated binary format; all files are text files. The
9755 font files for device @var{name} are stored in a directory
9756 @file{dev@var{name}}. There are two types of file: a device description
9757 file called @file{DESC} and for each font@w{ }@var{f} a font file
9758 called@w{ }@file{@var{f}}.
9761 * DESC File Format::
9762 * Font File Format::
9765 @c ---------------------------------------------------------------------
9767 @node DESC File Format, Font File Format, Font Files, Font Files
9768 @subsection @file{DESC} File Format
9769 @cindex @file{DESC} file format
9770 @cindex font description file format
9771 @cindex format of font description file
9772 @pindex DESC@r{ file format}
9774 The @file{DESC} file can contain the following types of line:
9779 There are @var{n} machine units per inch.
9783 The horizontal resolution is @var{n} machine units.
9787 The vertical resolution is @var{n} machine units.
9789 @item sizescale @var{n}
9791 The scale factor for point sizes. By default this has a value of@w{ }1.
9792 One scaled point is equal to one point/@var{n}. The arguments to the
9793 @code{unitwidth} and @code{sizes} commands are given in scaled points.
9794 @xref{Fractional Type Sizes}, for more information.
9796 @item unitwidth @var{n}
9798 Quantities in the font files are given in machine units for fonts whose
9799 point size is @var{n}@w{ }scaled points.
9803 This means that the postprocessor can handle the @samp{t} and @samp{u}
9806 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
9808 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
9809 @var{sn} scaled points. The list of sizes must be terminated by a@w{
9810 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
9811 list can extend over more than one line.
9813 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
9815 The first @var{m}@w{ }font positions are associated with styles
9816 @var{S1} @dots{} @var{Sm}.
9818 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
9820 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
9821 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
9822 styles. This command may extend over more than one line. A font name
9823 of@var{ }0 means no font is mounted on the corresponding font position.
9825 @item family @var{fam}
9827 The default font family is @var{fam}.
9831 This line and everything following in the file are ignored. It is
9832 allowed for the sake of backwards compatibility.
9835 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
9836 are mandatory. Other commands are ignored by @code{gtroff} but may be
9837 used by postprocessors to store arbitrary information about the device
9838 in the @file{DESC} file.
9840 @c XXX add other commands resp. xrefs to output devices
9841 @c XXX add obsolete commands
9843 @c ---------------------------------------------------------------------
9845 @node Font File Format, , DESC File Format, Font Files
9846 @subsection Font File Format
9847 @cindex font file format
9848 @cindex format of font files
9850 A font file has two sections. The first section is a sequence of lines
9851 each containing a sequence of blank delimited words; the first word in
9852 the line is a key, and subsequent words give a value for that key.
9857 The name of the font is@w{ }@var{f}.
9859 @item spacewidth @var{n}
9861 The normal width of a space is@w{ }@var{n}.
9865 The characters of the font have a slant of @var{n}@w{ }degrees.
9866 (Positive means forward.)
9868 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
9870 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
9871 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
9872 @samp{ffl}. For backwards compatibility, the list of ligatures may be
9873 terminated with a@w{ }0. The list of ligatures may not extend over more
9878 The font is special; this means that when a character is requested that
9879 is not present in the current font, it is searched for in any
9880 special fonts that are mounted.
9883 Other commands are ignored by @code{gtroff} but may be used by
9884 postprocessors to store arbitrary information about the font in the font
9887 @cindex comments in font files
9888 @cindex font files, comments
9890 The first section can contain comments which start with the @samp{#}
9891 character and extend to the end of a line.
9893 The second section contains one or two subsections. It must contain a
9894 @code{charset} subsection and it may also contain a @code{kernpairs}
9895 subsection. These subsections can appear in any order. Each
9896 subsection starts with a word on a line by itself.
9899 The word @code{charset} starts the character set subsection. The
9900 @code{charset} line is followed by a sequence of lines. Each line gives
9901 information for one character. A line comprises a number of fields
9902 separated by blanks or tabs. The format is
9904 @c XXX fix it for new HTML additions
9907 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
9911 @cindex input, 8-bit
9915 @var{name} identifies the character: If @var{name} is a single
9916 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
9917 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
9918 a single character, then it corresponds to the @code{gtroff} input
9919 character@w{ }\@var{c}; otherwise it corresponds to the groff input
9920 character @samp{\[@var{name}]}. (If it is exactly two characters
9921 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
9922 supports 8-bit characters; however some utilities have difficulties with
9923 eight-bit characters. For this reason, there is a convention that the
9924 name @samp{char@var{n}} is equivalent to the single character whose code
9925 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
9926 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
9927 Latin-1} character set. The name @samp{---} is special and indicates
9928 that the character is unnamed; such characters can only be used by means
9929 of the @code{\N} escape sequence in @code{gtroff}.
9931 @c XXX input encodings vs. output encodings
9933 The @var{type} field gives the character type:
9937 the character has an descender, for example, `p';
9940 the character has an ascender, for example, `b';
9943 the character has both an ascender and a descender, for example, `('.
9946 The @var{code} field gives the code which the postprocessor uses to
9947 print the character. The character can also be input to @code{gtroff}
9948 using this code by means of the @code{\N} escape sequence. The code can
9949 be any integer. If it starts with @samp{0} it is interpreted as
9950 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
9953 Anything on the line after the @var{code} field is ignored.
9955 The @var{metrics} field has the form:
9958 @var{width}[,@var{height}[,@var{depth}[,@var{italic_correction}
9959 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]]
9963 There must not be any spaces between these subfields (it has been split
9964 here into two lines for better legibility only). Missing subfields are
9965 assumed to be@w{ }0. The subfields are all decimal integers. Since
9966 there is no associated binary format, these values are not required to
9967 fit into a variable of type @samp{char} as they are in @code{ditroff}.
9968 The @var{width} subfield gives the width of the character. The
9969 @var{height} subfield gives the height of the character (upwards is
9970 positive); if a character does not extend above the baseline, it should
9971 be given a zero height, rather than a negative height. The @var{depth}
9972 subfield gives the depth of the character, that is, the distance below
9973 the lowest point below the baseline to which the character extends
9974 (downwards is positive); if a character does not extend below above the
9975 baseline, it should be given a zero depth, rather than a negative depth.
9976 The @var{italic_correction} subfield gives the amount of space that
9977 should be added after the character when it is immediately to be
9978 followed by a character from a roman font. The
9979 @var{left_italic_correction} subfield gives the amount of space that
9980 should be added before the character when it is immediately to be
9981 preceded by a character from a roman font. The
9982 @var{subscript_correction} gives the amount of space that should be
9983 added after a character before adding a subscript. This should be less
9984 than the italic correction.
9986 A line in the @code{charset} section can also have the format
9993 This indicates that @var{name} is just another name for the character
9994 mentioned in the preceding line.
9997 The word @code{kernpairs} starts the kernpairs section. This contains a
9998 sequence of lines of the form:
10001 @var{c1} @var{c2} @var{n}
10005 This means that when character @var{c1} appears next to character
10006 @var{c2} the space between them should be increased by@w{ }@var{n}.
10007 Most entries in the kernpairs section have a negative value for@w{
10012 @c =====================================================================
10013 @c =====================================================================
10015 @node Installation, Request Index, File formats, Top
10016 @chapter Installation
10017 @cindex installation
10023 @c =====================================================================
10024 @c =====================================================================
10026 @node Request Index, Escape Index, Installation, Top
10027 @chapter Request Index
10029 Requests appear without the leading control character (normally either
10030 @samp{.} or @samp{'}).
10036 @c =====================================================================
10037 @c =====================================================================
10039 @node Escape Index, Operator Index, Request Index, Top
10040 @chapter Escape Index
10046 @c =====================================================================
10047 @c =====================================================================
10049 @node Operator Index, Register Index, Escape Index, Top
10050 @chapter Operator Index
10056 @c =====================================================================
10057 @c =====================================================================
10059 @node Register Index, Macro Index, Operator Index, Top
10060 @chapter Register Index
10066 @c =====================================================================
10067 @c =====================================================================
10069 @node Macro Index, String Index, Register Index, Top
10070 @chapter Macro Index
10076 @c =====================================================================
10077 @c =====================================================================
10079 @node String Index, Glyph Name Index, Macro Index, Top
10080 @chapter String Index
10086 @c =====================================================================
10087 @c =====================================================================
10089 @node Glyph Name Index, Font File Keyword Index, String Index, Top
10090 @chapter Glyph Name Index
10092 A glyph name @code{xx} consisting of exactly two characters can be
10093 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
10094 accessed as @samp{\[xxx]}.
10100 @c =====================================================================
10101 @c =====================================================================
10103 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
10104 @chapter Font File Keyword Index
10110 @c =====================================================================
10111 @c =====================================================================
10113 @node Program and File Index, Concept Index, Font File Keyword Index, Top
10114 @chapter Program and File Index
10120 @c =====================================================================
10121 @c =====================================================================
10123 @node Concept Index, , Program and File Index, Top
10124 @chapter Concept Index