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
29 @c tindex and cindex are merged.
39 @c to avoid uppercasing in @deffn while converting to info, we define
42 @c due to a (not officially documented) `feature' in makeinfo 4.0,
43 @c macros are not expanded in @deffn (but the macro definition is
44 @c properly removed), so we have to define @Var{} directly in TeX also
54 @c To assure correct HTML translation, some ugly hacks are necessary.
55 @c While processing a @def... request, the HTML translator looks at the
56 @c next line to decide whether it should start indentation or not. If
57 @c it is something starting with @def... (e.g. @deffnx), it doesn't.
58 @c So we must assure during macro expansion that a @def... is seen.
60 @c The following macros have to be used:
79 @c The definition block must end with
83 @c The above is valid for texinfo 4.0f.
86 @c a dummy macro to assure the `@def...'
92 @c definition of requests
94 @macro Defreq{name, arg}
95 @deffn Request @t{.\name\} \arg\
99 @macro DefreqList{name, arg}
100 @deffn Request @t{.\name\} \arg\
105 @macro DefreqItem{name, arg}
106 @deffnx Request @t{.\name\} \arg\
111 @macro DefreqListEnd{name, arg}
112 @deffnx Request @t{.\name\} \arg\
121 @c definition of escapes
123 @macro Defesc{name, delimI, arg, delimII}
124 @deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
128 @macro DefescList{name, delimI, arg, delimII}
129 @deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
134 @macro DefescItem{name, delimI, arg, delimII}
135 @deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
140 @macro DefescListEnd{name, delimI, arg, delimII}
141 @deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
150 @c definition of registers
153 @deffn Register @t{\\n[\name\]}
157 @macro DefregList{name}
158 @deffn Register @t{\\n[\name\]}
163 @macro DefregItem{name}
164 @deffnx Register @t{\\n[\name\]}
169 @macro DefregListEnd{name}
170 @deffnx Register @t{\\n[\name\]}
179 @c definition of registers specific to macro packages
181 @macro Defmpreg{name, package}
182 @deffn Register @t{\\n[\name\]}
183 @vindex \name\ @r{[}\package\@r{]}
186 @macro DefmpregList{name, package}
187 @deffn Register @t{\\n[\name\]}
189 @vindex \name\ @r{[}\package\@r{]}
192 @macro DefmpregItem{name, package}
193 @deffnx Register @t{\\n[\name\]}
195 @vindex \name\ @r{[}\package\@r{]}
198 @macro DefmpregListEnd{name, package}
199 @deffnx Register @t{\\n[\name\]}
200 @vindex \name\ @r{[}\package\@r{]}
208 @c definition of macros
210 @macro Defmac{name, arg, package}
211 @defmac @t{.\name\} \arg\
212 @maindex \name\ @r{[}\package\@r{]}
215 @macro DefmacList{name, arg, package}
216 @defmac @t{.\name\} \arg\
218 @maindex \name\ @r{[}\package\@r{]}
221 @macro DefmacItem{name, arg, package}
222 @defmacx @t{.\name\} \arg\
224 @maindex \name\ @r{[}\package\@r{]}
227 @macro DefmacListEnd{name, arg, package}
228 @defmacx @t{.\name\} \arg\
229 @maindex \name\ @r{[}\package\@r{]}
237 @c definition of strings
239 @macro Defstr{name, package}
240 @deffn String @t{\\*[\name\]}
241 @stindex \name\ @r{[}\package\@r{]}
244 @macro DefstrList{name, package}
245 @deffn String @t{\\*[\name\]}
247 @stindex \name\ @r{[}\package\@r{]}
250 @macro DefstrItem{name, package}
251 @deffnx String @t{\\*[\name\]}
253 @stindex \name\ @r{[}\package\@r{]}
256 @macro DefstrListEnd{name, package}
257 @deffnx String @t{\\*[\name\]}
258 @stindex \name\ @r{[}\package\@r{]}
279 @c We need special parentheses and brackets:
281 @c . Real parentheses in @deffn produce an error while compiling with
283 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
285 @c This is true for texinfo 4.0.
318 @c Note: We say `Roman numerals' but `roman font'.
321 @c XXX comment all examples
324 @dircategory Miscellaneous
326 * Groff: (groff). The GNU troff document formatting system.
339 This Info file documents GNU troff version 1.18.
341 Published by the Free Software Foundation
342 59 Temple Place, Suite 330
343 Boston, MA 02111-1307 USA
345 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
347 Permission is granted to make and distribute verbatim copies of this
348 manual provided the copyright notice and this permission notice are
349 preserved on all copies.
352 Permission is granted to process this file through TeX and print the
353 results, provided the printed document carries copying permission notice
354 identical to this one except for the removal of this paragraph (this
355 paragraph not being relevant to the printed manual).
358 Permission is granted to copy and distribute modified versions of this
359 manual under the conditions for verbatim copying, provided that the
360 entire resulting derived work is distributed under the terms of a
361 permission notice identical to this one.
363 Permission is granted to copy and distribute translations of this manual
364 into another language, under the above conditions for modified versions,
365 except that this permission notice may be stated in a translation
366 approved by the Foundation.
368 Permission is granted to copy and distribute modified versions of this
369 manual under the conditions for verbatim copying, provided also that the
370 section entitled ``GNU General Public License'' is included exactly as
371 in the original, and provided that the entire resulting derived work is
372 distributed under the terms of a permission notice identical to this
375 Permission is granted to copy and distribute translations of this manual
376 into another language, under the above conditions for modified versions,
377 except that the section entitled ``GNU General Public License'' may be
378 included in a translation approved by the Free Software Foundation
379 instead of in the original English.
385 @subtitle The GNU implementation of @code{troff}
386 @subtitle Edition 1.18
387 @subtitle Spring 2002
388 @author by Trent A.@w{ }Fisher
389 @author and Werner Lemberg
391 @c Include the Distribution inside the titlepage environment so
392 @c that headings are turned off. Headings on and off do not work.
395 @vskip 0pt plus 1filll
396 Copyright @copyright@w{ }1994-2000, 2001, 2002 Free Software
399 Version 1.18 of @code{groff}, @*
402 Published by the Free Software Foundation @*
403 59 Temple Place, Suite 330 @*
404 Boston, MA 02111-1307 USA
407 Permission is granted to make and distribute verbatim copies of this
408 manual provided the copyright notice and this permission notice are
409 preserved on all copies.
411 Permission is granted to copy and distribute modified versions of this
412 manual under the conditions for verbatim copying, provided also that the
413 section entitled ``GNU General Public License'' is included exactly as
414 in the original, and provided that the entire resulting derived work is
415 distributed under the terms of a permission notice identical to this
418 Permission is granted to copy and distribute translations of this manual
419 into another language, under the above conditions for modified versions,
420 except that the section entitled ``GNU General Public License'' may be
421 included in a translation approved by the Free Software Foundation
422 instead of in the original English.
424 Cover art by Etienne Suvasa.
430 @node Top, Copying, (dir), (dir)
433 This Info file documents groff version 1.18, the GNU implementation of
434 the troff typesetting system.
436 This is an in-progress document; contributions, comments, or
437 contributions are welcome. Send them to bug-groff@@gnu.org.
444 * Tutorial for Macro Users::
458 * Font File Keyword Index::
459 * Program and File Index::
465 @node Copying, Introduction, Top, Top
467 @unnumbered GNU GENERAL PUBLIC LICENSE
468 @center Version 2, June 1991
471 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
472 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
474 Everyone is permitted to copy and distribute verbatim copies of this
475 license document, but changing it is not allowed.
478 @unnumberedsec Preamble
480 The licenses for most software are designed to take away your freedom to
481 share and change it. By contrast, the GNU General Public License is
482 intended to guarantee your freedom to share and change free software --
483 to make sure the software is free for all its users. This General
484 Public License applies to most of the Free Software Foundation's
485 software and to any other program whose authors commit to using it.
486 (Some other Free Software Foundation software is covered by the GNU
487 Library General Public License instead.) You can apply it to your
490 When we speak of free software, we are referring to freedom, not price.
491 Our General Public Licenses are designed to make sure that you have the
492 freedom to distribute copies of free software (and charge for this
493 service if you wish), that you receive source code or can get it if you
494 want it, that you can change the software or use pieces of it in new
495 free programs; and that you know you can do these things.
497 To protect your rights, we need to make restrictions that forbid anyone
498 to deny you these rights or to ask you to surrender the rights. These
499 restrictions translate to certain responsibilities for you if you
500 distribute copies of the software, or if you modify it.
502 For example, if you distribute copies of such a program, whether gratis
503 or for a fee, you must give the recipients all the rights that you have.
504 You must make sure that they, too, receive or can get the source code.
505 And you must show them these terms so they know their rights.
507 We protect your rights with two steps: (1)@w{ }copyright the software,
508 and (2)@w{ }offer you this license which gives you legal permission to
509 copy, distribute and/or modify the software.
511 Also, for each author's protection and ours, we want to make certain
512 that everyone understands that there is no warranty for this free
513 software. If the software is modified by someone else and passed on, we
514 want its recipients to know that what they have is not the original, so
515 that any problems introduced by others will not reflect on the original
516 authors' reputations.
518 Finally, any free program is threatened constantly by software patents.
519 We wish to avoid the danger that redistributors of a free program will
520 individually obtain patent licenses, in effect making the program
521 proprietary. To prevent this, we have made it clear that any patent
522 must be licensed for everyone's free use or not licensed at all.
524 The precise terms and conditions for copying, distribution and
528 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
531 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
536 This License applies to any program or other work which contains a
537 notice placed by the copyright holder saying it may be distributed under
538 the terms of this General Public License. The ``Program'', below,
539 refers to any such program or work, and a ``work based on the Program''
540 means either the Program or any derivative work under copyright law:
541 that is to say, a work containing the Program or a portion of it, either
542 verbatim or with modifications and/or translated into another language.
543 (Hereinafter, translation is included without limitation in the term
544 ``modification''.) Each licensee is addressed as ``you''.
546 Activities other than copying, distribution and modification are not
547 covered by this License; they are outside its scope. The act of running
548 the Program is not restricted, and the output from the Program is
549 covered only if its contents constitute a work based on the Program
550 (independent of having been made by running the Program). Whether that
551 is true depends on what the Program does.
554 You may copy and distribute verbatim copies of the Program's source code
555 as you receive it, in any medium, provided that you conspicuously and
556 appropriately publish on each copy an appropriate copyright notice and
557 disclaimer of warranty; keep intact all the notices that refer to this
558 License and to the absence of any warranty; and give any other
559 recipients of the Program a copy of this License along with the Program.
561 You may charge a fee for the physical act of transferring a copy, and
562 you may at your option offer warranty protection in exchange for a fee.
565 You may modify your copy or copies of the Program or any portion of it,
566 thus forming a work based on the Program, and copy and distribute such
567 modifications or work under the terms of Section@w{ }1 above, provided
568 that you also meet all of these conditions:
572 You must cause the modified files to carry prominent notices stating
573 that you changed the files and the date of any change.
576 You must cause any work that you distribute or publish, that in whole or
577 in part contains or is derived from the Program or any part thereof, to
578 be licensed as a whole at no charge to all third parties under the terms
582 If the modified program normally reads commands interactively when run,
583 you must cause it, when started running for such interactive use in the
584 most ordinary way, to print or display an announcement including an
585 appropriate copyright notice and a notice that there is no warranty (or
586 else, saying that you provide a warranty) and that users may
587 redistribute the program under these conditions, and telling the user
588 how to view a copy of this License. (Exception: if the Program itself
589 is interactive but does not normally print such an announcement, your
590 work based on the Program is not required to print an announcement.)
593 These requirements apply to the modified work as a whole. If
594 identifiable sections of that work are not derived from the Program, and
595 can be reasonably considered independent and separate works in
596 themselves, then this License, and its terms, do not apply to those
597 sections when you distribute them as separate works. But when you
598 distribute the same sections as part of a whole which is a work based on
599 the Program, the distribution of the whole must be on the terms of this
600 License, whose permissions for other licensees extend to the entire
601 whole, and thus to each and every part regardless of who wrote it.
603 Thus, it is not the intent of this section to claim rights or contest
604 your rights to work written entirely by you; rather, the intent is to
605 exercise the right to control the distribution of derivative or
606 collective works based on the Program.
608 In addition, mere aggregation of another work not based on the Program
609 with the Program (or with a work based on the Program) on a volume of a
610 storage or distribution medium does not bring the other work under the
611 scope of this License.
614 You may copy and distribute the Program (or a work based on it, under
615 Section@w{ }2) in object code or executable form under the terms of
616 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
621 Accompany it with the complete corresponding machine-readable source
622 code, which must be distributed under the terms of Sections@w{ }1 and@w{
623 }2 above on a medium customarily used for software interchange; or,
626 Accompany it with a written offer, valid for at least three years, to
627 give any third party, for a charge no more than your cost of physically
628 performing source distribution, a complete machine-readable copy of the
629 corresponding source code, to be distributed under the terms of
630 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
634 Accompany it with the information you received as to the offer to
635 distribute corresponding source code. (This alternative is allowed only
636 for noncommercial distribution and only if you received the program in
637 object code or executable form with such an offer, in accord with
638 Subsection@w{ }b above.)
641 The source code for a work means the preferred form of the work for
642 making modifications to it. For an executable work, complete source
643 code means all the source code for all modules it contains, plus any
644 associated interface definition files, plus the scripts used to control
645 compilation and installation of the executable. However, as a special
646 exception, the source code distributed need not include anything that is
647 normally distributed (in either source or binary form) with the major
648 components (compiler, kernel, and so on) of the operating system on
649 which the executable runs, unless that component itself accompanies the
652 If distribution of executable or object code is made by offering access
653 to copy from a designated place, then offering equivalent access to copy
654 the source code from the same place counts as distribution of the source
655 code, even though third parties are not compelled to copy the source
656 along with the object code.
659 You may not copy, modify, sublicense, or distribute the Program except
660 as expressly provided under this License. Any attempt otherwise to
661 copy, modify, sublicense or distribute the Program is void, and will
662 automatically terminate your rights under this License. However,
663 parties who have received copies, or rights, from you under this License
664 will not have their licenses terminated so long as such parties remain
668 You are not required to accept this License, since you have not signed
669 it. However, nothing else grants you permission to modify or distribute
670 the Program or its derivative works. These actions are prohibited by
671 law if you do not accept this License. Therefore, by modifying or
672 distributing the Program (or any work based on the Program), you
673 indicate your acceptance of this License to do so, and all its terms and
674 conditions for copying, distributing or modifying the Program or works
678 Each time you redistribute the Program (or any work based on the
679 Program), the recipient automatically receives a license from the
680 original licensor to copy, distribute or modify the Program subject to
681 these terms and conditions. You may not impose any further restrictions
682 on the recipients' exercise of the rights granted herein. You are not
683 responsible for enforcing compliance by third parties to this License.
686 If, as a consequence of a court judgment or allegation of patent
687 infringement or for any other reason (not limited to patent issues),
688 conditions are imposed on you (whether by court order, agreement or
689 otherwise) that contradict the conditions of this License, they do not
690 excuse you from the conditions of this License. If you cannot
691 distribute so as to satisfy simultaneously your obligations under this
692 License and any other pertinent obligations, then as a consequence you
693 may not distribute the Program at all. For example, if a patent license
694 would not permit royalty-free redistribution of the Program by all those
695 who receive copies directly or indirectly through you, then the only way
696 you could satisfy both it and this License would be to refrain entirely
697 from distribution of the Program.
699 If any portion of this section is held invalid or unenforceable under
700 any particular circumstance, the balance of the section is intended to
701 apply and the section as a whole is intended to apply in other
704 It is not the purpose of this section to induce you to infringe any
705 patents or other property right claims or to contest validity of any
706 such claims; this section has the sole purpose of protecting the
707 integrity of the free software distribution system, which is implemented
708 by public license practices. Many people have made generous
709 contributions to the wide range of software distributed through that
710 system in reliance on consistent application of that system; it is up to
711 the author/donor to decide if he or she is willing to distribute
712 software through any other system and a licensee cannot impose that
715 This section is intended to make thoroughly clear what is believed to be
716 a consequence of the rest of this License.
719 If the distribution and/or use of the Program is restricted in certain
720 countries either by patents or by copyrighted interfaces, the original
721 copyright holder who places the Program under this License may add an
722 explicit geographical distribution limitation excluding those countries,
723 so that distribution is permitted only in or among countries not thus
724 excluded. In such case, this License incorporates the limitation as if
725 written in the body of this License.
728 The Free Software Foundation may publish revised and/or new versions of
729 the General Public License from time to time. Such new versions will be
730 similar in spirit to the present version, but may differ in detail to
731 address new problems or concerns.
733 Each version is given a distinguishing version number. If the Program
734 specifies a version number of this License which applies to it and ``any
735 later version'', you have the option of following the terms and
736 conditions either of that version or of any later version published by
737 the Free Software Foundation. If the Program does not specify a version
738 number of this License, you may choose any version ever published by the
739 Free Software Foundation.
742 If you wish to incorporate parts of the Program into other free programs
743 whose distribution conditions are different, write to the author to ask
744 for permission. For software which is copyrighted by the Free Software
745 Foundation, write to the Free Software Foundation; we sometimes make
746 exceptions for this. Our decision will be guided by the two goals of
747 preserving the free status of all derivatives of our free software and
748 of promoting the sharing and reuse of software generally.
758 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
759 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
760 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
761 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
762 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
763 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
764 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
765 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
766 NECESSARY SERVICING, REPAIR OR CORRECTION.
769 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
770 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
771 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
772 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
773 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
774 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
775 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
776 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
777 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
781 @heading END OF TERMS AND CONDITIONS
784 @center END OF TERMS AND CONDITIONS
789 @unnumberedsec How to Apply These Terms to Your New Programs
791 If you develop a new program, and you want it to be of the greatest
792 possible use to the public, the best way to achieve this is to make it
793 free software which everyone can redistribute and change under these
796 To do so, attach the following notices to the program. It is safest to
797 attach them to the start of each source file to most effectively convey
798 the exclusion of warranty; and each file should have at least the
799 ``copyright'' line and a pointer to where the full notice is found.
802 @var{one line to give the program's name and an idea of what it does.}
803 Copyright (C) 19@var{yy} @var{name of author}
805 This program is free software; you can redistribute it and/or modify
806 it under the terms of the GNU General Public License as published by
807 the Free Software Foundation; either version 2 of the License, or (at
808 your option) any later version.
810 This program is distributed in the hope that it will be useful, but
811 WITHOUT ANY WARRANTY; without even the implied warranty of
812 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
813 General Public License for more details.
815 You should have received a copy of the GNU General Public License
816 along with this program; if not, write to the Free Software
817 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
820 Also add information on how to contact you by electronic and paper mail.
822 If the program is interactive, make it output a short notice like this
823 when it starts in an interactive mode:
826 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
827 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
828 `show w'. This is free software, and you are welcome to redistribute
829 it under certain conditions; type `show c' for details.
832 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
833 show the appropriate parts of the General Public License. Of course,
834 the commands you use may be called something other than @samp{show@w{
835 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items
836 -- whatever suits your program.
838 You should also get your employer (if you work as a programmer) or your
839 school, if any, to sign a ``copyright disclaimer'' for the program, if
840 necessary. Here is a sample; alter the names:
844 Yoyodyne, Inc., hereby disclaims all copyright interest
845 in the program `Gnomovision' (which makes passes at compilers)
846 written by James Hacker.
848 @var{signature of Ty Coon}, 1 April 1989
849 Ty Coon, President of Vice
853 This General Public License does not permit incorporating your program
854 into proprietary programs. If your program is a subroutine library, you
855 may consider it more useful to permit linking proprietary applications
856 with the library. If this is what you want to do, use the GNU Library
857 General Public License instead of this License.
861 @c =====================================================================
862 @c =====================================================================
864 @node Introduction, Invoking groff, Copying, Top
865 @chapter Introduction
868 GNU @code{troff} (or @code{groff}) is a system for typesetting
869 documents. @code{troff} is very flexible and has been in existence (and
870 use) for about 3@w{ }decades. It is quite widespread and firmly
871 entrenched in the @acronym{UNIX} community.
876 * groff Capabilities::
877 * Macro Package Intro::
878 * Preprocessor Intro::
879 * Output device intro::
884 @c =====================================================================
886 @node What Is groff?, History, Introduction, Introduction
887 @section What Is @code{groff}?
888 @cindex what is @code{groff}?
889 @cindex @code{groff} -- what is it?
891 @code{groff} belongs to an older generation of document preparation
892 systems, which operate more like compilers than the more recent
893 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
894 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
895 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
896 normal text files with embedded formatting commands. These files can
897 then be processed by @code{groff} to produce a typeset document on a
900 Likewise, @code{groff} should not be confused with a @dfn{word
901 processor}, since that term connotes an integrated system that includes
902 an editor and a text formatter. Also, many word processors follow the
903 @acronym{WYSIWYG} paradigm discussed earlier.
905 Although @acronym{WYSIWYG} systems may be easier to use, they have a
906 number of disadvantages compared to @code{troff}:
910 They must be used on a graphics display to work on a document.
913 Most of the @acronym{WYSIWYG} systems are either non-free or are not
917 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
920 It is difficult to have a wide range of capabilities available within
921 the confines of a GUI/window system.
924 It is more difficult to make global changes to a document.
928 ``GUIs normally make it simple to accomplish simple actions and
929 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
930 @code{comp.unix.wizards})
934 @c =====================================================================
936 @node History, groff Capabilities, What Is groff?, Introduction
940 @cindex @code{runoff}, the program
941 @cindex @code{rf}, the program
942 @code{troff} can trace its origins back to a formatting program called
943 @code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS
944 operating system in the mid-sixties. This name came from the common
945 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
946 the 635 architecture and called the program @code{roff} (an abbreviation
947 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
948 (before having @acronym{UNIX}), and at the same time (1969), Doug
949 McIllroy rewrote an extended and simplified version of @code{roff} in
950 the @acronym{BCPL} programming language.
952 @cindex @code{roff}, the program
953 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
954 was sitting around Bell Labs. In 1971 the developers wanted to get a
955 @w{PDP-11} for further work on the operating system. In order to
956 justify the cost for this system, they proposed that they would
957 implement a document formatting system for the AT&T patents division.
958 This first formatting program was a reimplementation of McIllroy's
959 @code{roff}, written by J.@w{ }F.@w{ }Ossanna.
961 @cindex @code{nroff}, the program
962 When they needed a more flexible language, a new version of @code{roff}
963 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
964 more complicated syntax, but provided the basis for all future versions.
965 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
966 version of @code{nroff} that would drive it. It was dubbed
967 @code{troff}, for ``typesetter @code{roff}'', although many people have
968 speculated that it actually means ``Times @code{roff}'' because of the
969 use of the Times font family in @code{troff} by default. As such, the
970 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
972 With @code{troff} came @code{nroff} (they were actually the same program
973 except for some @samp{#ifdef}s), which was for producing output for line
974 printers and character terminals. It understood everything @code{troff}
975 did, and ignored the commands which were not applicable (e.g.@: font
978 Since there are several things which cannot be done easily in
979 @code{troff}, work on several preprocessors began. These programs would
980 transform certain parts of a document into @code{troff}, which made a
981 very natural use of pipes in @acronym{UNIX}.
983 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
984 specified in a much simpler and more intuitive manner. @code{tbl} is a
985 preprocessor for formatting tables. The @code{refer} preprocessor (and
986 the similar program, @code{bib}) processes citations in a document
987 according to a bibliographic database.
989 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
990 language and produced output specifically for the CAT phototypesetter.
991 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
992 code and still dependent on the CAT. As the CAT became less common, and
993 was no longer supported by the manufacturer, the need to make it support
994 other devices became a priority. However, before this could be done,
995 Ossanna was killed in an auto accident.
998 @cindex @code{ditroff}, the program
999 So, Brian Kernighan took on the task of rewriting @code{troff}. The
1000 newly rewritten version produced a device independent code which was
1001 very easy for postprocessors to read and translate to the appropriate
1002 printer codes. Also, this new version of @code{troff} (called
1003 @code{ditroff} for ``device independent @code{troff}'') had several
1004 extensions, which included drawing functions.
1006 Due to the additional abilities of the new version of @code{troff},
1007 several new preprocessors appeared. The @code{pic} preprocessor
1008 provides a wide range of drawing functions. Likewise the @code{ideal}
1009 preprocessor did the same, although via a much different paradigm. The
1010 @code{grap} preprocessor took specifications for graphs, but, unlike
1011 other preprocessors, produced @code{pic} code.
1013 James Clark began work on a GNU implementation of @code{ditroff} in
1014 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
1015 June@w{ }1990. @code{groff} included:
1019 A replacement for @code{ditroff} with many extensions.
1022 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
1025 Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and
1026 X@w{ }windows. GNU @code{troff} also eliminated the need for a
1027 separate @code{nroff} program with a postprocessor which would produce
1028 @acronym{ASCII} output.
1031 A version of the @file{me} macros and an implementation of the
1035 Also, a front-end was included which could construct the, sometimes
1036 painfully long, pipelines required for all the post- and preprocessors.
1038 Development of GNU @code{troff} progressed rapidly, and saw the
1039 additions of a replacement for @code{refer}, an implementation of the
1040 @file{ms} and @file{mm} macros, and a program to deduce how to format a
1041 document (@code{grog}).
1043 It was declared a stable (i.e.@: non-beta) package with the release of
1044 version@w{ }1.04 around November@w{ }1991.
1046 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
1047 an orphan for a few years). As a result, new features and programs like
1048 @code{grn}, a preprocessor for gremlin images, and an output device to
1049 produce @acronym{HTML} output have been added.
1052 @c =====================================================================
1054 @node groff Capabilities, Macro Package Intro, History, Introduction
1055 @section @code{groff} Capabilities
1056 @cindex @code{groff} capabilities
1057 @cindex capabilities of @code{groff}
1059 So what exactly is @code{groff} capable of doing? @code{groff} provides
1060 a wide range of low-level text formatting operations. Using these, it
1061 is possible to perform a wide range of formatting tasks, such as
1062 footnotes, table of contents, multiple columns, etc. Here's a list of
1063 the most important operations supported by @code{groff}:
1067 text filling, adjusting, and centering
1076 font and character size control
1079 vertical spacing (i.e.@: double spacing)
1082 line length and indenting
1085 macros, strings, diversions, and traps
1091 tabs, leaders, and fields
1094 input and output conventions and character translation
1097 overstrike, bracket, line drawing, and zero-width functions
1100 local horizontal and vertical motions and the width function
1106 output line numbering
1109 conditional acceptance of input
1112 environment switching
1115 insertions from the standard input
1118 input/output file switching
1121 output and error messages
1125 @c =====================================================================
1127 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
1128 @section Macro Packages
1129 @cindex macro packages
1131 Since @code{groff} provides such low-level facilities, it can be quite
1132 difficult to use by itself. However, @code{groff} provides a
1133 @dfn{macro} facility to specify how certain routine operations (e.g.@w{
1134 }starting paragraphs, printing headers and footers, etc.)@: should be
1135 done. These macros can be collected together into a @dfn{macro
1136 package}. There are a number of macro packages available; the most
1137 common (and the ones described in this manual) are @file{man},
1138 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
1141 @c =====================================================================
1143 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
1144 @section Preprocessors
1145 @cindex preprocessors
1147 Although @code{groff} provides most functions needed to format a
1148 document, some operations would be unwieldy (e.g.@: to draw pictures).
1149 Therefore, programs called preprocessors were written which understand
1150 their own language and produce the necessary @code{groff} operations.
1151 These preprocessors are able to differentiate their own input from the
1152 rest of the document via markers.
1154 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
1155 from the preprocessor into @code{groff}. Any number of preprocessors
1156 may be used on a given document; in this case, the preprocessors are
1157 linked together into one pipeline. However, in @code{groff}, the user
1158 does not need to construct the pipe, but only tell @code{groff} what
1159 preprocessors to use.
1161 @code{groff} currently has preprocessors for producing tables
1162 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
1163 (@code{pic} and @code{grn}), and for processing bibliographies
1164 (@code{refer}). An associated program which is useful when dealing with
1165 preprocessors is @code{soelim}.
1167 A free implementation of @code{grap}, a preprocessor for drawing graphs,
1168 can be obtained as an extra package; @code{groff} can use @code{grap}
1171 There are other preprocessors in existence, but, unfortunately, no free
1172 implementations are available. Among them are preprocessors for drawing
1173 mathematical pictures (@code{ideal}) and chemical structures
1177 @c =====================================================================
1179 @node Output device intro, Credits, Preprocessor Intro, Introduction
1180 @section Output Devices
1181 @cindex postprocessors
1182 @cindex output devices
1183 @cindex devices for output
1185 @code{groff} actually produces device independent code which may be
1186 fed into a postprocessor to produce output for a particular device.
1187 Currently, @code{groff} has postprocessors for @sc{PostScript}
1188 devices, character terminals, X@w{ }Windows (for previewing), @TeX{}
1189 DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use
1190 @acronym{CAPSL}), and @acronym{HTML}.
1193 @c =====================================================================
1195 @node Credits, , Output device intro, Introduction
1199 Large portions of this manual were taken from existing documents, most
1200 notably, the manual pages for the @code{groff} package by James Clark,
1201 and Eric Allman's papers on the @file{me} macro package.
1203 The section on the @file{man} macro package is partly based on Susan@w{
1204 }G.@: Kleinmann's @file{groff_man} manual page written for the Debian
1209 @c =====================================================================
1210 @c =====================================================================
1212 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
1213 @chapter Invoking @code{groff}
1214 @cindex invoking @code{groff}
1215 @cindex @code{groff} invocation
1217 This section focuses on how to invoke the @code{groff} front end. This
1218 front end takes care of the details of constructing the pipeline among
1219 the preprocessors, @code{gtroff} and the postprocessor.
1221 It has become a tradition that GNU programs get the prefix @samp{g} to
1222 distinguish it from its original counterparts provided by the host (see
1223 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
1224 GNU @code{eqn}. On operating systems like Linux or the Hurd, which
1225 don't contain proprietary software, and on MS-DOS/MS-Windows, where
1226 @code{troff} and associated programs are not available at all, this
1227 prefix is omitted since GNU @code{troff} is the only used incarnation of
1228 @code{troff}. Exception: @code{groff} is never replaced by @code{roff}.
1233 * Invocation Examples::
1237 @c =====================================================================
1239 @node Groff Options, Environment, Invoking groff, Invoking groff
1252 @code{groff} normally runs the @code{gtroff} program and a postprocessor
1253 appropriate for the selected device. The default device is @samp{ps}
1254 (but it can be changed when @code{groff} is configured and built). It
1255 can optionally preprocess with any of @code{gpic}, @code{geqn},
1256 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
1258 This section only documents options to the @code{groff} front end. Many
1259 of the arguments to @code{groff} are passed on to @code{gtroff},
1260 therefore those are also included. Arguments to pre- or postprocessors
1261 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
1262 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
1263 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
1264 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
1265 grolbp}, and @ref{Invoking gxditview}.
1267 The command line format for @code{groff} is:
1270 groff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
1271 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
1272 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
1273 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
1274 [ @var{files}@dots{} ]
1277 The command line format for @code{gtroff} is as follows.
1280 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
1281 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
1282 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
1283 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
1287 Obviously, many of the options to @code{groff} are actually passed on to
1290 Options without an argument can be grouped behind a single@w{ }@option{-}.
1291 A filename of@w{ }@file{-} denotes the standard input. It is possible to
1292 have whitespace between an option and its parameter.
1294 The @code{grog} command can be used to guess the correct @code{groff}
1295 command to format a file.
1297 Here's the description of the command-line options:
1299 @cindex command-line options
1302 Print a help message.
1305 Preprocess with @code{geqn}.
1308 Preprocess with @code{gtbl}.
1311 Preprocess with @code{ggrn}.
1314 Preprocess with @code{grap}.
1317 Preprocess with @code{gpic}.
1320 Preprocess with @code{gsoelim}.
1323 Preprocess with @code{grefer}. No mechanism is provided for passing
1324 arguments to @code{grefer} because most @code{grefer} options have
1325 equivalent commands which can be included in the file. @xref{grefer},
1330 Note that @code{gtroff} also accepts a @option{-R} option, which is not
1331 accessible via @code{groff}. This option prevents the loading of the
1332 @file{troffrc} and @file{troffrc-end} files.
1335 Make programs run by @code{groff} print out their version number.
1338 Print the pipeline on @code{stdout} instead of executing it.
1341 Suppress output from @code{gtroff}. Only error messages are printed.
1344 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1345 automatically runs the appropriate postprocessor.
1348 Pass @var{arg} to the postprocessor. Each argument should be passed
1349 with a separate @option{-P} option. Note that @code{groff} does not
1350 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1353 Send the output to a spooler for printing. The command used for this is
1354 specified by the @code{print} command in the device description file
1355 (see @ref{Font Files}, for more info). If not present, @option{-l} is
1359 Pass @var{arg} to the spooler. Each argument should be passed with a
1360 separate @option{-L} option. Note that @code{groff} does not prepend
1361 a @samp{-} to @var{arg} before passing it to the postprocessor.
1362 If the @code{print} keyword in the device description file is missing,
1363 @option{-L} is ignored.
1366 Prepare output for device @var{dev}. The default device is @samp{ps},
1367 unless changed when @code{groff} was configured and built. The
1368 following are the output devices currently available:
1372 For @sc{PostScript} printers and previewers.
1375 For @TeX{} DVI format.
1378 For a 75@dmn{dpi} X11 previewer.
1381 For a 100@dmn{dpi} X11 previewer.
1384 For typewriter-like devices.
1387 For typewriter-like devices that support the @w{Latin-1} (@w{ISO
1388 8859-1}) character set.
1391 For typewriter-like devices which use the Unicode (@w{ISO 10646})
1392 character set with @w{UTF-8} encoding.
1395 @cindex @acronym{EBCDIC} encoding
1396 @cindex encoding, @acronym{EBCDIC}
1397 @cindex encoding, cp1047
1400 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1404 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
1407 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1411 @pindex post-grohtml
1412 @cindex @code{grohtml}, the program
1414 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1415 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1416 postprocessor (@code{post-grohtml}).
1419 @cindex output device name string register (@code{.T})
1420 @cindex output device usage number register (@code{.T})
1421 The predefined @code{gtroff} string register @code{.T} contains the
1422 current output device; the read-only number register @code{.T} is set
1423 to@w{ }1 if this option is used (which is always true if @code{groff} is
1424 used to call @code{gtroff}). @xref{Built-in Registers}.
1426 The postprocessor to be used for a device is specified by the
1427 @code{postpro} command in the device description file. (@xref{Font
1428 Files}, for more info.) This can be overridden with the @option{-X}
1432 Preview with @code{gxditview} instead of using the usual postprocessor.
1433 This is unlikely to produce good results except with @option{-Tps}.
1435 Note that this is not the same as using @option{-TX75} or
1436 @option{-TX100} to view a document with @code{gxditview}: The former
1437 uses the metrics of the specified device, whereas the latter uses
1438 X-specific fonts and metrics.
1441 Don't allow newlines with @code{eqn} delimiters. This is the same as
1442 the @option{-N} option in @code{geqn}.
1445 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1446 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1447 requests. For security reasons, this is enabled by default.
1450 Unsafe mode. Reverts to the old unsafe behaviour.
1453 @cindex @acronym{ASCII} approximation output register (@code{.A})
1454 Generate an @acronym{ASCII} approximation of the typeset output. The
1455 read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
1456 Registers}. A typical example is
1459 groff -a -man -Tdvi troff.man | less
1463 which shows how lines are broken for the DVI device. Note that this
1464 option is rather useless today since graphic output devices are
1465 available virtually everywhere.
1468 Print a backtrace with each warning or error message. This backtrace
1469 should help track down the cause of the error. The line numbers given
1470 in the backtrace may not always be correct: @code{gtroff} can get
1471 confused by @code{as} or @code{am} requests while counting line numbers.
1474 Read the standard input after all the named input files have been
1478 Enable warning @var{name}. Available warnings are described in
1479 @ref{Debugging}. Multiple @option{-w} options are allowed.
1482 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1485 Inhibit all error messages.
1488 Enable compatibility mode. @xref{Implementation Differences}, for the
1489 list of incompatibilities between @code{groff} and traditional Unix
1493 @itemx -d@var{name}=s
1494 Define @var{c} or @var{name} to be a string@w{ }@var{s}. @var{c}@w{ }must
1495 be a one-letter name; @var{name} can be of arbitrary length. All string
1496 assignments happen before loading any macro file (including the start-up
1500 Use @var{fam} as the default font family. @xref{Font Families}.
1503 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1504 for this in its macro directories. If it isn't found, it tries
1505 @file{tmac.@var{name}} (and searches in the same directories).
1507 @c XXX document local and system macro dirs
1510 Number the first page @var{num}.
1513 @cindex print current page register (@code{.P})
1514 Output only pages in @var{list}, which is a comma-separated list of page
1515 ranges; @samp{@var{n}} means print page@w{ }@var{n}, @samp{@var{m}-@var{n}}
1516 means print every page between @var{m} and@w{ }@var{n}, @samp{-@var{n}}
1517 means print every page up to@w{ }@var{n}, @samp{@var{n}-} means print every
1518 page beginning with@w{ }@var{n}. @code{gtroff} exits after printing the
1519 last page in the list. All the ranges are inclusive on both ends.
1521 Within @code{gtroff}, this information can be extracted with the
1522 @samp{.P} register. @xref{Built-in Registers}.
1524 If your document restarts page numbering at the beginning of each
1525 chapter, then @code{gtroff} prints the specified page range for each
1529 @itemx -r@var{name}=@var{n}
1530 Set number register@w{ }@var{c} or @var{name} to the value@w{ }@var{n}.
1531 @var{c}@w{ }must be a one-letter name; @var{name} can be of arbitrary
1532 length. @var{n}@w{ }can be any @code{gtroff} numeric expression. All
1533 register assignments happen before loading any macro file (including
1537 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1538 (@var{name} is the name of the device), for the @file{DESC} file, and
1539 for font files before looking in the standard directories.
1542 Search directory @file{@var{dir}} for macro files before the standard
1546 This option is as described in @ref{gsoelim}. It implies the
1551 @c =====================================================================
1553 @node Environment, Invocation Examples, Groff Options, Invoking groff
1554 @section Environment
1555 @cindex environment variables
1556 @cindex variables in environment
1558 There are also several environment variables (of the operating system,
1559 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1562 @item GROFF_COMMAND_PREFIX
1563 @tindex GROFF_COMMAND_PREFIX, environment variable
1564 If this is set to@w{ }@var{X}, then @code{groff} runs @code{@var{X}troff}
1565 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1566 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1567 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1568 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1570 @c XXX document default values
1572 @item GROFF_TMAC_PATH
1573 @tindex GROFF_TMAC_PATH@r{, environment variable}
1574 A colon-separated list of directories in which to search for macro files
1575 (before the default directories are tried).
1577 @c XXX document local and system macro dirs
1579 @item GROFF_TYPESETTER
1580 @tindex GROFF_TYPESETTER@r{, environment variable}
1581 The default output device.
1583 @item GROFF_FONT_PATH
1584 @tindex GROFF_FONT_PATH@r{, environment variable}
1585 A colon-separated list of directories in which to search for the
1586 @code{dev}@var{name} directory (before the default directories are
1589 @item GROFF_BIN_PATH
1590 @tindex GROFF_BIN_PATH@r{, environment variable}
1591 This search path, followed by @code{PATH}, is used for commands executed
1595 @tindex GROFF_TMPDIR@r{, environment variable}
1596 @tindex TMPDIR@r{, environment variable}
1597 The directory in which @code{groff} creates temporary files. If this is
1598 not set and @env{TMPDIR} is set, temporary files are created in that
1599 directory. Otherwise temporary files are created in a system-dependent
1600 default directory (on Unix and GNU/Linux systems, this is usually
1601 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1602 @code{post-grohtml} can create temporary files in this directory.
1605 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1606 rather than colons, to separate the directories in the lists described
1610 @c =====================================================================
1612 @node Invocation Examples, , Environment, Invoking groff
1613 @section Invocation Examples
1614 @cindex invocation examples
1615 @cindex examples of invocation
1617 This section lists several common uses of @code{groff} and the
1618 corresponding command lines.
1625 This command processes @file{file} without a macro package or a
1626 preprocessor. The output device is the default, @samp{ps}, and the
1627 output is sent to @code{stdout}.
1630 groff -t -mandoc -Tascii file | less
1634 This is basically what a call to the @code{man} program does.
1635 @code{gtroff} processes the manual page @file{file} with the
1636 @file{mandoc} macro file (which in turn either calls the @file{man} or
1637 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1638 the @acronym{ASCII} output device. Finally, the @code{less} pager
1639 displays the result.
1646 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1647 package. Since no @option{-T} option is specified, use the default
1648 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1649 @w{@samp{-me}}; the latter is an anachronism from the early days of
1650 @acronym{UNIX}.@footnote{The same is true for the other main macro
1651 packages that come with @code{groff}: @file{man}, @file{mdoc},
1652 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1653 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1654 @w{@samp{-m trace}} must be used.}
1657 groff -man -rD1 -z file
1661 Check @file{file} with the @file{man} macro package, forcing
1662 double-sided printing -- don't produce any output.
1668 @c ---------------------------------------------------------------------
1670 @node grog, , Invocation Examples, Invocation Examples
1671 @subsection @code{grog}
1674 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1675 and/or macro packages are required for formatting them, and prints the
1676 @code{groff} command including those options on the standard output. It
1677 generates one or more of the options @option{-e}, @option{-man},
1678 @option{-me}, @option{-mm}, @option{-ms}, @option{-mdoc},
1679 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1680 @option{-s}, and @option{-t}.
1682 A special file name@w{ }@file{-} refers to the standard input. Specifying
1683 no files also means to read the standard input. Any specified options
1684 are included in the printed command. No space is allowed between
1685 options and their arguments. The only options recognized are
1686 @option{-C} (which is also passed on) to enable compatibility mode, and
1687 @option{-v} (if it is the only parameter) to print the version number.
1696 guesses the appropriate command to print @file{paper.ms} and then prints
1697 it to the command line after adding the @option{-Tdvi} option. For
1698 direct execution, enclose the call to @code{grog} in backquotes at the
1699 @acronym{UNIX} shell prompt:
1702 `grog -Tdvi paper.ms` > paper.dvi
1706 As seen in the example, it is still necessary to redirect the output to
1707 something meaningful (i.e.@: either a file or a pager program like
1712 @c =====================================================================
1713 @c =====================================================================
1715 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1716 @chapter Tutorial for Macro Users
1717 @cindex tutorial for macro users
1718 @cindex macros, tutorial for users
1719 @cindex user's tutorial for macros
1720 @cindex user's macro tutorial
1722 Most users tend to use a macro package to format their papers. This
1723 means that the whole breadth of @code{groff} is not necessary for most
1724 people. This chapter covers the material needed to efficiently use a
1733 @c =====================================================================
1735 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1737 @cindex basics of macros
1738 @cindex macro basics
1740 This section covers some of the basic concepts necessary to understand
1741 how to use a macro package.@footnote{This section is derived from
1742 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1743 References are made throughout to more detailed information, if desired.
1745 @code{gtroff} reads an input file prepared by the user and outputs a
1746 formatted document suitable for publication or framing. The input
1747 consists of text, or words to be printed, and embedded commands
1748 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1749 format the output. For more detail on this, see @ref{Embedded
1752 The word @dfn{argument} is used in this chapter to mean a word or number
1753 which appears on the same line as a request, and which modifies the
1754 meaning of that request. For example, the request
1761 spaces one line, but
1768 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1769 request which says to space four lines instead of one. Arguments are
1770 separated from the request and from each other by spaces (@emph{no}
1771 tabs). More details on this can be found in @ref{Request Arguments}.
1773 The primary function of @code{gtroff} is to collect words from input
1774 lines, fill output lines with those words, justify the right-hand margin
1775 by inserting extra spaces in the line, and output the result. For
1783 Four score and seven
1788 is read, packed onto output lines, and justified to produce:
1791 Now is the time for all good men to come to the aid of their party.
1792 Four score and seven years ago,...
1797 Sometimes a new output line should be started even though the current
1798 line is not yet full; for example, at the end of a paragraph. To do
1799 this it is possible to cause a @dfn{break}, which starts a new output
1800 line. Some requests cause a break automatically, as normally do blank
1801 input lines and input lines beginning with a space.
1803 Not all input lines are text to be formatted. Some input lines are
1804 requests which describe how to format the text. Requests always have a
1805 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1808 The text formatter also does more complex things, such as automatically
1809 numbering pages, skipping over page boundaries, putting footnotes in the
1810 correct place, and so forth.
1812 Here are a few hints for preparing text for input to @code{gtroff}.
1816 First, keep the input lines short. Short input lines are easier to
1817 edit, and @code{gtroff} packs words onto longer lines anyhow.
1820 In keeping with this, it is helpful to begin a new line after every
1821 comma or phrase, since common corrections are to add or delete sentences
1825 End each sentence with two spaces -- or better, start each sentence on a
1826 new line. @code{gtroff} recognizes characters that usually end a
1827 sentence, and inserts sentence space accordingly.
1830 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1831 enough to hyphenate words as needed, but is not smart enough to take
1832 hyphens out and join a word back together. Also, words such as
1833 ``mother-in-law'' should not be broken over a line, since then a space
1834 can occur where not wanted, such as ``@w{mother- in}-law''.
1837 @cindex double spacing (@code{ls})
1839 @code{gtroff} double spaces output text automatically if you use the
1840 request @w{@samp{.ls 2}}. Reactivate single spaced mode by typing
1843 A number of requests allow to change the way the output looks,
1844 sometimes called the @dfn{layout} of the output page. Most of these
1845 requests adjust the placing of @dfn{white space} (blank lines or
1848 @cindex new page (@code{bp})
1849 The @samp{.bp} request starts a new page, causing a line break.
1851 @cindex blank line (@code{sp})
1852 @cindex empty line (@code{sp})
1853 @cindex line, empty (@code{sp})
1854 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1855 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1856 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1857 @var{N}@w{ }centimeters). For example, the input:
1861 My thoughts on the subject
1866 leaves one and a half inches of space, followed by the line ``My
1867 thoughts on the subject'', followed by a single blank line (more
1868 measurement units are available, see @ref{Measurements}).
1870 @cindex centering lines (@code{ce})
1871 @cindex lines, centering (@code{ce})
1872 Text lines can be centered by using the @code{ce} request. The line
1873 after @code{ce} is centered (horizontally) on the page. To center more
1874 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1875 of lines to center), followed by the @var{N}@w{ }lines. To center many
1876 lines without counting them, type:
1885 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1886 lines, in other words, stop centering.
1888 @cindex line break (@code{br})
1889 @cindex break (@code{br})
1890 All of these requests cause a break; that is, they always start a new
1891 line. To start a new line without performing any other action, use
1895 @c =====================================================================
1897 @node Common Features, , Basics, Tutorial for Macro Users
1898 @section Common Features
1899 @cindex common features
1900 @cindex features, common
1902 @code{gtroff} provides very low-level operations for formatting a
1903 document. There are many common routine operations which are done in
1904 all documents. These common operations are written into @dfn{macros}
1905 and collected into a @dfn{macro package}.
1907 All macro packages provide certain common capabilities which fall into
1908 the following categories.
1912 * Sections and Chapters::
1913 * Headers and Footers::
1914 * Page Layout Adjustment::
1916 * Footnotes and Annotations::
1917 * Table of Contents::
1920 * Multiple Columns::
1921 * Font and Size Changes::
1922 * Predefined Strings::
1923 * Preprocessor Support::
1924 * Configuration and Customization::
1927 @c ---------------------------------------------------------------------
1929 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1930 @subsection Paragraphs
1933 One of the most common and most used capability is starting a
1934 paragraph. There are a number of different types of paragraphs, any
1935 of which can be initiated with macros supplied by the macro package.
1936 Normally, paragraphs start with a blank line and the first line
1937 indented, like the text in this manual. There are also block style
1938 paragraphs, which omit the indentation:
1941 Some men look at constitutions with sanctimonious
1942 reverence, and deem them like the ark of the covenant, too
1943 sacred to be touched.
1947 And there are also indented paragraphs which begin with a tag or label
1948 at the margin and the remaining text indented.
1952 one This is the first paragraph. Notice how the first
1953 line of the resulting paragraph lines up with the
1954 other lines in the paragraph.
1958 This paragraph had a long label. The first
1959 character of text on the first line does not line up
1960 with the text on second and subsequent lines,
1961 although they line up with each other.
1965 A variation of this is a bulleted list.
1969 @c ---------------------------------------------------------------------
1971 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1972 @subsection Sections and Chapters
1974 Most macro packages supply some form of section headers. The simplest
1975 kind is simply the heading on a line by itself in bold type. Others
1976 supply automatically numbered section heading or different heading
1977 styles at different levels. Some, more sophisticated, macro packages
1978 supply macros for starting chapters and appendices.
1980 @c ---------------------------------------------------------------------
1982 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1983 @subsection Headers and Footers
1985 Every macro package gives some way to manipulate the headers and footers
1986 (or @dfn{titles}) on each page. Some packages allow for different ones
1987 on the even and odd pages (for material printed in a book form).
1989 The titles are called three-part titles, that is, there is a
1990 left-justified part, a centered part, and a right-justified part. An
1991 automatically generated page number may be put in any of these fields
1992 with the @samp{%} character (see @ref{Page Layout}, for more details).
1994 @c ---------------------------------------------------------------------
1996 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1997 @subsection Page Layout
1999 Most macro packages let the user specify top and bottom margins and
2000 other details about the appearance of the printed pages.
2002 @c ---------------------------------------------------------------------
2004 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
2005 @subsection Displays
2008 Displays are sections of text to be set off from the body of the paper.
2009 Major quotes, tables, and figures are types of displays, as are all the
2010 examples used in this document.
2012 @cindex quotes, major
2013 @cindex major quotes
2014 @dfn{Major quotes} are quotes which are several lines long, and hence
2015 are set in from the rest of the text without quote marks around them.
2018 A @dfn{list} is an indented, single spaced, unfilled display. Lists
2019 should be used when the material to be printed should not be filled and
2020 justified like normal text, such as columns of figures or the examples
2024 A @dfn{keep} is a display of lines which are kept on a single page if
2025 possible. An example for a keep might be a diagram. Keeps differ from
2026 lists in that lists may be broken over a page boundary whereas keeps are
2029 @cindex keep, floating
2030 @cindex floating keep
2031 Floating keeps move relative to the text. Hence, they are good for
2032 things which are referred to by name, such as ``See figure@w{ }3''. A
2033 floating keep appears at the bottom of the current page if it fits;
2034 otherwise, it appears at the top of the next page. Meanwhile, the
2035 surrounding text `flows' around the keep, thus leaving no blank areas.
2037 @c ---------------------------------------------------------------------
2039 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
2040 @subsection Footnotes and Annotations
2044 There are a number of requests to save text for later printing.
2046 @dfn{Footnotes} are printed at the bottom of the current page.
2048 @cindex delayed text
2049 @dfn{Delayed text} is very similar to a footnote except that it is
2050 printed when called for explicitly. This allows a list of references to
2051 appear (for example) at the end of each chapter, as is the convention in
2054 Most macro packages which supply this functionality also supply a means
2055 of automatically numbering either type of annotation.
2057 @c ---------------------------------------------------------------------
2059 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
2060 @subsection Table of Contents
2061 @cindex table of contents
2062 @cindex contents, table of
2064 @dfn{Tables of contents} are a type of delayed text having a tag
2065 (usually the page number) attached to each entry after a row of dots.
2066 The table accumulates throughout the paper until printed, usually after
2067 the paper has ended. Many macro packages provide the ability to have
2068 several tables of contents (e.g.@: a standard table of contents, a list
2071 @c ---------------------------------------------------------------------
2073 @node Indices, Paper Formats, Table of Contents, Common Features
2075 @cindex index, in macro package
2077 While some macro packages use the term @dfn{index}, none actually
2078 provide that functionality. The facilities they call indices are
2079 actually more appropriate for tables of contents.
2081 @c ---------------------------------------------------------------------
2083 @node Paper Formats, Multiple Columns, Indices, Common Features
2084 @subsection Paper Formats
2085 @cindex paper formats
2087 Some macro packages provide stock formats for various kinds of
2088 documents. Many of them provide a common format for the title and
2089 opening pages of a technical paper. The @file{mm} macros in particular
2090 provide formats for letters and memoranda.
2092 @c ---------------------------------------------------------------------
2094 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
2095 @subsection Multiple Columns
2097 Some macro packages (but not @file{man}) provide the ability to have two
2098 or more columns on a page.
2100 @c ---------------------------------------------------------------------
2102 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
2103 @subsection Font and Size Changes
2105 The built-in font and size functions are not always intuitive, so all
2106 macro packages provide macros to make these operations simpler.
2108 @c ---------------------------------------------------------------------
2110 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
2111 @subsection Predefined Strings
2113 Most macro packages provide various predefined strings for a variety of
2114 uses; examples are sub- and superscripts, printable dates, quotes and
2115 various special characters.
2117 @c ---------------------------------------------------------------------
2119 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
2120 @subsection Preprocessor Support
2122 All macro packages provide support for the various preprocessors and may
2123 extend their functionality.
2125 For example, all macro packages mark tables (which are processed with
2126 @code{gtbl}) by placing them between @code{.TS} and @code{.TE} macros.
2127 The @file{ms} macro package has an option, @code{.TS@w{}H}, that prints
2128 a caption at the top of a new page (when the table is too long to fit on
2131 @c ---------------------------------------------------------------------
2133 @node Configuration and Customization, , Preprocessor Support, Common Features
2134 @subsection Configuration and Customization
2136 Some macro packages provide means of customizing many of the details of
2137 how the package behaves. This ranges from setting the default type size
2138 to changing the appearance of section headers.
2142 @c =====================================================================
2143 @c =====================================================================
2145 @node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top
2146 @chapter Macro Packages
2147 @cindex macro packages
2148 @cindex packages, macros
2150 This chapter documents the main macro packages that come with
2162 @c =====================================================================
2164 @node man, mdoc, Macro Packages, Macro Packages
2166 @cindex manual pages
2169 @pindex man-old.tmac
2171 This is the most popular and probably the most important macro package
2172 of @code{groff}. It is easy to use, and a vast majority of manual pages
2179 * Miscellaneous man macros::
2180 * Predefined man strings::
2181 * Preprocessors in man pages::
2184 @c ---------------------------------------------------------------------
2186 @node Man options, Man usage, man, man
2189 The command line format for using the @file{man} macros with
2193 groff -m man [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ]
2194 [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ]
2198 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2202 This option (the default if a tty output device is used) creates a
2203 single, very long page instead of multiple pages. Use @code{-rcR=0}
2207 If more than one manual page is given on the command line, number the
2208 pages continuously, rather than starting each at@w{ }1.
2211 Double-sided printing. Footers for even and odd pages are formatted
2215 Page numbering starts with @var{nnn} rather than with@w{ }1.
2218 Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base
2219 document font size instead of the default value of@w{ }10@dmn{pt}.
2222 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2223 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2224 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2227 @c ---------------------------------------------------------------------
2229 @node Man usage, Man font macros, Man options, man
2231 @cindex @code{man} macros
2232 @cindex macros for manual pages [@code{man}]
2235 This section describes the available macros for manual pages. For
2236 further customization, put additional macros and requests into the file
2237 @file{man.local} which is loaded immediately after the @file{man}
2240 @Defmac {TH, title section [@Var{extra1}] [@Var{extra2}] [@Var{extra3}], man}
2241 Set the title of the man page to @var{title} and the section to
2242 @var{section}, which must have a value between 1 and@w{ }8. The value
2243 of @var{section} may also have a string appended, e.g.@: @samp{.pm},
2244 to indicate a specific subsection of the man pages.
2246 Both @var{title} and @var{section} are positioned at the left and right
2247 in the header line (with @var{section} in parentheses immediately
2248 appended to @var{title}. @var{extra1} is positioned in the middle of
2249 the footer line. @var{extra2} is positioned at the left in the footer
2250 line (or at the left on even pages and at the right on odd pages if
2251 double-sided printing is active). @var{extra3} is centered in the
2254 For @acronym{HTML} output, headers and footers are completely suppressed.
2256 Additionally, this macro starts a new page; the new line number is@w{ }1
2257 again (except if the @option{-rC1} option is given on the command line)
2258 -- this feature is intended only for formatting multiple man pages; a
2259 single man page should contain exactly one @code{TH} macro at the
2260 beginning of the file.
2263 @Defmac {SH, [@Var{heading}], man}
2264 Set up an unnumbered section heading sticking out to the left. Prints
2265 out all the text following @code{SH} up to the end of the line (or the
2266 text in the next line if there is no argument to @code{SH}) in bold
2267 face, one size larger than the base document size. Additionally, the
2268 left margin for the following text is reset to its default value.
2271 @Defmac {SS, [@Var{heading}], man}
2272 Set up an unnumbered (sub)section heading. Prints out all the text
2273 following @code{SS} up to the end of the line (or the text in the next
2274 line if there is no argument to @code{SS}) in bold face, at the same
2275 size as the base document size. Additionally, the left margin for the
2276 following text is reset to its default value.
2279 @Defmac {TP, [@Var{nnn}], man}
2280 Set up an indented paragraph with label. The indentation is set to
2281 @var{nnn} if that argument is supplied (the default unit is @samp{n}
2282 if omitted), otherwise it is set to the default indentation value.
2284 The first line of text following this macro is interpreted as a string
2285 to be printed flush-left, as it is appropriate for a label. It is not
2286 interpreted as part of a paragraph, so there is no attempt to fill the
2287 first line with text from the following input lines. Nevertheless, if
2288 the label is not as wide as the indentation, then the paragraph starts
2289 at the same line (but indented), continuing on the following lines.
2290 If the label is wider than the indentation, then the descriptive part
2291 of the paragraph begins on the line following the label, entirely
2292 indented. Note that neither font shape nor font size of the label is
2293 set to a default value; on the other hand, the rest of the text has
2294 default font settings.
2297 @DefmacList {LP, , man}
2298 @DefmacItem {PP, , man}
2299 @DefmacListEnd {P, , man}
2300 These macros are mutual aliases. Any of them causes a line break at
2301 the current position, followed by a vertical space downwards by the
2302 amount specified by the @code{PD} macro. The font size and shape are
2303 reset to the default value (10@dmn{pt} roman). Finally, the current
2304 left margin is restored.
2307 @Defmac {IP, [@Var{designator}] [@Var{nnn}], man}
2308 Set up an indented paragraph, using @var{designator} as a tag to mark
2309 its beginning. The indentation is set to @var{nnn} if that argument
2310 is supplied (default unit is @samp{n}), otherwise the default
2311 indentation value is used. Font size and face of the paragraph (but
2312 not the designator) are reset to their default values. To start an
2313 indented paragraph with a particular indentation but without a
2314 designator, use @samp{""} (two double quotes) as the first argument of
2317 For example, to start a paragraph with bullets as the designator and
2318 4@dmn{en} indentation, write
2325 @cindex hanging indentation [@code{man}]
2326 @cindex @code{man} macros, hanging indentation
2327 @Defmac {HP, [@Var{nnn}], man}
2328 Set up a paragraph with hanging left indentation. The indentation is
2329 set to @var{nnn} if that argument is supplied (default unit is
2330 @samp{n}), otherwise the default indentation value is used. Font size
2331 and face are reset to their default values.
2334 @cindex left margin, how to move [@code{man}]
2335 @cindex @code{man} macros, moving left margin
2336 @Defmac {RS, [@Var{nnn}], man}
2337 Move the left margin to the right by the value @var{nnn} if specified
2338 (default unit is @samp{n}); otherwise the default indentation value
2339 is used. Calls to the @code{RS} macro can be nested.
2342 @Defmac {RE, [@Var{nnn}], man}
2343 Move the left margin back to level @var{nnn}; if no argument is given,
2344 it moves one level back. The first level (i.e., no call to @code{RS}
2345 yet) has number@w{ }1, and each call to @code{RS} increases the level
2349 @cindex line breaks, with vertical space [@code{man}]
2350 @cindex @code{man} macros, line breaks with vertical space
2351 To summarize, the following macros cause a line break with the insertion
2352 of vertical space (which amount can be changed with the @code{PD}
2353 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2354 @code{P}), @code{IP}, and @code{HP}.
2356 @cindex line breaks, without vertical space [@code{man}]
2357 @cindex @code{man} macros, line breaks without vertical space
2358 The macros @code{RS} and @code{RE} also cause a break but do not insert
2361 @c ---------------------------------------------------------------------
2363 @node Man font macros, Miscellaneous man macros, Man usage, man
2364 @subsection Macros to set fonts
2365 @cindex font selection [@code{man}]
2366 @cindex @code{man} macros, how to set fonts
2368 The standard font is roman; the default text size is 10@w{ }point.
2370 @Defmac {SM, [@Var{text}], man}
2371 Set the text on the same line or the text on the next line in a font
2372 that is one point size smaller than the default font.
2375 @cindex boldface [@code{man}]
2376 @cindex @code{man} macros, boldface
2377 @Defmac {SB, [@Var{text}], man}
2378 Set the text on the same line or the text on the next line in boldface
2379 font, one point size smaller than the default font.
2382 @Defmac {BI, text, man}
2383 Set its arguments alternately in bold face and italic. Thus,
2386 .BI this "word and" that
2390 would set ``this'' and ``that'' in bold face, and ``word and'' in
2394 @Defmac {IB, text, man}
2395 Set its arguments alternately in italic and bold face.
2398 @Defmac {RI, text, man}
2399 Set its arguments alternately in roman and italic.
2402 @Defmac {IR, text, man}
2403 Set its arguments alternately in italic and roman.
2406 @Defmac {BR, text, man}
2407 Set its arguments alternately in bold face and roman.
2410 @Defmac {RB, text, man}
2411 Set its arguments alternately in roman and bold face.
2414 @Defmac {B, [@Var{text}], man}
2415 Set @var{text} in bold face. If no text is present on the line where
2416 the macro is called, then the text of the next line appears in bold
2420 @cindex italic fonts [@code{man}]
2421 @cindex @code{man} macros, italic fonts
2422 @Defmac {I, [@Var{text}], man}
2423 Set @var{text} in italic. If no text is present on the line where the
2424 macro is called, then the text of the next line appears in italic.
2427 @c ---------------------------------------------------------------------
2429 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2430 @subsection Miscellaneous macros
2433 @cindex @code{man} macros, default indentation
2434 @cindex default indentation [@code{man}]
2435 The default indentation is 7.2@dmn{n} for all output devices except for
2436 @code{grohtml} which ignores indentation.
2438 @cindex tab stops [@code{man}]
2439 @cindex @code{man} macros, tab stops
2441 Set tabs every 0.5@w{ }inches. Since this macro is always called
2442 during a @code{TH} request, it makes sense to call it only if the tab
2443 positions have been changed.
2446 @cindex empty space before a paragraph [@code{man}]
2447 @cindex @code{man} macros, empty space before a paragraph
2448 @Defmac {PD, [@Var{nnn}], man}
2449 Adjust the empty space before a new paragraph (or section). The
2450 optional argument gives the amount of space (default unit is
2451 @samp{v}); without parameter, the value is reset to its default value
2452 (1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise).
2455 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2456 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2458 @c ---------------------------------------------------------------------
2460 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2461 @subsection Predefined strings
2463 The following strings are defined:
2466 Switch back to the default font size.
2470 The `registered' sign.
2474 The `trademark' sign.
2477 @cindex @code{lq} glyph, and @code{lq} string [@code{man}]
2478 @cindex @code{rq} glyph, and @code{rq} string [@code{man}]
2479 @DefstrList {lq, man}
2480 @DefstrListEnd {rq, man}
2481 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2485 @c ---------------------------------------------------------------------
2487 @node Preprocessors in man pages, , Predefined man strings, man
2488 @subsection Preprocessors in @file{man} pages
2490 @cindex preprocessor, calling convention
2491 @cindex calling convention of preprocessors
2492 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2493 become common usage to make the first line of the man page look like
2500 @pindex geqn@r{, invocation in manual pages}
2501 @pindex grefer@r{, invocation in manual pages}
2502 @pindex gtbl@r{, invocation in manual pages}
2503 @pindex man@r{, invocation of preprocessors}
2505 Note the single space character after the double quote. @var{word}
2506 consists of letters for the needed preprocessors: @samp{e} for
2507 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2508 Modern implementations of the @code{man} program read this first line
2509 and automatically call the right preprocessor(s).
2512 @c =====================================================================
2514 @node mdoc, ms, man, Macro Packages
2515 @section @file{mdoc}
2518 @c XXX documentation
2521 @c =====================================================================
2523 @node ms, me, mdoc, Macro Packages
2528 macros are suitable for reports, letters, books,
2529 user manuals, and so forth.
2530 The package provides macros for cover pages, section headings,
2531 paragraphs, lists, footnotes, pagination,
2532 and a table of contents.
2536 * General ms Structure::
2537 * ms Document Control Registers::
2538 * ms Cover Page Macros::
2541 * Differences from AT&T ms::
2544 @c ---------------------------------------------------------------------
2546 @node ms Intro, General ms Structure, ms, ms
2547 @subsection Introduction to @file{ms}
2549 The original @file{-ms} macros were included with
2550 @acronym{AT&T} @code{troff} as well as the
2552 While the @file{man} package is intended for brief documents
2553 that can be read on-line as well as printed, the @file{ms}
2554 macros are suitable for longer documents that are meant to be
2555 printed rather than read on-line.
2557 The @file{ms} macro package included with @code{groff}
2558 is a complete, bottom-up re-implementation.
2559 Several macros (specific to @acronym{AT&T}
2560 or Berkeley) are not included, while several new commands are.
2561 @xref{Differences from AT&T ms}, for more information.
2563 @c ---------------------------------------------------------------------
2565 @node General ms Structure, ms Document Control Registers, ms Intro, ms
2566 @subsection General structure of an @file{ms} document
2567 @cindex @file{ms}, general structure
2569 The @file{ms} macro package expects a certain amount of structure,
2570 but not as much as packages such as @file{man} or @file{mdoc}.
2572 The simplest documents can begin with a paragraph macro
2573 (such as @code{LP} or @code{PP}),
2574 and consist of text separated by paragraph macros
2575 or even blank lines.
2576 Longer documents have a structure as follows:
2580 If you invoke the @code{RP}
2581 (report) macro on the first line of the document,
2582 @code{groff} prints the cover page information on its own page;
2583 otherwise it prints the information on the
2584 first page with your document text immediately following.
2585 Other document formats found in @acronym{AT&T} @code{troff}
2586 are specific to @acronym{AT&T} or Berkeley, and are not supported in
2589 @item Format and layout
2590 By setting number registers,
2591 you can change your document's type (font and size),
2592 margins, spacing, headers and footers, and footnotes.
2593 @xref{ms Document Control Registers}, for more details.
2596 A cover page consists of a title, the author's name and institution,
2597 an abstract, and the date.
2598 @footnote{Actually, only the title is required.}
2599 @xref{ms Cover Page Macros}, for more details.
2602 Following the cover page is your document.
2603 You can use the @file{ms}
2604 macros to write reports, letters, books, and so forth.
2605 The package is designed for structured documents,
2606 consisting of paragraphs interspersed with headings
2607 and augmented by lists, footnotes, tables, and other
2609 @xref{ms Body Text}, for more details.
2611 @item Table of contents
2612 Longer documents usually include a table of contents,
2613 which you can invoke by placing the
2615 macro at the end of your document.
2617 macros have minimal indexing facilities, consisting of the
2618 @code{IX} macro, which prints an entry on standard error.
2619 Printing the table of contents at the end is necessary since
2620 @code{groff} is a single-pass text formatter,
2621 thus it cannot determine the page number of each section
2622 until that section has actually been set and printed.
2623 Since @file{ms} output is intended for hardcopy,
2624 you can manually relocate the pages containing
2625 the table of contents between the cover page and the
2626 body text after printing.
2629 @c ---------------------------------------------------------------------
2631 @node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms
2632 @subsection Document control registers
2633 @cindex @file{ms}, document control registers
2635 The following is a list of document control number registers.
2636 For the sake of consistency,
2637 set registers related to margins at the beginning of your document,
2638 or just after the @code{RP} macro.
2639 You can set other registers later in your document,
2640 but you should keep them together at the beginning
2641 to make them easy to find and edit as necessary.
2643 @unnumberedsubsubsec Margin Settings
2646 Defines the page offset (i.e.@: the left margin).
2647 There is no explicit right margin setting; the combination of
2648 the @code{PO} and @code{LL} registers implicitly define the
2651 Effective: next page.
2653 Default value: 1@dmn{i}.
2657 Defines the line length (i.e.@: the width of the body text).
2659 Effective: next paragraph.
2665 Defines the title length (i.e.@: the header and footer width).
2666 This is usually the same as @code{LL}, but not necessarily.
2668 Effective: next paragraph.
2674 Defines the header margin height at the top of the page.
2676 Effective: next page.
2682 Defines the footer margin height at the bottom of the page.
2684 Effective: next page.
2689 @unnumberedsubsubsec Text Settings
2692 Defines the point size of the body text.
2694 Effective: next paragraph.
2700 Defines the space between lines (line height plus leading).
2702 Effective: next paragraph.
2707 @unnumberedsubsubsec Paragraph Settings
2710 Defines the initial indent of a @code{.PP} paragraph.
2712 Effective: next paragraph.
2718 Defines the space between paragraphs.
2720 Effective: next paragraph.
2722 Default: 0.3@dmn{v}.
2726 Defines the indent on both sides of a quoted (@code{.QP}) paragraph.
2728 Effective: next paragraph.
2733 @unnumberedsubsubsec Footnote Settings
2736 Defines the length of a footnote.
2738 Effective: next footnote.
2740 Default: @math{@code{\n[LL]} * 5 / 6}.
2744 Defines the footnote indent.
2746 Effective: next footnote.
2752 The footnote format:
2755 Prints the footnote number as a superscript; indents the footnote (default).
2758 Prints the number followed by a period (like 1.)
2759 and indents the footnote.
2762 Like 1, without an indent.
2765 Like 1, but prints the footnote number as a hanging paragraph.
2768 Effective: next footnote.
2773 @unnumberedsubsubsec Miscellaneous Number Registers
2775 @Defmpreg {MINGW, ms}
2776 Defines the minimum width between columns in a multi-column document.
2778 Effective: next page.
2783 @c ---------------------------------------------------------------------
2785 @node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms
2786 @subsection Cover page macros
2787 @cindex @file{ms}, cover page macros
2788 @cindex Cover page macros, @file{ms}
2790 Use the following macros to create a cover page for your document
2793 @Defmac {RP, [@code{no}], ms}
2794 Specifies the report format for your document.
2795 The report format creates a separate cover page.
2796 The default action (no @code{.RP}
2797 macro) is to print a subset of the
2798 cover page on page 1 of your document.
2800 If you use the word @code{no} as an optional argument,
2801 @code{groff} prints a title page but
2802 does not repeat any of the title page information
2803 (title, author, abstract, etc.)
2804 on page 1 of the document.
2807 @Defmac {DA, [@dots{}], ms}
2808 (optional) Print the current date, or the arguments to the macro if any,
2809 on the title page (if specified) and in the footers.
2810 This is the default for @code{nroff}.
2813 @Defmac {ND, [@dots{}], ms}
2814 (optional) Print the current date, or the arguments to the macro if any,
2815 on the title page (if specified) but not in the footers.
2816 This is the default for @code{troff}.
2820 Specifies the document title.
2821 @code{groff} collects text following the @code{.TL}
2822 macro into the title, until reaching the author name or abstract.
2826 Specifies the author's name, which appears on the
2827 line (or lines) immediately following.
2828 You can specify multiple authors as follows:
2834 University of West Bumblefuzz
2838 Monolithic Corporation
2845 Specifies the author's institution.
2846 You can specify multiple institutions in the same way
2847 that you specify multiple authors.
2850 @Defmac {AB, [@code{no}], ms}
2851 Begins the abstract.
2852 The default is to print the word @acronym{ABSTRACT},
2853 centered and in italics, above the text of the abstract.
2854 The word @code{no} as an optional argument suppresses this heading.
2861 The following is example mark-up for a title page.
2862 @cindex Title page, example markup
2863 @cindex Example markup, title page
2869 The Inevitability of Code Bloat
2870 in Commercial and Free Software
2874 University of West Bumblefuzz
2876 This report examines the long-term growth
2877 of the code bases in two large, popular software
2878 packages; the free Emacs and the commercial
2880 While differences appear in the type or order
2881 of features added, due to the different
2882 methodologies used, the results are the same
2885 The free software approach is shown to be
2886 superior in that while free software can
2887 become as bloated as commercial offerings,
2888 free software tends to have fewer serious
2889 bugs and the added features are in line with
2893 ... the rest of the paper follows ...
2897 @c ---------------------------------------------------------------------
2899 @node ms Body Text, ms Page Layout, ms Cover Page Macros, ms
2900 @subsection Body text
2901 @cindex @file{ms}, body text
2903 This section describes macros used to mark up the body of your document.
2904 Examples include paragraphs, sections, and other groups.
2907 * Paragraphs in ms::
2909 * Highlighting in ms::
2912 * ms Displays and Keeps::
2914 * Example multi-page table::
2918 @c ---------------------------------------------------------------------
2920 @node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text
2921 @subsubsection Paragraphs
2922 @cindex @file{ms}, paragraph macros
2924 The following paragraph types are available.
2927 Sets a paragraph with an initial indent.
2931 Sets a paragraph with no initial indent.
2935 Sets a paragraph that is indented at both left and right margins.
2936 The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
2937 The next paragraph or heading returns margins to normal.
2941 Sets a paragraph whose lines are indented,
2942 except for the first line.
2943 This is a Berkeley extension.
2946 The following markup uses all four paragraph macros.
2951 Cases used in the study
2953 The following software and versions were
2954 considered for this report.
2956 For commercial software, we chose
2957 .B "Microsoft Word for Windows" ,
2958 starting with version 1.0 through the
2959 current version (Word 2000).
2961 For free software, we chose
2963 from its first appearance as a standalone
2964 editor through the current version (v20).
2965 See [Bloggs 2002] for details.
2967 Franklin's Law applied to software:
2968 software expands to outgrow both
2969 RAM and disk space over time.
2974 .I "Everyone's a Critic" ,
2975 Underground Press, March 2002.
2976 A definitive work that answers all questions
2977 and criticisms about the quality and usability of
2983 @c ---------------------------------------------------------------------
2985 @node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text
2986 @subsubsection Headings
2987 @cindex @file{ms}, heading macros
2989 Use headings to create a hierarchical structure for your document.
2990 The @file{ms} macros print headings in @strong{bold},
2991 using the same font family and point size as the body text.
2993 The following describes the heading macros:
2995 @DefmacList {NH, @Var{curr-level}, ms}
2996 @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
2998 The argument is either a numeric argument to indicate the
2999 level of the heading, or the letter@w{ }@code{S} followed by numeric
3000 arguments to set the heading level explicitly.
3002 If you specify heading levels out of sequence, such as invoking
3003 @samp{.NH 3} after @samp{.NH 1}, @code{groff}
3004 prints a warning on standard error.
3008 Unnumbered subheading.
3011 @c ---------------------------------------------------------------------
3013 @node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text
3014 @subsubsection Highlighting
3015 @cindex @file{ms}, highlighting macros
3017 The @file{ms} macros provide a variety of methods to highlight
3020 @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3021 Sets its first argument in @strong{bold type}.
3022 If you specify a second argument, @code{groff} prints it in the
3023 previous font after the bold text, with no intervening space
3024 (this allows you to set punctuation after the highlighted text
3025 without highlighting the punctuation).
3026 Similarly, it prints the third argument (if any) in the previous
3027 font @strong{before} the first argument.
3034 prints (@strong{foo}).
3036 If you give this macro no arguments, @code{groff}
3037 prints all text following in bold until
3038 the next highlighting, paragraph, or heading macro.
3041 @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3042 Sets its first argument in roman (or regular) type.
3043 It operates similarly to the @code{B}@w{ }macro otherwise.
3046 @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3047 Sets its first argument in @emph{italic type}.
3048 It operates similarly to the @code{B}@w{ }macro otherwise.
3051 @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3052 Sets its first argument in a @code{constant width face}.
3053 It operates similarly to the @code{B}@w{ }macro otherwise.
3056 @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3057 Sets its first argument in bold italic type.
3058 It operates similarly to the @code{B}@w{ }macro otherwise.
3061 @Defmac {BX, [@Var{txt}], ms}
3062 Prints its argument and draws a box around it.
3063 If you want to box a string that contains spaces,
3064 use a digit-width space (@code{\0}).
3067 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3068 Prints its first argument with an underline.
3069 If you specify a second argument, @code{groff}
3070 prints it in the previous font after
3071 the underlined text, with no intervening space.
3075 Prints all text following in larger type
3076 (two points larger than the current point size) until
3077 the next font size, highlighting, paragraph, or heading macro.
3078 You can specify this macro multiple times
3079 to enlarge the point size as needed.
3083 Prints all text following in smaller type
3084 (two points smaller than the current point size) until
3085 the next type size, highlighting, paragraph, or heading macro.
3086 You can specify this macro multiple times
3087 to reduce the point size as needed.
3091 Prints all text following in the normal point size
3092 (that is, the value of the @code{PS} register).
3095 @c ---------------------------------------------------------------------
3097 @node Lists in ms, Tabstops in ms, Highlighting in ms, ms Body Text
3098 @subsubsection Lists
3099 @cindex @file{ms}, list macros
3101 The @code{.IP} macro handles duties for all lists.
3103 @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3104 The @var{marker} is usually a bullet character (@code{\[bu]})
3105 for unordered lists, a number (or auto-incrementing number
3106 register) for numbered lists, or a word or phrase for indented
3107 (glossary-style) lists.
3109 The @var{width} specifies the indent for the body of each list item;
3110 its default unit is @samp{n}.
3111 Once specified, the indent remains the same for all
3112 list items in the document until specified again.
3115 The following is an example of a bulleted list.
3116 @cindex Example markup, bulleted list (ms)
3117 @cindex Bulleted list, example markup (ms)
3143 The following is an example of a numbered list.
3144 @cindex Example markup, numbered list (ms)
3145 @cindex Numbered list, example markup (ms)
3170 Note the use of the auto-incrementing number
3171 register in this example.
3174 The following is an example of a glossary-style list.
3175 @cindex Example markup, glossary-style list (ms)
3176 @cindex Glossary-style list, example markup (ms)
3179 A glossary-style list:
3181 Two or more attorneys.
3183 Firearms, preferably
3193 A glossary-style list:
3196 Two or more attorneys.
3198 guns Firearms, preferably large-caliber.
3201 Gotta pay for those lawyers and guns!
3204 In the last example, the @code{IP} macro places the definition
3205 on the same line as the term if it has enough space; otherwise,
3206 it breaks to the next line and starts the definition below the
3208 This may or may not be the effect you want, especially if some
3209 of the definitions break and some do not.
3210 The following examples show two possible ways to force a break.
3212 The first workaround uses the @code{.br}
3213 request to force a break after printing the term or label.
3217 A glossary-style list:
3219 Two or more attorneys.
3222 Firearms, preferably large-caliber.
3224 Gotta pay for those lawyers and guns!
3229 The second workaround uses the @code{\p} escape to force the break.
3230 Note the space following the escape; this is important.
3231 If you omit the space, @code{groff} prints the first word on
3232 the same line as the term or label (if it fits) @strong{then}
3237 A glossary-style list:
3239 Two or more attorneys.
3241 \p Firearms, preferably large-caliber.
3243 Gotta pay for those lawyers and guns!
3248 To set nested lists, use the @code{RS} and @code{RE} macros.
3249 @cindex @file{ms}, nested lists
3250 @cindex Nested lists (ms)
3252 @DefmacList {RS, , ms}
3253 @DefmacListEnd {RE, , ms}
3254 These macros begin and end a section indented to line
3255 up with the body of an @code{IP} macro.
3291 @c ---------------------------------------------------------------------
3293 @node Tabstops in ms, ms Displays and Keeps, Lists in ms, ms Body Text
3294 @subsubsection Tab Stops
3296 Use the @code{ta} request to define tab stops as needed.
3297 @xref{Tabs and Fields}.
3300 Use this macro to reset the tab stops to the default for @file{ms}
3302 You can redefine the @code{TA} macro to create a different set
3303 of default tab stops.
3306 @c ---------------------------------------------------------------------
3308 @node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
3309 @subsubsection Displays and keeps
3310 @cindex @file{ms}, displays
3311 @cindex @file{ms}, keeps
3313 @cindex Displays (ms)
3315 Use displays to show text-based examples or figures
3316 (such as code listings).
3318 Displays turn off filling, so lines of code are displayed
3319 as-is without inserting @code{br} requests in between each line.
3320 Displays can be @dfn{kept} on a single page, or allowed
3321 to break across pages.
3323 @DefmacList {DS, @t{L}, ms}
3324 @DefmacItem {LD, , ms}
3325 @DefmacListEnd {DE, , ms}
3326 Left-justified display.
3327 The @samp{.DS L} call generates a page break, if necessary,
3328 to keep the entire display on one page.
3329 The @code{LD} macro allows the display to break across pages.
3330 The @code{DE} macro ends the display.
3333 @DefmacList {DS, @t{I}, ms}
3334 @DefmacItem {ID, , ms}
3335 @DefmacListEnd {DE, , ms}
3336 Indents the display as defined by the @code{DI} register.
3337 The @samp{.DS I} call generates a page break, if necessary,
3338 to keep the entire display on one page.
3339 The @code{ID} macro allows the display to break across pages.
3340 The @code{DE} macro ends the display.
3343 @DefmacList {DS, @t{B}, ms}
3344 @DefmacItem {BD, , ms}
3345 @DefmacListEnd {DE, , ms}
3346 Sets a block-centered display: the entire display is left-justified,
3347 but indented so that the longest line in the display is centered
3349 The @samp{.DS B} call generates a page break, if necessary,
3350 to keep the entire display on one page.
3351 The @code{BD} macro allows the display to break across pages.
3352 The @code{DE} macro ends the display.
3355 @DefmacList {DS, @t{C}, ms}
3356 @DefmacItem {CD, , ms}
3357 @DefmacListEnd {DE, , ms}
3358 Sets a centered display: each line in the display is centered.
3359 The @samp{.DS C} call generates a page break, if necessary,
3360 to keep the entire display on one page.
3361 The @code{CD} macro allows the display to break across pages.
3362 The @code{DE} macro ends the display.
3365 @DefmacList {DS, @t{R}, ms}
3366 @DefmacItem {RD, , ms}
3367 @DefmacListEnd {DE, , ms}
3368 Right-justifies each line in the display.
3369 The @samp{.DS R} call generates a page break, if necessary,
3370 to keep the entire display on one page.
3371 The @code{RD} macro allows the display to break across pages.
3372 The @code{DE} macro ends the display.
3376 On occasion, you may want to @dfn{keep} other text together on a page.
3377 For example, you may want to keep two paragraphs together, or
3378 a paragraph that refers to a table (or list, or other item)
3379 immediately following.
3380 The @file{ms} macros provide the @code{KS} and @code{KE}
3381 macros for this purpose.
3383 @DefmacList {KS, , ms}
3384 @DefmacListEnd {KE, , ms}
3385 The @code{KS} macro begins a block of text to be kept on a
3386 single page, and the @code{KE} macro ends the block.
3389 @DefmacList {KF, , ms}
3390 @DefmacListEnd {KE, , ms}
3391 Specifies a @dfn{floating keep};
3392 if the keep cannot fit on the current page, @code{groff}
3393 holds the contents of the keep and allows text following
3394 the keep (in the source file) to fill in the remainder of
3396 When the page breaks, whether by an explicit @code{bp}
3397 request or by reaching the end of the page, @code{groff}
3398 prints the floating keep at the top of the new page.
3399 This is useful for printing large graphics or tables
3400 that do not need to appear exactly where specified.
3403 You can also use the @code{ne} request to force a page break if
3404 there is not enough vertical space remaining on the page.
3407 Use the following macros to draw a box around a section of
3408 text (such as a display).
3410 @DefmacList {B1, , ms}
3411 @DefmacListEnd {B2, , ms}
3412 Marks the beginning and ending of text that is to have a
3413 box drawn around it.
3414 The @code{B1} macro begins the box; the @code{B2} macro ends it.
3415 Text in the box is automatically placed in a diversion (keep).
3418 @c ---------------------------------------------------------------------
3420 @node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text
3421 @subsubsection Tables, figures, equations, and references
3422 @cindex @file{ms}, tables
3423 @cindex @file{ms}, figures
3424 @cindex @file{ms}, equations
3425 @cindex @file{ms}, references
3427 @cindex Figures (ms)
3428 @cindex Equations (ms)
3429 @cindex References (ms)
3431 The @file{ms} macros support the standard
3432 @code{groff} preprocessors:
3433 @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3438 You mark text meant for preprocessors by enclosing it
3439 in pairs of tags as follows.
3441 @DefmacList {TS, [@code{H}], ms}
3442 @DefmacListEnd {TE, , ms}
3443 Denotes a table, to be processed by the @code{tbl} preprocessor.
3444 The optional argument@w{ }@code{H} to @code{TS} instructs @code{groff}
3445 to create a running header with the information
3446 up to the @code{TH} macro.
3447 @code{groff} prints the header at the beginning of the
3448 table; if the table runs onto another page, @code{groff}
3449 prints the header on the next page as well.
3452 @DefmacList {PS, , ms}
3453 @DefmacListEnd {PE, , ms}
3454 Denotes a graphic, to be processed by the @code{pic} preprocessor.
3455 You can create a @code{pic} file by hand, using the @acronym{AT&T}
3456 @code{pic} manual available on the Web as a reference, or by using
3457 a graphics program such as @code{xfig}.
3460 @DefmacList {EQ, [@Var{align}], ms}
3461 @DefmacListEnd {EN, , ms}
3462 Denotes an equation, to be processed by the @code{eqn} preprocessor.
3463 The optional @var{align} argument can be @code{C}, @code{L}, or@w{
3464 }@code{I} to center (the default), left-justify, or indent the equation.
3467 @DefmacList {[, , ms}
3468 @DefmacListEnd {], , ms}
3469 Denotes a reference, to be processed by the @code{refer} preprocessor.
3470 The @acronym{GNU} @cite{refer(1)} manpage provides a comprehensive
3471 reference to the preprocessor and the format of the bibliographic
3476 * Example multi-page table::
3479 @c ---------------------------------------------------------------------
3481 @node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text
3482 @subsubsection An example multi-page table
3483 @cindex Example markup, multi-page table (ms)
3484 @cindex Multi-page table, example markup (ms)
3486 The following is an example of how to set up a
3487 table that may print across two or more pages.
3494 Text ...of heading...
3499 ... the rest of the table follows...
3505 @c ---------------------------------------------------------------------
3507 @node ms Footnotes, , Example multi-page table, ms Body Text
3508 @subsubsection Footnotes
3509 @cindex @file{ms}, footnotes
3510 @cindex Footnotes (ms)
3512 The @file{ms} macro package has a flexible footnote system.
3513 You can specify either numbered footnotes or symbolic footnotes
3514 (that is, using a marker such as a dagger symbol).
3517 Specifies the location of a numbered footnote marker in the text.
3520 @DefmacList {FS, , ms}
3521 @DefmacListEnd {FE, , ms}
3522 Specifies the text of the footnote.
3523 The default action is to create a numbered footnote;
3524 you can create a symbolic footnote by specifying
3525 a @dfn{mark} character
3526 (such as @code{\[dg]} for the dagger character)
3527 in the body text and as an argument to the @code{FS} macro,
3528 followed by the text of the footnote
3529 and the @code{FE} macro.
3532 You can control how @code{groff}
3533 prints footnote numbers by changing the value of the
3534 @code{FF} register. @xref{ms Document Control Registers}.
3536 @c ---------------------------------------------------------------------
3538 @node ms Page Layout, Differences from AT&T ms, ms Body Text, ms
3539 @subsection Page layout
3540 @cindex @file{ms}, page layout
3541 @cindex Page layout (ms)
3543 The default output from the @file{ms}
3544 macros provides a minimalist page layout:
3545 it prints a single column, with the page number centered at the top
3547 It prints no footers.
3549 You can change the layout by setting
3550 the proper number registers and strings.
3553 * ms Headers and Footers::
3555 * ms Multiple Columns::
3557 * ms Strings and Special Characters::
3560 @c ---------------------------------------------------------------------
3562 @node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout
3563 @subsubsection Headers and footers
3564 @cindex @file{ms}, headers
3565 @cindex @file{ms}, footers
3566 @cindex Headers (ms)
3567 @cindex Footers (ms)
3569 For documents that do not distinguish between odd and even pages,
3570 set the following strings:
3572 @DefstrList {LH, ms}
3573 @DefstrItem {CH, ms}
3574 @DefstrListEnd {RH, ms}
3575 Sets the left, center, and right headers.
3578 @DefstrList {LF, ms}
3579 @DefstrItem {CF, ms}
3580 @DefstrListEnd {RF, ms}
3581 Sets the left, center, and right footers.
3585 For documents that need different information printed in the
3586 even and odd pages, use the following macros:
3588 @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3589 @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3590 @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3591 @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3592 The @code{OH} and @code{EH} macros define headers for the odd and even pages;
3593 the @code{OF} and @code{EF} macros define footers for the odd and even pages.
3594 This is more flexible than defining the individual strings.
3596 You can replace the quote (@code{'}) marks with any character not
3597 appearing in the header or footer text.
3600 @c ---------------------------------------------------------------------
3602 @node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout
3603 @subsubsection Margins
3604 @cindex @file{ms}, margins
3606 You control margins using a set of number registers.
3607 @xref{ms Document Control Registers}, for details.
3609 @c ---------------------------------------------------------------------
3611 @node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout
3612 @subsubsection Multiple columns
3613 @cindex @file{ms}, multiple columns
3614 @cindex Multiple columns (ms)
3616 The @file{ms} macros can set text in as many columns as will
3617 reasonably fit on the page.
3618 The following macros are available;
3619 all of them force a page break if a multi-column mode is already set.
3620 However, if the current mode is single-column, starting a multi-column
3621 mode does @strong{not} force a page break.
3631 @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
3633 If you specify no arguments, it is equivalent to the
3635 Otherwise, @var{width} is the width of each column and
3636 @var{gutter} is the space between columns.
3637 The @code{MINGW} number register controls the default gutter width.
3640 @c ---------------------------------------------------------------------
3642 @node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout
3643 @subsubsection Creating a table of contents
3644 @cindex @file{ms}, creating table of contents
3645 @cindex Table of contents, creating (ms)
3647 The facilities in the @file{ms} macro package for creating
3648 a table of contents are semi-automated at best.
3649 Assuming that you want the table of contents to consist of
3650 the document's headings, you need to repeat those headings
3651 wrapped in @code{XS} and @code{XE} macros.
3653 @DefmacList {XS, [@Var{page}, ms}
3654 @DefmacItem {XA, [@Var{page}, ms}
3655 @DefmacListEnd {XE, , ms}
3656 These macros define a table of contents
3657 or an individual entry in the table of contents,
3658 depending on their use.
3659 The macros are very simple; they cannot indent a heading based on its level.
3660 The easiest way to work around this is to add tabs
3661 to the table of contents string.
3662 The following is an example:
3684 You can manually create a table of contents
3685 by beginning with the @code{XS} macro for the first entry,
3686 specifying the page number for that entry as the argument to @code{XS}.
3687 Add subsequent entries using the @code{XA} macro,
3688 specifying the page number for that entry as the argument to @code{XA}.
3689 The following is an example:
3696 A Brief History of the Universe
3698 Details of Galactic Formation
3705 @Defmac {TC, [@code{no}], ms}
3706 Prints the table of contents on a new page,
3707 setting the page number to@w{ }@strong{i} (Roman numeral one).
3708 You should usually place this macro at the end of the
3709 file, since @code{groff} is a single-pass formatter and
3710 can only print what has been collected up to the point
3711 that the @code{TC} macro appears.
3713 The optional argument @code{no} suppresses printing
3714 the title specified by the string register @code{TOC}.
3717 @Defmac{PX, [@code{no}], ms}
3718 Prints the table of contents on a new page,
3719 using the current page numbering sequence.
3720 Use this macro to print a manually-generated table of contents
3721 at the beginning of your document.
3723 The optional argument @code{no} suppresses printing
3724 the title specified by the string register @code{TOC}.
3727 The @cite{Groff and Friends HOWTO}
3728 includes a @code{sed} script that automatically inserts
3729 @code{XS} and @code{XE} macro entries after each heading in a document.
3731 Altering the @code{NH} macro to automatically build the table
3732 of contents is perhaps initially more difficult, but would save
3733 a great deal of time in the long run if you use @file{ms} regularly.
3735 @c ---------------------------------------------------------------------
3737 @node ms Strings and Special Characters, , ms TOC, ms Page Layout
3738 @subsubsection Strings and Special Characters
3739 @cindex @file{ms}, strings
3740 @cindex @file{ms}, special characters
3741 @cindex @file{ms}, accent marks
3742 @cindex Accent marks
3743 @cindex Special characters
3744 @cindex Strings in @file{ms}
3746 The @file{ms} macros provide the following predefined strings.
3747 You can change the string definitions to help in creating
3748 documents in languages other than English.
3750 @Defstr {REFERENCES, ms}
3751 Contains the string printed at the beginning of the
3752 references (bibliography) page.
3753 The default is @samp{References}.
3756 @Defstr {ABSTRACT, ms}
3757 Contains the string printed at the beginning of the abstract.
3758 The default is @samp{ABSTRACT}.
3762 Contains the string printed at the beginning of the table of contents.
3765 @DefstrList {MONTH1, ms}
3766 @DefstrItem {MONTH2, ms}
3767 @DefstrItem {MONTH3, ms}
3768 @DefstrItem {MONTH4, ms}
3769 @DefstrItem {MONTH5, ms}
3770 @DefstrItem {MONTH6, ms}
3771 @DefstrItem {MONTH7, ms}
3772 @DefstrItem {MONTH8, ms}
3773 @DefstrItem {MONTH9, ms}
3774 @DefstrItem {MONTH10, ms}
3775 @DefstrItem {MONTH11, ms}
3776 @DefstrListEnd {MONTH12, ms}
3777 Prints the full name of the month in dates.
3778 The default is @samp{January}, @samp{February}, etc.
3781 The following special characters are available:
3787 @DefstrList {*Q, ms}
3788 @DefstrListEnd {*U, ms}
3789 Prints typographer's quotes in troff,
3790 plain quotes in nroff.
3791 @code{*Q} is the left quote and @code{*U} is the right quote.
3794 Improved accent marks are available in the @file{ms} macros.
3797 Specify this macro at the beginning of your document
3798 to enable extended accent marks and special characters.
3799 This is a Berkeley extension.
3801 To use the accent marks, place them @strong{after}
3802 the character being accented.
3805 The following accent marks are available
3806 after invoking the @code{AM} macro:
3848 The following are standalone characters
3849 available after invoking the @code{AM} macro:
3852 Upside-down question mark.
3856 Upside-down exclamation point.
3860 German @ss{} ligature.
3888 Lowercase @ae{} ligature.
3892 Uppercase @AE{} ligature.
3895 @c ---------------------------------------------------------------------
3897 @node Differences from AT&T ms, , ms Page Layout, ms
3898 @subsection Differences from @acronym{AT&T} @file{ms}
3899 @cindex @file{ms}, differences from @acronym{AT&T}
3900 @cindex @acronym{AT&T}, @code{ms} differences
3902 This section lists the (minor) differences between the
3903 @code{groff -ms} macros and @acronym{AT&T}
3904 @code{troff -ms} macros.
3907 * Missing ms Macros::
3908 * Additional ms Macros::
3911 @c ---------------------------------------------------------------------
3913 @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
3914 @subsubsection @code{troff} macros not appearing in @code{groff}
3916 Macros missing from @code{groff -ms}
3917 are cover page macros specific to Bell Labs.
3918 The macros known to be missing are:
3922 Technical memorandum; a cover sheet style
3925 Internal memorandum; a cover sheet style
3928 Memo for record; a cover sheet style
3931 Memo for file; a cover sheet style
3934 Engineer's notes; a cover sheet style
3937 Computing Science Tech Report; a cover sheet style
3943 Cover sheet information
3949 @c ---------------------------------------------------------------------
3951 @node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms
3952 @subsubsection @code{groff} macros not appearing in AT&T @code{troff}
3954 The @code{groff -ms} macros have a few minor extensions
3955 compared to the @acronym{AT&T} @code{troff -ms} macros.
3958 Improved accent marks.
3959 @xref{ms Strings and Special Characters}, for details.
3962 @Defmac {DS, @t{I}, ms}
3964 The default behavior of @acronym{AT&T} @code{troff -ms}
3965 was to indent; the @code{groff} default prints displays
3966 flush left with the body text.
3970 Print text in @code{constant width} (Courier) font.
3974 Indexing term (printed on standard error).
3975 You can write a script to capture and process an index
3976 generated in this manner.
3980 The following additional number registers
3981 appear in @code{groff -ms}:
3983 @Defmpreg {MINGW, ms}
3984 Specifies a minimum space
3985 between columns (for multi-column output); this takes the
3986 place of the @code{GW} register that was documented but apparently
3987 not implemented in @acronym{AT&T} @code{troff}.
3991 Several new string registers are available as well.
3992 You can change these to handle (for example) the local language.
3993 @xref{ms Strings and Special Characters}, for details.
3995 @c =====================================================================
3997 @node me, mm, ms, Macro Packages
4001 @c XXX documentation
4002 @c XXX this is a placeholder until we get stuff knocked into shape
4003 See the @file{meintro.me} and @file{meref.me} documents in
4004 groff's @file{doc} directory.
4007 @c =====================================================================
4009 @node mm, , me, Macro Packages
4013 @c XXX documentation
4014 @c XXX this is a placeholder until we get stuff knocked into shape
4015 See the @code{mm} manpage (type @command{man 7 groff_mm} at
4019 @c =====================================================================
4020 @c =====================================================================
4022 @node gtroff Reference, Preprocessors, Macro Packages, Top
4023 @chapter @code{gtroff} Reference
4024 @cindex reference, @code{gtroff}
4025 @cindex @code{gtroff} reference
4027 This chapter covers @strong{all} of the facilities of @code{gtroff}.
4028 Users of macro packages may skip it if not interested in details.
4033 * Input Conventions::
4037 * Embedded Commands::
4039 * Manipulating Filling and Adjusting::
4040 * Manipulating Hyphenation::
4041 * Manipulating Spacing::
4043 * Character Translations::
4044 * Troff and Nroff Mode::
4051 * Conditionals and Loops::
4054 * Drawing Requests::
4058 * Suppressing output::
4061 * Postprocessor Access::
4063 * Gtroff Internals::
4065 * Implementation Differences::
4070 @c =====================================================================
4072 @node Text, Input Conventions, gtroff Reference, gtroff Reference
4074 @cindex text, @code{gtroff} processing
4076 @code{gtroff} input files contain text with control commands
4077 interspersed throughout. But, even without control codes, @code{gtroff}
4078 still does several things with the input text:
4082 filling and adjusting
4085 adding additional space after sentences
4091 inserting implicit line breaks
4095 * Filling and Adjusting::
4099 * Implicit Line Breaks::
4102 @c ---------------------------------------------------------------------
4104 @node Filling and Adjusting, Hyphenation, Text, Text
4105 @subsection Filling and Adjusting
4109 When @code{gtroff} reads text, it collects words from the input and fits
4110 as many of them together on one output line as it can. This is known as
4113 @cindex leading spaces
4114 @cindex spaces, leading and trailing
4115 @cindex extra spaces
4116 @cindex trailing spaces
4117 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
4118 it. This means it widens the spacing between words until the text
4119 reaches the right margin (in the default adjustment mode). Extra spaces
4120 between words are preserved, but spaces at the end of lines are ignored.
4121 Spaces at the front of a line cause a @dfn{break} (breaks are
4122 explained in @ref{Implicit Line Breaks})
4124 @xref{Manipulating Filling and Adjusting}.
4126 @c ---------------------------------------------------------------------
4128 @node Hyphenation, Sentences, Filling and Adjusting, Text
4129 @subsection Hyphenation
4132 Since the odds are not great for finding a set of words, for every
4133 output line, which fit nicely on a line without inserting excessive
4134 amounts of space between words, @code{gtroff} hyphenates words so
4135 that it can justify lines without inserting too much space between
4136 words. It uses an internal hyphenation algorithm (a simplified version
4137 of the algorithm used within @TeX{}) to indicate which words can be
4138 hyphenated and how to do so. When a word is hyphenated, the first part
4139 of the word is added to the current filled line being output (with
4140 an attached hyphen), and the other portion is added to the next
4143 @xref{Manipulating Hyphenation}.
4145 @c ---------------------------------------------------------------------
4147 @node Sentences, Tab Stops, Hyphenation, Text
4148 @subsection Sentences
4151 Although it is often debated, some typesetting rules say there should be
4152 different amounts of space after various punctuation marks. For
4153 example, the @cite{Chicago typsetting manual} says that a period at the
4154 end of a sentence should have twice as much space following it as would
4155 a comma or a period as part of an abbreviation.
4157 @c XXX exact citation of Chicago manual
4159 @cindex sentence space
4160 @cindex space between sentences
4161 @cindex french-spacing
4162 @code{gtroff} does this by flagging certain characters (normally
4163 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters.
4164 When @code{gtroff} encounters one of these characters at the end of a
4165 line, it appends a normal space followed by a @dfn{sentence space} in
4166 the formatted output. (This justifies one of the conventions mentioned
4167 in @ref{Input Conventions}.)
4169 @cindex transparent characters
4170 @cindex character, transparent
4171 @cindex @code{dg} glyph, at end of sentence
4172 @cindex @code{rq} glyph, at end of sentence
4173 @cindex @code{"}, at end of sentence
4174 @cindex @code{'}, at end of sentence
4175 @cindex @code{)}, at end of sentence
4176 @cindex @code{]}, at end of sentence
4177 @cindex @code{*}, at end of sentence
4178 In addition, the following characters or glyphs are treated
4179 transparently while handling end-of-sentence characters: @samp{"},
4180 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}.
4182 See the @code{cflags} request in @ref{Using Symbols}, for more details.
4184 @cindex @code{\&}, at end of sentence
4185 To prevent the insertion of extra space after an end-of-sentence
4186 character (at the end of a line), append @code{\&}.
4188 @c ---------------------------------------------------------------------
4190 @node Tab Stops, Implicit Line Breaks, Sentences, Text
4191 @subsection Tab Stops
4193 @cindex stops, tabulator
4194 @cindex tab character
4195 @cindex character, tabulator
4197 @cindex @acronym{EBCDIC} encoding
4198 @cindex encoding, @acronym{EBCDIC}
4199 @code{gtroff} translates @dfn{tabulator characters}, also called
4200 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
4201 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
4202 tabulator stop. These tab stops are initially located every half inch
4203 across the page. Using this, simple tables can be made easily.
4204 However, it can often be deceptive as the appearance (and width) of the
4205 text on a terminal and the results from @code{gtroff} can vary greatly.
4207 Also, a possible sticking point is that lines beginning with tab
4208 characters are still filled, again producing unexpected results.
4209 For example, the following input
4211 @multitable {12345678} {12345678} {12345678} {12345678}
4213 @tab 1 @tab 2 @tab 3
4221 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
4223 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
4226 @xref{Tabs and Fields}.
4228 @c ---------------------------------------------------------------------
4230 @node Implicit Line Breaks, , Tab Stops, Text
4231 @subsection Implicit Line Breaks
4232 @cindex implicit line breaks
4233 @cindex implicit breaks of lines
4234 @cindex line, implicit breaks
4235 @cindex break, implicit
4238 An important concept in @code{gtroff} is the @dfn{break}. When a break
4239 occurs, @code{gtroff} outputs the partially filled line
4240 (unjustified), and resumes collecting and filling text on the next output
4246 @cindex blank line macro (@code{blm})
4247 There are several ways to cause a break in @code{gtroff}. A blank
4248 line not only causes a break, but it also outputs a one line vertical
4249 space (effectively a blank line). Note that this behaviour can be
4250 modified with the blank line macro request @code{blm}.
4256 A line that begins with a space causes a break and the space is
4257 output at the beginning of the next line. Note that this space isn't
4258 adjusted, even in fill mode.
4260 The end of file also causes a break -- otherwise the last line of
4261 the document may vanish!
4263 Certain requests also cause breaks, implicitly or explicitly. This is
4264 discussed in @ref{Manipulating Filling and Adjusting}.
4267 @c =====================================================================
4269 @node Input Conventions, Measurements, Text, gtroff Reference
4270 @section Input Conventions
4271 @cindex input conventions
4272 @cindex conventions for input
4274 Since @code{gtroff} does filling automatically, it is traditional in
4275 @code{groff} not to try and type things in as nicely formatted
4276 paragraphs. These are some conventions commonly used when typing
4281 Break lines after punctuation, particularly at the end of a sentence
4282 and in other logical places. Keep separate phrases on lines by
4283 themselves, as entire phrases are often added or deleted when editing.
4286 Try to keep lines less than 40-60@w{ }characters, to allow space for
4287 inserting more text.
4290 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
4291 don't try using spaces to get proper indentation).
4295 @c =====================================================================
4297 @node Measurements, Expressions, Input Conventions, gtroff Reference
4298 @section Measurements
4299 @cindex measurements
4301 @cindex units of measurement
4302 @cindex basic unit (@code{u})
4303 @cindex machine unit (@code{u})
4304 @cindex measurement unit
4305 @cindex @code{u} unit
4306 @cindex unit, @code{u}
4307 @code{gtroff} (like many other programs) requires numeric parameters to
4308 specify various measurements. Most numeric parameters@footnote{those
4309 that specify vertical or horizontal motion or a type size} may have a
4310 @dfn{measurement unit} attached. These units are specified as a single
4311 character which immediately follows the number or expression. Each of
4312 these units are understood, by @code{gtroff}, to be a multiple of its
4313 @dfn{basic unit}. So, whenever a different measurement unit is
4314 specified @code{gtroff} converts this into its @dfn{basic units}. This
4315 basic unit, represented by a @samp{u}, is a device dependent measurement
4316 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
4317 inch. The values may be given as fractional numbers; however,
4318 fractional basic units are always rounded to integers.
4320 Some of the measurement units are completely independent of any of the
4321 current settings (e.g.@: type size) of @code{gtroff}.
4325 @cindex inch unit (@code{i})
4326 @cindex @code{i} unit
4327 @cindex unit, @code{i}
4328 Inches. An antiquated measurement unit still in use in certain
4329 backwards countries with incredibly low-cost computer equipment. One
4330 inch is equal to@w{ }2.54@dmn{cm}.
4333 @cindex centimeter unit (@code{c})
4334 @cindex @code{c} unit
4335 @cindex unit, @code{c}
4336 Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
4339 @cindex point unit (@code{p})
4340 @cindex @code{p} unit
4341 @cindex unit, @code{p}
4342 Points. This is a typesetter's measurement used for measure type size.
4343 It is 72@w{ }points to an inch.
4346 @cindex pica unit (@code{P})
4347 @cindex @code{P} unit
4348 @cindex unit, @code{P}
4349 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
4350 12@w{ }points to a pica).
4354 @cindex @code{s} unit
4355 @cindex unit, @code{s}
4356 @cindex @code{z} unit
4357 @cindex unit, @code{z}
4358 @xref{Fractional Type Sizes}, for a discussion of these units.
4361 @cindex @code{f} unit
4362 @cindex unit, @code{f}
4363 Fractions. Value is 65536.
4364 @xref{Colors}, for usage.
4367 The other measurements understood by @code{gtroff} depend on
4368 settings currently in effect in @code{gtroff}. These are very useful
4369 for specifying measurements which should look proper with any size of
4374 @cindex em unit (@code{m})
4375 @cindex @code{m} unit
4376 @cindex unit, @code{m}
4377 Ems. This unit is equal to the current font size in points. So called
4378 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
4379 in the current font.
4382 @cindex en unit (@code{n})
4383 @cindex @code{n} unit
4384 @cindex unit, @code{n}
4385 Ens. This is half of an em.
4388 @cindex vertical space unit (@code{v})
4389 @cindex space, vertical, unit (@code{v})
4390 @cindex @code{v} unit
4391 @cindex unit, @code{v}
4392 Vertical space. This is equivalent to the current line spacing.
4393 @xref{Sizes}, for more information about this.
4396 @cindex @code{M} unit
4397 @cindex unit, @code{M}
4405 @c ---------------------------------------------------------------------
4407 @node Default Units, , Measurements, Measurements
4408 @subsection Default Units
4409 @cindex default units
4410 @cindex units, default
4412 Many requests take a default unit. While this can be helpful at times,
4413 it can cause strange errors in some expressions. For example, the line
4414 length request expects em units. Here are several attempts to get a
4415 line length of 3.5@w{ }inches and their results:
4422 7i/2u @result{} 3.5i
4426 Everything is converted to basic units first. In the above example it
4427 is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{
4428 }10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2
4429 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
4430 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
4433 @cindex measurements, specifying safely
4434 Thus, the safest way to specify measurements is to always
4435 attach a scaling indicator. If you want to multiply or divide by a
4436 certain scalar value, use @samp{u} as the unit for that value.
4439 @c =====================================================================
4441 @node Expressions, Identifiers, Measurements, gtroff Reference
4442 @section Expressions
4445 @code{gtroff} has most arithmetic operators common to other languages:
4447 @c XXX more details; examples
4451 @cindex arithmetic operators
4452 @cindex operators, arithmetic
4458 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
4459 (division), @samp{*} (multiplication), @samp{%} (modulo).
4461 @code{gtroff} only provides integer arithmetic. The internal type used
4462 for computing results is @samp{int}, which is usually a 32@dmn{bit}
4466 @cindex comparison operators
4467 @cindex operators, comparison
4474 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
4475 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
4476 (equal), @samp{==} (the same as @samp{=}).
4479 @cindex logical operators
4480 @cindex operators, logical
4483 Logical: @samp{&} (logical and), @samp{:} (logical or).
4486 @cindex unary operators
4487 @cindex operators, unary
4491 @cindex @code{if} request, and the @samp{!} operator
4492 @cindex @code{while} request, and the @samp{!} operator
4493 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
4494 (just for completeness; does nothing in expressions), @samp{!} (logical
4495 not; this works only within @code{if} and @code{while} requests). See
4496 below for the use of unary operators in motion requests.
4499 @cindex extremum operators
4500 @cindex operators, extremum
4503 Extrema: @samp{>?} (maximum), @samp{<?} (minimum). For example,
4504 @samp{5>?3} yields@w{ }@samp{5}.
4509 @cindex scaling operator
4510 @cindex operator, scaling
4511 Scaling: @code{(@var{c};@var{e})}. Evaluate@w{ }@var{e} using@w{ }@var{c}
4512 as the default scaling indicator. If @var{c} is missing, ignore scaling
4513 indicators in the evaluation of@w{ }@var{e}.
4517 @cindex order of evaluation in expressions
4518 @cindex expression, order of evaluation
4521 Parentheses may be used as in any other language. However, in
4522 @code{gtroff} they are necessary to ensure order of evaluation.
4523 @code{gtroff} has no operator precedence; expressions are evaluated left
4524 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
4525 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
4528 @cindex @code{+}, and page motion
4529 @cindex @code{-}, and page motion
4530 @cindex @code{|}, and page motion
4531 @cindex motion operators
4532 @cindex operators, motion
4533 For many requests which cause a motion on the page, the unary operators
4534 work differently. The @samp{+} and @samp{-} operators then indicate a
4535 motion relative to the current position (down or up, respectively), and
4536 the @samp{|} operator indicates an absolute position on the page or
4539 @samp{+} and @samp{-} are also treated differently by the following
4540 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
4541 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
4542 @code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus
4543 signs indicate increments and decrements.
4545 @c XXX add more xref
4546 @xref{Setting Registers}.
4548 @cindex space characters in expressions
4549 @cindex expressions and space characters
4550 Due to the way arguments are parsed, spaces are not allowed in
4551 expressions, unless the entire expression is surrounded by parentheses.
4553 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
4556 @c =====================================================================
4558 @node Identifiers, Embedded Commands, Expressions, gtroff Reference
4559 @section Identifiers
4562 Like any other language, @code{gtroff} has rules for properly formed
4563 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
4564 almost any printable character, with the exception of the following
4569 @cindex whitespace characters
4570 @cindex newline character
4571 @cindex character, whitespace
4572 Whitespace characters (spaces, tabs, and newlines).
4575 @cindex character, backspace
4576 @cindex backspace character
4577 @cindex @acronym{EBCDIC} encoding of backspace
4578 Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{
4579 }@code{0x16}) and character code @code{0x01}.
4582 @cindex invalid input characters
4583 @cindex input characters, invalid
4584 @cindex characters, invalid input
4586 The following input characters are invalid and are ignored if
4587 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
4588 warning message of type @samp{input} (see @ref{Debugging}, for more
4589 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
4590 @code{0x80}-@code{0x9F}.
4592 And here are the invalid input characters if @code{groff} runs on an
4593 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
4594 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
4595 @code{0x30}-@code{0x3F}.
4597 Currently, some of these reserved codepoints are used internally, thus
4598 making it non-trivial to extend @code{gtroff} to cover Unicode or other
4599 character sets and encodings which use characters of these ranges.
4601 Note that invalid characters are removed before parsing; an
4602 identifier @code{foo}, followed by an invalid character, followed by
4603 @code{bar} is treated as @code{foobar}.
4606 For example, any of the following is valid.
4616 @cindex @code{]}, as part of an identifier
4618 Note that identifiers longer than two characters with a closing bracket
4619 (@samp{]}) in its name can't be accessed with escape sequences which
4620 expect an identifier as a parameter. For example, @samp{\[foo]]}
4621 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
4622 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
4626 @Defesc {\\A, ', ident, '}
4627 Test whether an identifier @var{ident} is valid in @code{gtroff}. It
4628 expands to the character@w{ }1 or@w{ }0 according to whether its
4629 argument (usually delimited by quotes) is or is not acceptable as the
4630 name of a string, macro, diversion, number register, environment, or
4631 font. It returns@w{ }0 if no argument is given. This is useful for
4632 looking up user input in some sort of associative table.
4640 @xref{Escapes}, for details on parameter delimiting characters.
4642 @c XXX add xrefs above
4644 Identifiers in @code{gtroff} can be any length, but, in some contexts,
4645 @code{gtroff} needs to be told where identifiers end and text begins
4646 (and in different ways depending on their length):
4652 @cindex @code{(}, starting a two-character identifier
4654 Two characters. Must be prefixed with @samp{(} in some situations.
4656 @cindex @code{[}, starting an identifier
4657 @cindex @code{]}, ending an identifier
4659 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
4660 and@w{ }@samp{]} in some situations. Any length identifier can be put
4664 @cindex undefined identifiers
4665 @cindex identifiers, undefined
4666 Unlike many other programming languages, undefined identifiers are
4667 silently ignored or expanded to nothing.
4668 When @code{gtroff} finds an undefined identifier, it emits a
4673 If the identifier is a string, macro, or diversion,
4674 @code{gtroff} defines it as empty.
4677 If the identifier is a number register, @code{gtroff}
4678 defines it with a value of@w{ }0.
4683 @c XXX info about common identifier pool for strings and macros.
4685 @xref{Interpolating Registers}, and @ref{Strings}.
4688 @c =====================================================================
4690 @node Embedded Commands, Registers, Identifiers, gtroff Reference
4691 @section Embedded Commands
4692 @cindex embedded commands
4693 @cindex commands, embedded
4695 Most documents need more functionality beyond filling, adjusting and
4696 implicit line breaking. In order to gain further functionality,
4697 @code{gtroff} allows commands to be embedded into the text, in two ways.
4699 The first is a @dfn{request} which takes up an entire line, and does
4700 some large-scale operation (e.g.@: break lines, start new pages).
4702 The other is an @dfn{escape} which can be embedded anywhere in the text,
4703 or even as an argument to a request.
4704 @c XXX (Not always?)
4705 Escapes generally do more minor operations like sub- and superscripts,
4706 print a symbol, etc.
4714 @c ---------------------------------------------------------------------
4716 @node Requests, Macros, Embedded Commands, Embedded Commands
4717 @subsection Requests
4720 @cindex control character (@code{.})
4721 @cindex character, control (@code{.})
4722 @cindex no-break control character (@code{'})
4723 @cindex character, no-break control (@code{'})
4724 @cindex control character, no-break (@code{'})
4725 A request line begins with a control character, which is either a single
4726 quote (@samp{'}, the @dfn{no-break control character}) or a period
4727 (@samp{.}, the normal @dfn{control character}). These can be changed;
4728 see @ref{Character Translations}, for details. After this there may be
4729 optional tabs or spaces followed by an identifier which is the name of
4730 the request. This may be followed by any number of space-separated
4731 arguments (@emph{no} tabs here).
4733 @cindex structuring source code of documents or macro packages
4734 @cindex documents, structuring the source code
4735 @cindex macro packages, strucuring the source code
4736 Since a control character followed by whitespace only is ignored, it
4737 is common practice to use this feature for structuring the source code
4738 of documents or macro packages.
4752 @cindex blank line macro (@code{blm})
4753 Another possibility is to use the blank line macro request @code{blm}
4754 by assigning an empty macro to it.
4759 .blm do-nothing \" activate blank line macro
4770 .blm \" deactivate blank line macro
4775 @cindex zero width space character (@code{\&})
4776 @cindex character, zero width space (@code{\&})
4777 @cindex space character, zero width (@code{\&})
4778 @cindex @code{\&}, escaping control characters
4779 To begin a line with a control character without it being interpreted,
4780 precede it with @code{\&}. This represents a zero width space, which
4781 means it does not affect the output.
4783 In most cases the period is used as a control character. Several
4784 requests cause a break implicitly; using the single quote control
4785 character prevents this.
4788 * Request Arguments::
4791 @node Request Arguments, , Requests, Requests
4792 @subsubsection Request Arguments
4793 @cindex request arguments
4794 @cindex arguments to requests
4796 Arguments to requests (and macros) are processed much like the shell:
4797 The line is split into arguments according to spaces. An argument
4798 which is intended to contain spaces can either be enclosed in double
4799 quotes, or have the spaces @dfn{escaped} with backslashes.
4801 Here are a few examples:
4804 .uh The Mouse Problem
4805 .uh "The Mouse Problem"
4806 .uh The\ Mouse\ Problem
4809 @cindex @code{\~}, difference to @code{\@key{SP}}
4810 @cindex @code{\@key{SP}}, difference to @code{\~}
4812 The first line is the @code{uh} macro being called with 3 arguments,
4813 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
4814 same effect of calling the @code{uh} macro with one argument, @samp{The
4815 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
4816 is ``classical'' in the sense that it can be found in most @code{troff}
4817 documents. Nevertheless, it is not optimal in all situations, since
4818 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
4819 can't stretch. @code{gtroff} provides a different command @code{\~} to
4820 insert a stretchable, non-breaking space.}
4822 @cindex @code{"}, in a macro argument
4823 @cindex double quote, in a macro argument
4824 A double quote which isn't preceded by a space doesn't start a macro
4825 argument. If not closing a string, it is printed literally.
4830 .xxx a" "b c" "de"fg"
4834 has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}.
4836 @cindex @code{ds} request, and double quotes
4837 Double quotes in the @code{ds} request are handled differently.
4838 @xref{Strings}, for more details.
4840 @c ---------------------------------------------------------------------
4842 @node Macros, Escapes, Requests, Embedded Commands
4846 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
4847 which can be invoked by name. They are called in the same manner as
4848 requests -- arguments also may be passed in the same manner.
4850 @xref{Writing Macros}, and @ref{Request Arguments}.
4852 @c ---------------------------------------------------------------------
4854 @node Escapes, , Macros, Embedded Commands
4858 Escapes may occur anywhere in the input to @code{gtroff}. They usually
4859 begin with a backslash and are followed by a single character which
4860 indicates the function to be performed. The escape character can be
4861 changed; see @ref{Character Translations}.
4863 Escape sequences which require an identifier as a parameter accept three
4864 possible syntax forms.
4868 The next single character is the identifier.
4870 @cindex @code{(}, starting a two-character identifier
4872 If this single character is an opening parenthesis, take the following
4873 two characters as the identifier. Note that there is no closing
4874 parenthesis after the identifier.
4876 @cindex @code{[}, starting an identifier
4877 @cindex @code{]}, ending an identifier
4879 If this single character is an opening bracket, take all characters
4880 until a closing bracket as the identifier.
4892 @cindex @code{'}, delimiting arguments
4893 @cindex argument delimiting characters
4894 @cindex characters, argument delimiting
4895 @cindex delimiting characters for arguments
4896 Other escapes may require several arguments and/or some special format.
4897 In such cases the argument is traditionally enclosed in single quotes
4898 (and quotes are always used in this manual for the definitions of escape
4899 sequences). The enclosed text is then processed according to what that
4900 escape expects. Example:
4906 @cindex @code{\o}, possible quote characters
4907 @cindex @code{\b}, possible quote characters
4908 @cindex @code{\X}, possible quote characters
4909 Note that the quote character can be replaced with any other character
4910 which does not occur in the argument (even a newline or a space
4911 character) in the following escapes: @code{\o}, @code{\b}, and
4912 @code{\X}. This makes e.g.
4921 @result{} A caf@'e in Paris
4925 possible, but it is better not to use this feature to avoid confusion.
4927 @cindex @code{\%}, used as delimiter
4928 @cindex @code{\@key{SP}}, used as delimiter
4929 @cindex @code{\|}, used as delimiter
4930 @cindex @code{\^}, used as delimiter
4931 @cindex @code{\@{}, used as delimiter
4932 @cindex @code{\@}}, used as delimiter
4933 @cindex @code{\'}, used as delimiter
4934 @cindex @code{\`}, used as delimiter
4935 @cindex @code{\-}, used as delimiter
4936 @cindex @code{\_}, used as delimiter
4937 @cindex @code{\!}, used as delimiter
4938 @cindex @code{\?}, used as delimiter
4939 @cindex @code{\@@}, used as delimiter
4940 @cindex @code{\)}, used as delimiter
4941 @cindex @code{\/}, used as delimiter
4942 @cindex @code{\,}, used as delimiter
4943 @cindex @code{\&}, used as delimiter
4944 @cindex @code{\~}, used as delimiter
4945 @cindex @code{\0}, used as delimiter
4946 @cindex @code{\a}, used as delimiter
4947 @cindex @code{\c}, used as delimiter
4948 @cindex @code{\d}, used as delimiter
4949 @cindex @code{\e}, used as delimiter
4950 @cindex @code{\E}, used as delimiter
4951 @cindex @code{\p}, used as delimiter
4952 @cindex @code{\r}, used as delimiter
4953 @cindex @code{\t}, used as delimiter
4954 @cindex @code{\u}, used as delimiter
4955 The following escapes sequences (which are handled similarly to
4956 characters since they don't take a parameter) are also allowed as
4957 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
4958 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
4959 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
4960 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
4961 @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't
4962 use these if possible.
4964 @cindex @code{\A}, allowed delimiters
4965 @cindex @code{\Z}, allowed delimiters
4966 @cindex @code{\C}, allowed delimiters
4967 @cindex @code{\w}, allowed delimiters
4968 No newline characters as delimiters are allowed in the following
4969 escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}.
4971 @cindex @code{\D}, allowed delimiters
4972 @cindex @code{\h}, allowed delimiters
4973 @cindex @code{\H}, allowed delimiters
4974 @cindex @code{\l}, allowed delimiters
4975 @cindex @code{\L}, allowed delimiters
4976 @cindex @code{\N}, allowed delimiters
4977 @cindex @code{\R}, allowed delimiters
4978 @cindex @code{\s}, allowed delimiters
4979 @cindex @code{\S}, allowed delimiters
4980 @cindex @code{\v}, allowed delimiters
4981 @cindex @code{\x}, allowed delimiters
4982 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
4983 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
4984 @code{\x} can't use the following characters as delimiters:
4988 @cindex numbers, and delimiters
4989 @cindex digits, and delimiters
4990 The digits @code{0}-@code{9}.
4993 @cindex operators, as delimiters
4994 @cindex @code{+}, as delimiter
4995 @cindex @code{-}, as delimiter
4996 @cindex @code{/}, as delimiter
4997 @cindex @code{*}, as delimiter
4998 @cindex @code{%}, as delimiter
4999 @cindex @code{<}, as delimiter
5000 @cindex @code{>}, as delimiter
5001 @cindex @code{=}, as delimiter
5002 @cindex @code{&}, as delimiter
5003 @cindex @code{:}, as delimiter
5004 @cindex @code{(}, as delimiter
5005 @cindex @code{)}, as delimiter
5006 @cindex @code{.}, as delimiter
5007 The (single-character) operators @samp{+-/*%<>=&:().}.
5010 @cindex space character
5011 @cindex character, space
5012 @cindex tab character
5013 @cindex character, tab
5014 @cindex newline character
5015 @cindex character, newline
5016 The space, tab, and newline characters.
5019 @cindex @code{\%}, used as delimiter
5020 @cindex @code{\@{}, used as delimiter
5021 @cindex @code{\@}}, used as delimiter
5022 @cindex @code{\'}, used as delimiter
5023 @cindex @code{\`}, used as delimiter
5024 @cindex @code{\-}, used as delimiter
5025 @cindex @code{\_}, used as delimiter
5026 @cindex @code{\!}, used as delimiter
5027 @cindex @code{\@@}, used as delimiter
5028 @cindex @code{\/}, used as delimiter
5029 @cindex @code{\c}, used as delimiter
5030 @cindex @code{\e}, used as delimiter
5031 @cindex @code{\p}, used as delimiter
5032 All escape sequences except @code{\%}, @code{\@{}, @code{\@}},
5033 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
5034 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
5037 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\(rs})
5038 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\(rs})
5039 To have a backslash (actually, the current escape character) appear in the
5040 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
5041 These are very similar, and only differ with respect to being used in
5042 macros or diversions. @xref{Implementation Differences}, @ref{Copy-in
5043 Mode}, and @ref{Diversions}, for more information.
5045 @c XXX explanation of \E
5047 @xref{Identifiers}, and @ref{Character Translations}.
5053 @node Comments, , Escapes, Escapes
5054 @subsubsection Comments
5057 Probably one of the most@footnote{Unfortunately, this is a lie. But
5058 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
5059 common forms of escapes is the comment.
5062 Start a comment. Everything to the end of the input line is ignored.
5064 This may sound simple, but it can be tricky to keep the comments from
5065 interfering with the appearance of the final output.
5067 @cindex @code{ds} request, and comments
5068 @cindex @code{as} request, and comments
5069 If the escape is to the right of some text or a request, that portion
5070 of the line is ignored, but the space leading up to it is noticed by
5071 @code{gtroff}. This only affects the @code{.ds} and @code{.as}
5074 @cindex tabs before comments
5075 @cindex comments, lining up with tabs
5076 One possibly irritating idiosyncracy is that tabs must not be used to
5077 line up comments. Tabs are not treated as white space between the
5078 request and macro arguments.
5080 @cindex undefined request
5081 @cindex request, undefined
5082 A comment on a line by itself is treated as a blank line, because
5083 after eliminating the comment, that is all that remains:
5100 To avoid this, it is common to start the line with @code{.\"} which
5101 causes the line to be treated as an undefined request and thus ignored
5104 @cindex @code{'}, as a comment
5105 Another commenting scheme seen sometimes is three consecutive single
5106 quotes (@code{'''}) at the beginning of a line. This works, but
5107 @code{gtroff} gives a warning about an undefined macro (namely
5108 @code{''}), which is harmless, but irritating.
5112 To avoid all this, @code{gtroff} has a new comment mechanism using the
5113 @code{\#} escape. This escape works the same as @code{\"} except that
5114 the newline is also ignored:
5134 Ignore all input until @code{gtroff} encounters the macro named
5135 @code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not
5136 specified). This is useful for commenting out large blocks of text:
5141 This is part of a large block
5142 of text that has been
5143 temporarily(?) commented out.
5145 We can restore it simply by removing
5146 the .ig request and the ".." at the
5149 More text text text...
5156 text text text@dots{} More text text text@dots{}
5160 Note that the commented-out block of text does not
5163 The input is read in copy-mode; auto-incremented registers @emph{are}
5164 affected (@pxref{Auto-increment}).
5168 @c =====================================================================
5170 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference
5174 Numeric variables in @code{gtroff} are called @dfn{registers}. There
5175 are a number of built-in registers, supplying anything from the date to
5176 details of formatting parameters.
5178 @xref{Identifiers}, for details on register identifiers.
5181 * Setting Registers::
5182 * Interpolating Registers::
5184 * Assigning Formats::
5185 * Built-in Registers::
5188 @c ---------------------------------------------------------------------
5190 @node Setting Registers, Interpolating Registers, Registers, Registers
5191 @subsection Setting Registers
5192 @cindex setting registers (@code{nr}, @code{\R})
5193 @cindex registers, setting (@code{nr}, @code{\R})
5195 Define or set registers using the @code{nr} request or the
5198 @DefreqList {nr, ident value}
5199 @DefescListEnd {\\R, ', ident value, '}
5200 Set number register @var{ident} to @var{value}. If @var{ident}
5201 doesn't exist, @code{gtroff} creates it.
5203 The argument to @code{\R} usually has to be enclosed in quotes.
5204 @xref{Escapes}, for details on parameter delimiting characters.
5207 For example, the following two lines are equivalent:
5214 Both @code{nr} and @code{\R} have two additional special forms to
5215 increment or decrement a register.
5217 @DefreqList {nr, ident @t{+}@Var{value}}
5218 @DefreqItem {nr, ident @t{-}@Var{value}}
5219 @DefescItem {\\R, ', ident @t{+}@Var{value}, '}
5220 @DefescListEnd {\\R, ', ident @t{-}@Var{value}, '}
5221 Increment (decrement) register @var{ident} by @var{value}.
5230 @cindex negating register values
5231 To assign the negated value of a register to another register, some care
5232 must be taken to get the desired result:
5246 The surrounding parentheses prevent the interpretation of the minus sign
5247 as a decrementing operator. An alternative is to start the assignment
5263 Remove number register @var{ident}. If @var{ident} doesn't exist, the
5267 @Defreq {rnn, ident1 ident2}
5268 Rename number register @var{ident1} to @var{ident2}. If either
5269 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
5272 @Defreq {aln, ident1 ident2}
5273 Create an alias @var{ident1} for a number register @var{ident2}. The
5274 new name and the old name are exactly equivalent. If @var{ident1} is
5275 undefined, a warning of type @samp{reg} is generated, and the request
5276 is ignored. @xref{Debugging}, for information about warnings.
5279 @c ---------------------------------------------------------------------
5281 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
5282 @subsection Interpolating Registers
5283 @cindex interpolating registers (@code{\n})
5284 @cindex registers, interpolating (@code{\n})
5286 Numeric registers can be accessed via the @code{\n} escape.
5288 @cindex nested assignments
5289 @cindex assignments, nested
5290 @cindex indirect assignments
5291 @cindex assignments, indirect
5292 @DefescList {\\n, , i, }
5293 @DefescItem {\\n, @lparen{}, id, }
5294 @DefescListEnd {\\n, @lbrack{}, ident, @rbrack}
5295 Interpolate number register with name @var{ident} (one-character name@w{
5296 }@var{i}, two-character name @var{id}). This means that the value of the
5297 register is expanded in-place while @code{gtroff} is parsing the input line.
5298 Nested assignments (also called indirect assignments) are possible.
5319 @c ---------------------------------------------------------------------
5321 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
5322 @subsection Auto-increment
5323 @cindex auto-increment
5324 @cindex increment, automatic
5326 Number registers can also be auto-incremented and auto-decremented.
5327 The increment or decrement value can be specified with a third
5328 argument to the @code{nr} request or @code{\R} escape.
5330 @cindex @code{\R}, difference to @code{nr}
5331 @Defreq {nr, ident value incr}
5332 Set number register @var{ident} to @var{value}; the increment for
5333 auto-incrementing is set to @var{incr}. Note that the @code{\R}
5334 escape doesn't support this notation.
5337 To activate auto-incrementing, the escape @code{\n} has a special
5340 @DefescList {\\n, +, i, }
5341 @DefescItem {\\n, -, i, }
5342 @DefescItem {\\n, @lparen{}+, id, }
5343 @DefescItem {\\n, @lparen{}-, id, }
5344 @DefescItem {\\n, +@lparen{}, id, }
5345 @DefescItem {\\n, -@lparen{}, id, }
5346 @DefescItem {\\n, @lbrack{}+, ident, @rbrack{}}
5347 @DefescItem {\\n, @lbrack{}-, ident, @rbrack{}}
5348 @DefescItem {\\n, +@lbrack{}, ident, @rbrack{}}
5349 @DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}}
5350 Before interpolating, increment or decrement @var{ident}
5351 (one-character name@w{ }@var{i}, two-character name @var{id}) by the
5352 auto-increment value as specified with the @code{nr} request (or the
5353 @code{\R} escape). If no auto-increment value has been specified,
5354 these syntax forms are identical to @code{\n}.
5363 \n+a, \n+a, \n+a, \n+a, \n+a
5365 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
5367 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
5375 -5, -10, -15, -20, -25
5379 @cindex increment value without changing the register
5380 @cindex value, incrementing without changing the register
5381 To change the increment value without changing the value of a register
5382 (@var{a} in the example), the following can be used:
5388 @c ---------------------------------------------------------------------
5390 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
5391 @subsection Assigning Formats
5392 @cindex assigning formats (@code{af})
5393 @cindex formats, assigning (@code{af})
5395 When a register is used in the text of an input file (as opposed to
5396 part of an expression), it is textually replaced (or interpolated)
5397 with a representation of that number. This output format can be
5398 changed to a variety of formats (numbers, Roman numerals, etc.). This
5399 is done using the @code{af} request.
5401 @Defreq {af, ident format}
5402 Change the output format of a number register. The first argument
5403 @var{ident} is the name of the number register to be changed, and the
5404 second argument @var{format} is the output format. The following
5405 output formats are available:
5409 Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{
5413 Decimal numbers with as many digits as specified. So, @samp{00} would
5414 result in printing numbers as 01, 02, 03,@w{ }@enddots{}
5416 In fact, any digit instead of zero will do; @code{gtroff} only counts
5417 how many digits are specified. As a consequence, @code{af}'s default
5418 format @samp{1} could be specified as @samp{0} also (and exactly this is
5419 returned by the @code{\g} escape, see below).
5422 @cindex Roman numerals
5423 @cindex numerals, Roman
5424 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{}
5427 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{}
5430 Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{}
5433 Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{}
5436 Omitting the number register format causes a warning of type
5437 @samp{missing}. @xref{Debugging}, for more details. Specifying a
5438 nonexistent format causes an error.
5440 The following example produces @samp{10, X, j, 010}:
5444 .af a 1 \" the default format
5454 @cindex Roman numerals, maximum and minimum
5455 @cindex maximum values of Roman numerals
5456 @cindex minimum values of Roman numerals
5457 The largest number representable for the @samp{i} and @samp{I} formats
5458 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
5459 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
5460 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
5461 thousand and Roman numeral ten thousand (Unicode code points
5462 @code{U+2182} and @code{U+2181}, respectively) are not available.
5464 If @var{ident} doesn't exist, it is created.
5466 @cindex read-only register, changing format
5467 @cindex changing format, read-only register
5468 Changing the output format of a read-only register causes an error. It
5469 is necessary to first copy the register's value to a writeable register,
5470 then apply the @code{af} request to this other register.
5473 @cindex format of register (@code{\g})
5474 @cindex register, format (@code{\g})
5475 @DefescList {\\g, , i, }
5476 @DefescItem {\\g, @lparen{}, id, }
5477 @DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}}
5478 Return the current format of the specified register @var{ident}
5479 (one-character name@w{ }@var{i}, two-character name @var{id}). For
5480 example, @samp{\ga} after the previous example would produce the
5481 string @samp{000}. If the register hasn't been defined yet, nothing
5485 @c ---------------------------------------------------------------------
5487 @node Built-in Registers, , Assigning Formats, Registers
5488 @subsection Built-in Registers
5489 @cindex built-in registers
5490 @cindex registers, built-in
5492 The following lists some built-in registers which are not described
5493 elsewhere in this manual. Any register which begins with a @samp{.} is
5494 read-only. A complete listing of all built-in registers can be found in
5495 @ref{Register Index}.
5499 @cindex horizontal resolution register (@code{.H})
5500 @cindex resolution, horizontal, register (@code{.H})
5502 Horizontal resolution in basic units.
5505 @cindex vertical resolution register (@code{.V})
5506 @cindex resolution, vertical, register (@code{.V})
5508 Vertical resolution in basic units.
5511 @cindex day of the week register (@code{dw})
5512 @cindex date, day of the week register (@code{dw})
5514 Day of the week (1-7).
5517 @cindex day of the month register (@code{dy})
5518 @cindex date, day of the month register (@code{dy})
5520 Day of the month (1-31).
5523 @cindex month of the year register (@code{mo})
5524 @cindex date, month of the year register (@code{mo})
5526 Current month (1-12).
5529 @cindex date, year register (@code{year}, @code{yr})
5530 @cindex year, current, register (@code{year}, @code{yr})
5536 The current year minus@w{ }1900. Unfortunately, the documentation of
5537 @acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
5538 incorrectly claimed that @code{yr} contains the last two digits of the
5539 year. That claim has never been true of either traditional @code{troff}
5540 or GNU @code{troff}. Old @code{troff} input that looks like this:
5543 '\" The following line stopped working after 1999
5544 This document was formatted in 19\n(yr.
5548 can be corrected as follows:
5551 This document was formatted in \n[year].
5555 or, to be portable to older @code{troff} versions, as follows:
5559 This document was formatted in \n(y4.
5566 @cindex input line number register (@code{.c}, @code{c.})
5567 @cindex line number, input, register (@code{.c}, @code{c.})
5568 The current @emph{input} line number. Register @samp{.c} is read-only,
5569 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
5570 affecting both @samp{.c} and @samp{c.}.
5574 @cindex output line number register (@code{ln})
5575 @cindex line number, output, register (@code{ln})
5576 The current @emph{output} line number after a call to the @code{nm}
5577 request to activate line numbering.
5579 @xref{Miscellaneous}, for more information about line numbering.
5583 @cindex major version number register (@code{.x})
5584 @cindex version number, major, register (@code{.x})
5585 The major version number. For example, if the version number is@w{
5586 }1.03 then @code{.x} contains@w{ }@samp{1}.
5590 @cindex minor version number register (@code{.y})
5591 @cindex version number, minor, register (@code{.y})
5592 The minor version number. For example, if the version number is@w{
5593 }1.03 then @code{.y} contains@w{ }@samp{03}.
5597 @cindex revision number register (@code{.Y})
5598 The revision number of @code{groff}.
5602 @cindex @code{gtroff} identification register (@code{.g})
5603 @cindex GNU-specific register (@code{.g})
5604 Always@w{ }1. Macros should use this to determine whether they are
5605 running under GNU @code{troff}.
5609 @cindex @acronym{ASCII} approximation output register (@code{.A})
5610 If the command line option @option{-a} is used to produce an
5611 @acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
5612 otherwise. @xref{Groff Options}.
5616 This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current
5617 page is actually being printed, i.e., if the @option{-o} option is being
5618 used to only print selected pages. @xref{Groff Options}, for more
5623 If @code{gtroff} is called with the @option{-T} command line option, the
5624 number register @code{.T} is set to@w{ }1, and zero otherwise.
5625 @xref{Groff Options}.
5628 @cindex output device name string register (@code{.T})
5629 Additionally, @code{gtroff} predefines a single read-write string
5630 register @code{.T} which contains the current output device (for
5631 example, @samp{latin1} or @samp{ps}).
5635 @c =====================================================================
5637 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference
5638 @section Manipulating Filling and Adjusting
5639 @cindex manipulating filling and adjusting
5640 @cindex filling and adjusting, manipulating
5641 @cindex adjusting and filling, manipulating
5642 @cindex justifying text
5643 @cindex text, justifying
5647 @cindex @code{bp} request, causing implicit linebreak
5648 @cindex @code{ce} request, causing implicit linebreak
5649 @cindex @code{cf} request, causing implicit linebreak
5650 @cindex @code{fi} request, causing implicit linebreak
5651 @cindex @code{fl} request, causing implicit linebreak
5652 @cindex @code{in} request, causing implicit linebreak
5653 @cindex @code{nf} request, causing implicit linebreak
5654 @cindex @code{rj} request, causing implicit linebreak
5655 @cindex @code{sp} request, causing implicit linebreak
5656 @cindex @code{ti} request, causing implicit linebreak
5657 @cindex @code{trf} request, causing implicit linebreak
5658 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
5659 Breaks}. The @code{br} request likewise causes a break. Several
5660 other requests also cause breaks, but implicitly. These are
5661 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
5662 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
5665 Break the current line, i.e., the input collected so far is emitted
5668 If the no-break control character is used, @code{gtroff} suppresses
5679 Initially, @code{gtroff} fills and adjusts text to both margins.
5680 Filling can be disabled via the @code{nf} request and re-enabled with
5681 the @code{fi} request.
5683 @cindex fill mode (@code{fi})
5684 @cindex mode, fill (@code{fi})
5687 Activate fill mode (which is the default). This request implicitly
5688 enables adjusting; it also inserts a break in the text currently being
5689 filled. The read-only number register @code{.u} is set to@w{ }1.
5691 The fill mode status is associated with the current environment
5692 (@pxref{Environments}).
5695 @cindex no-fill mode (@code{nf})
5696 @cindex mode, no-fill (@code{nf})
5698 Activate no-fill mode. Input lines are output as-is, retaining line
5699 breaks and ignoring the current line length. This command implicitly
5700 disables adjusting; it also causes a break. The number register
5701 @code{.u} is set to@w{ }0.
5703 The fill mode status is associated with the current environment
5704 (@pxref{Environments}).
5707 @DefreqList {ad, [@Var{mode}]}
5711 Activation and deactivation of adjusting is done implicitly with
5712 calls to the @code{fi} or @code{nf} requests.
5714 @var{mode} can have one of the following values:
5718 @cindex ragged-right
5719 Adjust text to the left margin. This produces what is traditionally
5720 called ragged-right text.
5724 Adjust text to the right margin, producing ragged-left text.
5727 @cindex centered text
5728 @cindex @code{ce} request, difference to @code{ad@w{ }c}
5729 Center filled text. This is different to the @code{ce} request which
5730 only centers text without filling.
5734 Justify to both margins. This is the default used by @code{gtroff}.
5737 With no argument, @code{gtroff} adjusts lines in the same way it did
5738 before adjusting was deactivated (with a call to @code{na}, for
5749 .ad \" back to centering
5753 @cindex adjustment mode register (@code{.j})
5754 The current adjustment mode is available in the read-only number
5755 register @code{.j}; it can be stored and subsequently used to set
5758 The adjustment mode status is associated with the current environment
5759 (@pxref{Environments}).
5763 Disable adjusting. This request won't change the current adjustment
5764 mode: A subsequent call to @code{ad} uses the previous adjustment
5767 The adjustment mode status is associated with the current environment
5768 (@pxref{Environments}).
5772 Adjust the current line and cause a break.
5774 In most cases this produces very ugly results, since @code{gtroff}
5775 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
5776 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
5780 This is an uninteresting sentence.
5781 This is an uninteresting sentence.\p
5782 This is an uninteresting sentence.
5789 This is an uninteresting sentence. This is an
5790 uninteresting sentence.
5791 This is an uninteresting sentence.
5795 @cindex word space size register (@code{.ss})
5796 @cindex size of word space register (@code{.ss})
5797 @cindex space between words register (@code{.ss})
5798 @cindex sentence space size register (@code{.sss})
5799 @cindex size of sentence space register (@code{.sss})
5800 @cindex space between sentences register (@code{.sss})
5801 @DefreqList {ss, word_space_size [@Var{sentence_space_size}]}
5803 @DefregListEnd {.sss}
5804 Change the minimum size of a space between filled words. It takes its
5805 units as one twelfth of the space width parameter for the current
5806 font. Initially both the @var{word_space_size} and
5807 @var{sentence_space_size} are@w{ }12.
5811 If two arguments are given to the @code{ss} request, the second
5812 argument sets the sentence space size. If the second argument is not
5813 given, sentence space size is set to @var{word_space_size}. The
5814 sentence space size is used in two circumstances: If the end of a
5815 sentence occurs at the end of a line in fill mode, then both an
5816 inter-word space and a sentence space are added; if two spaces follow
5817 the end of a sentence in the middle of a line, then the second space
5818 is a sentence space. If a second argument is never given to the
5819 @code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the
5820 same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as
5821 in @acronym{UNIX} @code{troff}, a sentence should always be followed
5822 by either a newline or two spaces.
5824 The read-only number registers @code{.ss} and @code{.sss} hold the
5825 values of the parameters set by the first and second arguments of the
5828 The word space and sentence space values are associated with the current
5829 environment (@pxref{Environments}).
5831 Contrary to traditional Unix @code{troff}, this request is @emph{not}
5832 ignored if a tty output device is used; the given values are then
5833 rounded down to a multiple of@w{ }12.
5835 @c XXX xref implementation differences
5837 The request is ignored if there is no parameter.
5840 @cindex centering lines (@code{ce})
5841 @cindex lines, centering (@code{ce})
5842 @DefreqList {ce, [@Var{nnn}]}
5843 @DefregListEnd {.ce}
5844 Center text. While the @w{@samp{.ad c}} request also centers text,
5845 it fills the text as well. @code{ce} does not fill the
5846 text it affects. This request causes a break.
5848 The following example demonstrates the differences.
5854 This is a small text fragment which shows the differences
5855 between the `.ce' and the `.ad c' request.
5859 This is a small text fragment which shows the differences
5860 between the `.ce' and the `.ad c' request.
5864 And here the result:
5867 This is a small text fragment which
5868 shows the differences
5869 between the `.ce' and the `.ad c' request.
5871 This is a small text fragment which
5872 shows the differences between the `.ce'
5873 and the `.ad c' request.
5876 With no arguments, @code{ce} centers the next line of text. @var{nnn}
5877 specifies the number of lines to be centered. If the argument is zero
5878 or negative, centering is disabled.
5880 The basic length for centering text is the line length (as set with the
5881 @code{ll} request) minus the indentation (as set with the @code{in}
5882 request). Temporary indentation is ignored.
5884 As can be seen in the previous example, it is a common idiom to turn
5885 on centering for a large number of lines, and to turn off centering
5886 after text to be centered. This is useful for any request which takes
5887 a number of lines as an argument.
5889 The @code{.ce} read-only number register contains the number of lines
5890 remaining to be centered, as set by the @code{ce} request.
5893 @cindex justifying text (@code{rj})
5894 @cindex text, justifying (@code{rj})
5895 @cindex right-justifying (@code{rj})
5896 @DefreqList {rj, [@Var{nnn}]}
5897 @DefregListEnd {.rj}
5898 Justify unfilled text to the right margin. Arguments are identical to
5899 the @code{ce} request. The @code{.rj} read-only number register is
5900 the number of lines to be right-justified as set by the @code{rj}
5901 request. This request causes a break.
5905 @c =====================================================================
5907 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference
5908 @section Manipulating Hyphenation
5909 @cindex manipulating hyphenation
5910 @cindex hyphenation, manipulating
5912 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
5913 There are a number of ways to influence hyphenation.
5915 @DefreqList {hy, [@Var{mode}]}
5916 @DefregListEnd {.hy}
5917 Enable hyphenation. The request has an optional numeric argument,
5918 @var{mode}, to restrict hyphenation if necessary:
5922 The default argument if @var{mode} is omitted. Hyphenate without
5923 restrictions. This is also the start-up value of @code{gtroff}.
5926 Do not hyphenate the last word on a page or column.
5929 Do not hyphenate the last two characters of a word.
5932 Do not hyphenate the first two characters of a word.
5935 Values in the previous table are additive. For example, the value@w{
5936 }12 causes @code{gtroff} to neither hyphenate the last two nor the first
5937 two characters of a word.
5939 @cindex hyphenation restrictions register (@code{.hy})
5940 The current hyphenation restrictions can be found in the read-only
5941 number register @samp{.hy}.
5943 The hyphenation mode is associated with the current environment
5944 (@pxref{Environments}).
5948 Disable hyphenation (i.e., set the hyphenation mode to zero). Note
5949 that the hyphenation mode of the last call to @code{hy} is not
5952 The hyphenation mode is associated with the current environment
5953 (@pxref{Environments}).
5956 @cindex explicit hyphen (@code{\%})
5957 @cindex hyphen, explicit (@code{\%})
5958 @cindex consecutive hyphenated lines (@code{hlm})
5959 @cindex lines, consecutive hyphenated (@code{hlm})
5960 @cindex hyphenated lines, consecutive (@code{hlm})
5961 @DefreqList {hlm, [@Var{nnn}]}
5963 @DefregListEnd {.hlc}
5964 Set the maximum number of consecutive hyphenated lines to @var{nnn}.
5965 If this number is negative, there is no maximum. The default value
5966 is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated
5967 with the current environment (@pxref{Environments}). Only lines
5968 output from a given environment count towards the maximum associated
5969 with that environment. Hyphens resulting from @code{\%} are counted;
5970 explicit hyphens are not.
5972 The current setting of @code{hlm} is available in the @code{.hlm}
5973 read-only number register. Also the number of immediately preceding
5974 consecutive hyphenated lines are available in the read-only number
5975 register @samp{.hlc}.
5978 @Defreq {hw, word1 word2 @dots{}}
5979 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
5980 words must be given with hyphens at the hyphenation points. For
5988 Besides the space character, any character whose hyphenation code value
5989 is zero can be used to separate the arguments of @code{hw} (see the
5990 documentation for the @code{hcode} request below for more information).
5991 In addition, this request can be used more than once.
5993 Hyphenation exceptions specified with the @code{hw} request are
5994 associated with the current hyphenation language; it causes an error
5995 if there is no current hyphenation language.
5997 This request is ignored if there is no parameter.
5999 In old versions of @code{troff} there was a limited amount of space to
6000 store such information; fortunately, with @code{gtroff}, this is no
6001 longer a restriction.
6004 @cindex hyphenation character (@code{\%})
6005 @cindex character, hyphenation (@code{\%})
6006 @cindex disabling hyphenation (@code{\%})
6007 @cindex hyphenation, disabling (@code{\%})
6009 To tell @code{gtroff} how to hyphenate words on the fly, use the
6010 @code{\%} escape, also known as the @dfn{hyphenation character}.
6011 Preceding a word with this character prevents it from being
6012 hyphenated; putting it inside a word indicates to @code{gtroff} that
6013 the word may be hyphenated at that point. Note that this mechanism
6014 only affects that one occurrence of the word; to change the
6015 hyphenation of a word for the entire document, use the @code{hw}
6019 @Defreq {hc, [@Var{char}]}
6020 Change the hyphenation character to @var{char}. This character then
6021 works the same as the @code{\%} escape, and thus, no longer appears in
6022 the output. Without an argument, @code{hc} resets the hyphenation
6023 character to be @code{\%} (the default) only.
6025 The hyphenation character is associated with the current environment
6026 (@pxref{Environments}).
6029 @cindex hyphenation patterns (@code{hpf})
6030 @cindex patterns for hyphenation (@code{hpf})
6031 @Defreq {hpf, pattern_file}
6032 Read in a file of hyphenation patterns. This file is searched for in
6033 the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is
6034 searched for if the @option{-m@var{name}} option is specified.
6036 It should have the same format as the argument to the @code{\patterns}
6037 primitive in @TeX{} (without using @TeX{}'s macro expansion); the
6038 letters appearing in this file are interpreted as hyphenation codes. A
6039 @samp{%} character in the patterns file introduces a comment that
6040 continues to the end of the line.
6042 If no @code{hpf} request is specified (either in the document or in a
6043 macro package), @code{gtroff} won't hyphenate at all.
6048 The set of hyphenation patterns is associated with the current language
6049 set by the @code{hla} request. The @code{hpf} request is usually
6050 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
6051 @file{troffrc} loads hyphenation patterns for American English (in file
6054 Invoking @code{hpf} causes an error if there is no current hyphenation
6058 @cindex hyphenation code (@code{hcode})
6059 @cindex code, hyphenation (@code{hcode})
6060 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
6061 Set the hyphenation code of character @var{c1} to @var{code1}, that of
6062 @var{c2} to @var{code2}, etc. A hyphenation code must be a single
6063 input character (not a special character) other than a digit or a
6064 space. Initially each lower-case letter (@samp{a}-@samp{z}) has its
6065 hyphenation set to itself, and each upper-case letter
6066 (@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case
6069 This request is ignored if it has no parameter.
6072 @cindex hyphenation margin (@code{hym})
6073 @cindex margin for hyphenation (@code{hym})
6074 @cindex @code{ad} request, and hyphenation margin
6075 @DefreqList {hym, [@Var{length}]}
6076 @DefregListEnd {.hym}
6077 Set the (right) hyphenation margin to @var{length}. If the current
6078 adjustment mode is not @samp{b} or @samp{n}, the line is not
6079 hyphenated if it is shorter than @var{length}. Without an argument,
6080 the hyphenation margin is reset to its default value, which is@w{ }0.
6081 The default scaling indicator for this request is @samp{m}. The
6082 hyphenation margin is associated with the current environment
6083 (@pxref{Environments}).
6085 A negative argument resets the hyphenation margin to zero, emitting
6086 a warning of type @samp{range}.
6088 @cindex hyphenation margin register (@code{.hym})
6089 The current hyphenation margin is available in the @code{.hym} read-only
6093 @cindex hyphenation space (@code{hys})
6094 @cindex @code{ad} request, and hyphenation space
6095 @DefreqList {hys, [@Var{hyphenation_space}]}
6096 @DefregListEnd {.hys}
6097 Set the hyphenation space to @var{hyphenation_space}. If the current
6098 adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line
6099 if it can be justified by adding no more than @var{hyphenation_space}
6100 extra space to each word space. Without argument, the hyphenation
6101 space is set to its default value, which is@w{ }0. The default
6102 scaling indicator for this request is @samp{m}. The hyphenation
6103 space is associated with the current environment
6104 (@pxref{Environments}).
6106 A negative argument resets the hyphenation space to zero, emitting a
6107 warning of type @samp{range}.
6109 @cindex hyphenation space register (@code{.hys})
6110 The current hyphenation space is available in the @code{.hys} read-only
6114 @cindex soft hyphen character, setting (@code{shc})
6115 @cindex character, soft hyphen, setting (@code{shc})
6116 @cindex glyph, soft hyphen (@code{hy})
6117 @cindex soft hyphen glyph (@code{hy})
6118 @cindex @code{char} request, and soft hyphen character
6119 @cindex @code{tr} request, and soft hyphen character
6120 @Defreq {shc, [@Var{char}]}
6121 Set the soft hyphen character to @var{char}. If the argument is
6122 omitted, the soft hyphen character is set to the default character
6123 @code{\(hy} (this is the start-up value of @code{gtroff} also). The
6124 soft hyphen character is the character that is inserted when a word is
6125 hyphenated at a line break. If the soft hyphen character does not
6126 exist in the font of the character immediately preceding a potential
6127 break point, then the line is not broken at that point. Neither
6128 definitions (specified with the @code{char} request) nor translations
6129 (specified with the @code{tr} request) are considered when finding the
6130 soft hyphen character.
6133 @cindex @code{hpf} request, and hyphenation language
6134 @cindex @code{hw} request, and hyphenation language
6137 @DefreqList {hla, language}
6138 @DefregListEnd {.hla}
6139 Set the current hyphenation language to the string @var{language}.
6140 Hyphenation exceptions specified with the @code{hw} request and
6141 hyphenation patterns specified with the @code{hpf} request are both
6142 associated with the current hyphenation language. The @code{hla}
6143 request is usually invoked by the @file{troffrc} or the
6144 @file{troffrc-end} files; @file{troffrc} sets the default language to
6147 @cindex hyphenation language register (@code{.hla})
6148 The current hyphenation language is available as a string in the
6149 read-only number register @samp{.hla}.
6152 .ds curr_language \n[.hla]
6159 @c =====================================================================
6161 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference
6162 @section Manipulating Spacing
6163 @cindex manipulating spacing
6164 @cindex spacing, manipulating
6166 @Defreq {sp, [@Var{distance}]}
6167 Space downwards @var{distance}. With no argument it advances 1@w{
6168 }line. A negative argument causes @code{gtroff} to move up the page
6169 the specified distance. If the argument is preceded by a @samp{|}
6170 then @code{gtroff} moves that distance from the top of the page. This
6171 request causes a line break. The default scaling indicator is @samp{v}.
6174 @cindex double spacing (@code{ls})
6175 @DefreqList {ls, [@Var{nnn}]}
6177 Output @w{@var{nnn}@minus{}1} blank lines after each line of text.
6178 With no argument, @code{gtroff} uses the previous value before the
6179 last @code{ls} call.
6182 .ls 2 \" This causes double-spaced output
6183 .ls 3 \" This causes triple-spaced output
6184 .ls \" Again double spaced
6187 The line spacing is associated with the current environment
6188 (@pxref{Environments}).
6190 @cindex line spacing register (@code{.L})
6191 The read-only number register @code{.L} contains the current line
6195 @c XXX document \n[nl]
6196 @c XXX document \n[nl] == -1 if vertical position is zero
6198 @DefescList {\\x, ', spacing, '}
6200 Sometimes, extra vertical spacing is only needed occasionally, e.g.@:
6201 to allow space for a tall construct (like an equation). The @code{\x}
6202 escape does this. The escape is given a numerical argument, usually
6203 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
6204 is @samp{v}. If this number is positive extra vertical space is
6205 inserted below the current line. A negative number adds space above.
6206 If this escape is used multiple times on the same line, the maximum of
6209 @xref{Escapes}, for details on parameter delimiting characters.
6211 @cindex extra vertical line space register (@code{.a})
6212 The @code{.a} read-only number register contains the most recent
6213 (nonnegative) extra vertical line space.
6218 ... example of inline equation ...
6223 @cindex @code{sp} request, and no-space mode
6224 @cindex no-space mode (@code{ns})
6225 @cindex mode, no-space (@code{ns})
6226 @cindex blank lines, disabling
6227 @cindex lines, blank, disabling
6229 @DefregListEnd {.ns}
6230 Enable @dfn{no-space mode}. In this mode, spacing (either via
6231 @code{sp} or via blank lines) is disabled. The @code{bp} request to
6232 advance to the next page is also disabled, except if it is accompanied
6233 by a page number (see @ref{Page Control}, for more information). This
6234 mode ends when actual text is output or the @code{rs} request is
6235 encountered. The read-only number register @code{.ns} is set to@w{ }1.
6237 This request is useful for macros which want to avoid that subsequent
6238 macros inadvertently insert some vertical space before the text starts
6239 (for example, to set up the first paragraph after a section header).
6245 Disable no-space mode.
6251 @c =====================================================================
6253 @node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference
6254 @section Tabs and Fields
6255 @cindex tabs and fields
6256 @cindex fields and tabs
6258 @cindex @acronym{EBCDIC} encoding of a tab
6259 A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
6260 }5) causes a horizontal movement to the next tab stop (much
6261 like it did on a typewriter).
6263 @cindex tab character, non-interpreted (@code{\t})
6265 This escape is a non-interpreted tab character. In copy mode
6266 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
6269 @DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
6270 @DefregListEnd {.tabs}
6271 Change tab stop positions. This request takes a series of tab
6272 specifiers as arguments (optionally divided into two groups with the
6273 letter @samp{T}) which indicate where each tab stop is to be
6274 (overriding any previous settings).
6276 Tab stops can be specified absolutely, i.e., as the distance from the
6277 left margin. For example, the following sets 6@w{ }tab stops every
6281 .ta 1i 2i 3i 4i 5i 6i
6284 Tab stops can also be specified using a leading @samp{+}
6285 which means that the specified tab stop is set relative to
6286 the previous tab stop. For example, the following is equivalent to the
6290 .ta 1i +1i +1i +1i +1i +1i
6293 @code{gtroff} supports an extended syntax to specify repeat values after
6294 the @samp{T} mark (these values are always taken as relative) -- this is
6295 the usual way to specify tabs set at equal intervals. The following is,
6296 yet again, the same as the previous examples. It does even more since
6297 it defines an infinite number of tab stops separated by one inch.
6303 Now we are ready to interpret the full syntax given at the beginning:
6304 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
6305 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
6306 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
6307 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
6309 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
6310 20c 23c 28c 30c @dots{}}.
6312 The material in each tab column (i.e., the column between two tab stops)
6313 may be justified to the right or left or centered in the column. This
6314 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
6315 specifier. The default justification is @samp{L}. Example:
6325 The default unit of the @code{ta} request is @samp{m}.
6328 A tab stop is converted into a non-breakable horizontal movement which
6329 can be neither stretched nor squeezed. For example,
6338 creates a single line which is a bit longer than 10@w{ }inches (a string
6339 is used to show exactly where the tab characters are). Now consider the
6349 @code{gtroff} first converts the tab stops of the line into unbreakable
6350 horizontal movements, then splits the line after the second @samp{b}
6351 (assuming a sufficiently short line length). Usually, this isn't what
6355 Superfluous tabs (i.e., tab characters which do not correspond to a tab
6356 stop) are ignored except the first one which delimits the characters
6357 belonging to the last tab stop for right-justifying or centering.
6358 Consider the following example
6362 .ds ZZ foo\tbar\tfoobar
6363 .ds ZZZ foo\tbar\tfoo\tbar
6374 which produces the following output:
6383 The first line right-justifies the second `foo' relative to the tab
6384 stop. The second line right-justifies `foobar'. The third line finally
6385 right-justifies only `foo' because of the additional tab character which
6386 marks the end of the string belonging to the last defined tab stop.
6389 Tab stops are associated with the current environment
6390 (@pxref{Environments}).
6393 Calling @code{ta} without an argument removes all tab stops.
6396 @cindex tab stops, for tty output devices
6397 The start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. This value
6398 is used even for tty output devices (contrary to @acronym{UNIX}
6399 @code{nroff} which has tab stops preset every 0.8@dmn{i}).
6401 @c XXX xref implementation differences
6404 @cindex tab settings register (@code{.tabs})
6405 The read-only number register @code{.tabs} contains a string
6406 representation of the current tab settings suitable for use as an
6407 argument to the @code{ta} request.
6410 .ds tab-string \n[.tabs]
6416 @cindex tab repetition character (@code{tc})
6417 @cindex character, tab repetition (@code{tc})
6418 @Defreq {tc, [@Var{fill-char}]}
6419 Normally @code{gtroff} fills the space to the next tab stop with
6420 whitespace. This can be changed with the @code{tc} request. With no
6421 argument @code{gtroff} reverts to using whitespace, which is the
6422 default. The value of this @dfn{tab repetition} character is
6423 associated with the current environment (@pxref{Environments}).
6431 @c ---------------------------------------------------------------------
6433 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
6437 Sometimes it may may be desirable to use the @code{tc} request to fill a
6438 particular tab stop with a given character (for example dots in a table
6439 of contents), but also normal tab stops on the rest of the line. For
6440 this @code{gtroff} provides an alternate tab mechanism, called
6441 @dfn{leaders} which does just that.
6443 @cindex leader character
6444 A leader character (character code@w{ }1) behaves similarly to a tab
6445 character: It moves to the next tab stop. The only difference is that
6446 for this movement, the fill character defaults to a period character and
6449 @cindex leader character, non-interpreted (@code{\a})
6451 This escape is a non-interpreted leader character. In copy mode
6452 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
6456 @cindex leader repetition character (@code{lc})
6457 @cindex character, leader repetition (@code{lc})
6458 @Defreq {lc, [@Var{fill-char}]}
6459 Declare the leader character. Without an argument, leaders act the
6460 same as tabs (i.e., using whitespace for filling). @code{gtroff}'s
6461 start-up value is @samp{.}. The value of this @dfn{leader repetition}
6462 character is associated with the current environment
6463 (@pxref{Environments}).
6466 @cindex table of contents
6467 @cindex contents, table of
6468 For a table of contents, to name an example, tab stops may be defined so
6469 that the section number is one tab stop, the title is the second with
6470 the remaining space being filled with a line of dots, and then the page
6471 number slightly separated from the dots.
6474 .ds entry 1.1\tFoo\a\t12
6484 1.1 Foo.......................................... 12
6487 @c ---------------------------------------------------------------------
6489 @node Fields, , Leaders, Tabs and Fields
6493 @cindex field delimiting character (@code{fc})
6494 @cindex delimiting character for fields (@code{fc})
6495 @cindex character, field delimiting (@code{fc})
6496 @cindex field padding character (@code{fc})
6497 @cindex padding character for fields (@code{fc})
6498 @cindex character, field padding (@code{fc})
6499 @dfn{Fields} are a more general way of laying out tabular data. A field
6500 is defined as the data between a pair of @dfn{delimiting characters}.
6501 It contains substrings which are separated by @dfn{padding characters}.
6502 The width of a field is the distance on the @emph{input} line from the
6503 position where the field starts to the next tab stop. A padding
6504 character inserts stretchable space similar to @TeX{}'s @code{\hss}
6505 command (thus it can even be negative) to make the sum of all substring
6506 lengths plus the stretchable space equal to the field width. If more
6507 than one padding character is inserted, the available space is evenly
6508 distributed among them.
6510 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
6511 Define a delimiting and a padding character for fields. If the latter
6512 is missing, the padding character defaults to a space character. If
6513 there is no argument at all, the field mechanism is disabled (which is
6514 the default). Note that contrary to e.g.@: the tab repetition
6515 character, delimiting and padding characters are not associated to the
6516 current environment (@pxref{Environments}).
6529 and here the result:
6538 @c =====================================================================
6540 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference
6541 @section Character Translations
6542 @cindex character translations
6543 @cindex translations of characters
6545 @cindex control character, changing (@code{cc})
6546 @cindex character, control, changing (@code{cc})
6547 @cindex no-break control character, changing (@code{c2})
6548 @cindex character, no-break control, changing (@code{c2})
6549 @cindex control character, no-break, changing (@code{c2})
6550 The control character (@samp{.}) and the no-break control character
6551 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
6554 @Defreq {cc, [@Var{c}]}
6555 Set the control character to@w{ }@var{c}. With no argument the default
6556 control character @samp{.} is restored. The value of the control
6557 character is associated with the current environment
6558 (@pxref{Environments}).
6561 @Defreq {c2, [@Var{c}]}
6562 Set the no-break control character to@w{ }@var{c}. With no argument the
6563 default control character @samp{'} is restored. The value of the
6564 no-break control character is associated with the current environment
6565 (@pxref{Environments}).
6568 @cindex disabling @code{\\} (@code{eo})
6569 @cindex @code{\\}, disabling (@code{eo})
6571 Disable the escape mechanism completely. After executing this
6572 request, the backslash character @samp{\} no longer starts an escape
6575 This request can be very helpful in writing macros since it is not
6576 necessary then to double the escape character. Here an example:
6579 .\" This is a simplified version of the
6580 .\" .BR request from the man macro package
6584 . while (\n[.$] >= 2) \@{\
6585 . as result \fB\$1\fR\$2
6588 . if \n[.$] .as result \fB\$1
6596 @cindex escape character, changing (@code{ec})
6597 @cindex character, escape, changing (@code{ec})
6598 @Defreq {ec, [@Var{c}]}
6599 Set the escape character to@w{ }@var{c}. With no argument the default
6600 escape character @samp{\} is restored. It can be also used to
6601 re-enable the escape mechanism after an @code{eo} request.
6603 Note that changing the escape character globally will likely break
6604 macro packages since @code{gtroff} has no mechanism (like @TeX{}) to
6605 `intern' macros, i.e., to convert a macro definition into an internal
6606 form which is independent of its representation. If a macro is
6607 called, it is executed literally.
6611 This escape sequence prints the current escape character (which is the
6612 backslash character @samp{\} by default).
6615 A @dfn{translation} is a mapping of an input character to an output
6616 character. The default mappings are given in the font definition files
6617 for the specific output device (@pxref{Font Files}); all mappings (both
6618 with @code{tr} and in the font definition files) occur at output time,
6619 i.e., the input character gets assigned the metric information of the
6620 mapped output character.
6622 @Defreq {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
6623 Translate character @var{a} to@w{ }@var{b}, character @var{c} to@w{
6624 }@var{d}, etc. If there is an odd number of arguments, the last one is
6625 translated to the space character.
6631 @cindex @code{\(}, and translations
6632 @cindex @code{\[}, and translations
6633 @cindex @code{\'}, and translations
6634 @cindex @code{\`}, and translations
6635 @cindex @code{\-}, and translations
6636 @cindex @code{\_}, and translations
6637 @cindex @code{\C}, and translations
6638 @cindex @code{\N}, and translations
6639 @cindex @code{char} request, and translations
6640 @cindex special character
6641 @cindex character, special
6642 @cindex numbered character (@code{\N})
6643 @cindex character, numbered (@code{\N})
6644 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
6645 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
6646 characters defined with the @code{char} request, and numbered characters
6647 (@code{\N'@var{xxx}'}) can be translated also.
6650 @cindex @code{\e}, and translations
6651 The @code{\e} escape can be translated also.
6654 @cindex @code{\%}, and translations
6655 @cindex @code{\~}, and translations
6656 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
6657 @code{\%} and @code{\~} can't be mapped onto another character).
6660 @cindex backspace character and translations
6661 @cindex character, backspace, and translations
6662 @cindex leader character and translations
6663 @cindex character, leader, and translations
6664 @cindex newline character and translations
6665 @cindex character, newline, and translations
6666 @cindex tab character and translations
6667 @cindex character, tab, and translations
6668 @cindex @code{\a}, and translations
6669 @cindex @code{\t}, and translations
6670 The following characters can't be translated: space (with one exception,
6671 see below), backspace, newline, leader (and @code{\a}), tab (and
6675 @cindex @code{shc} request, and translations
6676 Translations are not considered for finding the soft hyphen character
6677 set with the @code{shc} request.
6680 @cindex @code{\&}, and translations
6681 The character pair @samp{@var{c}\&} (this is an arbitrary character@w{
6682 }@var{c} followed by the zero width space character) maps this
6683 character to nothing.
6692 It is even possible to map the space character to nothing:
6701 As shown in the example, the space character can't be the first
6702 character pair as an argument of @code{tr}. Additionally, it is not
6703 possible to map the space character to any other character; requests
6704 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
6706 If justification is active, lines are justified in spite of the
6707 `empty' space character (but there is no minimal distance, i.e.@: the
6708 space character, between words).
6711 After an output character has been constructed (this happens at the
6712 moment immediately before the character is appended to an output
6713 character list, either by direct output, in a macro, diversion, or
6714 string), it is no longer affected by @code{tr}.
6719 Without an argument, the @code{tr} request is ignored.
6723 @cindex @code{\!}, and @code{trnt}
6724 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
6725 @code{trnt} is the same as the @code{tr} request except that the
6726 translations do not apply to text that is transparently throughput
6727 into a diversion with @code{\!}. @xref{Diversions}, for more
6741 prints @samp{b} to the standard error stream; if @code{trnt} is used
6742 instead of @code{tr} it prints @samp{a}.
6746 @c =====================================================================
6748 @node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference
6749 @section Troff and Nroff Mode
6755 Originally, @code{nroff} and @code{troff} were two separate programs,
6756 the former for tty output, the latter for everything else. With GNU
6757 @code{troff}, both programs are merged into one executable, sending
6758 its output to a device driver (@code{grotty} for tty devices,
6759 @code{grops} for @sc{PostScript}, etc.) which interprets the
6760 intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff}
6761 it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode}
6762 since the differences are hardcoded. For GNU @code{troff}, this
6763 distinction is not appropriate because @code{gtroff} simply takes the
6764 information given in the font files for a particular device without
6765 handling requests specially if a tty output device is used.
6767 Usually, a macro package can be used with all output devices.
6768 Nevertheless, it is sometimes necessary to make a distinction between
6769 tty and non-tty devices: @code{gtroff} provides two built-in
6770 conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and
6771 @code{while} requests to decide whether @code{gtroff} shall behave
6772 like @code{nroff} or like @code{troff}.
6777 Make the @samp{t} built-in condition true (and the @samp{n} built-in
6778 condition false) for @code{if}, @code{ie}, and @code{while}
6779 conditional requests. This is the default if @code{gtroff}
6780 (@emph{not} @code{groff}) is started with the @option{-R} switch to
6781 avoid loading of the start-up files @file{troffrc} and
6782 @file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff
6783 mode if the output device is not a tty (e.g.@: `ps').
6788 Make the @samp{n} built-in condition true (and the @samp{t} built-in
6789 condition false) for @code{if}, @code{ie}, and @code{while}
6790 conditional requests. This is the default if @code{gtroff} uses a tty
6791 output device; the code for switching to nroff mode is in the file
6792 @file{tty.tmac} which is loaded by the start-up file @code{troffrc}.
6795 @xref{Conditionals and Loops}, for more details on built-in
6798 @c XXX move the following to grotty section
6802 @cindex ISO 6249 SGR
6803 @cindex terminal control sequences
6804 @cindex control sequences, for terminals
6805 For tty output devices, underlining is done by emitting sequences of
6806 @samp{_} and @samp{\b} (the backspace character) before the actual
6807 character. Literally, this is printing an underline character, then
6808 moving back one character position, and printing the actual character
6809 at the same position as the underline character (similar to a
6810 typewriter). Usually, a modern terminal can't interpret this (and the
6811 original Teletype machines for which this sequence was appropriate are
6812 no longer in use). You need a pager program like @code{less} which
6813 translates this into ISO 6429 SGR sequences to control terminals.
6815 @c =====================================================================
6817 @node Line Layout, Page Layout, Troff and Nroff Mode, gtroff Reference
6818 @section Line Layout
6820 @cindex layout, line
6822 @cindex dimensions, line
6823 @cindex line dimensions
6824 The following drawing shows the dimensions which @code{gtroff} uses for
6825 placing a line of output onto the page. They are labeled with the
6826 request which manipulates each dimension.
6830 |<-----------ll------------>|
6831 +----+----+----------------------+----+
6833 +----+----+----------------------+----+
6835 |<--------paper width---------------->|
6839 These dimensions are:
6843 @cindex left margin (@code{po})
6844 @cindex margin, left (@code{po})
6845 @cindex page offset (@code{po})
6846 @cindex offset, page (@code{po})
6847 @dfn{Page offset} -- this is the leftmost position of text on the final
6848 output, defining the @dfn{left margin}.
6851 @cindex indentation (@code{in})
6852 @cindex line indentation (@code{in})
6853 @dfn{Indentation} -- this is the distance from the left margin where
6857 @cindex line length (@code{ll})
6858 @cindex length of line (@code{ll})
6859 @dfn{Line length} -- this is the distance from the left margin to right
6863 @c XXX improve example
6868 A bunch of really boring text which should
6869 be indented from both margins.
6870 Replace me with a better (and more) example!
6876 @DefreqList {po, [@Var{offset}]}
6877 @DefreqItem {po, @t{+}@Var{offset}}
6878 @DefreqItem {po, @t{-}@Var{offset}}
6880 Set horizontal page offset to @var{offset} (or increment or decrement
6881 the current value by @var{offset}). Note that this request does not
6882 cause a break, so changing the page offset in the middle of text being
6883 filled may not yield the expected result. The initial value is
6884 1@dmn{i}. For tty output devices, it is set to 0 in the startup file
6885 @file{troffrc}; the default scaling indicator is @samp{m} (and
6886 not @samp{v} as incorrectly documented in the original
6887 @acronym{UNIX} troff manual).
6889 The current page offset can be found in the read-only number register
6892 If @code{po} is called without an argument, the page offset is reset to
6893 the previous value before the last call to @code{po}.
6908 @DefreqList {in, [@Var{indent}]}
6909 @DefreqItem {in, @t{+}@Var{indent}}
6910 @DefreqItem {in, @t{-}@Var{indent}}
6912 Set indentation to @var{indent} (or increment or decrement the
6913 current value by @var{indent}). This request causes a break.
6914 Initially, there is no indentation.
6916 If @code{in} is called without an argument, the indentation is reset to
6917 the previous value before the last call to @code{in}. The default
6918 scaling indicator is @samp{m}.
6920 The indentation is associated with the current environment
6921 (@pxref{Environments}).
6923 If a negative indentation value is specified (which is not allowed),
6924 @code{gtroff} emits a warning of type @samp{range} and sets the
6925 indentation to zero.
6927 The effect of @code{in} is delayed until a partially collected line (if
6928 it exists) is output. A temporary indent value is reset to zero also.
6930 The current indentation (as set by @code{in}) can be found in the
6931 read-only number register @samp{.i}.
6934 @DefreqList {ti, offset}
6935 @DefreqItem {ti, @t{+}@Var{offset}}
6936 @DefreqItem {ti, @t{-}@Var{offset}}
6937 @DefregListEnd {.in}
6938 Temporarily indent the next output line by @var{offset}. If an
6939 increment or decrement value is specified, adjust the temporary
6940 indentation relative to the value set by the @code{in} request.
6942 This request causes a break; its value is associated with the current
6943 environment (@pxref{Environments}). The default scaling indicator
6944 is @samp{m}. A call of @code{ti} without an argument is ignored.
6946 If the total indentation value is negative (which is not allowed),
6947 @code{gtroff} emits a warning of type @samp{range} and sets the
6948 temporary indentation to zero. `Total indentation' is either
6949 @var{offset} if specified as an absolute value, or the temporary plus
6950 normal indentation, if @var{offset} is given as a relative value.
6952 The effect of @code{ti} is delayed until a partially collected line (if
6953 it exists) is output.
6955 The read-only number register @code{.in} is the indentation that applies
6956 to the current output line.
6958 The difference between @code{.i} and @code{.in} is that the latter takes
6959 into account whether a partially collected line still uses the old
6960 indentation value or a temporary indentation value is active.
6963 @DefreqList {ll, [@Var{length}]}
6964 @DefreqItem {ll, @t{+}@Var{length}}
6965 @DefreqItem {ll, @t{-}@Var{length}}
6967 @DefregListEnd {.ll}
6968 Set the line length to @var{length} (or increment or decrement the
6969 current value by @var{length}). Initially, the line length is set to
6970 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
6971 collected line (if it exists) is output. The default scaling
6972 indicator is @samp{m}.
6974 If @code{ll} is called without an argument, the line length is reset to
6975 the previous value before the last call to @code{ll}. If a negative
6976 line length is specified (which is not allowed), @code{gtroff} emits a
6977 warning of type @samp{range} and sets the line length to zero.
6979 The line length is associated with the current environment
6980 (@pxref{Environments}).
6982 @cindex line length register (@code{.l})
6983 The current line length (as set by @code{ll}) can be found in the
6984 read-only number register @samp{.l}. The read-only number register
6985 @code{.ll} is the line length that applies to the current output line.
6987 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
6988 and @code{.ll} is that the latter takes into account whether a partially
6989 collected line still uses the old line length value.
6993 @c =====================================================================
6995 @node Page Layout, Page Control, Line Layout, gtroff Reference
6996 @section Page Layout
6998 @cindex layout, page
7000 @code{gtroff} provides some very primitive operations for controlling
7003 @cindex page length (@code{pl})
7004 @cindex length of page (@code{pl})
7005 @DefreqList {pl, [@Var{length}]}
7006 @DefreqItem {pl, @t{+}@Var{length}}
7007 @DefreqItem {pl, @t{-}@Var{length}}
7009 Set the @dfn{page length} to @var{length} (or increment or decrement
7010 the current value by @var{length}). This is the length of the
7011 physical output page. The default scaling indicator is @samp{v}.
7013 @cindex page length register (@code{.p})
7014 The current setting can be found in the read-only number register
7019 @cindex bottom margin
7020 @cindex margin, bottom
7021 Note that this only specifies the size of the page, not the top and
7022 bottom margins. Those are not set by @code{gtroff} directly.
7023 @xref{Traps}, for further information on how to do this.
7025 Negative @code{pl} values are possible also, but not very useful: No
7026 trap is sprung, and each line is output on a single page (thus
7027 suppressing all vertical spacing).
7029 If no argument or an invalid argument is given, @code{pl} sets the page
7030 length to 11@dmn{i}.
7036 @code{gtroff} provides several operations which help in setting up top
7037 and bottom titles (or headers and footers).
7039 @cindex title line (@code{tl})
7040 @cindex three-part title (@code{tl})
7041 @cindex page number character (@code{%})
7042 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
7043 Print a @dfn{title line}. It consists of three parts: a left
7044 justified portion, a centered portion, and a right justified portion.
7045 The argument separator @samp{'} can be replaced with any character not
7046 occurring in the title line. The @samp{%} character is replaced with
7047 the current page number. This character can be changed with the
7048 @code{pc} request (see below).
7050 Without argument, @code{tl} is ignored.
7056 A title line is not restricted to the top or bottom of a page.
7059 @code{tl} prints the title line immediately, ignoring a partially filled
7060 line (which stays untouched).
7063 It is not an error to omit closing delimiters. For example,
7064 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
7065 title line with the left justified word @samp{foo}; the centered and
7066 right justfied parts are empty.
7069 Any modifications to the current environment within @code{tl} (e.g.@:
7070 changing the font or font size) are undone after processing @code{tl}.
7073 @code{tl} accepts the same parameter delimiting characters as the
7074 @code{\A} escape; see @ref{Escapes}.
7078 @cindex length of title line (@code{lt})
7079 @cindex title line, length (@code{lt})
7080 @cindex title line length register (@code{.lt})
7081 @DefreqList {lt, [@Var{length}]}
7082 @DefreqItem {lt, @t{+}@Var{length}}
7083 @DefreqItem {lt, @t{-}@Var{length}}
7084 @DefregListEnd {.lt}
7085 The title line is printed using its own line length, which is
7086 specified (or incremented or decremented) with the @code{lt} request.
7087 Initially, the title line length is set to 6.5@dmn{i}. If a negative
7088 line length is specified (which is not allowed), @code{gtroff} emits a
7089 warning of type @samp{range} and sets the title line length to zero.
7090 The default scaling indicator is @samp{m}. If @code{lt} is called
7091 without an argument, the title length is reset to the previous value
7092 before the last call to @code{lt}.
7094 The current setting of this is available in the @code{.lt} read-only
7095 number register; it is associated with the current environment
7096 (@pxref{Environments}).
7100 @cindex page number (@code{pn})
7101 @cindex number, page (@code{pn})
7102 @DefreqList {pn, page}
7103 @DefreqItem {pn, @t{+}@Var{page}}
7104 @DefreqItem {pn, @t{-}@Var{page}}
7105 @DefregListEnd {.pn}
7106 Change (increase or decrease) the page number of the @emph{next} page.
7107 The only argument is the page number; the request is ignored without a
7110 The read-only number register @code{.pn} contains the number of the next
7111 page: either the value set by a @code{pn} request, or the number of the
7112 current page plus@w{ }1.
7115 @cindex page number register (@code{%})
7117 A read-write register holding the current page number.
7120 @cindex changing the page number character (@code{pc})
7121 @cindex page number character, changing (@code{pc})
7123 @Defreq {pc, [@Var{char}]}
7124 Change the page number character (used by the @code{tl} request) to a
7125 different character. With no argument, this mechanism is disabled.
7126 Note that this doesn't affect the number register@w{ }@code{%}.
7132 @c =====================================================================
7134 @node Page Control, Fonts, Page Layout, gtroff Reference
7135 @section Page Control
7136 @cindex page control
7137 @cindex control, page
7139 @cindex new page (@code{bp})
7140 @cindex page, new (@code{bp})
7141 @DefreqList {bp, [@Var{page}]}
7142 @DefreqItem {bp, @t{+}@Var{page}}
7143 @DefreqListEnd {bp, @t{-}@Var{page}}
7144 Stop processing the current page and move to the next page. This
7145 request causes a break. It can also take an argument to set
7146 (increase, decrease) the page number of the next page. The only
7147 difference between @code{bp} and @code{pn} is that @code{pn} does not
7148 cause a break or actually eject a page.
7151 .de newpage \" define macro
7153 'sp .5i \" vertical space
7154 .tl 'left top'center top'right top' \" title
7155 'sp .3i \" vertical space
7159 @cindex @code{bp} request, and top-level diversion
7160 @cindex top-level diversion and @code{bp}
7161 @cindex diversion, top-level, and @code{bp}
7162 @code{bp} has no effect if not called within the top-level diversion
7163 (@pxref{Diversions}).
7166 @cindex orphan lines, preventing with @code{ne}
7167 @cindex conditional page break (@code{ne})
7168 @cindex page break, conditional (@code{ne})
7169 @Defreq {ne, [@Var{space}]}
7170 It is often necessary to force a certain amount of space before a new
7171 page occurs. This is most useful to make sure that there is not a
7172 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
7173 request ensures that there is a certain distance, specified by the
7174 first argument, before the next page is triggered (see @ref{Traps},
7175 for further information). The default unit for @code{ne} is @samp{v};
7176 the default value of @var{space} is@w{ }1@dmn{v} if no argument is
7179 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
7180 do the following before each paragraph:
7187 @code{ne} will then automatically cause a page break if there is space
7191 @cindex @code{ne} request, comparison with @code{sv}
7192 @Defreq {sv, [@Var{space}]}
7193 @code{sv} is similar to the @code{ne} request; it reserves the
7194 specified amount of vertical space. If the desired amount of space
7195 exists before the next trap (bottom page boundary), the space is
7196 output immediately (ignoring a partial filled line which stays
7197 untouched). If there is not enough space, it is stored for later
7198 output via the @code{os} request. The default value is@w{ }1@dmn{v}
7199 if no argument is given; the default unit is @samp{v}.
7203 @c =====================================================================
7205 @node Fonts, Sizes, Page Control, gtroff Reference
7209 @code{gtroff} can switch fonts at any point in the text.
7211 The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
7212 These are Times Roman, Italic, Bold, and Bold Italic. For non-tty
7213 devices, there is also at least one symbol font which contains various
7214 special symbols (Greek, mathematics).
7222 * Artificial Fonts::
7223 * Ligatures and Kerning::
7226 @c ---------------------------------------------------------------------
7228 @node Changing Fonts, Font Families, Fonts, Fonts
7229 @subsection Changing Fonts
7232 @cindex changing fonts (@code{ft}, @code{\f})
7233 @cindex fonts, changing (@code{ft}, @code{\f})
7234 @cindex @code{sty} request, and changing fonts
7235 @cindex @code{fam} request, and changing fonts
7239 @DefreqList {ft, [@Var{font}]}
7240 @DefescItem {\\f, , f, }
7241 @DefescItem {\\f, @lparen{}, fn, }
7242 @DefescListEnd {\\f, @lbrack{}, font, @rbrack}
7243 The @code{ft} request and the @code{\f} escape change the current font
7244 to @var{font} (one-character name@w{ }@var{f}, two-character name
7247 If @var{font} is a style name (as set with the @code{sty} request or
7248 with the @code{styles} command in the @file{DESC} file), use it within
7249 the current font family (as set with the @code{fam} request or with
7250 the @code{family} command in the @file{DESC} file).
7252 @cindex previous font (@code{ft}, @code{\fP})
7253 @cindex font, previous (@code{ft}, @code{\fP})
7254 With no argument or using @samp{P} as an argument, @code{.ft} switches
7255 to the previous font. Use @code{\fP} or @code{\f[P]} to do this with
7258 Fonts are generally specified as upper-case strings, which are usually
7259 1@w{ }to 4 characters representing an abbreviation or acronym of the
7260 font name. This is no limitation, just a convention.
7262 The example below produces two identical lines.
7271 eggs, bacon, \fBspam\fP and sausage.
7274 @xref{Font Positions}, for an alternative syntax.
7277 @cindex @code{ft} request, and font translations
7278 @cindex @code{ul} request, and font translations
7279 @cindex @code{bd} request, and font translations
7280 @cindex @code{\f}, and font translations
7281 @cindex @code{cs} request, and font translations
7282 @cindex @code{tkf} request, and font translations
7283 @cindex @code{special} request, and font translations
7284 @cindex @code{fspecial} request, and font translations
7285 @cindex @code{fp} request, and font translations
7286 @cindex @code{sty} request, and font translations
7287 @Defreq {ftr, f [@Var{g}]}
7288 Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named@w{
7289 }@var{f} is referred to in a @code{\f} escape sequence, or in the
7290 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf},
7291 @code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests,
7292 font@w{ }@var{g} is used. If @var{g} is missing or equal to@w{ }@var{f}
7293 the translation is undone.
7296 @c ---------------------------------------------------------------------
7298 @node Font Families, Font Positions, Changing Fonts, Fonts
7299 @subsection Font Families
7300 @cindex font families
7301 @cindex families, font
7303 @cindex styles, font
7305 Due to the variety of fonts available, @code{gtroff} has added the
7306 concept of @dfn{font families} and @dfn{font styles}. The fonts are
7307 specified as the concatenation of the font family and style. Specifying
7308 a font without the family part causes @code{gtroff} to use that style of
7311 @cindex postscript fonts
7312 @cindex fonts, postscript
7313 Currently, only @sc{PostScript} fonts are set up to this mechanism.
7314 By default, @code{gtroff} uses the Times family with the four styles
7315 @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
7317 This way, it is possible to use the basic four fonts and to select a
7318 different font family on the command line (@pxref{Groff Options}).
7320 @cindex changing font family (@code{fam})
7321 @cindex font family, changing (@code{fam})
7322 @DefreqList {fam, [@Var{family}]}
7323 @DefregListEnd {.fam}
7324 Switch font family to @var{family}. If no argument is given, switch
7325 back to the previous font family. The current font family is available
7326 in the read-only number register @samp{.fam} (this is a string-valued
7327 register); it is associated with the current environment.
7331 .fam H \" helvetica family
7332 spam, \" used font is family H + style R = HR
7333 .ft B \" family H + style B = font HB
7335 .fam T \" times family
7336 spam, \" used font is family T + style B = TB
7337 .ft AR \" font AR (not a style)
7339 .ft R \" family T + style R = font TR
7344 @cindex changing font style (@code{sty})
7345 @cindex font style, changing (@code{sty})
7346 @cindex @code{cs} request, and font styles
7347 @cindex @code{bd} request, and font styles
7348 @cindex @code{tkf} request, and font styles
7349 @cindex @code{uf} request, and font styles
7350 @cindex @code{fspecial} request, and font styles
7351 @Defreq {sty, n style}
7352 Associate @var{style} with font position@w{ }@var{n}. A font position
7353 can be associated either with a font or with a style. The current
7354 font is the index of a font position and so is also either a font or a
7355 style. If it is a style, the font that is actually used is the font
7356 which name is the concatenation of the name of the current
7357 family and the name of the current style. For example, if the current
7358 font is@w{ }1 and font position@w{ }1 is associated with style
7359 @samp{R} and the current font family is @samp{T}, then font
7360 @samp{TR} will be used. If the current font is not a style, then the
7361 current family is ignored. If the requests @code{cs}, @code{bd},
7362 @code{tkf}, @code{uf}, or @code{fspecial} are applied to a style,
7363 they will instead be applied to the member of the current family
7364 corresponding to that style.
7366 @var{n}@w{ }must be a non-negative integer value.
7370 The default family can be set with the @option{-f} option
7371 (@pxref{Groff Options}). The @code{styles} command in the @file{DESC}
7372 file controls which font positions (if any) are initially associated
7373 with styles rather than fonts. For example, the default setting for
7374 @sc{PostScript} fonts
7390 @code{.fam} always checks whether the current font position is valid;
7391 this can give surprising results if the current font position is
7392 associated with a style.
7394 In the following example, we want to access the @sc{PostScript} font
7395 @code{FooBar} from the font family @code{Foo}:
7400 @result{} warning: can't find font `FooR'
7404 The default font position at start-up is@w{ }1; for the
7405 @sc{PostScript} device, this is associated with style @samp{R}, so
7406 @code{gtroff} tries to open @code{FooR}.
7408 A solution to this problem is to use a dummy font like the following:
7411 .fp 0 dummy TR \" set up dummy font at position 0
7412 .sty \n[.fp] Bar \" register style `Bar'
7413 .ft 0 \" switch to font at position 0
7414 .fam Foo \" activate family `Foo'
7415 .ft Bar \" switch to font `FooBar'
7418 @xref{Font Positions}.
7421 @c ---------------------------------------------------------------------
7423 @node Font Positions, Using Symbols, Font Families, Fonts
7424 @subsection Font Positions
7425 @cindex font positions
7426 @cindex positions, font
7428 For the sake of old phototypesetters and compatibility with old versions
7429 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
7430 on which various fonts are mounted.
7432 @cindex mounting font (@code{fp})
7433 @cindex font, mounting (@code{fp})
7434 @DefreqList {fp, pos font [@Var{external-name}]}
7436 @DefregListEnd {.fp}
7437 Mount font @var{font} at position @var{pos} (which must be a
7438 non-negative integer). This numeric position can then be referred to
7439 with font changing commands. When @code{gtroff} starts it is using
7440 font position@w{ }1 (which must exist; position@w{ }0 is unused
7441 usually at start-up).
7443 @cindex font position register (@code{.f})
7444 The current font in use, as a font position, is available in the
7445 read-only number register @samp{.f}. This can be useful to remember the
7446 current font for later recall. It is associated with the current
7447 environment (@pxref{Environments}).
7450 .nr save-font \n[.f]
7452 ... text text text ...
7456 @cindex next free font position register (@code{.fp})
7457 The number of the next free font position is available in the read-only
7458 number register @samp{.fp}. This is useful when mounting a new font,
7462 .fp \n[.fp] NEATOFONT
7465 @pindex DESC@r{, and font mounting}
7466 Fonts not listed in the @file{DESC} file are automatically mounted on
7467 the next available font position when they are referenced. If a font
7468 is to be mounted explicitly with the @code{fp} request on an unused
7469 font position, it should be mounted on the first unused font position,
7470 which can be found in the @code{.fp} register. Although @code{gtroff}
7471 does not enforce this strictly, it is not allowed to mount a font at a
7472 position whose number is much greater (approx.@: 1000 positions) than
7473 that of any currently used position.
7475 The @code{fp} request has an optional third argument. This argument
7476 gives the external name of the font, which is used for finding the font
7477 description file. The second argument gives the internal name of the
7478 font which is used to refer to the font in @code{gtroff} after it has
7479 been mounted. If there is no third argument then the internal name is
7480 used as the external name. This feature makes it possible to use
7481 fonts with long names in compatibility mode.
7484 Both the @code{ft} request and the @code{\f} escape have alternative
7485 syntax forms to access font positions.
7487 @cindex changing font position (@code{\f})
7488 @cindex font position, changing (@code{\f})
7489 @cindex @code{sty} request, and font positions
7490 @cindex @code{fam} request, and font positions
7494 @DefreqList {ft, nnn}
7495 @DefescItem {\\f, , n, }
7496 @DefescItem {\\f, @lparen{}, nn, }
7497 @DefescListEnd {\\f, @lbrack{}, nnn, @rbrack}
7498 Change the current font position to @var{nnn} (one-digit position@w{
7499 }@var{n}, two-digit position @var{nn}), which must be a non-negative
7502 If @var{nnn} is associated with a style (as set with the @code{sty}
7503 request or with the @code{styles} command in the @file{DESC} file), use
7504 it within the current font family (as set with the @code{fam} request or
7505 with the @code{family} command in the @file{DESC} file).
7511 .ft \" switch back to font 1
7515 this is font 1 again
7518 @xref{Changing Fonts}, for the standard syntax form.
7521 @c ---------------------------------------------------------------------
7523 @node Using Symbols, Special Fonts, Font Positions, Fonts
7524 @subsection Using Symbols
7525 @cindex using symbols
7526 @cindex symbols, using
7531 A @dfn{glyph} is a graphical representation of a @dfn{character}.
7532 While a character is an abstract entity containing semantic
7533 information, a glyph is something which can be actually seen on screen
7534 or paper. It is possible that a character has multiple glyph
7535 representation forms (for example, the character `A' can be either
7536 written in a roman or an italic font, yielding two different glyphs);
7537 sometimes more than one character maps to a single glyph (this is a
7538 @dfn{ligature} -- the most common is `fi').
7542 Please note that currently the distinction between glyphs and
7543 characters in this reference is not clearly carried out. This will be
7544 improved eventually in the next revision.
7547 @cindex special fonts
7550 A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all
7551 glyph names of a particular font are defined in its font file. If the
7552 user requests a glyph not available in this font, @code{gtroff} looks
7553 up an ordered list of @dfn{special fonts}. By default, the
7554 @sc{PostScript} output device supports the two special fonts @samp{SS}
7555 (slanted symbols) and @samp{S} (symbols) (the former is looked up
7556 before the latter). Other output devices use different names for
7557 special fonts. Fonts mounted with the @code{fonts} keyword in the
7558 @file{DESC} file are globally available. To install additional
7559 special fonts locally (i.e.@: for a particular font), use the
7560 @code{fspecial} request.
7562 In summary, @code{gtroff} tries the following to find a given symbol:
7566 If the symbol has been defined with the @code{char} request, use it.
7567 This hides a symbol with the same name in the current font.
7570 Check the current font.
7573 If the symbol has been defined with the @code{fchar} request, use it.
7576 Check all fonts given with the @code{fspecial} request, in the order
7577 of appearance in @code{fspecial} calls.
7580 Check all fonts given with the @code{special} request, in the order
7581 of appearance in @code{special} calls (inclusively the special fonts
7582 defined in the @file{DESC} file, which come first).
7585 As a last resort, consult all fonts loaded up to now (in the order they
7586 have been called the first time) for special fonts and check them.
7589 @xref{Font Files}, and @ref{Special Fonts}, for more details.
7591 @DefescList {\\, @lparen{}, nm, }
7592 @DefescListEnd {\\, @lbrack{}, name, @rbrack}
7593 Insert a symbol @var{name} (two-character name @var{nm}). There is no
7594 special syntax for one-character names -- the natural form
7595 @samp{\@var{n}} would collide with escapes.
7597 If @var{name} is undefined, a warning of type @samp{char} is generated,
7598 and the escape is ignored. @xref{Debugging}, for information about
7601 The list of available symbols is device dependent; see @ref{Glyph Name
7602 Index} for some of them discussed in this reference.
7604 @c XXX list of common symbols
7607 @cindex named character (@code{\C})
7608 @cindex character, named (@code{\C})
7609 @Defesc {\\C, ', xxx, '}
7610 Typeset the character named @var{xxx}. Normally it is more convenient
7611 to use @code{\[@var{xxx}]}, but @code{\C} has the advantage that it is
7612 compatible with newer versions of @code{ditroff} and is available in
7616 @cindex numbered character (@code{\N})
7617 @cindex character, numbered (@code{\N})
7618 @cindex @code{char} request, used with @code{\N}
7620 @Defesc {\\N, ', n, '}
7621 Typeset the character with code@w{ }@var{n} in the current font (this
7622 is @strong{not} the input character code). @var{n}@w{ }can be any
7623 integer. Most devices only have characters with codes between 0
7624 and@w{ }255; the Unicode output device uses codes in the range
7625 0--65535. If the current font does not contain a character with that
7626 code, special fonts are @emph{not} searched. The @code{\N} escape
7627 sequence can be conveniently used in conjunction with the @code{char}
7631 .char \[phone] \f[ZD]\N'37'
7636 @cindex unnamed characters
7637 @cindex characters, unnamed
7638 The code of each character is given in the fourth column in the font
7639 description file after the @code{charset} command. It is possible to
7640 include unnamed characters in the font description file by using a
7641 name of @samp{---}; the @code{\N} escape sequence is the only way to
7645 @c XXX should be `glyph', not `character'
7647 @cindex character properties (@code{cflags})
7648 @cindex properties of characters (@code{cflags})
7649 @Defreq {cflags, n c1 c2 @dots{}}
7650 Each character has certain properties associated with it. These
7651 properties can be modified with the @code{cflags} request. The first
7652 argument is the the sum of the desired flags and the remaining
7653 arguments are the characters to have those properties. It is possible
7654 to omit the spaces between the characters.
7658 @cindex end-of-sentence characters
7659 @cindex characters, end-of-sentence
7660 the character ends sentences (initially characters @samp{.?!} have this
7664 @cindex hyphenating characters
7665 @cindex characters, hyphenation
7666 lines can be broken before the character (initially no characters have
7670 @cindex @code{hy} glyph, and @code{cflags}
7671 @cindex @code{em} glyph, and @code{cflags}
7672 lines can be broken after the character (initially the characters
7673 @samp{-\(hy\(em} have this property)
7676 @cindex overlapping characters
7677 @cindex characters, overlapping
7678 @cindex @code{ul} glyph, and @code{cflags}
7679 @cindex @code{rn} glyph, and @code{cflags}
7680 @cindex @code{ru} glyph, and @code{cflags}
7681 the character overlaps horizontally (initially the characters
7682 @samp{\(ul\(rn\(ru} have this property)
7685 @cindex @code{br} glyph, and @code{cflags}
7686 the character overlaps vertically (initially character @samp{\(br} has
7690 @cindex transparent characters
7691 @cindex character, transparent
7692 @cindex @code{"}, at end of sentence
7693 @cindex @code{'}, at end of sentence
7694 @cindex @code{)}, at end of sentence
7695 @cindex @code{]}, at end of sentence
7696 @cindex @code{*}, at end of sentence
7697 @cindex @code{dg} glyph, at end of sentence
7698 @cindex @code{rq} glyph, at end of sentence
7699 an end-of-sentence character followed by any number of characters with
7700 this property is treated as the end of a sentence if followed by a
7701 newline or two spaces; in other words the character is
7702 @dfn{transparent} for the purposes of end-of-sentence recognition --
7703 this is the same as having a zero space factor in @TeX{} (initially
7704 characters @samp{"')]*\(dg\(rq} have this property).
7708 @cindex defining character (@code{char})
7709 @cindex character, defining (@code{char})
7710 @cindex creating new characters (@code{char})
7711 @cindex escape character, while defining character
7712 @cindex character, escape, while defining character
7713 @cindex @code{tr} request, and character definitions
7714 @cindex @code{cp} request, and character definitions
7715 @cindex @code{rc} request, and character definitions
7716 @cindex @code{lc} request, and character definitions
7717 @cindex @code{\l}, and character definitions
7718 @cindex @code{\L}, and character definitions
7719 @cindex @code{\&}, and character definitions
7720 @cindex @code{\e}, and character definitions
7721 @cindex @code{hcode} request, and character definitions
7722 @Defreq {char, c [@Var{string}]}
7723 Define a new character@w{ }@var{c} to be @var{string} (which can be
7724 empty). Every time character@w{ }@var{c} needs to be printed,
7725 @var{string} is processed in a temporary environment and the result is
7726 wrapped up into a single object. Compatibility mode is turned off and
7727 the escape character is set to @samp{\} while @var{string} is being
7728 processed. Any emboldening, constant spacing or track kerning is
7729 applied to this object rather than to individual characters in
7730 @var{string}. A character defined by this request can be used just
7731 like a normal character provided by the output device. In particular,
7732 other characters can be translated to it with the @code{tr} request;
7733 it can be made the leader character by the @code{lc} request; repeated
7734 patterns can be drawn with the character using the @code{\l} and
7735 @code{\L} escape sequences; words containing the character can be
7736 hyphenated correctly, if the @code{hcode} request is used to give the
7737 character a hyphenation code. There is a special anti-recursion
7738 feature: Use of character within the character's definition is handled
7739 like normal characters not defined with @code{char}.
7742 @cindex removing character definition (@code{rchar})
7743 @cindex character, removing definition (@code{rchar})
7744 @Defreq {rchar, c1 c2 @dots{}}
7745 Remove the definitions of characters @var{c1}, @var{c2},@w{
7746 }@enddots{} This undoes the effect of a @code{char} request.
7748 It is possible to omit the whitespace between arguments.
7751 @xref{Special Characters}.
7753 @c ---------------------------------------------------------------------
7755 @node Special Fonts, Artificial Fonts, Using Symbols, Fonts
7756 @subsection Special Fonts
7757 @cindex special fonts
7758 @cindex fonts, special
7764 @c ---------------------------------------------------------------------
7766 @node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts
7767 @subsection Artificial Fonts
7768 @cindex artificial fonts
7769 @cindex fonts, artificial
7771 There are a number of requests for artificially creating fonts. These
7772 are largely vestiges of the days when output devices did not have a
7773 wide variety of fonts, and when @code{nroff} and @code{troff} were
7774 separate programs. These are no longer necessary in GNU
7775 @code{troff}. Nevertheless, they are supported.
7777 @cindex underlining (@code{ul})
7778 @Defreq {ul, [@Var{lines}]}
7779 The @code{ul} request normally underlines subsequent lines if a tty
7780 output device is used. Otherwise, the lines are printed in italics
7781 (only the term `underlined' is used in the following). The single
7782 argument is the number of input lines to be underlined; with no
7783 argument, the next line is underlined. If @var{lines} is zero or
7784 negative, stop the effects of @code{ul} (if it was active). Requests
7785 and empty lines do not count for computing the number of underlined
7786 input lines, even if they produce some output like @code{tl}. Lines
7787 inserted by macros (e.g.@: invoked by a trap) do count.
7789 At the beginning of @code{ul}, the current font is stored and the
7790 underline font is activated. Within the span of a @code{ul} request,
7791 it is possible to change fonts, but after the last line affected by
7792 @code{ul} the saved font is restored.
7794 This command is associated with the current environment
7795 (@pxref{Environments}). The underline font can be changed with the
7798 @c XXX @xref should be changed to grotty
7800 @xref{Troff and Nroff Mode}, for a discussion how underlining is
7801 implemented in for tty output devices, and which problems can arise.
7803 The @code{ul} request does not underline spaces.
7806 @cindex continuous underlining (@code{cu})
7807 @cindex underlining, continuous (@code{cu})
7808 @Defreq {cu, [@Var{lines}]}
7809 The @code{cu} request is similar to @code{ul} but underlines spaces as
7810 well (if a tty output device is used).
7813 @cindex underline font (@code{uf})
7814 @cindex font for underlining (@code{uf})
7816 Set the underline font (globally) used by @code{ul} and @code{cu}. By
7817 default, this is the font at position@w{ }2. @var{font} can be either
7818 a non-negative font position or the name of a font.
7821 @cindex imitating bold face (@code{bd})
7822 @cindex bold face, imitating (@code{bd})
7823 @DefreqList {bd, font [@Var{offset}]}
7824 @DefreqItem {bd, font1 font2 [@Var{offset}]}
7826 Artificially create a bold font by printing each character twice,
7829 Two syntax forms are available.
7833 Imitate a bold font unconditionally. The first argument specifies the
7834 font to embolden, and the second is the number of basic units, minus
7835 one, by which the two characters is offset. If the second argument is
7836 missing, emboldening is turned off.
7838 @var{font} can be either a non-negative font position or the name of a
7841 @var{offset} is available in the @code{.b} read-only register if a
7842 special font is active; in the @code{bd} request, its default unit is
7845 @cindex @code{fspecial} request, and imitating bold
7847 @cindex embolding of special fonts
7848 @cindex special fonts, emboldening
7850 Imitate a bold form conditionally. Embolden @var{font1} by
7851 @var{offset} only if font @var{font2} is the current font. This
7852 command can be issued repeatedly to set up different emboldening
7853 values for different current fonts. If the second argument is
7854 missing, emboldening is turned off for this particular current font.
7856 This affects special fonts only (either set up with the @code{special}
7857 command in font files or with the @code{fspecial} request).
7861 @cindex constant character space mode (@code{cs})
7862 @cindex mode for constant character space (@code{cs})
7863 @cindex character, constant space
7864 @cindex @code{ps} request, and constant character space mode
7865 @Defreq {cs, font [@Var{width} [@Var{em-size}]]}
7866 Switch to and from constant character space mode. If activated, the
7867 width of every character is @math{@var{width}/36} ems. The em size is
7868 given absolutely by @var{em-size}; if this argument is missing, the em
7869 value is taken from the current font size (as set with the @code{ps}
7870 request) when the font is effectively in use. Without second and
7871 third argument, constant character space mode is deactivated.
7873 Default unit for @var{em-size} is @samp{z}; @var{width} is an integer.
7876 @c ---------------------------------------------------------------------
7878 @node Ligatures and Kerning, , Artificial Fonts, Fonts
7879 @subsection Ligatures and Kerning
7880 @cindex ligatures and kerning
7881 @cindex kerning and ligatures
7883 Ligatures are groups of characters that are run together. For
7884 example, the letters `f' and `i' can form a ligature `fi' as in the
7885 word `file'. This produces a cleaner look (albeit subtle) to the
7886 printed output. Usually, ligatures are not available in fonts for tty
7889 Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T
7890 typesetter that was the target of AT&T @code{troff} also supported
7891 `ff', `ffi', and `ffl' ligatures. Advanced typesetters or `expert'
7892 fonts may include ligatures for `ft' and `ct', although GNU
7893 @code{troff} does not support these (yet).
7895 @cindex activating ligatures (@code{lg})
7896 @cindex ligatures, activating (@code{lg})
7897 @cindex ligatures enabled register (@code{.lg})
7898 @DefreqList {lg, [@Var{flag}]}
7899 @DefregListEnd {.lg}
7900 The ligature mechanism can be switched on or off with the @code{lg}
7901 request; if the parameter is non-zero or missing, ligatures are
7902 enabled, otherwise disabled. Default is on. The current ligature
7903 mode can be found in the read-only number register @code{.lg} (set to
7904 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise).
7906 Setting the ligature mode to@w{ }2 enables the two-character ligatures
7907 (fi, fl, and ff) and disables the three-character ligatures (ffi and
7911 @dfn{Pairwise kerning} is another subtle typesetting mechanism that
7912 modifies the distance between a character pair to improve readability.
7913 In most cases (but not always) the distance is decreased.
7915 For example, compare the combination of the letters `V' and `A'. With
7916 kerning, `VA' is printed. Without kerning it appears as `V@w{}A'.
7918 Typewriter-like fonts and fonts for terminals where all characters
7919 have the same width don't use kerning.
7921 @cindex activating kerning (@code{kern})
7922 @cindex kerning, activating (@code{kern})
7923 @cindex kerning enabled register (@code{.kern})
7924 @DefreqList {kern, [@Var{flag}]}
7925 @DefregListEnd {.kern}
7926 Kerning can be activated with the @code{kern} request. If the
7927 parameter is non-zero or missing, enable pairwise kerning, otherwise
7928 disable it. The read-only number register @code{.kern} is set to@w{
7929 }1 if pairwise kerning is enabled, 0@w{ }otherwise.
7931 @cindex zero width space character (@code{\&})
7932 @cindex character, zero width space (@code{\&})
7933 @cindex space character, zero width (@code{\&})
7934 If the font description file contains pairwise kerning information,
7935 characters from that font are kerned. Kerning between two characters
7936 can be inhibited by placing @code{\&} between them: @samp{V\&A}.
7938 @xref{Font File Format}.
7941 @cindex track kerning
7942 @cindex kerning, track
7943 @dfn{Track kerning} expands or reduces the space between characters.
7944 This can be handy, for example, if you need to squeeze a long word
7945 onto a single line or spread some text to fill a narrow column. It
7946 must be used with great care since it is usually considered bad
7947 typography if the reader notices the effect.
7949 @cindex activating track kerning (@code{tkf})
7950 @cindex track kerning, activating (@code{tkf})
7951 @Defreq {tkf, f s1 n1 s2 n2}
7952 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
7953 }@var{f} the width of every character is increased by an amount
7954 between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if
7955 the current point size is less than or equal to @var{s1} the width is
7956 increased by @var{n1}; if it is greater than or equal to @var{s2} the
7957 width is increased by @var{n2}; if the point size is greater than or
7958 equal to @var{s1} and less than or equal to @var{s2} the increase in
7959 width is a linear function of the point size.
7961 The default unit is @samp{z} for @var{s1} and @var{s2}, @samp{p} for
7962 @var{n1} and @var{n2}.
7965 Sometimes, when typesetting letters of different fonts, more or less
7966 space at such boundaries are needed. There are two escapes to help
7969 @cindex italic correction (@code{\/})
7970 @cindex correction, italic (@code{\/})
7971 @cindex correction between italic and roman character (@code{\/})
7972 @cindex roman character, correction after italic character (@code{\/})
7973 @cindex italic character, correction before roman character (@code{\/})
7975 Increase the width of the preceding character so that the spacing
7976 between that character and the following character is correct if the
7977 following character is a roman character. For example, if an
7978 italic@w{ }@code{f} is immediately followed by a roman right
7979 parenthesis, then in many fonts the top right portion of the@w{ }@code{f}
7980 overlaps the top left of the right parenthesis. Use this escape
7981 sequence whenever an italic character is immediately followed by a
7982 roman character without any intervening space. This small amount of
7983 space is also called @dfn{italic correction}.
7989 @result{} {@it f}@r{)}
7991 @result{} @i{f}@r{)}
7997 @cindex left italic correction (@code{\,})
7998 @cindex correction, left italic (@code{\,})
7999 @cindex roman character, correction before italic character (@code{\,})
8000 @cindex italic character, correction after roman character (@code{\,})
8001 @Defesc {\\\,, , , }
8002 Modify the spacing of the following character so that the spacing
8003 between that character and the preceding character is correct if the
8004 preceding character is a roman character. Use this escape sequence
8005 whenever a roman character is immediately followed by an italic
8006 character without any intervening space. In analogy to above, this
8007 space could be called @dfn{left italic correction}, but this term
8014 @result{} @r{q}@i{f}
8016 @result{} @r{q}@math{@ptexcomma}@i{f}
8023 Insert a zero-width character, which is invisible. Its intended use
8024 is to stop interaction of a character with its surrounding.
8028 It prevents the insertion of extra space after an end-of-sentence
8034 @result{} Test. Test.
8037 @result{} Test. Test.
8041 It prevents interpretation of a control character at the beginning of
8046 @result{} warning: `Test' not defined
8052 It prevents kerning between two characters.
8060 @result{} @r{V@w{}A}
8066 It is needed to map an arbitrary character to nothing in the @code{tr}
8067 request (@pxref{Character Translations}).
8072 @c =====================================================================
8074 @node Sizes, Strings, Fonts, gtroff Reference
8080 @cindex size of type
8081 @cindex vertical spacing
8082 @cindex spacing, vertical
8083 @code{gtroff} uses two dimensions with each line of text, type size
8084 and vertical spacing. The @dfn{type size} is approximately the height
8085 of the tallest character.@footnote{This is usually the parenthesis.
8086 Note that in most cases the real dimensions of the glyphs in a font
8087 are @emph{not} related to its type size! For example, the standard
8088 @sc{PostScript} font families `Times Roman', `Helvetica', and
8089 `Courier' can't be used together at 10@dmn{pt}; to get acceptable
8090 output, the size of `Helvetica' has to be reduced by one point, and
8091 the size of `Courier' must be increased by one point.} @dfn{Vertical
8092 spacing} is the amount of space @code{gtroff} allows for a line of
8093 text; normally, this is about 20%@w{ }larger than the current type
8094 size. Ratios smaller than this can result in hard-to-read text;
8095 larger than this, it spreads the text out more vertically (useful for
8096 term papers). By default, @code{gtroff} uses 10@w{ }point type on
8097 12@w{ }point spacing.
8100 The difference between type size and vertical spacing is known, by
8101 typesetters, as @dfn{leading}.
8104 * Changing Type Sizes::
8105 * Fractional Type Sizes::
8108 @c ---------------------------------------------------------------------
8110 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
8111 @subsection Changing Type Sizes
8113 @cindex changing type sizes (@code{ps}, @code{\s})
8114 @cindex type sizes, changing (@code{ps}, @code{\s})
8115 @cindex point sizes, changing (@code{ps}, @code{\s})
8116 @DefreqList {ps, [@Var{size}]}
8117 @DefreqItem {ps, @t{+}@Var{size}}
8118 @DefreqItem {ps, @t{-}@Var{size}}
8119 @DefescItem {\\s, , size, }
8121 Use the @code{ps} request or the @code{\s} escape to change (increase,
8122 decrease) the type size (in points). Specify @var{size} as either an
8123 absolute point size, or as a relative change from the current size.
8124 The size@w{ }0, or no argument, goes back to the previous size.
8126 Default unit of @code{size} is @samp{z}. If @code{size} is zero or
8127 negative, it is set to 1@dmn{u}.
8129 @cindex type size registers (@code{.s}, @code{.ps})
8130 @cindex point size registers (@code{.s}, @code{.ps})
8131 The read-only number register @code{.s} returns the point size in
8132 points as a decimal fraction. This is a string. To get the point
8133 size in scaled points, use the @code{.ps} register instead.
8135 @code{.s} is associated with the current environment
8136 (@pxref{Environments}).
8143 wink, wink, \s+2nudge, nudge,\s+8 say no more!
8147 The @code{\s} escape may be called in a variety of ways. Much like
8148 other escapes there must be a way to determine where the argument ends
8149 and the text begins. Any of the following forms are valid:
8153 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either
8154 0 or in the range 4 to@w{ }39.
8158 Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{
8159 }must be exactly one digit.
8162 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly
8169 Increase or decrease the point size by @var{nn}@w{ }points. @var{nn}
8170 must be exactly two digits.
8173 @xref{Fractional Type Sizes}, for yet another syntactical form of
8174 using the @code{\s} escape.
8176 Some devices may only have certain permissible sizes, in which case
8177 @code{gtroff} rounds to the nearest permissible size.
8180 @cindex changing vertical spacing (@code{vs})
8181 @cindex vertical spacing, changing (@code{vs})
8182 @cindex vertical spacing register (@code{.v})
8183 @DefreqList {vs, [@Var{space}]}
8184 @DefreqItem {vs, @t{+}@Var{space}}
8185 @DefreqItem {vs, @t{-}@Var{space}}
8187 Change (increase, decrease) the vertical spacing by @var{space}. The
8188 default unit is @samp{p}.
8190 If @code{vs} is called without an argument, the vertical spacing is
8191 reset to the previous value before the last call to @code{vs}.
8193 @cindex @code{.V} register, and @code{vs}
8194 @code{gtroff} creates a warning of type @samp{range} if @var{space} is
8195 zero or negative; the vertical spacing is then set to the vertical
8196 resolution (as given in the @code{.V} register).
8198 The read-only number register @code{.v} contains the current vertical
8199 spacing; it is associated with the current environment
8200 (@pxref{Environments}).
8207 ... .sz macro example?? ...
8211 @c ---------------------------------------------------------------------
8213 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
8214 @subsection Fractional Type Sizes
8215 @cindex fractional type sizes
8216 @cindex type sizes, fractional
8218 @cindex @code{s} unit
8219 @cindex unit, @code{s}
8220 @cindex @code{z} unit
8221 @cindex unit, @code{z}
8222 @cindex @code{ps} request, with fractional type sizes
8223 @cindex @code{cs} request, with fractional type sizes
8224 @cindex @code{tkf} request, with fractional type sizes
8225 @cindex @code{\H}, with fractional type sizes
8226 @cindex @code{\s}, with fractional type sizes
8227 A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points,
8228 where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by
8229 default). There is a new scale indicator @samp{z} which has the
8230 effect of multiplying by @var{sizescale}. Requests and escape
8231 sequences in @code{gtroff} interpret arguments that represent a point
8232 size as being in units of scaled points, but they evaluate each such
8233 argument using a default scale indicator of @samp{z}. Arguments
8234 treated in this way are the argument to the @code{ps} request, the
8235 third argument to the @code{cs} request, the second and fourth
8236 arguments to the @code{tkf} request, the argument to the @code{\H}
8237 escape sequence, and those variants of the @code{\s} escape sequence
8238 that take a numeric expression as their argument (see below).
8240 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
8241 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
8242 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
8243 10250@w{ }scaled points, which is equal to 10.25@w{ }points.
8245 @code{gtroff} disallows the use of the @samp{z} scale indicator in
8246 instances where it would make no sense, such as a numeric
8247 expression whose default scale indicator was neither @samp{u} nor
8248 @samp{z}. Similarly it would make
8249 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
8250 numeric expression whose default scale indicator was @samp{z}, and so
8251 @code{gtroff} disallows this as well.
8253 There is also new scale indicator @samp{s} which multiplies by the
8254 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
8255 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
8259 A read-only number register returning the point size in scaled points.
8261 @code{.ps} is associated with the current environment
8262 (@pxref{Environments}).
8265 @cindex last-requested point size registers (@code{.psr}, @code{.sr})
8266 @cindex point size registers, last-requested (@code{.psr}, @code{.sr})
8267 @cindex @code{.ps} register, in comparison with @code{.psr}
8268 @cindex @code{.s} register, in comparison with @code{.sr}
8270 @DefregListEnd {.sr}
8271 The last-requested point size in scaled points is contained in the
8272 @code{.psr} read-only number register. The last requested point size
8273 in points as a decimal fraction can be found in @code{.sr}. This is a
8274 string-valued read-only number register.
8276 Note that the requested point sizes are device-independent, whereas
8277 the values returned by the @code{.ps} and @code{.s} registers are not.
8278 For example, if a point size of 11@dmn{pt} is requested for a DVI
8279 device, 10.95@dmn{pt} are actually used (as specified in the
8282 Both registers are associated with the current environment
8283 (@pxref{Environments}).
8286 The @code{\s} escape has the following syntax for working with
8287 fractional type sizes:
8292 Set the point size to @var{n}@w{ }scaled points; @var{n}@w{ }is a numeric
8293 expression with a default scale indicator of @samp{z}.
8303 Increase or or decrease the point size by @var{n}@w{ }scaled points;
8304 @var{n}@w{ }is a numeric expression with a default scale indicator of
8311 @c =====================================================================
8313 @node Strings, Conditionals and Loops, Sizes, gtroff Reference
8317 @code{gtroff} has string variables, which are entirely for user
8318 convenience (i.e.@: there are no built-in strings exept @code{.T}, but
8319 even this is a read-write string variable).
8321 @cindex string interpolation (@code{\*})
8322 @cindex string expansion (@code{\*})
8323 @cindex interpolation of strings (@code{\*})
8324 @cindex expansion of strings (@code{\*})
8325 @DefreqList {ds, name [@Var{string}]}
8326 @DefescItem {\\*, , n, }
8327 @DefescItem {\\*, @lparen{}, nm, }
8328 @DefescListEnd {\\*, @lbrack{}, name, @rbrack{}}
8329 Define and access a string variable @var{name} (one-character name@w{
8330 }@var{n}, two-character name @var{nm}). If @var{name} already exists,
8331 @code{ds} overwrites the previous definition.
8336 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
8338 The \*(UX Operating System
8341 The @code{\*} escape @dfn{interpolates} (expands in-place) a
8342 previously-defined string variable. To be more precise, the stored
8343 string is pushed onto the input stack which is then parsed by
8344 @code{gtroff}. Similar to number registers, it is possible to nest
8345 strings, i.e. a string variables can be called within string
8348 If the string named by the @code{\*} does not exist, it is defined as
8349 empty, and a warning of type @samp{mac} is emitted (see
8350 @ref{Debugging}, for more details).
8352 @cindex comments, with @code{ds}
8353 @cindex @code{ds} request, and comments
8354 @strong{Caution:} Unlike other requests, the second argument to the
8355 @code{ds} request takes up the entire line including trailing spaces.
8356 This means that comments on a line with such a request can introduce
8357 unwanted space into a string.
8360 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
8364 Instead the comment should be put on another line or have the comment
8365 escape adjacent with the end of the string.
8368 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
8371 @cindex trailing quotes
8372 @cindex quotes, trailing
8373 @cindex leading spaces with @code{ds}
8374 @cindex spaces with @code{ds}
8375 @cindex @code{ds} request, and leading spaces
8376 To produce leading space the string can be started with a double
8377 quote. No trailing quote is needed; in fact, any trailing quote is
8378 included in your string.
8381 .ds sign " Yours in a white wine sauce,
8384 @cindex multi-line strings
8385 @cindex strings, multi-line
8386 @cindex newline character in strings, escaping
8387 @cindex escaping newline characters in strings
8388 Strings are not limited to a single line of text. A string can span
8389 several lines by escaping the newlines with a backslash. The
8390 resulting string is stored @emph{without} the newlines.
8393 .ds foo lots and lots \
8394 of text are on these \
8398 It is not possible to have real newlines in a string.
8400 @cindex name space of macros and strings
8401 @cindex macros, shared name space with strings
8402 @cindex strings, shared name space with macros
8403 Strings, macros, and diversions (and boxes) share the same name space.
8404 Internally, even the same mechanism is used to store them. This has
8405 some interesting consequences. For example, it is possible to call a
8406 macro with string syntax and vice versa.
8413 @result{} This is a funny test.
8415 .ds yyy a funny test
8418 @result{} This is a funny test.
8421 Diversions and boxes can be also called with string syntax. It is not
8422 possible to pass arguments to a macro if called with @code{\*}.
8424 Another consequence is that you can copy one-line diversions or boxes
8432 .ds yyy This is \*[xxx]\c
8434 @result{} @r{This is a }@i{test}.
8438 As the previous example shows, it is possible to store formatted
8439 output in strings. The @code{\c} escape prevents the insertion of an
8440 additional blank line in the output.
8442 Copying diversions longer than a single output line produces
8452 .ds yyy This is \*[xxx]\c
8454 @result{} test This is a funny.
8457 Usually, it is not predictable whether a diversion contains one or
8458 more output lines, so this mechanism should be avoided. With
8459 @acronym{UNIX} @code{troff}, this was the only solution to strip off a
8460 final newline from a diversion. Another disadvantage is that the
8461 spaces in the copied string are already formatted, making them
8462 unstretchable. This can cause ugly results.
8464 @cindex stripping final newline in diversions
8465 @cindex diversions, stripping final newline
8466 @cindex final newline, stripping in diversions
8467 @cindex newline, final, stripping in diversions
8468 @cindex horizontal space, unformatting
8469 @cindex space, horizontal, unformatting
8470 @cindex unformatting horizontal space
8471 A clean solution to this problem is available in GNU @code{troff},
8472 using the requests @code{chop} to remove the final newline of a
8473 diversion, and @code{unformat} to make the horizontal spaces
8486 @result{} This is a funny test.
8489 @xref{Gtroff Internals}, for more information.
8492 @cindex appending to strings (@code{as})
8493 @cindex strings, appending (@code{as})
8494 @Defreq {as, name [@Var{string}]}
8495 The @code{as} request is similar to @code{ds} but appends @var{string}
8496 to the string stored as @var{name} instead of redefining it. If
8497 @var{name} doesn't exist yet, it is created.
8500 .as sign " with shallots, onions and garlic,
8504 Rudimentary string manipulation routines are given with the next two
8507 @cindex substring (@code{substring})
8508 @Defreq {substring, str n1 [@Var{n2}]}
8509 Replace the string in register@w{ }@var{str} with the substring
8510 defined by the indices @var{n1} and@w{ }@var{n2}. The first character
8511 in the string has index one. If @var{n2} is omitted, it is taken to
8512 be equal to the string's length. If the index value @var{n1} or
8513 @var{n2} is negative or zero, it is counted from the end of the
8514 string, going backwards: The last character has index@w{ }0, the
8515 character before the last character has index@w{ }@minus{}1, etc.
8525 @cindex length of a string (@code{length})
8526 @cindex string, length of (@code{length})
8527 @Defreq {length, reg str}
8528 Compute the length of @var{str} and returns it in the number
8529 register@w{ }@var{reg}. If @var{reg} doesn't exist, it is created.
8539 @cindex rename request (@code{rn})
8540 @cindex rename macro (@code{rn})
8541 @cindex rename string (@code{rn})
8543 Rename the request, macro, or string @var{xx} to @var{yy}.
8546 @cindex remove request (@code{rm})
8547 @cindex remove macro (@code{rm})
8548 @cindex remove string (@code{rm})
8550 Remove the request, macro, or string @var{xx}. @code{gtroff} treats
8551 subsequent invocations as if the object had never been defined.
8554 @cindex alias, creating (@code{als})
8555 @cindex creating alias (@code{als})
8556 @Defreq {als, new old}
8557 Create an alias named @var{new} for the request, string, macro, or
8558 diversion object named @var{old}. The new name and the old name are
8559 exactly equivalent (it is similar to a hard rather than a soft
8560 link). If @var{old} is undefined, @code{gtroff} generates a warning of
8561 type @samp{mac} and ignores the request.
8565 Remove (chop) the last character from the macro, string, or diversion
8566 named @var{xx}. This is useful for removing the newline from the end
8567 of diversions that are to be interpolated as strings. This command
8568 can be used repeatedly; see @ref{Gtroff Internals}, for details on
8569 nodes inserted by @code{gtroff} automatically.
8572 @xref{Identifiers}, and @ref{Comments}.
8575 @c =====================================================================
8577 @node Conditionals and Loops, Writing Macros, Strings, gtroff Reference
8578 @section Conditionals and Loops
8579 @cindex conditionals and loops
8580 @cindex loops and conditionals
8583 * Operators in Conditionals::
8588 @c ---------------------------------------------------------------------
8590 @node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops
8591 @subsection Operators in Conditionals
8593 @cindex @code{if} request, operators to use with it
8594 @cindex @code{while} request, operators to use with it
8595 In @code{if} and @code{while} requests, there are several more
8596 operators available:
8601 True if the current page is even or odd numbered (respectively).
8604 True if the document is being processed in nroff mode (i.e., the
8605 @code{.nroff} command has been issued).
8608 True if the document is being processed in troff mode (i.e., the
8609 @code{.troff} command has been issued).
8614 @item '@var{xxx}'@var{yyy}'
8615 True if the string @var{xxx} is equal to the string @var{yyy}. Other
8616 characters can be used in place of the single quotes; the same set of
8617 delimiters as for the @code{\D} escape is used (@pxref{Escapes}).
8618 @code{gtroff} formats the strings before being compared:
8629 The resulting motions, character sizes, and fonts have to
8630 match,@footnote{The created output nodes must be identical.
8631 @xref{Gtroff Internals}.} and not the individual motion, size, and
8632 font requests. In the previous example, @samp{|} and @samp{\fR|\fP}
8633 both result in a roman @samp{|} character with the same point size and
8634 at the same location on the page, so the strings are equal. If
8635 @samp{.ft@w{ }I} had been added before the @samp{.ie}, the result
8636 would be ``false'' because (the first) @samp{|} produces an italic
8637 @samp{|} rather than a roman one.
8640 True if there is a number register named @var{xxx}.
8643 True if there is a string, macro, diversion, or request named @var{xxx}.
8646 True if there is a color named @var{xxx}.
8649 True if there is a character @var{ch} available; @var{ch} is either an
8650 @acronym{ASCII} character or a special character (@code{\(@var{ch}} or
8651 @code{\[@var{ch}]}); the condition is also true if @var{ch} has been
8652 defined by the @code{char} request.
8655 Note that these operators can't be combined with other operators like
8656 @samp{:} or @samp{&}; only a leading @samp{!} (without whitespace
8657 between the exclamation mark and the operator) can be used to negate
8669 A whitespace after @samp{!} always evaluates to zero (this bizarre
8670 behaviour is due to compatibility with @acronym{UNIX} @code{troff}).
8678 @result{} r xxx true
8681 It is possible to omit the whitespace before the argument to the
8682 @samp{r}, @samp{d}, and @samp{c} operators.
8686 @c ---------------------------------------------------------------------
8688 @node if-else, while, Operators in Conditionals, Conditionals and Loops
8692 @code{gtroff} has if-then-else constructs like other languages, although
8693 the formatting can be painful.
8695 @Defreq {if, expr anything}
8696 Evaluate the expression @var{expr}, and executes @var{anything} (the
8697 remainder of the line) if @var{expr} evaluates to non-zero (true).
8698 @var{anything} is interpreted as though it was on a line by itself
8699 (except that leading spaces are swallowed). @xref{Expressions}, for
8705 .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
8712 @DefreqList {ie, expr anything}
8713 @DefreqListEnd {el, anything}
8714 Use the @code{ie} and @code{el} requests to write an if-then-else.
8715 The first request is the `if' part and the latter is the `else' part.
8718 .ie n .ls 2 \" double spacing in nroff
8719 .el .ls 1 \" single spacing in troff
8723 @c this is a bug in makeinfo: you can't have `@{' as an argument
8726 @cindex begin of conditional block (@code{\@{})
8727 @cindex end of conditional block (@code{\@}})
8728 @cindex conditional block, begin (@code{\@{})
8729 @cindex conditional block, end (@code{\@}})
8730 @cindex block, conditional, begin (@code{\@{})
8731 @cindex block, condititional, end (@code{\@}})
8732 @c @DefescList {\\@@@{, , , }
8733 @c @DefescListEnd {\\@@@}, , , }
8734 In many cases, an if (or if-else) construct needs to execute more than
8735 one request. This can be done using the @code{\@{} and @code{\@}}
8736 escapes. The following example shows the possible ways to use these
8737 escapes (note the position of the opening and closing braces).
8753 @c ---------------------------------------------------------------------
8755 @node while, , if-else, Conditionals and Loops
8759 @code{gtroff} provides a looping construct using the @code{while}
8760 request, which is used much like the @code{if} (and related) requests.
8762 @Defreq {while, expr anything}
8763 Evaluate the expression @var{expr}, and repeatedly execute
8764 @var{anything} (the remainder of the line) until @var{expr} evaluates
8769 .while (\na < 9) \@{\
8773 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
8778 @cindex @code{de} request, and @code{while}
8781 The body of a @code{while} request is treated like the body of a
8782 @code{de} request: @code{gtroff} temporarily stores it in a macro
8783 which is deleted after the loop has been exited. It can considerably
8784 slow down a macro if the body of the @code{while} request (within the
8785 macro) is large. Each time the macro is executed, the @code{while}
8786 body is parsed and stored again as a temporary macro.
8791 . while (\\n[num] > 0) \@{\
8792 . \" many lines of code
8798 @cindex recursive macros
8799 @cindex macros, recursive
8801 The traditional and ofter better solution (@acronym{UNIX} @code{troff}
8802 doesn't have the @code{while} request) is to use a recursive macro
8803 instead which is parsed only once during its definition.
8807 . if (\\n[num] > 0) \@{\
8808 . \" many lines of code
8821 Note that the number of available recursion levels is set to@w{ }1000
8822 (this is a compile-time constant value of @code{gtroff}).
8825 The closing brace of a @code{while} body must end a line.
8830 . while (\n[a] < 10) \@{\
8833 @result{} unbalanced \@{ \@}
8838 @cindex @code{while} request, confusing with @code{br}
8839 @cindex @code{break} request, in a @code{while} loop
8840 @cindex @code{continue} request, in a @code{while} loop
8842 Break out of a @code{while} loop. Be sure not to confuse this with
8843 the @code{br} request (causing a line break).
8846 @Defreq {continue, }
8847 Finishes the current iteration of a @code{while} loop, immediately
8848 restarting the next iteration.
8854 @c =====================================================================
8856 @node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference
8857 @section Writing Macros
8858 @cindex writing macros
8859 @cindex macros, writing
8861 A @dfn{macro} is a collection of text and embedded commands which can
8862 be invoked multiple times. Use macros to define common operations.
8864 @Defreq {de, name [@Var{end}]}
8865 Define a new macro named @var{name}. @code{gtroff} copies subsequent
8866 lines (starting with the next one) into an internal buffer until it
8867 encounters the line @samp{..} (two dots). The optional second
8868 argument to @code{de} changes this to a macro to @samp{.@var{end}}.
8870 There can be whitespace after the first dot in the line containing the
8871 ending token (either @samp{.} or macro @samp{@var{end}}).
8873 Here a small example macro called @samp{P} which causes a break and
8874 inserts some vertical space. It could be used to separate paragraphs.
8883 @c XXX add info about macro definitions in macros.
8885 @c XXX give example for end macro.
8887 @c XXX add info about indirect macro calls:
8893 @c test \*[xxx] test
8894 @c => test from yyy test
8896 @c XXX info about common identifier pool for strings, macros, and
8900 @cindex appending, to a macro (@code{am})
8901 @cindex macro appending (@code{am})
8903 Works similarly to @code{de} except it appends onto the macro named
8904 @var{xx}. So, to make the previously defined @samp{P} macro actually
8905 do indented instead of block paragraphs, add the necessary code to the
8906 existing macro like this:
8915 @cindex alias, creating (@code{als})
8916 @cindex creating alias (@code{als})
8917 @xref{Strings}, for the @code{als} request to rename a macro.
8919 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and
8920 @code{as} requests only create a new object if the name of the macro,
8921 diversion or string diversion is currently undefined or if it is
8922 defined to be a request; normally they modify the value of an existing
8930 @c ---------------------------------------------------------------------
8932 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
8933 @subsection Copy-in Mode
8934 @cindex copy-in mode
8935 @cindex mode, copy-in
8937 @cindex @code{\n}, when reading text for a macro
8938 @cindex @code{\$}, when reading text for a macro
8939 @cindex @code{\*}, when reading text for a macro
8940 @cindex @code{\\}, when reading text for a macro
8941 @cindex \@key{RET}, when reading text for a macro
8942 When @code{gtroff} reads in the text for a macro or diversion, it copies
8943 the text (including request lines, but excluding escapes) into an
8944 internal buffer. Escapes are converted into an internal form,
8945 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
8946 @code{\@key{RET}} which are evaluated and inserted into the text where
8947 the escape was located. This is known as @dfn{copy-in} mode or
8950 What this means is that you can specify when these escapes are to be
8951 evaluated (either at copy-in time or at the time of use) by insulating
8952 the escapes with an extra backslash. Compare this to the @code{\def}
8953 and @code{\edef} commands in @TeX{}.
8955 The following example prints the numbers 20 and@w{ }10:
8967 @c ---------------------------------------------------------------------
8969 @node Parameters, , Copy-in Mode, Writing Macros
8970 @subsection Parameters
8973 @cindex number of arguments register (@code{.$})
8975 The arguments to a macro can be examined using a variety of escapes.
8976 The number of arguments is available in the @code{.$} number register.
8977 Any individual argument can be retrieved with one of the following
8980 @cindex copy-in mode, and macro arguments
8981 @cindex macro arguments (@code{\$})
8982 @cindex arguments, macro (@code{\$})
8983 @DefescList {\\$, n, , }
8984 @DefescItem {\\$, @lparen{}, nn, }
8985 @DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}}
8986 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
8987 @code{\$[@var{nnn}]} retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or
8988 @var{nnn}@dmn{th} argument. As usual, the first form only accepts a
8989 single number (larger than zero), the second a two-digit number (larger
8990 or equal to@w{ }10), and the third any positive integer value (larger
8991 than zero). Macros can have an unlimited number of arguments. Note
8992 that due to copy-in mode, use two backslashes on these in actual use to
8993 prevent interpolation until the macro is actually invoked.
8996 @Defreq {shift, [@Var{n}]}
8997 Shifts the arguments 1@w{ }position, or as
8998 many positions as specified by its argument. After executing this
8999 request, argument@w{ }@var{i} becomes argument @var{i}-@var{n};
9000 arguments 1 to@w{ }@var{n} are no longer available. Shifting by
9001 negative amounts is currently undefined.
9004 @DefescList {\\$*, , , }
9005 @DefescListEnd {\\$@@, , , }
9006 In some cases it is convenient to use all of the arguments at once (for
9007 example, to pass the arguments along to another macro). The @code{\$*}
9008 escape concatenates all the arguments separated by spaces. A
9009 similar escape is @code{\$@@}, which concatenates all the
9010 arguments with each surrounded by double quotes, and separated by
9014 @cindex macro name register (@code{\$0})
9015 @cindex @code{als} request, and @code{\$0}
9016 @cindex @code{als} request, use with @code{\$0}
9017 @Defesc {\\$0, , , }
9018 The name used to invoke the current macro.
9019 The @code{als} request can make a macro have more than one name.
9023 .ie \\n(.$=1 .ds Vl Pre-Release Version
9024 .el .ds Vl Version \\$3, \\$4.
9029 This would be called as
9036 @xref{Request Arguments}.
9039 @c =====================================================================
9041 @node Page Motions, Drawing Requests, Writing Macros, gtroff Reference
9042 @section Page Motions
9043 @cindex page motions
9044 @cindex motions, page
9046 @xref{Manipulating Spacing}, for a discussion of the main request for
9047 vertical motion, @code{sp}.
9049 @cindex marking page location (@code{mk})
9050 @cindex page location, marking (@code{mk})
9051 @cindex location, page, marking (@code{mk})
9052 @cindex returning to marked page location (@code{rt})
9053 @cindex page location, returning to marked (@code{rt})
9054 @cindex location, page, returning to marked (@code{rt})
9055 @DefreqList {mk, [@Var{reg}]}
9056 @DefreqListEnd {rt, [@Var{dist}]}
9057 The request @code{mk} can be used to mark a location on a page, for
9058 movement to later. This request takes a register name as an argument
9059 in which to store the current page location. With no argument it
9060 stores the location in an internal register. The results of this can
9061 be used later by the @code{rt} or the @code{sp} request (or the
9064 The @code{rt} request returns @emph{upwards} to the location marked
9065 with the last @code{mk} request. If used with an argument, return to
9066 a position which distance from the top of the page is @var{dist} (no
9067 previous call to @code{mk} is necessary in this case).
9072 ... dual column example ...
9077 The following escapes give fine control of movements about the page.
9079 @cindex vertical motion (@code{\v})
9080 @cindex motion, vertical (@code{\v})
9081 @Defesc {\\v, ', e, '}
9082 The @code{\v'@var{e}'} escape enables arbitrary vertical motion from the
9083 current location on the page. The argument@w{ }@var{e} specifies the
9084 distance to move; positive is downwards and negative upwards. The
9085 default unit for this escape @samp{v}. Beware, however, that
9086 @code{gtroff} continues text processing at the point where the motion
9087 ends, so you should always balance motions to avoid interference with
9090 @code{\v} doesn't trigger a trap. This can be quite useful; for example,
9091 consider a page bottom trap macro which prints a marker in the margin to
9092 indicate continuation of a footnote or something similar.
9095 There are some special case escapes for vertical motion.
9099 move upwards@w{ }1@dmn{v}.
9102 move upwards@w{ }.5@dmn{v}.
9105 move down@w{ }.5@dmn{v}.
9108 @cindex inserting horizontal space (@code{\h})
9109 @cindex horizontal space (@code{\h})
9110 @cindex space, horizontal (@code{\h})
9111 @Defesc {\\h, ', e, '}
9112 The @code{\h'@var{e}'} escape provides horizontal motions. The
9113 expression@w{ }@var{e} indicates how far to move: positive is rightwards
9114 and negative leftwards.
9115 @c XXX Is there a default unit for this?
9118 There are a number of special case escapes for horizontal motion:
9122 An unbreakable and unpaddable (i.e.@: not expanded during filling)
9123 space. (Note: This is a backslash followed by a space.)
9126 An unbreakable space that stretches like a normal inter-word space
9127 when a line is adjusted.
9130 A 1/6@dmn{th} em space. Ignored for tty output devices (rounded to
9134 A 1/12@dmn{th} em space. Ignored for tty output devices (rounded to
9138 A space the size of a digit.
9141 @cindex zero width space character (@code{\&})
9142 @cindex character, zero width space (@code{\&})
9143 @cindex space character, zero width (@code{\&})
9147 Like @code{\&} except that it behaves like a character declared with
9148 the @code{cflags} request to be transparent for the purposes of
9149 end-of-sentence recognition.
9152 The following string sets the @TeX{} logo:
9155 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
9158 @cindex width escape (@code{\w})
9159 @cindex escape, width (@code{\w})
9160 @Defesc {\\w, ', text, '}
9161 Used as @code{\w'@var{text}'},
9162 returns the width of the specified @var{text} in basic units.
9163 This allows horizontal movement based on the width of some
9164 arbitrary text (e.g.@: given as an argument to a macro).
9170 ... strlen example ...
9174 Font changes may occur in @var{text} which don't affect current
9177 After use, @code{\w} sets several registers:
9184 The highest and lowest point, respectively, in @var{text}.
9190 Like the @code{st} and @code{sb} registers, but takes account of the
9191 heights and depths of characters.
9195 Defines the kinds of characters occurring in @var{text}:
9199 only short characters, no descenders or tall characters.
9202 at least one descender.
9205 at least one tall character.
9208 at least one each of a descender and a tall character.
9213 The amount of horizontal space (possibly negative) that should be added
9214 to the last character before a subscript.
9218 How far to right of the center of the last character in the @code{\w}
9219 argument, the center of an accent from a roman font should be placed
9220 over that character.
9224 @Defesc {\\k, ', x, '}
9225 Stores the current horizontal position in register@w{ }@var{x}.
9226 Use this, for example, to return to the beginning of a string
9227 for highlighting or other decoration.
9231 A read-only number register containing the current horizontal output
9235 @c XXX documentation
9238 @c =====================================================================
9240 @node Drawing Requests, Traps, Page Motions, gtroff Reference
9241 @section Drawing Requests
9242 @cindex drawing requests
9243 @cindex requests for drawing
9245 @code{gtroff} provides a number of ways to draw lines and other figures
9246 on the page. Used in combination with the page motion commands (see
9247 @ref{Page Motions}, for more info), a wide variety of figures can be
9248 drawn. However, for complex drawings these operations can be quite
9249 cumbersome, and it may be wise to use graphic preprocessors like
9250 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
9253 All drawing is done via escapes.
9255 @cindex drawing horizontal lines (@code{\l})
9256 @cindex horizontal line, drawing (@code{\l})
9257 @cindex line, horizontal, drawing (@code{\l})
9258 @Defesc {\\l, ', l c, '}
9259 Draws a line rightwards from the current
9260 location. The full syntax for this escape is:
9267 where @var{l} is the length of the line to be drawn, starting at the
9268 current location; positive numbers draw to the right, and negative
9269 numbers draw towards the left. This can also be specified absolutely
9270 (i.e.@: with a leading @samp{|}) which draws back to the beginning
9273 @cindex underscore character
9274 @cindex character, underscore
9275 @cindex line drawing character
9276 @cindex character for line drawing
9277 The optional second parameter@w{ }@var{c} is a character to draw the line
9278 with. If this second argument is not specified, @code{gtroff} uses
9279 the underscore character.
9281 @cindex zero width space character (@code{\&})
9282 @cindex character, zero width space (@code{\&})
9283 @cindex space character, zero width (@code{\&})
9284 To separate the two arguments (to prevent @code{gtroff} from
9285 interpreting a drawing character as a scaling indicator) use @code{\&}.
9287 Here a small useful example:
9291 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
9295 @cindex @code{|}, used as a box rule
9297 Note that this works by outputting a box rule (a vertical line), then
9298 the text given as an argument and then another box rule. Then the line
9299 drawing escapes both draw from the current location to the beginning of
9300 the @emph{input} line.
9303 @cindex drawing vertical lines (@code{\L})
9304 @cindex vertical line drawing (@code{\L})
9305 @cindex line, vertical, drawing (@code{\L})
9306 @cindex line drawing character
9307 @cindex character for line drawing
9308 @cindex box rule character
9309 @cindex character, box rule
9310 @Defesc {\\L, ', l c, '}
9311 Draws vertical lines. Its parameters are
9312 similar to the @code{\l} escape. The
9313 movement is downwards for positive values,
9314 and upwards for negative values. The
9315 default character is the box rule character. As with the vertical
9316 motion escapes, text processing blindly continues where the line
9328 @Defesc {\\D, ', command arg @dots{}, '}
9329 The @code{\D} escape provides a variety of drawing functions.
9330 Note that on character devices, only vertical and horizontal lines are
9331 supported within @code{grotty}.
9334 @item \D'l @var{dx} @var{dy}'
9335 Draw a line from the current location to the relative point specified by
9336 (@var{dx},@var{dy}).
9342 ...revised box macro...
9347 @cindex circle drawing (@code{\D})
9348 @cindex drawing a circle (@code{\D})
9349 Draw a circle with a diameter of@w{ }@var{d} with the leftmost point at the
9353 Draw a solid circle with the same parameters as an outlined circle.
9355 @item \D'e @var{dx} @var{dy}'
9356 @cindex drawing an ellipse (@code{\D})
9357 @cindex ellipse drawing (@code{\D})
9358 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
9359 diameter of @var{dy} with the leftmost point at the current position.
9361 @item \D'E @var{dx} @var{dy}'
9362 Draw a solid ellipse with the same parameters as an outlined ellipse.
9364 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
9365 @cindex arc drawing (@code{\D})
9366 @cindex drawing an arc (@code{\D})
9367 Draw an arc clockwise from the current location through the two
9368 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
9370 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
9371 @cindex drawing a spline (@code{\D})
9372 @cindex spline drawing (@code{\D})
9373 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
9374 then to (@var{dx2},@var{dy2}), and so on.
9377 @cindex gray shading (@code{\D})
9378 @cindex shading (@code{\D})
9379 @cindex shades for filling objects (@code{\D})
9380 Set the shade of gray to be used for filling solid objects to@w{
9381 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
9382 corresponds solid white and 1000 to solid black, and values in between
9383 correspond to intermediate shades of gray. This applies only to solid
9384 circles, solid ellipses and solid polygons. By default, a level of@w{
9387 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
9388 @cindex drawing a polygon (@code{\D})
9389 @cindex polygon drawing (@code{\D})
9390 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
9391 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
9392 are exhausted, a line is drawn back to the starting point.
9398 ... box example (yes, again)...
9402 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
9403 Draw a solid polygon with the same parameters as an outlined polygon.
9409 ... shaded box example ...
9414 @cindex line thickness (@code{\D})
9415 @cindex thickness of lines (@code{\D})
9416 Set the current line thickness to @var{n}@w{ }machine units. A value of
9417 zero selects the smallest available line thickness. A negative value
9418 makes the line thickness proportional to the current point size (this is
9419 the default behaviour of @code{ditroff}).
9423 @cindex pile, character (@code{\b})
9424 @cindex character pile (@code{\b})
9425 @cindex stacking characters (@code{\b})
9426 @Defesc {\\b, ', string, '}
9427 @dfn{Piles} a sequence of characters
9428 vertically, and centers it vertically on the current line. Use it
9429 to build large brackets and braces.
9432 \b'\(lt\(bv\(lk\(bv\(lb'
9436 @xref{Drawing Functions}.
9439 @c =====================================================================
9441 @node Traps, Diversions, Drawing Requests, gtroff Reference
9445 @dfn{Traps} are locations, which, when reached, call a specified
9446 macro. These traps can occur at a given location on the page, at a
9447 given location in the current diversion, after a certain number of input
9448 lines or at the end of input.
9451 * Page Location Traps::
9453 * Input Line Traps::
9454 * End-of-input Traps::
9457 @c ---------------------------------------------------------------------
9459 @node Page Location Traps, Diversion Traps, Traps, Traps
9460 @subsection Page Location Traps
9461 @cindex page location traps
9462 @cindex traps, page location
9464 @dfn{Page location traps} perform an action when @code{gtroff}
9465 reaches a certain vertical location on the page. Page location
9466 traps have a variety of purposes, including:
9470 setting headers and footers
9473 setting body text in multiple columns
9479 @cindex enabling vertical position traps (@code{vpt})
9480 @cindex vertical position traps, enabling (@code{vpt})
9481 @cindex vertical position trap enable register (@code{.vpt})
9482 @DefreqList {vpt, flag}
9483 @DefregListEnd {.vpt}
9484 Enables vertical position traps if @var{flag} is non-zero, or disables
9485 them otherwise. Vertical position traps are traps set by the @code{wh}
9486 or @code{dt} requests. Traps set by the @code{it} request are not
9487 vertical position traps. The parameter that controls whether vertical
9488 position traps are enabled is global. Initially vertical position traps
9489 are enabled. The current setting of this is available in the
9490 @code{.vpt} read-only number register.
9493 @Defreq {wh, dist macro}
9494 Sets a page location trap. Positive values for @var{dist} set
9495 the trap relative to the top of the page; negative values set
9496 the trap relative to the bottom of the page.
9498 @var{macro} is the name of the macro to execute when the
9501 @cindex page headers
9502 @cindex page footers
9505 The following is a simple example of how many macro packages
9506 set headers and footers.
9509 .de hd \" Page header
9514 .de fo \" Page footer
9519 .wh 0 hd \" trap at top of the page
9520 .wh -1i fo \" trap one inch from bottom
9524 @cindex distance to next trap register (@code{.t})
9525 @cindex trap, distance, register (@code{.t})
9527 A read-only number register holding the distance to the next trap.
9530 @cindex changing trap location (@code{ch})
9531 @cindex trap, changing location (@code{ch})
9532 @Defreq {ch, dist macro}
9533 Changes the location of a trap.
9534 The first argument is the name of the macro to be invoked at
9535 the trap, and the second argument is the new location for the trap
9536 (note that the parameters are specified the opposite of the @code{.wh} request).
9537 This is useful for building up footnotes in a diversion to allow more
9538 space at the bottom of the page for them.
9544 ... (simplified) footnote example ...
9550 The read-only number register @code{.ne} contains the amount of space
9551 that was needed in the last @code{ne} request that caused a trap to be
9552 sprung. Useful in conjunction with the @code{.trunc} register.
9553 @xref{Page Control}, for more information.
9556 @cindex @code{ne} request, and the @code{.trunc} register
9557 @cindex truncated vertical space register (@code{.trunc})
9559 A read-only register containing the amount of vertical space truncated
9560 by the most recently sprung vertical position trap, or, if the trap was
9561 sprung by an @code{ne} request, minus the amount of vertical motion
9562 produced by the @code{ne} request. In other words, at the point a trap
9563 is sprung, it represents the difference of what the vertical position
9564 would have been but for the trap, and what the vertical position
9568 @c ---------------------------------------------------------------------
9570 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
9571 @subsection Diversion Traps
9572 @cindex diversion traps
9573 @cindex traps, diversion
9575 @cindex @code{.t} register, and diversions
9576 @cindex setting diversion trap (@code{dt})
9577 @cindex diversion trap, setting (@code{dt})
9578 @cindex trap, diversion, setting (@code{dt})
9579 @Defreq {dt, dist macro}
9580 Sets a trap @emph{within} a diversion.
9581 @var{dist} is the first argument is the location of the trap
9582 (identical to the @code{.wh} request)
9583 and @var{macro} is the name of the macro to be invoked. The
9584 number register @code{.t} still works within diversions.
9585 @xref{Diversions}, for more information.
9588 @c ---------------------------------------------------------------------
9590 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
9591 @subsection Input Line Traps
9592 @cindex input line traps
9593 @cindex traps, input line
9595 @cindex setting input line trap (@code{it})
9596 @cindex input line trap, setting (@code{it})
9597 @cindex trap, input line, setting (@code{it})
9598 @Defreq {it, n macro}
9599 Sets an input line trap.
9600 @var{n}@w{ }is the number of lines of input which may be read before
9601 @dfn{springing} the trap, @var{macro} is the macro to be invoked.
9602 Request lines are not counted as input lines.
9604 For example, one possible use is to have a macro which prints the
9605 next @var{n}@w{ }lines in a bold font.
9618 @c ---------------------------------------------------------------------
9620 @node End-of-input Traps, , Input Line Traps, Traps
9621 @subsection End-of-input Traps
9622 @cindex end-of-input traps
9623 @cindex traps, end-of-input
9625 @cindex setting end-of-input trap (@code{em})
9626 @cindex end-of-input trap, setting (@code{em})
9627 @cindex trap, end-of-input, setting (@code{em})
9628 @cindex end-of-input macro (@code{em})
9629 @cindex macro, end-of-input (@code{em})
9631 Sets a trap at the end of input. The @var{macro}
9632 specified is executed after the last line of the
9633 input file has been processed.
9635 For example, if the document had to have a section at the bottom of the
9636 last page for someone to approve it, the @code{em} request could be
9655 @c =====================================================================
9657 @node Diversions, Environments, Traps, gtroff Reference
9661 In @code{gtroff} it is possible to @dfn{divert} text into a named
9662 storage area. Due to the similarity to defining macros it is sometimes
9663 said to be stored in a macro. This is used for saving text for output
9664 at a later time, which is useful for keeping blocks of text on the same
9665 page, footnotes, tables of contents and indices.
9667 @c XXX describe top-level diversion
9668 @c XXX index entry for top-level diversion
9670 @cindex beginning diversion (@code{di})
9671 @cindex diversion, beginning (@code{di})
9672 @cindex ending diversion (@code{di})
9673 @cindex diversion, ending (@code{di})
9674 @cindex appending to diversion (@code{da})
9675 @cindex diversion, appending (@code{da})
9676 @DefreqList {di, macro}
9677 @DefreqListEnd {da, macro}
9678 Begins a diversion. Like the @code{de}
9679 request, it takes an argument of a macro name to divert subsequent text
9680 into. The @code{da} macro appends to an existing diversion.
9682 @code{di} or @code{da} without an argument ends the diversion.
9688 ... end-note example ...
9693 @cindex @code{nl} register, and @code{.d}
9694 @cindex nested diversions
9695 @cindex diversion, nested
9696 @cindex diversion name register (@code{.z})
9697 @cindex vertical position in diversion register (@code{.d})
9698 @cindex position, vertical, in diversion, register (@code{.d})
9699 @cindex diversion, vertical position in, register (@code{.d})
9702 Diversions may be nested. The read-only number register @code{.z}
9703 contains the name of the current diversion (this is a string-valued
9704 register). The read-only number register @code{.d} contains the current
9705 vertical place in the diversion. If not in a diversion it is the same
9706 as the register @code{nl}.
9712 The @dfn{high-water mark} on the current page. It corresponds to the
9713 text baseline of the lowest line on the page. This is a read-only
9719 After completing a diversion, the read-write number registers @code{dn}
9720 and @code{dl} contain the vertical and horizontal size of the diversion.
9724 .\" Center text both horizontally & vertically
9726 .\" Enclose macro definitions in .eo and .ec
9727 .\" to avoid the doubling of the backslash
9729 .\" macro .(c starts centering mode
9737 .\" macro .)c terminates centering mode
9741 . nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
9753 .\" End of macro definitions, restore escape mechanism
9759 @cindex transparent output (@code{\!})
9760 @cindex output, transparent (@code{\!})
9761 @DefescList {\\!, , , }
9762 @DefescListEnd {\\?, , @Var{anything}, \\?}
9763 Prevents requests, macros and escapes from being
9764 interpreted when read into a diversion. This takes the given text
9765 and @dfn{transparently} embeds it into the diversion. This is useful for
9766 macros which shouldn't be invoked until the diverted text is actually
9769 @c XXX anything is read in copy mode. (what about \! ??)
9771 The @code{\!} escape transparently embeds text up to
9772 and including the end of the line.
9773 The @code{\?} escape transparently embeds text until the next
9774 occurrence of the @code{\?} escape. For example:
9781 @var{anything} may not contain newlines; use @code{\!} to embed
9782 newlines in a diversion. The escape sequence @code{\?} is also
9783 recognized in copy mode and turned into a single internal code; it is
9784 this code that terminates anything. Thus the following example
9791 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
9806 @cindex unformatting diversions (@code{asciify})
9807 @cindex diversion, unformatting (@code{asciify})
9808 @Defreq {asciify, div}
9809 @dfn{Unformats} the diversion specified by @var{div}
9810 in such a way that @acronym{ASCII} and space characters that
9811 were formatted and diverted are treated like ordinary input
9812 characters when the diversion is reread. It can be also used for gross
9813 hacks; for example, the following sets register@w{ }@code{n} to@w{ }1.
9826 @xref{Copy-in Mode}.
9830 @c =====================================================================
9832 @node Environments, Suppressing output, Diversions, gtroff Reference
9833 @section Environments
9834 @cindex environments
9836 It happens frequently that some text should be printed in a certain
9837 format regardless of what may be in effect at the time, for example, in
9838 a trap invoked macro to print headers and footers. To solve this
9839 @code{gtroff} processes text in @dfn{environments}. An
9840 environment contains most of the parameters that control text
9841 processing. It is possible to switch amongst these environments; by
9842 default @code{gtroff} processes text in environment@w{ }0. The
9843 following is the information kept in an environment.
9847 font parameters (size, family, style, character height and slant, space
9848 and sentence space size)
9851 page parameters (line length, title length, vertical spacing,
9852 line spacing, indentation, line numbering, hyphenation data)
9855 fill and adjust mode
9858 tab stops, tab and leader characters, escape character, no-break and
9859 hyphen indicators, margin character data
9862 partially collected lines
9865 These environments may be given arbitrary names (see @ref{Identifiers},
9866 for more info). Old versions of @code{troff} only had environments
9867 named @samp{0}, @samp{1} and @samp{2}.
9869 @cindex switching environment (@code{ev})
9870 @cindex environment, switching (@code{ev})
9871 @cindex environment number/name register (@code{.ev})
9872 @DefreqList {ev, env}
9873 @DefregListEnd {.ev}
9874 Switches to another environment. The argument @var{env} is the name of
9875 the environment to switch to. With no argument, @code{gtroff} switches
9876 back to the previous environment. There is no limit on the number of
9877 named environments; they are created the first time that they are
9878 referenced. The @code{.ev} read-only register contains the name or
9879 number of the current environment. This is a string-valued register.
9881 Note that a call to @code{ev} (with argument) pushes the previously
9882 active environment onto a stack. If, say, environments @samp{foo},
9883 @samp{bar}, and @samp{zap} are called (in that order), the first
9884 @code{ev} request without parameter switches back to environment
9885 @samp{bar} (which is popped off the stack), and a second call
9886 switches back to environment @samp{foo}.
9892 ... page break macro, revised ...
9909 \(dg Note the large, friendly letters.
9914 @cindex copying environment (@code{evc})
9915 @cindex environment, copying (@code{evc})
9917 Copies the environment @var{env} into the current environment.
9921 @c =====================================================================
9923 @node Suppressing output, Colors, Environments, gtroff Reference
9924 @section Suppressing output
9926 @cindex suppressing output (@code{\O})
9927 @cindex output, suppressing (@code{\O})
9928 @Defesc {\\O, , num, }
9929 Disables or enables output depending on the value of @var{num}:
9933 Disable any ditroff glyphs from being emitted to the device driver,
9934 provided that the escape occurs at the outer level (see @code{\O3} and
9938 Enable output of glyphs, provided that the escape occurs at the outer
9946 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
9947 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
9948 @xref{Register Index}. These four registers mark the top left and
9949 bottom right hand corners of a box which encompasses all written glyphs.
9953 Provided that the escape occurs at the outer level, enable output of
9954 glyphs and also write out to @code{stderr} the page number and four
9955 registers encompassing the glyphs previously written since the last call
9959 Begin a nesting level. This is really an internal mechanism for
9960 @code{grohtml} while producing images. They are generated by running
9961 the troff source through troff to the postscript device and ghostscript
9962 to produce images in PNG format. The @code{\O3} escape will start a new
9963 page if the device is not html (to reduce the possibility of images
9964 crossing a page boundary).
9967 End a nesting level.
9969 @item \O[5Pfilename]
9970 This escape is @code{grohtml} specific. Provided that this escape
9971 occurs at the outer nesting level write the @code{filename} to
9972 @code{stderr}. The position of the image, @var{P}, must be specified
9973 and must be one of @code{l}, @code{r}, @code{c}, or@w{ }@code{i} (left,
9974 right, centered, inline). @var{filename} will be associated with the
9975 production of the next inline image.
9980 @c =====================================================================
9982 @node Colors, I/O, Suppressing output, gtroff Reference
9985 @Defreq {defcolor, ident scheme color_components}
9986 Define color with name @var{ident}. @var{scheme} can be one of the
9987 following values: @code{rgb} (three components), @code{cym} (three
9988 components), @code{cmyk} (four components), and @code{gray} or
9989 @code{grey} (one component).
9991 @cindex default color
9992 @cindex color, default
9993 Color components can be given either as a hexadecimal string or as
9994 positive decimal integers in the range 0--65535. A hexadecimal string
9995 contains all color components concatenated. It must start with either
9996 @code{#} or @code{##}; the former specifies hex values in the range
9997 0--255 (which are internally multiplied by@w{ }257), the latter in the
9998 range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff}
9999 (magenta). The default color name @c{default} can't be redefined; its
10000 value is device-specific (usually black). It is possible that the
10001 default color for @code{\m} and @code{\M} is not identical.
10003 @cindex @code{f} unit, and colors
10004 @cindex unit, @code{f}, and colors
10005 A new scaling indicator@w{ }@code{f} has been introduced which multiplies
10006 its value by 65536; this makes it convenient to specify color components
10007 as fractions in the range 0 to@w{ }1 (1f equals 65536u). Example:
10010 .defcolor darkgreen rgb 0.1f 0.5f 0.2f
10013 Note that @code{f} is the default scaling indicator for the
10014 @code{defcolor} request, thus the above statement is equivalent to
10017 .defcolor darkgreen rgb 0.1 0.5 0.2
10021 @DefescList {\\m, , c, }
10022 @DefescItem {\\m, @lparen{}, co, }
10023 @DefescListEnd {\\m, @lbrack{}, color, @rbrack}
10024 Set drawing color. The following example shows how to turn the next four
10028 \m[red]these are in red\mP and these words are in black.
10031 The escape @code{\mP} returns to the previous color.
10034 @DefescList {\\M, , c, }
10035 @DefescItem {\\M, @lparen{}, co, }
10036 @DefescListEnd {\\M, @lbrack{}, color, @rbrack}
10037 Set background color for filled objects drawn with the
10038 @code{\D'@dots{}'} commands.
10040 A red ellipse can be created with the following code:
10043 \M[red]\h'0.5i'\D'E 2i 1i'\Mp
10046 The escape @code{\MP} returns to the previous fill color.
10049 @c =====================================================================
10051 @node I/O, Postprocessor Access, Colors, gtroff Reference
10054 @cindex input and output requests
10055 @cindex requests for input and output
10056 @cindex output and input requests
10058 @code{gtroff} has several requests for including files:
10060 @cindex including a file (@code{so})
10061 @cindex file inclusion (@code{so})
10063 Reads in the specified @var{file} and
10064 includes it in place of the @code{so} request. This is quite useful for
10065 large documents, e.g.@: keeping each chapter in a separate file.
10066 @xref{gsoelim}, for more information.
10069 @Defreq {mso, file}
10070 Identical to the @code{so} request except that @code{gtroff}
10071 searches for the specified
10072 @var{file} in the same directories as macro files for the
10073 the @option{-m} command line option. If the file name to be included
10074 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
10075 to include @file{tmac.@var{name}} and vice versa.
10078 @cindex transparent output (@code{cf}, @code{trf})
10079 @cindex output, transparent (@code{cf}, @code{trf})
10080 @DefreqList {cf, file}
10081 @DefreqListEnd {trf, file}
10082 Transparently outputs the contents of @var{file}. Each line is output
10083 as it were preceded by @code{\!}; however, the lines are not subject to
10084 copy mode interpretation. If the file does not end with a newline, then
10085 a newline is added. For example, to define a macro@w{ }@code{x}
10086 containing the contents of file@w{ }@file{f}, use
10094 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
10095 embeds an object in the diversion which, when reread, causes the
10096 contents of @var{filename} to be transparently copied through to the
10099 In @acronym{UNIX} @code{troff}, the contents of @var{filename}
10100 is immediately copied through to the output regardless of whether there
10101 is a current diversion; this behaviour is so anomalous that it must be
10102 considered a bug. This request causes a line break.
10104 @cindex @code{trf} request, and invalid characters
10105 With @code{trf}, unlike @code{cf}, the file cannot contain characters
10106 such as NUL that are not valid @code{gtroff} input characters
10107 (@pxref{Identifiers}). This request causes a line break.
10110 @cindex processing next file (@code{nx})
10111 @cindex file, processing next (@code{nx})
10112 @cindex next file, processing (@code{nx})
10114 Forces @code{gtroff} to continue processing of
10115 the file specified as an argument.
10118 @cindex reading from standard input (@code{rd})
10119 @cindex standard input, reading from (@code{rd})
10120 @cindex input, standard, reading from (@code{rd})
10122 The @code{rd} request reads from standard input, and includes what is
10123 read as though it were part of the input file. Text is read until a
10124 blank line is encountered.
10127 @cindex form letters
10128 @cindex letters, form
10129 Using the @code{nx} and @code{rd} requests,
10130 it is easy to set up form letters. The form
10131 letter template is constructed like this:
10147 @cindex @code{ex} request, used with @code{nx} and @code{rd}
10149 When this is run, the following file should be redirected in. Note that
10150 requests included in this file are executed as though they were part of
10151 the form letter. The last block of input is the @code{ex} requests
10152 which tells groff to stop processing. If this was not there, groff
10153 would not know when to stop.
10157 708 NW 19th Av., #202
10164 San Diego, CA 92103
10172 Pipes the output of @code{gtroff} to the shell command(s)
10173 specified by @var{pipe}. This request must occur before
10174 @code{gtroff} has a chance to print anything.
10177 @DefreqList {sy, cmds}
10178 @DefregListEnd {systat}
10179 In @dfn{unsafe} mode, executes the shell command(s) specified by
10180 @var{cmds}. The output is not saved anyplace, so it is up to the user
10183 @c XXX add info about safer and unsafe mode
10185 For example, the following example introduces the current time
10188 @cindex time, current
10189 @cindex current time
10192 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
10193 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
10195 .sy rm /tmp/x\n[$$]
10200 Note that this works by having the @code{perl} script (run by @code{sy})
10201 print out the @code{nr} requests which set the number registers
10202 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
10203 the @code{so} request.
10205 @cindex @code{system()} return value register (@code{systat})
10206 The @code{systat} read-write number register contains the return value
10207 of the @code{system()} function executed by the last @code{sy} request.
10210 @cindex opening file (@code{open})
10211 @cindex file, opening (@code{open})
10212 @cindex appending to file (@code{opena})
10213 @cindex file, appending to (@code{opena})
10214 @DefreqList {open, stream file}
10215 @DefreqListEnd {opena, stream file}
10216 Opens the specified @var{file} for writing and
10217 associates the specified @var{stream} with it.
10219 The @code{opena} is like @code{open}, but if the file exists, append to
10220 it instead of truncating it.
10223 @cindex copy-in mode, and @code{write} requests
10224 @cindex mode, copy-in, and @code{write} requests
10225 @cindex writing to file (@code{write})
10226 @cindex file, writing to (@code{write})
10227 @Defreq {write, stream data}
10228 Writes to the file associated with the specified @var{stream}.
10229 The stream must previously have
10230 been the subject of an open request. The remainder of the line is
10231 interpreted as the @code{ds} request reads its second argument: A
10232 leading @samp{"} is stripped, and it is read in copy-in mode.
10235 @cindex closing file (@code{close})
10236 @cindex file, closing (@code{close})
10237 @Defreq {close, stream}
10238 Closes the specified @var{stream};
10239 the stream is no longer an acceptable argument to the
10240 @code{write} request.
10246 ... example of open write &c...
10251 @Defesc {\\V, ', xxx, '}
10252 Interpolates the contents of the specified
10253 environment variable, as returned by the function @code{getenv}.
10254 Specify the argument to @code{\V} as an identifier, i.e.@:
10255 @samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V}
10256 is interpreted in copy-in mode.
10260 @c =====================================================================
10262 @node Postprocessor Access, Miscellaneous, I/O, gtroff Reference
10263 @section Postprocessor Access
10264 @cindex postprocessor access
10265 @cindex access of postprocessor
10267 There are two escapes which give information directly to the
10268 postprocessor. This is particularly useful for embedding
10269 @sc{PostScript} into the final document.
10271 @Defesc {\\X, ', xxx, '}
10272 Embeds its argument into the @code{gtroff}
10273 output preceded with @w{@samp{x X}}.
10276 @Defesc {\\Y, ', xxx, '}
10277 The @code{\Y} escape is called with an identifier (i.e.@:
10278 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
10279 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
10280 contents of the string or macro @var{xxx} are not interpreted; also it
10281 is permitted for @var{xxx} to have been defined as a macro and thus
10282 contain newlines (it is not permitted for the argument to @code{\X} to
10283 contain newlines). The inclusion of newlines requires an extension to
10284 the @acronym{UNIX} @code{troff} output format, and confuses drivers
10285 that do not know about this extension.
10288 @xref{Output Devices}.
10291 @c =====================================================================
10293 @node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference
10294 @section Miscellaneous
10295 @cindex miscellaneous
10297 This section documents parts of @code{gtroff} which cannot (yet) be
10298 categorized elsewhere in this manual.
10300 @cindex printing line numbers (@code{nm})
10301 @cindex line numbers, printing (@code{nm})
10302 @cindex numbers, line, printing (@code{nm})
10303 @Defreq {nm, start inc space indent}
10304 Prints line numbers in the left margin.
10305 @var{start} is the line number of the @emph{next}
10306 output line; this defaults to@w{ }1. @var{inc} indicates on
10307 which lines numbers are printed, i.e.@: 5 means put line numbers on
10308 every 5@w{ }lines; this defaults to@w{ }1. @var{space} is the
10309 space to be left between the number and the text; this defaults to@w{
10310 }1. The fourth argument is the indentation of the line numbers.
10311 Without arguments, line numbers are turned off.
10314 @c XXX xref ln register
10316 @Defreq {nn, [@Var{skip}]}
10317 Temporarily turns off line numbering. The
10318 argument is the number of lines not to be numbered; this defaults
10321 @c XXX (does this disable incrementing or display?)
10327 ... line numbering example ...
10332 @cindex margin characters (@code{mc})
10333 @cindex characters for margins (@code{mc})
10334 @Defreq {mc, char dist}
10335 Prints margin characters to the right of the text.
10336 The first argument is the character to be
10337 printed, and the second argument is the distance away from the main body
10338 text. With no arguments the margin characters are turned off. If this
10339 occurs before a break, no margin character is printed.
10343 This is quite useful for indicating text that has changed, and, in fact,
10344 there are programs available for doing this (they are called
10345 @code{nrchbar} and @code{changebar} and can be found in any
10346 @samp{comp.sources.unix} archive.
10352 ... margin char example ...
10358 @cindex multi-file documents
10359 @cindex documents, multi-file
10360 @cindex setting input line number (@code{lf})
10361 @cindex input line number, setting (@code{lf})
10362 @cindex number, input line, setting (@code{lf})
10363 @Defreq {lf, line filename}
10364 A debugging aid for
10365 documents which are split into many files, then put together
10366 with @code{soelim} and other preprocessors. The second argument is the
10367 name of the file and the first argument is the input line number in
10368 that file. This way @code{gtroff} can produce error messages which are
10369 intelligible to the user.
10375 ... example of soelim'ed doc ...
10381 @c =====================================================================
10383 @node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference
10384 @section @code{gtroff} Internals
10386 @cindex input token
10387 @cindex token, input
10388 @cindex output node
10389 @cindex node, output
10390 @code{gtroff} processes input in three steps. One or more input
10391 characters are converted to an @dfn{input token}. Then, one or more
10392 input tokens are converted to an @dfn{output node}. Finally, output
10393 nodes are converted to the intermediate output language understood by
10394 all output devices.
10396 For example, the input string @samp{fi\[:u]} is converted in a
10397 character token @samp{f}, a character token @samp{i}, and a special
10398 token @samp{:u} (representing u@w{ }umlaut). Later on, the character
10399 tokens @samp{f} and @samp{i} are merged to a single output node
10400 representing the ligature glyph @samp{fi}; the same happens with
10401 @samp{:u}. All output glyph nodes are `processed' which means that
10402 they are invariably associated with a given font, font size, advance
10403 width, etc. During the formatting process, @code{gtroff} itself adds
10404 various nodes to control the data flow.
10406 Macros, diversions, and strings collect elements in two chained lists:
10407 a list of input tokens which have been passed unprocessed, and a list
10408 of output nodes. Consider the following the diversion.
10420 It contains these elements.
10422 @multitable {@i{vertical size node}} {token list} {element number}
10423 @item node list @tab token list @tab element number
10425 @item @i{line start node} @tab --- @tab 1
10426 @item @i{glyph node @code{a}} @tab --- @tab 2
10427 @item @i{word space node} @tab --- @tab 3
10428 @item --- @tab @code{b} @tab 4
10429 @item --- @tab @code{\n} @tab 5
10430 @item @i{glyph node @code{c}} @tab --- @tab 6
10431 @item @i{vertical size node} @tab --- @tab 7
10432 @item @i{vertical size node} @tab --- @tab 8
10433 @item --- @tab @code{\n} @tab 9
10436 @cindex @code{\v}, internal representation
10438 Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two
10439 (which are always present) specify the vertical extent of the last
10440 line, possibly modified by @code{\v}. The @code{br} request finishes
10441 the current partial line, inserting a newline input token which is
10442 subsequently converted to a space when the diversion is reread. Note
10443 that the word space node has a fixed width which isn't stretchable
10444 anymore. To convert horizontal space nodes back to input tokens, use
10445 the @code{unformat} request.
10447 Macros only contain elements in the token list (and the node list is
10448 empty); diversions and strings can contain elements in both lists.
10451 @c =====================================================================
10453 @node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference
10457 @code{gtroff} is not easy to debug, but there are some useful features
10458 and strategies for debugging.
10460 @cindex printing to stderr (@code{tm})
10461 @cindex stderr, printing to (@code{tm})
10462 @Defreq {tm, string}
10463 Sends the @var{string} to the standard error stream;
10464 this is very useful for printing debugging output among other things.
10467 @cindex aborting (@code{ab})
10468 @Defreq {ab, [@Var{string}]}
10469 Similar to the @code{tm} request, except that
10470 it causes @code{gtroff} to stop processing. With no argument it
10471 prints @samp{User Abort}.
10474 @cindex @code{ex} request, use in debugging
10475 @cindex exiting (@code{ex})
10477 The @code{ex} request also causes @code{gtroff} to stop processing
10478 if encountered at the topmost level; see also @ref{I/O}.
10481 When doing something involved it is useful to leave the debugging
10482 statements in the code and have them turned on by a command line flag.
10485 .if \n(DB .tm debugging output
10489 To activate these statements say
10495 @c XXX .tm1, .tmc requests
10497 If it is known in advance that there will be many errors and no useful
10498 output, @code{gtroff} can be forced to suppress formatted output with
10499 the @option{-z} flag.
10501 @cindex dumping symbol table (@code{pm})
10502 @cindex symbol table, dumping (@code{pm})
10504 The @code{pm} request prints out the entire symbol table on @code{stderr}.
10507 @cindex dumping number registers (@code{pnr})
10508 @cindex number registers, dumping (@code{pnr})
10510 Prints the names and contents of all
10511 currently defined number registers on @code{stderr}.
10514 @cindex dumping traps (@code{ptr})
10515 @cindex traps, dumping (@code{ptr})
10517 Prints the names and positions of all traps
10518 (not including input line traps and diversion traps) on @code{stderr}.
10519 Empty slots in the page trap list are printed as well, because they can
10520 affect the priority of subsequently planted traps.
10523 @cindex flush output (@code{fl})
10524 @cindex output, flush (@code{fl})
10525 @cindex interactive use of @code{gtroff}
10526 @cindex @code{gtroff}, interactive use
10528 Instructs @code{gtroff} to flush its output
10529 immediately. The intent is for interactive use.
10530 @code{gtroff}; there is little other use for it. This
10531 request causes a line break.
10534 @cindex backtrace of input stack (@code{backtrace})
10535 @cindex input stack, backtrace (@code{backtrace})
10536 @Defreq {backtrace, }
10537 The @code{backtrace} request prints a backtrace of the input stack
10538 to the standard error stream.
10542 @code{gtroff} has command line options for printing out more warnings
10543 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
10544 or an error occurs. The most verbose level of warnings is @option{-ww}.
10546 @cindex level of warnings (@code{warn})
10547 @cindex warnings, level (@code{warn})
10548 @DefreqList {warn, [@Var{flags}]}
10549 @DefregListEnd {.warn}
10550 Controls the level of warnings checked for. The @var{flags} are the sum
10551 of the numbers associated with each warning that is to be enabled; all
10552 other warnings are disabled. The number associated with each warning is
10553 listed below. For example, @w{@code{.warn 0}} disables all warnings,
10554 and @w{@code{.warn 1}} disables all warnings except that about missing
10555 characters. If an argument is not given, all warnings are enabled.
10557 The read-only number register @code{.warn} contains the current warning
10565 @c ---------------------------------------------------------------------
10567 @node Warnings, , Debugging, Debugging
10568 @subsection Warnings
10571 The warnings that can be given to @code{gtroff} are divided into the
10572 following categories. The name associated with each warning is used by
10573 the @option{-w} and @option{-W} options; the number is used by the
10574 @code{warn} request and by the @code{.warn} register.
10579 Non-existent characters. This is enabled by default.
10583 Invalid numeric expressions. This is enabled by default.
10584 @xref{Expressions}.
10590 In fill mode, lines which could not be broken so that their length was
10591 less than the line length. This is enabled by default.
10595 Missing or mismatched closing delimiters.
10599 @cindex @code{ie} request, and warnings
10600 @cindex @code{el} request, and warnings
10601 Use of the @code{el} request with no matching @code{ie} request.
10606 Meaningless scaling indicators.
10610 Out of range arguments.
10614 Dubious syntax in numeric expressions.
10618 @cindex @code{di} request, and warnings
10619 @cindex @code{da} request, and warnings
10620 Use of @code{di} or @code{da} without an argument when there is no
10625 @cindex @code{de} request, and warnings
10626 @c XXX more index entries
10627 Use of undefined strings, macros and diversions. When an undefined
10628 string, macro or diversion is used, that string is automatically defined
10629 as empty. So, in most cases, at most one warning is given for each
10634 @cindex @code{nr} request, and warnings
10635 @c XXX more index entries
10636 Use of undefined number registers. When an undefined number register is
10637 used, that register is automatically defined to have a value of@w{ }0.
10638 A definition is automatically made with a value of@w{ }0. So, in most
10639 cases, at most one warning is given for use of a particular name.
10643 Use of a tab character where a number was expected.
10647 @cindex @code{\@}}, debugging
10648 Use of @code{\@}} where a number was expected.
10652 Requests that are missing non-optional arguments.
10656 Illegal input characters.
10660 Unrecognized escape sequences. When an unrecognized escape sequence is
10661 encountered, the escape character is ignored.
10665 @cindex compatibility mode
10666 Missing space between a request or macro and its argument. This warning
10667 is given when an undefined name longer than two characters is
10668 encountered, and the first two characters of the name make a defined
10669 name. The request or macro is not invoked. When this warning is
10670 given, no macro is automatically defined. This is enabled by default.
10671 This warning never occurs in compatibility mode.
10675 Non-existent fonts. This is enabled by default.
10678 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
10679 intended that this covers all warnings that are useful with traditional
10687 @c =====================================================================
10689 @node Implementation Differences, Summary, Debugging, gtroff Reference
10690 @section Implementation Differences
10691 @cindex implementation differences
10692 @cindex differences in implementation
10693 @cindex incompatibilities with Unix @code{troff}
10694 @cindex compatibility mode
10695 @cindex mode, compatibility
10697 GNU @code{troff} has a number of features which cause incompatibilities
10698 with documents written with old versions of @code{troff}.
10701 @cindex names, long
10702 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
10709 @cindex @code{\*}, incompatibilities with Unix @code{troff}
10710 @cindex @code{\n}, incompatibilities with Unix @code{troff}
10712 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
10713 @code{troff} interprets this as a call of a macro named
10714 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
10715 @code{\*[} or @code{\n[} as references to a string or number register
10716 called @samp{[}. In GNU @code{troff}, however, this is normally
10717 interpreted as the start of a long name. In compatibility mode GNU
10718 @code{troff} interprets long names in the traditional way
10719 (which means that they are not recognized as names).
10720 Compatibility mode can be turned on with the @option{-C} command line
10721 option, and turned on or off with the @code{cp} request. The number
10722 register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{
10725 @cindex input level in delimited arguments
10726 @cindex delimited arguments, incompatibilities with Unix @code{troff}
10727 Two other features are controlled by @option{-C}. If not in
10728 compatibility mode, GNU @code{troff} preserves the input level in
10729 delimited arguments:
10737 In compatibility mode, the string @samp{72def'} is returned; without
10738 @option{-C} the resulting string is @samp{168} (assuming a TTY output
10741 @cindex @code{\f}, incompatibilities with Unix @code{troff}
10742 @cindex @code{\H}, incompatibilities with Unix @code{troff}
10743 @cindex @code{\R}, incompatibilities with Unix @code{troff}
10744 @cindex @code{\s}, incompatibilities with Unix @code{troff}
10745 @cindex @code{\S}, incompatibilities with Unix @code{troff}
10746 Finally, the escapes @code{\f}, @code{\H}, @code{\R}, @code{\s}, and
10747 @code{\S} are transparent for recognizing the beginning of a line only
10748 in compatibility mode (this is a rather obscure feature). For example,
10758 prints @samp{Hallo!} in bold face if in compatibility mode, and
10759 @samp{.xx} in bold face otherwise.
10761 @cindex @code{\A}, incompatibilities with Unix @code{troff}
10762 @cindex @code{\|}, incompatibilities with Unix @code{troff}
10763 @cindex @code{\^}, incompatibilities with Unix @code{troff}
10764 @cindex @code{\&}, incompatibilities with Unix @code{troff}
10765 @cindex @code{\@{}, incompatibilities with Unix @code{troff}
10766 @cindex @code{\@}}, incompatibilities with Unix @code{troff}
10767 @cindex @code{\@key{SP}}, incompatibilities with Unix @code{troff}
10768 @cindex @code{\'}, incompatibilities with Unix @code{troff}
10769 @cindex @code{\`}, incompatibilities with Unix @code{troff}
10770 @cindex @code{\-}, incompatibilities with Unix @code{troff}
10771 @cindex @code{\_}, incompatibilities with Unix @code{troff}
10772 @cindex @code{\!}, incompatibilities with Unix @code{troff}
10773 @cindex @code{\%}, incompatibilities with Unix @code{troff}
10774 @cindex @code{\c}, incompatibilities with Unix @code{troff}
10775 GNU @code{troff} does not allow the use of the escape sequences
10776 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
10777 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
10778 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
10779 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
10780 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
10781 avoiding use of these escape sequences in names.
10783 @cindex fractional point sizes
10784 @cindex point sizes, fractional
10785 @cindex @code{ps} request, incompatibilities with Unix @code{troff}
10786 Fractional point sizes cause one noteworthy incompatibility. In
10787 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
10788 indicators and thus
10795 sets the point size to 10@w{ }points, whereas in GNU @code{troff} it
10796 sets the point size to 10@w{ }scaled points. @xref{Fractional Type
10797 Sizes}, for more information.
10799 @cindex @code{bd} request, incompatibilities with Unix @code{troff}
10800 @cindex @code{cs} request, incompatibilities with Unix @code{troff}
10801 @cindex @code{tkf} request, incompatibilities with Unix @code{troff}
10802 @cindex @code{tr} request, incompatibilities with Unix @code{troff}
10803 @cindex @code{fp} request, incompatibilities with Unix @code{troff}
10804 @cindex input and output characters, compatibility with Unix
10805 @cindex output characters, compatibility with Unix
10806 @cindex characters, input and output, compatibility with Unix
10807 In GNU @code{troff} there is a fundamental difference between
10808 unformatted, input characters, and formatted, output characters.
10809 Everything that affects how an output character is output is stored
10810 with the character; once an output character has been constructed it is
10811 unaffected by any subsequent requests that are executed, including
10812 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
10813 Normally output characters are constructed from input characters at the
10814 moment immediately before the character is added to the current output
10815 line. Macros, diversions and strings are all, in fact, the same type of
10816 object; they contain lists of input characters and output characters in
10817 any combination. An output character does not behave like an input
10818 character for the purposes of macro processing; it does not inherit any
10819 of the special properties that the input character from which it was
10820 constructed might have had. For example,
10830 @cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\(rs})
10831 @cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\(rs})
10832 @cindex @code{\e}, incompatibilities with Unix @code{troff}
10833 @cindex @code{\!}, incompatibilities with Unix @code{troff}
10834 @cindex @code{\?}, incompatibilities with Unix @code{troff}
10835 @cindex transparent output, incompatibilities with Unix @code{troff}
10836 @cindex output, transparent, incompatibilities with Unix @code{troff}
10838 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
10839 is turned into one output backslash and the resulting output backslashes
10840 are not interpreted as escape characters when they are reread.
10841 @acronym{UNIX} @code{troff} would interpret them as escape characters
10842 when they were reread and would end up printing one @samp{\}. The
10843 correct way to obtain a printable backslash is to use the @code{\e}
10844 escape sequence: This always prints a single instance of the current
10845 escape character, regardless of whether or not it is used in a
10846 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
10847 @code{troff}.@footnote{To be completely independent of the current
10848 escape character, use @code{\(rs} which represents a reverse solidus
10849 (backslash) glyph.} To store, for some reason, an escape sequence in a
10850 diversion that will be interpreted when the diversion is reread, either
10851 use the traditional @code{\!} transparent output facility, or, if this
10852 is unsuitable, the new @code{\?} escape sequence.
10854 @xref{Diversions}, for more information.
10857 @c =====================================================================
10859 @node Summary, , Implementation Differences, gtroff Reference
10863 @c XXX documentation
10867 @c =====================================================================
10868 @c =====================================================================
10870 @node Preprocessors, Output Devices, gtroff Reference, Top
10871 @chapter Preprocessors
10872 @cindex preprocessors
10874 This chapter describes all preprocessors that come with @code{groff} or
10875 which are freely available.
10888 @c =====================================================================
10890 @node geqn, gtbl, Preprocessors, Preprocessors
10891 @section @code{geqn}
10892 @cindex @code{eqn}, the program
10893 @cindex @code{geqn}, the program
10901 @c ---------------------------------------------------------------------
10903 @node Invoking geqn, , geqn, geqn
10904 @subsection Invoking @code{geqn}
10905 @cindex invoking @code{geqn}
10906 @cindex @code{geqn}, invoking
10911 @c =====================================================================
10913 @node gtbl, gpic, geqn, Preprocessors
10914 @section @code{gtbl}
10915 @cindex @code{tbl}, the program
10916 @cindex @code{gtbl}, the program
10924 @c ---------------------------------------------------------------------
10926 @node Invoking gtbl, , gtbl, gtbl
10927 @subsection Invoking @code{gtbl}
10928 @cindex invoking @code{gtbl}
10929 @cindex @code{gtbl}, invoking
10934 @c =====================================================================
10936 @node gpic, ggrn, gtbl, Preprocessors
10937 @section @code{gpic}
10938 @cindex @code{pic}, the program
10939 @cindex @code{gpic}, the program
10947 @c ---------------------------------------------------------------------
10949 @node Invoking gpic, , gpic, gpic
10950 @subsection Invoking @code{gpic}
10951 @cindex invoking @code{gpic}
10952 @cindex @code{gpic}, invoking
10957 @c =====================================================================
10959 @node ggrn, grap, gpic, Preprocessors
10960 @section @code{ggrn}
10961 @cindex @code{grn}, the program
10962 @cindex @code{ggrn}, the program
10970 @c ---------------------------------------------------------------------
10972 @node Invoking ggrn, , ggrn, ggrn
10973 @subsection Invoking @code{ggrn}
10974 @cindex invoking @code{ggrn}
10975 @cindex @code{ggrn}, invoking
10980 @c =====================================================================
10982 @node grap, grefer, ggrn, Preprocessors
10983 @section @code{grap}
10984 @cindex @code{grap}, the program
10986 A free implementation of @code{grap}, written by Ted Faber,
10987 is available as an extra package from the following address:
10990 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
10994 @c =====================================================================
10996 @node grefer, gsoelim, grap, Preprocessors
10997 @section @code{grefer}
10998 @cindex @code{refer}, the program
10999 @cindex @code{grefer}, the program
11004 * Invoking grefer::
11007 @c ---------------------------------------------------------------------
11009 @node Invoking grefer, , grefer, grefer
11010 @subsection Invoking @code{grefer}
11011 @cindex invoking @code{grefer}
11012 @cindex @code{grefer}, invoking
11017 @c =====================================================================
11019 @node gsoelim, , grefer, Preprocessors
11020 @section @code{gsoelim}
11021 @cindex @code{soelim}, the program
11022 @cindex @code{gsoelim}, the program
11027 * Invoking gsoelim::
11030 @c ---------------------------------------------------------------------
11032 @node Invoking gsoelim, , gsoelim, gsoelim
11033 @subsection Invoking @code{gsoelim}
11034 @cindex invoking @code{gsoelim}
11035 @cindex @code{gsoelim}, invoking
11041 @c =====================================================================
11042 @c =====================================================================
11044 @node Output Devices, File formats, Preprocessors, Top
11045 @chapter Output Devices
11046 @cindex output devices
11047 @cindex devices for output
11052 * Special Characters::
11063 @c =====================================================================
11065 @node Special Characters, grotty, Output Devices, Output Devices
11066 @section Special Characters
11067 @cindex special characters
11068 @cindex characters, special
11075 @c =====================================================================
11077 @node grotty, grops, Special Characters, Output Devices
11078 @section @code{grotty}
11079 @cindex @code{grotty}, the program
11084 * Invoking grotty::
11087 @c ---------------------------------------------------------------------
11089 @node Invoking grotty, , grotty, grotty
11090 @subsection Invoking @code{grotty}
11091 @cindex invoking @code{grotty}
11092 @cindex @code{grotty}, invoking
11097 @c =====================================================================
11099 @node grops, grodvi, grotty, Output Devices
11100 @section @code{grops}
11101 @cindex @code{grops}, the program
11107 * Embedding PostScript::
11110 @c ---------------------------------------------------------------------
11112 @node Invoking grops, Embedding PostScript, grops, grops
11113 @subsection Invoking @code{grops}
11114 @cindex invoking @code{grops}
11115 @cindex @code{grops}, invoking
11119 @c ---------------------------------------------------------------------
11121 @node Embedding PostScript, , Invoking grops, grops
11122 @subsection Embedding @sc{PostScript}
11123 @cindex embedding postscript
11124 @cindex postscript, embedding
11129 @c =====================================================================
11131 @node grodvi, grolj4, grops, Output Devices
11132 @section @code{grodvi}
11133 @cindex @code{grodvi}, the program
11138 * Invoking grodvi::
11141 @c ---------------------------------------------------------------------
11143 @node Invoking grodvi, , grodvi, grodvi
11144 @subsection Invoking @code{grodvi}
11145 @cindex invoking @code{grodvi}
11146 @cindex @code{grodvi}, invoking
11151 @c =====================================================================
11153 @node grolj4, grolbp, grodvi, Output Devices
11154 @section @code{grolj4}
11155 @cindex @code{grolj4}, the program
11160 * Invoking grolj4::
11163 @c ---------------------------------------------------------------------
11165 @node Invoking grolj4, , grolj4, grolj4
11166 @subsection Invoking @code{grolj4}
11167 @cindex invoking @code{grolj4}
11168 @cindex @code{grolj4}, invoking
11173 @c =====================================================================
11175 @node grolbp, grohtml, grolj4, Output Devices
11176 @section @code{grolbp}
11177 @cindex @code{grolbp}, the program
11182 * Invoking grolbp::
11185 @c ---------------------------------------------------------------------
11187 @node Invoking grolbp, , grolbp, grolbp
11188 @subsection Invoking @code{grolbp}
11189 @cindex invoking @code{grolbp}
11190 @cindex @code{grolbp}, invoking
11195 @c =====================================================================
11197 @node grohtml, gxditview, grolbp, Output Devices
11198 @section @code{grohtml}
11199 @cindex @code{grohtml}, the program
11204 * Invoking grohtml::
11207 @c ---------------------------------------------------------------------
11209 @node Invoking grohtml, , grohtml, grohtml
11210 @subsection Invoking @code{grohtml}
11211 @cindex invoking @code{grohtml}
11212 @cindex @code{grohtml}, invoking
11217 @c =====================================================================
11219 @node gxditview, , grohtml, Output Devices
11220 @section @code{gxditview}
11221 @cindex @code{gxditview}, the program
11226 * Invoking gxditview::
11229 @c ---------------------------------------------------------------------
11231 @node Invoking gxditview, , gxditview, gxditview
11232 @subsection Invoking @code{gxditview}
11233 @cindex invoking @code{gxditview}
11234 @cindex @code{gxditview}, invoking
11241 @c =====================================================================
11242 @c =====================================================================
11244 @node File formats, Installation, Output Devices, Top
11245 @chapter File formats
11246 @cindex file formats
11247 @cindex formats, file
11257 @c =====================================================================
11259 @node gtroff Output, Font Files, File formats, File formats
11260 @section @code{gtroff} Output
11261 @cindex @code{gtroff} output
11262 @cindex output, @code{gtroff}
11264 This section describes the format output of GNU @code{troff}. The
11265 output format used by GNU @code{troff} is very similar -- but
11266 not identical -- to that used by
11267 @acronym{UNIX} device-independent @code{troff} (@code{ditroff}).
11272 * Drawing Functions::
11273 * Line Continuation::
11276 @c ---------------------------------------------------------------------
11278 @node Output Format, Device Control, gtroff Output, gtroff Output
11279 @subsection Output Format
11280 @cindex output format
11281 @cindex format of output
11283 @cindex 8-bit input
11284 @cindex input, 8-bit
11285 The output format is text based, as opposed to a binary format (like
11286 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
11287 characters can have the eighth bit set, as can the names of fonts and
11288 special characters.
11290 The output format consists of single command characters with attached
11291 parameters which are separated from subsequent text by whitespace or a
11294 The names of characters and fonts can be of arbitrary length; drivers
11295 should not assume that they are only two characters long (as
11296 @code{ditroff} does).
11298 When a character is to be printed, that character is always in the
11299 current font. Unlike @code{ditroff}, it is not necessary for drivers to
11300 search special fonts to find a character.
11321 @item @var{nn}@var{c}
11325 @var{xxx} is any sequence of characters terminated by a space or a
11326 newline; the first character should be printed at the current position,
11327 the the current horizontal position should be increased by the width of
11328 the first character, and so on for each character. The width of the
11329 character is that given in the font file, appropriately scaled for the
11330 current point size, and rounded so that it is a multiple of the
11331 horizontal resolution. Special characters cannot be printed using this
11335 @pindex DESC@r{, and @code{tcommand}}
11336 This command is only allowed if the @samp{tcommand} line is present in
11337 the @file{DESC} file.
11339 @item u@var{n} @var{xxx}
11340 This is same as the @samp{t} command except that after printing each
11341 character, the current horizontal position is increased by the sum of
11342 the width of that character and@w{ }@var{n}.
11344 This command is only allowed if the @samp{tcommand} line is present in
11345 the @file{DESC} file.
11347 @item n@var{a}@var{b}
11355 @pindex DESC@r{, and @code{sizescale}}
11356 The argument to the @samp{s} command is in scaled points (units of
11357 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
11358 command in the @file{DESC} file).
11365 @item D@var{c} @var{x}@dots{}\n
11369 @c ---------------------------------------------------------------------
11371 @node Device Control, Drawing Functions, Output Format, gtroff Output
11372 @subsection Device Control
11373 @cindex device control
11374 @cindex control of devices
11376 The @samp{x} command is normally followed by a letter or word indicating
11377 the function to perform, followed by white space separated arguments.
11379 The first argument can be abbreviated to the first letter.
11388 @item x res @var{n} @var{h} @var{v}
11393 The argument to the @w{@samp{x Height}} command is also in scaled
11397 The first three output commands are guaranteed to be:
11406 For example, the input
11409 crunchy \fH\s+2frog\s0\fP!?
11419 ... sample output here ...
11423 @c ---------------------------------------------------------------------
11425 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
11426 @subsection Drawing Functions
11427 @cindex drawing functions
11428 @cindex functions for drawing
11431 The @samp{D} drawing command has been extended. These extensions are
11432 used by GNU @code{pic} only if the @option{-x} option is given.
11434 @xref{Drawing Requests}.
11439 Set the shade of gray to be used for filling solid objects to@w{
11440 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
11441 corresponds solid white and 1000 to solid black, and values in between
11442 correspond to intermediate shades of gray. This applies only to solid
11443 circles, solid ellipses and solid polygons. By default, a level of@w{
11444 }1000 is used. Whatever color a solid object has, it should
11445 completely obscure everything beneath it. A value greater than@w{ }1000
11446 or less than@w{ }0 can also be used: this means fill with the shade of
11447 gray that is currently being used for lines and text. Normally this
11448 is black, but some drivers may provide a way of changing this.
11451 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
11452 point at the current position.
11454 @item DE @var{dx} @var{dy}
11455 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
11456 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
11459 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
11460 Draw a polygon with automatic closure. The first vertex is at the
11461 current position, the second vertex at an offset (@var{dx1},@var{dy1})
11462 from the current position, the second vertex at an offset
11463 (@var{dx2},@var{dy2}) from the first vertex, and so on up to the
11464 @var{n}@dmn{th} vertex. At the moment, GNU @code{pic} only uses this
11465 command to generate triangles and rectangles.
11467 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
11468 Like @code{Dp} but draw a solid rather than outlined polygon.
11471 @cindex line thickness
11472 @cindex thickness of lines
11473 Set the current line thickness to @var{n}@w{ }machine units.
11474 Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness
11475 proportional to the current point size; drivers should continue to do
11476 this if no @code{Dt} command has been given, or if a @code{Dt} command
11477 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
11478 }@var{n} selects the smallest available line thickness.
11481 A difficulty arises in how the current position should be changed after
11482 the execution of these commands. This is not of great importance since
11483 the code generated by GNU @code{pic} does not depend on this. Given a
11484 drawing command of the form
11487 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
11490 @cindex @code{\w}, and drawing commands
11491 @cindex @code{st} register, and drawing commands
11492 @cindex @code{sb} register, and drawing commands
11494 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
11495 @samp{~}, @acronym{UNIX} @code{troff} treats each x@w{ }value
11496 as a horizontal quantity, and each y@w{ }value as a vertical
11497 quantity; it assumes that the width of the drawn object is the sum of
11498 all x@w{ }values, and that the height is the sum of all y@w{ }values.
11499 (The assumption about the height can be seen by examining the @code{st}
11500 and @code{sb} registers after using such a @code{D}@w{ }command in a
11501 @code{\w} escape sequence.) This rule also holds for all the original
11502 drawing commands with the exception of @code{De}. For the sake of
11503 compatibility GNU @code{troff} also follows this rule, even though it
11504 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
11505 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
11506 @code{D}@w{ }command of the form
11509 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
11513 the current position should be increased horizontally by the sum of all
11514 x@w{ }values and vertically by the sum of all y@w{ }values.
11516 @c ---------------------------------------------------------------------
11518 @node Line Continuation, , Drawing Functions, gtroff Output
11519 @subsection Line Continuation
11520 @cindex line continuation in output commands
11521 @cindex output commands, line continuation
11523 There is a continuation convention which permits the argument to the
11524 @w{@samp{x X}} command to contain newlines: When outputting the argument
11525 to the @w{@samp{x X}} command, GNU @code{troff} follows each newline
11526 in the argument with a @samp{+} character (as usual, it terminates
11527 the entire argument with a newline); thus if the line after the line
11528 containing the @w{@samp{x X}} command starts with @samp{+}, then the
11529 newline ending the line containing the @w{@samp{x X}} command should be
11530 treated as part of the argument to the @w{@samp{x X}} command, the
11531 @samp{+} should be ignored, and the part of the line following the
11532 @samp{+} should be treated like the part of the line following the
11533 @w{@samp{x X}} command.
11536 @c =====================================================================
11538 @node Font Files, , gtroff Output, File formats
11539 @section Font Files
11541 @cindex files, font
11543 The @code{gtroff} font format is roughly a superset of the
11544 @code{ditroff} font format. Unlike the @code{ditroff} font format,
11545 there is no associated binary format; all files are text files. The
11546 font files for device @var{name} are stored in a directory
11547 @file{dev@var{name}}. There are two types of file: a device description
11548 file called @file{DESC} and for each font@w{ }@var{f} a font file
11549 called@w{ }@file{@var{f}}.
11552 * DESC File Format::
11553 * Font File Format::
11556 @c ---------------------------------------------------------------------
11558 @node DESC File Format, Font File Format, Font Files, Font Files
11559 @subsection @file{DESC} File Format
11560 @cindex @file{DESC} file format
11561 @cindex font description file format
11562 @cindex format of font description file
11563 @pindex DESC@r{ file format}
11565 The @file{DESC} file can contain the following types of line:
11570 There are @var{n}@w{ }machine units per inch.
11574 The horizontal resolution is @var{n}@w{ }machine units.
11578 The vertical resolution is @var{n}@w{ }machine units.
11580 @item sizescale @var{n}
11582 The scale factor for point sizes. By default this has a value of@w{ }1.
11583 One scaled point is equal to one point/@var{n}. The arguments to the
11584 @code{unitwidth} and @code{sizes} commands are given in scaled points.
11585 @xref{Fractional Type Sizes}, for more information.
11587 @item unitwidth @var{n}
11589 Quantities in the font files are given in machine units for fonts whose
11590 point size is @var{n}@w{ }scaled points.
11594 This means that the postprocessor can handle the @samp{t} and @samp{u}
11597 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
11599 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
11600 @var{sn} scaled points. The list of sizes must be terminated by a@w{
11601 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
11602 list can extend over more than one line.
11604 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
11606 The first @var{m}@w{ }font positions are associated with styles
11607 @var{S1} @dots{} @var{Sm}.
11609 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
11611 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
11612 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
11613 styles. This command may extend over more than one line. A font name
11614 of@var{ }0 means no font is mounted on the corresponding font position.
11616 @item family @var{fam}
11618 The default font family is @var{fam}.
11622 This line and everything following in the file are ignored. It is
11623 allowed for the sake of backwards compatibility.
11626 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
11627 are mandatory. Other commands are ignored by @code{gtroff} but may be
11628 used by postprocessors to store arbitrary information about the device
11629 in the @file{DESC} file.
11631 @c XXX add other commands resp. xrefs to output devices
11632 @c XXX add obsolete commands
11634 @c ---------------------------------------------------------------------
11636 @node Font File Format, , DESC File Format, Font Files
11637 @subsection Font File Format
11638 @cindex font file format
11639 @cindex format of font files
11641 A font file has two sections. The first section is a sequence of lines
11642 each containing a sequence of blank delimited words; the first word in
11643 the line is a key, and subsequent words give a value for that key.
11648 The name of the font is@w{ }@var{f}.
11650 @item spacewidth @var{n}
11652 The normal width of a space is@w{ }@var{n}.
11654 @item slant @var{n}
11656 The characters of the font have a slant of @var{n}@w{ }degrees.
11657 (Positive means forward.)
11659 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
11661 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
11662 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
11663 @samp{ffl}. For backwards compatibility, the list of ligatures may be
11664 terminated with a@w{ }0. The list of ligatures may not extend over more
11669 The font is special; this means that when a character is requested that
11670 is not present in the current font, it is searched for in any
11671 special fonts that are mounted.
11674 Other commands are ignored by @code{gtroff} but may be used by
11675 postprocessors to store arbitrary information about the font in the font
11678 @cindex comments in font files
11679 @cindex font files, comments
11681 The first section can contain comments which start with the @samp{#}
11682 character and extend to the end of a line.
11684 The second section contains one or two subsections. It must contain a
11685 @code{charset} subsection and it may also contain a @code{kernpairs}
11686 subsection. These subsections can appear in any order. Each
11687 subsection starts with a word on a line by itself.
11690 The word @code{charset} starts the character set subsection. The
11691 @code{charset} line is followed by a sequence of lines. Each line gives
11692 information for one character. A line comprises a number of fields
11693 separated by blanks or tabs. The format is
11695 @c XXX fix it for new HTML additions
11698 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
11701 @cindex 8-bit input
11702 @cindex input, 8-bit
11703 @cindex accessing unnamed characters with @code{\N}
11704 @cindex unnamed characters, accessing with @code{\N}
11705 @cindex characters, unnamed, accessing with @code{\N}
11708 @var{name} identifies the character: If @var{name} is a single
11709 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
11710 character@w{ }@var{c}; if it is of the form @samp{\@var{c}} where @var{c}
11711 is a single character, then it corresponds to the @code{gtroff} input
11712 character@w{ }\@var{c}; otherwise it corresponds to the groff input
11713 character @samp{\[@var{name}]}. (If it is exactly two characters
11714 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
11715 supports 8-bit characters; however some utilities have difficulties with
11716 eight-bit characters. For this reason, there is a convention that the
11717 name @samp{char@var{n}} is equivalent to the single character whose code
11718 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
11719 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
11720 Latin-1} character set. The name @samp{---} is special and indicates
11721 that the character is unnamed; such characters can only be used by means
11722 of the @code{\N} escape sequence in @code{gtroff}.
11724 @c XXX input encodings vs. output encodings
11726 The @var{type} field gives the character type:
11730 the character has an descender, for example, `p';
11733 the character has an ascender, for example, `b';
11736 the character has both an ascender and a descender, for example, `('.
11739 The @var{code} field gives the code which the postprocessor uses to
11740 print the character. The character can also be input to @code{gtroff}
11741 using this code by means of the @code{\N} escape sequence. The code can
11742 be any integer. If it starts with @samp{0} it is interpreted as
11743 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
11746 Anything on the line after the @var{code} field is ignored.
11748 The @var{metrics} field has the form:
11751 @var{width}[,@var{height}[,@var{depth}[,@var{italic_correction}
11752 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]]
11756 There must not be any spaces between these subfields (it has been split
11757 here into two lines for better legibility only). Missing subfields are
11758 assumed to be@w{ }0. The subfields are all decimal integers. Since
11759 there is no associated binary format, these values are not required to
11760 fit into a variable of type @samp{char} as they are in @code{ditroff}.
11761 The @var{width} subfield gives the width of the character. The
11762 @var{height} subfield gives the height of the character (upwards is
11763 positive); if a character does not extend above the baseline, it should
11764 be given a zero height, rather than a negative height. The @var{depth}
11765 subfield gives the depth of the character, that is, the distance below
11766 the lowest point below the baseline to which the character extends
11767 (downwards is positive); if a character does not extend below above the
11768 baseline, it should be given a zero depth, rather than a negative depth.
11769 The @var{italic_correction} subfield gives the amount of space that
11770 should be added after the character when it is immediately to be
11771 followed by a character from a roman font. The
11772 @var{left_italic_correction} subfield gives the amount of space that
11773 should be added before the character when it is immediately to be
11774 preceded by a character from a roman font. The
11775 @var{subscript_correction} gives the amount of space that should be
11776 added after a character before adding a subscript. This should be less
11777 than the italic correction.
11779 A line in the @code{charset} section can also have the format
11786 This indicates that @var{name} is just another name for the character
11787 mentioned in the preceding line.
11790 The word @code{kernpairs} starts the kernpairs section. This contains a
11791 sequence of lines of the form:
11794 @var{c1} @var{c2} @var{n}
11798 This means that when character @var{c1} appears next to character
11799 @var{c2} the space between them should be increased by@w{ }@var{n}.
11800 Most entries in the kernpairs section have a negative value for@w{
11805 @c =====================================================================
11806 @c =====================================================================
11808 @node Installation, Request Index, File formats, Top
11809 @chapter Installation
11810 @cindex installation
11816 @c =====================================================================
11817 @c =====================================================================
11819 @node Request Index, Escape Index, Installation, Top
11820 @chapter Request Index
11822 Requests appear without the leading control character (normally either
11823 @samp{.} or @samp{'}).
11829 @c =====================================================================
11830 @c =====================================================================
11832 @node Escape Index, Operator Index, Request Index, Top
11833 @chapter Escape Index
11839 @c =====================================================================
11840 @c =====================================================================
11842 @node Operator Index, Register Index, Escape Index, Top
11843 @chapter Operator Index
11849 @c =====================================================================
11850 @c =====================================================================
11852 @node Register Index, Macro Index, Operator Index, Top
11853 @chapter Register Index
11855 The macro package a specific register belongs to is appended in brackets.
11857 A register name@w{ }@code{x} consisting of exactly one character can be
11858 accessed as @samp{\nx}. A register name @code{xx} consisting of exactly
11859 two characters can be accessed as @samp{\n(xx}. Register names @code{xxx}
11860 of any length can be accessed as @samp{\n[xxx]}.
11866 @c =====================================================================
11867 @c =====================================================================
11869 @node Macro Index, String Index, Register Index, Top
11870 @chapter Macro Index
11872 The macro package a specific macro belongs to is appended in brackets.
11873 They appear without the leading control character (normally @samp{.}).
11879 @c =====================================================================
11880 @c =====================================================================
11882 @node String Index, Glyph Name Index, Macro Index, Top
11883 @chapter String Index
11885 The macro package a specific string belongs to is appended in brackets.
11887 A string name@w{ }@code{x} consisting of exactly one character can be
11888 accessed as @samp{\*x}. A string name @code{xx} consisting of exactly
11889 two characters can be accessed as @samp{\*(xx}. String names @code{xxx}
11890 of any length can be accessed as @samp{\*[xxx]}.
11897 @c =====================================================================
11898 @c =====================================================================
11900 @node Glyph Name Index, Font File Keyword Index, String Index, Top
11901 @chapter Glyph Name Index
11903 A glyph name @code{xx} consisting of exactly two characters can be
11904 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
11905 accessed as @samp{\[xxx]}.
11911 @c =====================================================================
11912 @c =====================================================================
11914 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
11915 @chapter Font File Keyword Index
11921 @c =====================================================================
11922 @c =====================================================================
11924 @node Program and File Index, Concept Index, Font File Keyword Index, Top
11925 @chapter Program and File Index
11931 @c =====================================================================
11932 @c =====================================================================
11934 @node Concept Index, , Program and File Index, Top
11935 @chapter Concept Index