groff.texinfo revision 79543
1\input texinfo @c -*-texinfo-*- 2 3@c 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. 6@c 7 8@c %**start of header (This is for running Texinfo on a region.) 9@setfilename groff 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.) 14 15 16@c We use the following indices: 17@c 18@c cindex: concepts 19@c rqindex: requests 20@c esindex: escapes 21@c vindex: registers 22@c kindex: commands in font files 23@c pindex: programs and files 24@c tindex: environment variables 25@c maindex: macros 26@c stindex: strings 27@c glindex: glyph names 28@c opindex: operators 29@c 30@c tindex and cindex are merged. 31 32@defcodeindex rq 33@defcodeindex es 34@defcodeindex ma 35@defcodeindex st 36@defcodeindex gl 37@defcodeindex op 38@syncodeindex tp cp 39 40 41@c to avoid uppercasing in @deffn while converting to info, we define 42@c our special @Var{} 43@c 44@c due to a (not officially documented) `feature' in makeinfo 4.0, 45@c macros are not expanded in @deffn (but the macro definition is 46@c properly removed), so we have to define @Var{} directly in TeX also 47 48@macro Var{arg} 49\arg\ 50@end macro 51@tex 52\gdef\Var#1{\var{#1}} 53@end tex 54 55 56@c definition of requests 57 58@macro Defreq{name, arg} 59@rqindex \name\ 60@deffn Request @t{.\name\} \arg\ 61@end macro 62 63@macro Defreqx{name, arg} 64@rqindex \name\ 65@deffnx Request @t{.\name\} \arg\ 66@end macro 67 68@macro endDefreq 69@end deffn 70@end macro 71 72 73@c definition of escapes 74 75@macro Defesc{name, delimI, arg, delimII} 76@esindex \name\ 77@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 78@end macro 79 80@macro Defescx{name, delimI, arg, delimII} 81@esindex \name\ 82@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 83@end macro 84 85@macro endDefesc 86@end deffn 87@end macro 88 89 90@c definition of registers 91 92@macro Defreg{name} 93@vindex \name\ 94@deffn Register @t{\\n[\name\]} 95@end macro 96 97@macro Defregx{name} 98@vindex \name\ 99@deffnx Register @t{\\n[\name\]} 100@end macro 101 102@macro endDefreg 103@end deffn 104@end macro 105 106 107@c definition of macros 108 109@macro Defmac{name, arg} 110@maindex \name\ 111@defmac @t{.\name\} \arg\ 112@end macro 113 114@macro Defmacx{name, arg} 115@maindex \name\ 116@defmacx @t{.\name\} \arg\ 117@end macro 118 119@macro endDefmac 120@end defmac 121@end macro 122 123 124@c definition of strings 125 126@macro Defstr{name, arg} 127@stindex \name\ 128@deffn String @t{\name\} \arg\ 129@end macro 130 131@macro Defstrx{name, arg} 132@stindex \name\ 133@deffnx String @t{\name\} \arg\ 134@end macro 135 136@macro endDefstr 137@end deffn 138@end macro 139 140 141@c our example macro 142 143@macro Example 144@example 145@group 146@end macro 147 148@macro endExample 149@end group 150@end example 151@end macro 152 153 154@c We need special parentheses and brackets: 155@c 156@c . Real parentheses in @deffn produce an error while compiling with 157@c TeX 158@c . Real brackets use the wrong font in @deffn, overriding @t{}. 159@c 160@c This is true for texinfo 4.0. 161 162@ifnottex 163@macro lparen 164( 165@end macro 166@macro rparen 167) 168@end macro 169@macro lbrack 170[ 171@end macro 172@macro rbrack 173] 174@end macro 175@end ifnottex 176 177@iftex 178@macro lparen 179@@lparen 180@end macro 181@macro rparen 182@@rparen 183@end macro 184@macro lbrack 185@@lbrack 186@end macro 187@macro rbrack 188@@rbrack 189@end macro 190@end iftex 191 192 193@c Note: We say `Roman numerals' but `roman font'. 194 195 196@c XXX comment all examples 197 198 199@dircategory Miscellaneous 200@direntry 201* Groff: (groff). The GNU troff document formatting system. 202@end direntry 203 204 205@smallbook 206 207 208@iftex 209@finalout 210@end iftex 211 212 213@ifinfo 214This Info file documents GNU troff version 1.16. 215 216Published by the Free Software Foundation 21759 Temple Place, Suite 330 218Boston, MA 02111-1307 USA 219 220Copyright (C) 1994-2000 Free Software Foundation, Inc. 221 222Permission is granted to make and distribute verbatim copies of this 223manual provided the copyright notice and this permission notice are 224preserved on all copies. 225 226@ignore 227Permission is granted to process this file through TeX and print the 228results, provided the printed document carries copying permission notice 229identical to this one except for the removal of this paragraph (this 230paragraph not being relevant to the printed manual). 231 232@end ignore 233Permission is granted to copy and distribute modified versions of this 234manual under the conditions for verbatim copying, provided that the 235entire resulting derived work is distributed under the terms of a 236permission notice identical to this one. 237 238Permission is granted to copy and distribute translations of this manual 239into another language, under the above conditions for modified versions, 240except that this permission notice may be stated in a translation 241approved by the Foundation. 242 243Permission is granted to copy and distribute modified versions of this 244manual under the conditions for verbatim copying, provided also that the 245section entitled ``GNU General Public License'' is included exactly as 246in the original, and provided that the entire resulting derived work is 247distributed under the terms of a permission notice identical to this 248one. 249 250Permission is granted to copy and distribute translations of this manual 251into another language, under the above conditions for modified versions, 252except that the section entitled ``GNU General Public License'' may be 253included in a translation approved by the Free Software Foundation 254instead of in the original English. 255@end ifinfo 256 257 258@titlepage 259@title groff 260@subtitle The GNU implementation of @code{troff} 261@subtitle Edition 1.16 262@subtitle Spring 2000 263@author by Trent A.@w{ }Fisher 264@author and Werner Lemberg 265 266@c Include the Distribution inside the titlepage environment so 267@c that headings are turned off. Headings on and off do not work. 268 269@page 270@vskip 0pt plus 1filll 271Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc. 272@sp 2 273Version 1.16 of @code{groff}, @* 274Spring 2000 275@sp 2 276Published by the Free Software Foundation @* 27759 Temple Place, Suite 330 @* 278Boston, MA 02111-1307 USA 279 280 281Permission is granted to make and distribute verbatim copies of this 282manual provided the copyright notice and this permission notice are 283preserved on all copies. 284 285Permission is granted to copy and distribute modified versions of this 286manual under the conditions for verbatim copying, provided also that the 287section entitled ``GNU General Public License'' is included exactly as 288in the original, and provided that the entire resulting derived work is 289distributed under the terms of a permission notice identical to this 290one. 291 292Permission is granted to copy and distribute translations of this manual 293into another language, under the above conditions for modified versions, 294except that the section entitled ``GNU General Public License'' may be 295included in a translation approved by the Free Software Foundation 296instead of in the original English. 297 298Cover art by Etienne Suvasa. 299@end titlepage 300@page 301 302 303 304@node Top, Copying, (dir), (dir) 305 306@ifinfo 307This Info file documents groff version 1.16, the GNU implementation of 308the troff typesetting system. 309 310This is an in-progress document; contributions, comments, or 311contributions are welcome. Send them to bug-groff@@gnu.org. 312@end ifinfo 313 314@menu 315* Copying:: 316* Introduction:: 317* Invoking groff:: 318* Tutorial for Macro Users:: 319* Macro Packages:: 320* gtroff Reference:: 321* Preprocessors:: 322* Output Devices:: 323* File formats:: 324* Installation:: 325* Request Index:: 326* Escape Index:: 327* Operator Index:: 328* Register Index:: 329* Macro Index:: 330* String Index:: 331* Glyph Name Index:: 332* Font File Keyword Index:: 333* Program and File Index:: 334* Concept Index:: 335@end menu 336 337 338 339@node Copying, Introduction, Top, Top 340@cindex copying 341@unnumbered GNU GENERAL PUBLIC LICENSE 342@center Version 2, June 1991 343 344@display 345Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc. 34659@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA 347 348Everyone is permitted to copy and distribute verbatim copies of this 349license document, but changing it is not allowed. 350@end display 351 352@unnumberedsec Preamble 353 354The licenses for most software are designed to take away your freedom to 355share and change it. By contrast, the GNU General Public License is 356intended to guarantee your freedom to share and change free software -- 357to make sure the software is free for all its users. This General 358Public License applies to most of the Free Software Foundation's 359software and to any other program whose authors commit to using it. 360(Some other Free Software Foundation software is covered by the GNU 361Library General Public License instead.) You can apply it to your 362programs, too. 363 364When we speak of free software, we are referring to freedom, not price. 365Our General Public Licenses are designed to make sure that you have the 366freedom to distribute copies of free software (and charge for this 367service if you wish), that you receive source code or can get it if you 368want it, that you can change the software or use pieces of it in new 369free programs; and that you know you can do these things. 370 371To protect your rights, we need to make restrictions that forbid anyone 372to deny you these rights or to ask you to surrender the rights. These 373restrictions translate to certain responsibilities for you if you 374distribute copies of the software, or if you modify it. 375 376For example, if you distribute copies of such a program, whether gratis 377or for a fee, you must give the recipients all the rights that you have. 378You must make sure that they, too, receive or can get the source code. 379And you must show them these terms so they know their rights. 380 381We protect your rights with two steps: (1)@w{ }copyright the software, 382and (2)@w{ }offer you this license which gives you legal permission to 383copy, distribute and/or modify the software. 384 385Also, for each author's protection and ours, we want to make certain 386that everyone understands that there is no warranty for this free 387software. If the software is modified by someone else and passed on, we 388want its recipients to know that what they have is not the original, so 389that any problems introduced by others will not reflect on the original 390authors' reputations. 391 392Finally, any free program is threatened constantly by software patents. 393We wish to avoid the danger that redistributors of a free program will 394individually obtain patent licenses, in effect making the program 395proprietary. To prevent this, we have made it clear that any patent 396must be licensed for everyone's free use or not licensed at all. 397 398The precise terms and conditions for copying, distribution and 399modification follow. 400 401@iftex 402@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 403@end iftex 404@ifinfo 405@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 406@end ifinfo 407 408@enumerate 0 409@item 410This License applies to any program or other work which contains a 411notice placed by the copyright holder saying it may be distributed under 412the terms of this General Public License. The ``Program'', below, 413refers to any such program or work, and a ``work based on the Program'' 414means either the Program or any derivative work under copyright law: 415that is to say, a work containing the Program or a portion of it, either 416verbatim or with modifications and/or translated into another language. 417(Hereinafter, translation is included without limitation in the term 418``modification''.) Each licensee is addressed as ``you''. 419 420Activities other than copying, distribution and modification are not 421covered by this License; they are outside its scope. The act of running 422the Program is not restricted, and the output from the Program is 423covered only if its contents constitute a work based on the Program 424(independent of having been made by running the Program). Whether that 425is true depends on what the Program does. 426 427@item 428You may copy and distribute verbatim copies of the Program's source code 429as you receive it, in any medium, provided that you conspicuously and 430appropriately publish on each copy an appropriate copyright notice and 431disclaimer of warranty; keep intact all the notices that refer to this 432License and to the absence of any warranty; and give any other 433recipients of the Program a copy of this License along with the Program. 434 435You may charge a fee for the physical act of transferring a copy, and 436you may at your option offer warranty protection in exchange for a fee. 437 438@item 439You may modify your copy or copies of the Program or any portion of it, 440thus forming a work based on the Program, and copy and distribute such 441modifications or work under the terms of Section@w{ }1 above, provided 442that you also meet all of these conditions: 443 444@enumerate a 445@item 446You must cause the modified files to carry prominent notices stating 447that you changed the files and the date of any change. 448 449@item 450You must cause any work that you distribute or publish, that in whole or 451in part contains or is derived from the Program or any part thereof, to 452be licensed as a whole at no charge to all third parties under the terms 453of this License. 454 455@item 456If the modified program normally reads commands interactively when run, 457you must cause it, when started running for such interactive use in the 458most ordinary way, to print or display an announcement including an 459appropriate copyright notice and a notice that there is no warranty (or 460else, saying that you provide a warranty) and that users may 461redistribute the program under these conditions, and telling the user 462how to view a copy of this License. (Exception: if the Program itself 463is interactive but does not normally print such an announcement, your 464work based on the Program is not required to print an announcement.) 465@end enumerate 466 467These requirements apply to the modified work as a whole. If 468identifiable sections of that work are not derived from the Program, and 469can be reasonably considered independent and separate works in 470themselves, then this License, and its terms, do not apply to those 471sections when you distribute them as separate works. But when you 472distribute the same sections as part of a whole which is a work based on 473the Program, the distribution of the whole must be on the terms of this 474License, whose permissions for other licensees extend to the entire 475whole, and thus to each and every part regardless of who wrote it. 476 477Thus, it is not the intent of this section to claim rights or contest 478your rights to work written entirely by you; rather, the intent is to 479exercise the right to control the distribution of derivative or 480collective works based on the Program. 481 482In addition, mere aggregation of another work not based on the Program 483with the Program (or with a work based on the Program) on a volume of a 484storage or distribution medium does not bring the other work under the 485scope of this License. 486 487@item 488You may copy and distribute the Program (or a work based on it, under 489Section@w{ }2) in object code or executable form under the terms of 490Sections@w{ }1 and@w{ }2 above provided that you also do one of the 491following: 492 493@enumerate a 494@item 495Accompany it with the complete corresponding machine-readable source 496code, which must be distributed under the terms of Sections@w{ }1 and@w{ 497}2 above on a medium customarily used for software interchange; or, 498 499@item 500Accompany it with a written offer, valid for at least three years, to 501give any third party, for a charge no more than your cost of physically 502performing source distribution, a complete machine-readable copy of the 503corresponding source code, to be distributed under the terms of 504Sections@w{ }1 and@w{ }2 above on a medium customarily used for software 505interchange; or, 506 507@item 508Accompany it with the information you received as to the offer to 509distribute corresponding source code. (This alternative is allowed only 510for noncommercial distribution and only if you received the program in 511object code or executable form with such an offer, in accord with 512Subsection@w{ }b above.) 513@end enumerate 514 515The source code for a work means the preferred form of the work for 516making modifications to it. For an executable work, complete source 517code means all the source code for all modules it contains, plus any 518associated interface definition files, plus the scripts used to control 519compilation and installation of the executable. However, as a special 520exception, the source code distributed need not include anything that is 521normally distributed (in either source or binary form) with the major 522components (compiler, kernel, and so on) of the operating system on 523which the executable runs, unless that component itself accompanies the 524executable. 525 526If distribution of executable or object code is made by offering access 527to copy from a designated place, then offering equivalent access to copy 528the source code from the same place counts as distribution of the source 529code, even though third parties are not compelled to copy the source 530along with the object code. 531 532@item 533You may not copy, modify, sublicense, or distribute the Program except 534as expressly provided under this License. Any attempt otherwise to 535copy, modify, sublicense or distribute the Program is void, and will 536automatically terminate your rights under this License. However, 537parties who have received copies, or rights, from you under this License 538will not have their licenses terminated so long as such parties remain 539in full compliance. 540 541@item 542You are not required to accept this License, since you have not signed 543it. However, nothing else grants you permission to modify or distribute 544the Program or its derivative works. These actions are prohibited by 545law if you do not accept this License. Therefore, by modifying or 546distributing the Program (or any work based on the Program), you 547indicate your acceptance of this License to do so, and all its terms and 548conditions for copying, distributing or modifying the Program or works 549based on it. 550 551@item 552Each time you redistribute the Program (or any work based on the 553Program), the recipient automatically receives a license from the 554original licensor to copy, distribute or modify the Program subject to 555these terms and conditions. You may not impose any further restrictions 556on the recipients' exercise of the rights granted herein. You are not 557responsible for enforcing compliance by third parties to this License. 558 559@item 560If, as a consequence of a court judgment or allegation of patent 561infringement or for any other reason (not limited to patent issues), 562conditions are imposed on you (whether by court order, agreement or 563otherwise) that contradict the conditions of this License, they do not 564excuse you from the conditions of this License. If you cannot 565distribute so as to satisfy simultaneously your obligations under this 566License and any other pertinent obligations, then as a consequence you 567may not distribute the Program at all. For example, if a patent license 568would not permit royalty-free redistribution of the Program by all those 569who receive copies directly or indirectly through you, then the only way 570you could satisfy both it and this License would be to refrain entirely 571from distribution of the Program. 572 573If any portion of this section is held invalid or unenforceable under 574any particular circumstance, the balance of the section is intended to 575apply and the section as a whole is intended to apply in other 576circumstances. 577 578It is not the purpose of this section to induce you to infringe any 579patents or other property right claims or to contest validity of any 580such claims; this section has the sole purpose of protecting the 581integrity of the free software distribution system, which is implemented 582by public license practices. Many people have made generous 583contributions to the wide range of software distributed through that 584system in reliance on consistent application of that system; it is up to 585the author/donor to decide if he or she is willing to distribute 586software through any other system and a licensee cannot impose that 587choice. 588 589This section is intended to make thoroughly clear what is believed to be 590a consequence of the rest of this License. 591 592@item 593If the distribution and/or use of the Program is restricted in certain 594countries either by patents or by copyrighted interfaces, the original 595copyright holder who places the Program under this License may add an 596explicit geographical distribution limitation excluding those countries, 597so that distribution is permitted only in or among countries not thus 598excluded. In such case, this License incorporates the limitation as if 599written in the body of this License. 600 601@item 602The Free Software Foundation may publish revised and/or new versions of 603the General Public License from time to time. Such new versions will be 604similar in spirit to the present version, but may differ in detail to 605address new problems or concerns. 606 607Each version is given a distinguishing version number. If the Program 608specifies a version number of this License which applies to it and ``any 609later version'', you have the option of following the terms and 610conditions either of that version or of any later version published by 611the Free Software Foundation. If the Program does not specify a version 612number of this License, you may choose any version ever published by the 613Free Software Foundation. 614 615@item 616If you wish to incorporate parts of the Program into other free programs 617whose distribution conditions are different, write to the author to ask 618for permission. For software which is copyrighted by the Free Software 619Foundation, write to the Free Software Foundation; we sometimes make 620exceptions for this. Our decision will be guided by the two goals of 621preserving the free status of all derivatives of our free software and 622of promoting the sharing and reuse of software generally. 623 624@iftex 625@heading NO WARRANTY 626@end iftex 627@ifinfo 628@center NO WARRANTY 629@end ifinfo 630 631@item 632BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR 633THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN 634OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 635PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER 636EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 637WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. 638THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH 639YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 640NECESSARY SERVICING, REPAIR OR CORRECTION. 641 642@item 643IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 644WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 645REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 646DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL 647DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM 648(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED 649INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF 650THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR 651OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 652@end enumerate 653 654@iftex 655@heading END OF TERMS AND CONDITIONS 656@end iftex 657@ifinfo 658@center END OF TERMS AND CONDITIONS 659@end ifinfo 660 661 662@page 663@unnumberedsec How to Apply These Terms to Your New Programs 664 665If you develop a new program, and you want it to be of the greatest 666possible use to the public, the best way to achieve this is to make it 667free software which everyone can redistribute and change under these 668terms. 669 670To do so, attach the following notices to the program. It is safest to 671attach them to the start of each source file to most effectively convey 672the exclusion of warranty; and each file should have at least the 673``copyright'' line and a pointer to where the full notice is found. 674 675@smallexample 676@var{one line to give the program's name and an idea of what it does.} 677Copyright (C) 19@var{yy} @var{name of author} 678 679This program is free software; you can redistribute it and/or modify 680it under the terms of the GNU General Public License as published by 681the Free Software Foundation; either version 2 of the License, or (at 682your option) any later version. 683 684This program is distributed in the hope that it will be useful, but 685WITHOUT ANY WARRANTY; without even the implied warranty of 686MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU 687General Public License for more details. 688 689You should have received a copy of the GNU General Public License 690along with this program; if not, write to the Free Software 691Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. 692@end smallexample 693 694Also add information on how to contact you by electronic and paper mail. 695 696If the program is interactive, make it output a short notice like this 697when it starts in an interactive mode: 698 699@smallexample 700Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} 701Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 702`show w'. This is free software, and you are welcome to redistribute 703it under certain conditions; type `show c' for details. 704@end smallexample 705 706The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should 707show the appropriate parts of the General Public License. Of course, 708the commands you use may be called something other than @samp{show@w{ 709}w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items 710-- whatever suits your program. 711 712You should also get your employer (if you work as a programmer) or your 713school, if any, to sign a ``copyright disclaimer'' for the program, if 714necessary. Here is a sample; alter the names: 715 716@smallexample 717@group 718Yoyodyne, Inc., hereby disclaims all copyright interest 719in the program `Gnomovision' (which makes passes at compilers) 720written by James Hacker. 721 722@var{signature of Ty Coon}, 1 April 1989 723Ty Coon, President of Vice 724@end group 725@end smallexample 726 727This General Public License does not permit incorporating your program 728into proprietary programs. If your program is a subroutine library, you 729may consider it more useful to permit linking proprietary applications 730with the library. If this is what you want to do, use the GNU Library 731General Public License instead of this License. 732 733 734 735@c ===================================================================== 736@c ===================================================================== 737 738@node Introduction, Invoking groff, Copying, Top 739@chapter Introduction 740@cindex introduction 741 742GNU @code{troff} (or @code{groff}) is a system for typesetting 743documents. @code{troff} is very flexible and has been in existence (and 744use) for about 3@w{ }decades. It is quite widespread and firmly 745entrenched in the @acronym{UNIX} community. 746 747@menu 748* What Is groff?:: 749* History:: 750* groff Capabilities:: 751* Macro Package Intro:: 752* Preprocessor Intro:: 753* Output device intro:: 754* Credits:: 755@end menu 756 757 758@c ===================================================================== 759 760@node What Is groff?, History, Introduction, Introduction 761@section What Is @code{groff}? 762@cindex what is @code{groff}? 763@cindex @code{groff} -- what is it? 764 765@code{groff} belongs to an older generation of document preparation 766systems, which operate more like compilers than the more recent 767interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 768systems. @code{groff} and its contemporary counterpart, @TeX{}, both 769work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 770normal text files with embedded formatting commands. These files can 771then be processed by @code{groff} to produce a typeset document on a 772variety of devices. 773 774Likewise, @code{groff} should not be confused with a @dfn{word 775processor}, since that term connotes an integrated system that includes 776an editor and a text formatter. Also, many word processors follow the 777@acronym{WYSIWYG} paradigm discussed earlier. 778 779Although @acronym{WYSIWYG} systems may be easier to use, they have a 780number of disadvantages compared to @code{troff}: 781 782@itemize @bullet 783@item 784They must be used on a graphics display to work on a document. 785 786@item 787Most of the @acronym{WYSIWYG} systems are either non-free or are not 788very portable. 789 790@item 791@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 792 793@item 794It is difficult to have a wide range of capabilities available within 795the confines of a GUI/window system. 796 797@item 798It is more difficult to make global changes to a document. 799@end itemize 800 801@quotation 802``GUIs normally make it simple to accomplish simple actions and 803impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 804@code{comp.unix.wizards}) 805@end quotation 806 807 808@c ===================================================================== 809 810@node History, groff Capabilities, What Is groff?, Introduction 811@section History 812@cindex history 813 814@cindex @code{runoff} 815@cindex @code{rf} 816@code{troff} can trace its origins back to a formatting program called 817@code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS 818operating system in the mid-sixties. This name came from the common 819phrase of the time ``I'll run off a document.'' Bob Morris ported it to 820the 635 architecture and called the program @code{roff} (an abbreviation 821of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 822(before having @acronym{UNIX}), and at the same time (1969), Doug 823McIllroy rewrote an extended and simplified version of @code{roff} in 824the @acronym{BCPL} programming language. 825 826@cindex @code{roff} 827The first version of @acronym{UNIX} was developed on a @w{PDP-7} which 828was sitting around Bell Labs. In 1971 the developers wanted to get a 829@w{PDP-11} for further work on the operating system. In order to 830justify the cost for this system, they proposed that they would 831implement a document formatting system for the AT&T patents division. 832This first formatting program was a reimplementation of McIllroy's 833@code{roff}, written by J.@w{ }F.@w{ }Ossanna. 834 835@cindex @code{nroff} 836When they needed a more flexible language, a new version of @code{roff} 837called @code{nroff} (``Newer @code{roff}'') was written. It had a much 838more complicated syntax, but provided the basis for all future versions. 839When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 840version of @code{nroff} that would drive it. It was dubbed 841@code{troff}, for ``typesetter @code{roff}'', although many people have 842speculated that it actually means ``Times @code{roff}'' because of the 843use of the Times font family in @code{troff} by default. As such, the 844name @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 845 846With @code{troff} came @code{nroff} (they were actually the same program 847except for some @samp{#ifdef}s), which was for producing output for line 848printers and character terminals. It understood everything @code{troff} 849did, and ignored the commands which were not applicable (e.g.@: font 850changes). 851 852Since there are several things which cannot be done easily in 853@code{troff}, work on several preprocessors began. These programs would 854transform certain parts of a document into @code{troff}, which made a 855very natural use of pipes in @acronym{UNIX}. 856 857The @code{eqn} preprocessor allowed mathematical formul@ae{} to be 858specified in a much simpler and more intuitive manner. @code{tbl} is a 859preprocessor for formatting tables. The @code{refer} preprocessor (and 860the similar program, @code{bib}) processes citations in a document 861according to a bibliographic database. 862 863Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 864language and produced output specifically for the CAT phototypesetter. 865He rewrote it in C, although it was now 7000@w{ }lines of uncommented 866code and still dependent on the CAT. As the CAT became less common, and 867was no longer supported by the manufacturer, the need to make it support 868other devices became a priority. However, before this could be done, 869Ossanna was killed in an auto accident. 870 871@pindex ditroff 872@cindex @code{ditroff} 873So, Brian Kernighan took on the task of rewriting @code{troff}. The 874newly rewritten version produced a device independent code which was 875very easy for postprocessors to read and translate to the appropriate 876printer codes. Also, this new version of @code{troff} (called 877@code{ditroff} for ``device independent @code{troff}'') had several 878extensions, which included drawing functions. 879 880Due to the additional abilities of the new version of @code{troff}, 881several new preprocessors appeared. The @code{pic} preprocessor 882provides a wide range of drawing functions. Likewise the @code{ideal} 883preprocessor did the same, although via a much different paradigm. The 884@code{grap} preprocessor took specifications for graphs, but, unlike 885other preprocessors, produced @code{pic} code. 886 887James Clark began work on a GNU implementation of @code{ditroff} in 888early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released 889June@w{ }1990. @code{groff} included: 890 891@itemize @bullet 892@item 893A replacement for @code{ditroff} with many extensions. 894 895@item 896The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 897 898@item 899Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 900X@w{ }windows. GNU @code{troff} also eliminated the need for a 901separate @code{nroff} program with a postprocessor which would produce 902@acronym{ASCII} output. 903 904@item 905A version of the @file{me} macros and an implementation of the 906@file{man} macros. 907@end itemize 908 909Also, a front-end was included which could construct the, sometimes 910painfully long, pipelines required for all the post- and preprocessors. 911 912Development of GNU @code{troff} progressed rapidly, and saw the 913additions of a replacement for @code{refer}, an implementation of the 914@file{ms} and @file{mm} macros, and a program to deduce how to format a 915document (@code{grog}). 916 917It was declared a stable (i.e.@: non-beta) package with the release of 918version@w{ }1.04 around November@w{ }1991. 919 920Beginning in@w{ }1999, @code{groff} has new maintainers (the package was 921an orphan for a few years). As a result, new features and programs like 922@code{grn}, a preprocessor for gremlin images, and an output device to 923produce @acronym{HTML} output have been added. 924 925 926@c ===================================================================== 927 928@node groff Capabilities, Macro Package Intro, History, Introduction 929@section @code{groff} Capabilities 930@cindex @code{groff} capabilities 931@cindex capabilities of @code{groff} 932 933So what exactly is @code{groff} capable of doing? @code{groff} provides 934a wide range of low-level text formatting operations. Using these, it 935is possible to perform a wide range of formatting tasks, such as 936footnotes, table of contents, multiple columns, etc. Here's a list of 937the most important operations supported by @code{groff}: 938 939@itemize @bullet 940@item 941text filling, adjusting, and centering 942 943@item 944hyphenation 945 946@item 947page control 948 949@item 950font and character size control 951 952@item 953vertical spacing (i.e.@: double spacing) 954 955@item 956line length and indenting 957 958@item 959macros, strings, diversions, and traps 960 961@item 962number registers 963 964@item 965tabs, leaders, and fields 966 967@item 968input and output conventions and character translation 969 970@item 971overstrike, bracket, line drawing, and zero-width functions 972 973@item 974local horizontal and vertical motions and the width function 975 976@item 977three-part titles 978 979@item 980output line numbering 981 982@item 983conditional acceptance of input 984 985@item 986environment switching 987 988@item 989insertions from the standard input 990 991@item 992input/output file switching 993 994@item 995output and error messages 996@end itemize 997 998 999@c ===================================================================== 1000 1001@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 1002@section Macro Packages 1003@cindex macro packages 1004 1005Since @code{groff} provides such low-level facilities, it can be quite 1006difficult to use by itself. However, @code{groff} provides a 1007@dfn{macro} facility to specify how certain routine operations (e.g.@w{ 1008}starting paragraphs, printing headers and footers, etc.)@: should be 1009done. These macros can be collected together into a @dfn{macro 1010package}. There are a number of macro packages available; the most 1011common (and the ones described in this manual) are @file{man}, 1012@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 1013 1014 1015@c ===================================================================== 1016 1017@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 1018@section Preprocessors 1019@cindex preprocessors 1020 1021Although @code{groff} provides most functions needed to format a 1022document, some operations would be unwieldy (e.g.@: to draw pictures). 1023Therefore, programs called preprocessors were written which understand 1024their own language and produce the necessary @code{groff} operations. 1025These preprocessors are able to differentiate their own input from the 1026rest of the document via markers. 1027 1028To use a preprocessor, @acronym{UNIX} pipes are used to feed the output 1029from the preprocessor into @code{groff}. Any number of preprocessors 1030may be used on a given document; in this case, the preprocessors are 1031linked together into one pipeline. However, in @code{groff}, the user 1032does not need to construct the pipe, but only tell @code{groff} what 1033preprocessors to use. 1034 1035@code{groff} currently has preprocessors for producing tables 1036(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 1037(@code{pic} and @code{grn}), and for processing bibliographies 1038(@code{refer}). An associated program which is useful when dealing with 1039preprocessors is @code{soelim}. 1040 1041A free implementation of @code{grap}, a preprocessor for drawing graphs, 1042can be obtained as an extra package; @code{groff} can use @code{grap} 1043also. 1044 1045There are other preprocessors in existence, but, unfortunately, no free 1046implementations are available. Among them are preprocessors for drawing 1047mathematical pictures (@code{ideal}) and chemical structures 1048(@code{chem}). 1049 1050 1051@c ===================================================================== 1052 1053@node Output device intro, Credits, Preprocessor Intro, Introduction 1054@section Output Devices 1055@cindex postprocessors 1056@cindex output devices 1057@cindex devices for output 1058 1059@code{groff} actually produces device independent code which may be 1060fed into a postprocessor to produce output for a particular device. 1061Currently, @code{groff} has postprocessors for @sc{PostScript} 1062devices, character terminals, X@w{ }Windows (for previewing), @TeX{} 1063DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use 1064@acronym{CAPSL}), and @acronym{HTML}. 1065 1066 1067@c ===================================================================== 1068 1069@node Credits, , Output device intro, Introduction 1070@section Credits 1071@cindex credits 1072 1073Large portions of this manual were taken from existing documents, most 1074notably, the manual pages for the @code{groff} package by James Clark, 1075and Eric Allman's papers on the @file{me} macro package. 1076 1077The section on the @file{man} macro package is partly based on Susan@w{ 1078}G.@: Kleinmann's @file{groff_man} manual page written for the Debian 1079GNU/Linux system. 1080 1081 1082 1083 1084@c ===================================================================== 1085@c ===================================================================== 1086 1087@node Invoking groff, Tutorial for Macro Users, Introduction, Top 1088@chapter Invoking @code{groff} 1089@cindex invoking @code{groff} 1090@cindex @code{groff} invocation 1091 1092This section focuses on how to invoke the @code{groff} front end. This 1093front end takes care of the details of constructing the pipeline among 1094the preprocessors, @code{gtroff} and the postprocessor. 1095 1096It has become a tradition that GNU programs get the prefix @samp{g} to 1097distinguish it from its original counterparts provided by the host (see 1098@ref{Environment}, for more details). Thus, for example, @code{geqn} is 1099GNU @code{eqn}. On operating systems like Linux or the Hurd, which 1100don't contain proprietary software, and on MS-DOS/MS-Windows, where 1101@code{troff} and associated programs are not available at all, this 1102prefix is omitted since GNU @code{troff} is the only used incarnation of 1103@code{troff}. Exception: @code{groff} is never replaced by @code{roff}. 1104 1105@menu 1106* Groff Options:: 1107* Environment:: 1108* Invocation Examples:: 1109@end menu 1110 1111 1112@c ===================================================================== 1113 1114@node Groff Options, Environment, Invoking groff, Invoking groff 1115@section Options 1116@cindex options 1117 1118@pindex groff 1119@pindex gtroff 1120@pindex gpic 1121@pindex geqn 1122@pindex ggrn 1123@pindex grap 1124@pindex gtbl 1125@pindex grefer 1126@pindex gsoelim 1127@code{groff} normally runs the @code{gtroff} program and a postprocessor 1128appropriate for the selected device. The default device is @samp{ps} 1129(but it can be changed when @code{groff} is configured and built). It 1130can optionally preprocess with any of @code{gpic}, @code{geqn}, 1131@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 1132 1133This section only documents options to the @code{groff} front end. Many 1134of the arguments to @code{groff} are passed on to @code{gtroff}, 1135therefore those are also included. Arguments to pre- or postprocessors 1136can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 1137gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 1138gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 1139grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 1140grolbp}, and @ref{Invoking gxditview}. 1141 1142The command line format for @code{groff} is: 1143 1144@Example 1145groff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 1146 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 1147 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 1148 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 1149 [ @var{files}@dots{} ] 1150@endExample 1151 1152The command line format for @code{gtroff} is as follows. 1153 1154@Example 1155gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 1156 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 1157 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 1158 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 1159@endExample 1160 1161@noindent 1162Obviously, many of the options to @code{groff} are actually passed on to 1163@code{gtroff}. 1164 1165Options without an argument can be grouped behind a single @option{-}. 1166A filename of @file{-} denotes the standard input. It is possible to 1167have whitespace between an option and its parameter. 1168 1169The @code{grog} command can be used to guess the correct @code{groff} 1170command to format a file. 1171 1172Here's the description of the command-line options: 1173 1174@cindex command-line options 1175@table @samp 1176@item -h 1177Print a help message. 1178 1179@item -e 1180Preprocess with @code{geqn}. 1181 1182@item -t 1183Preprocess with @code{gtbl}. 1184 1185@item -g 1186Preprocess with @code{ggrn}. 1187 1188@item -G 1189Preprocess with @code{grap}. 1190 1191@item -p 1192Preprocess with @code{gpic}. 1193 1194@item -s 1195Preprocess with @code{gsoelim}. 1196 1197@item -R 1198Preprocess with @code{grefer}. No mechanism is provided for passing 1199arguments to @code{grefer} because most @code{grefer} options have 1200equivalent commands which can be included in the file. @xref{grefer}, 1201for more details. 1202 1203@pindex troffrc 1204@pindex troffrc-end 1205Note that @code{gtroff} also accepts a @option{-R} option, which is not 1206accessible via @code{groff}. This option prevents the loading of the 1207@file{troffrc} and @file{troffrc-end} files. 1208 1209@item -v 1210Make programs run by @code{groff} print out their version number. 1211 1212@item -V 1213Print the pipeline on @code{stdout} instead of executing it. 1214 1215@item -z 1216Suppress output from @code{gtroff}. Only error messages are printed. 1217 1218@item -Z 1219Do not postprocess the output of @code{gtroff}. Normally @code{groff} 1220automatically runs the appropriate postprocessor. 1221 1222@item -P@var{arg} 1223Pass @var{arg} to the postprocessor. Each argument should be passed 1224with a separate @option{-P} option. Note that @code{groff} does not 1225prepend @samp{-} to @var{arg} before passing it to the postprocessor. 1226 1227@item -l 1228Send the output to a spooler for printing. The command used for this is 1229specified by the @code{print} command in the device description file 1230(see @ref{Font Files}, for more info). If not present, @option{-l} is 1231ignored. 1232 1233@item -L@var{arg} 1234Pass @var{arg} to the spooler. Each argument should be passed with a 1235separate @option{-L} option. Note that @code{groff} does not prepend a 1236@samp{-} to @var{arg} before passing it to the postprocessor. If the 1237@code{print} keyword in the device description file is missing, 1238@option{-L} is ignored. 1239 1240@item -T@var{dev} 1241Prepare output for device @var{dev}. The default device is @samp{ps}, 1242unless changed when @code{groff} was configured and built. The 1243following are the output devices currently available: 1244 1245@table @code 1246@item ps 1247For @sc{PostScript} printers and previewers. 1248 1249@item dvi 1250For @TeX{} DVI format. 1251 1252@item X75 1253For a 75@dmn{dpi} X11 previewer. 1254 1255@item X100 1256For a 100@dmn{dpi} X11 previewer. 1257 1258@item ascii 1259For typewriter-like devices. 1260 1261@item latin1 1262For typewriter-like devices that support the @w{Latin-1} (@w{ISO 12638859-1}) character set. 1264 1265@item utf8 1266For typewriter-like devices which use the Unicode (@w{ISO 10646}) 1267character set with @w{UTF-8} encoding. 1268 1269@item cp1047 1270@cindex @acronym{EBCDIC} encoding 1271@cindex cp1047 1272@cindex IBM cp1047 1273For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 1274cp1047. 1275 1276@item lj4 1277For an HP LaserJet4-compatible (or other PCL5-compatible) printer. 1278 1279@item lbp 1280For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 1281printers). 1282 1283@pindex pre-grohtml 1284@pindex post-grohtml 1285@cindex @code{grohtml} 1286@item html 1287To produce @acronym{HTML} output. Note that the @acronym{HTML} driver 1288consists of two parts, a preprocessor (@code{pre-grohtml}) and a 1289postprocessor (@code{post-grohtml}). 1290@end table 1291 1292@vindex .T 1293@stindex .T 1294The predefined @code{gtroff} string register @code{.T} contains the 1295current output device; the read-only number register @code{.T} is set 1296to@w{ }1 if this option is used (which is always true if @code{groff} is 1297used to call @code{gtroff}). @xref{Built-in Registers}. 1298 1299The postprocessor to be used for a device is specified by the 1300@code{postpro} command in the device description file. (@xref{Font 1301Files}, for more info.) This can be overridden with the @option{-X} 1302option. 1303 1304@item -X 1305Preview with @code{gxditview} instead of using the usual postprocessor. 1306This is unlikely to produce good results except with @option{-Tps}. 1307 1308Note that this is not the same as using @option{-TX75} or 1309@option{-TX100} to view a document with @code{gxditview}: The former 1310uses the metrics of the specified device, whereas the latter uses 1311X-specific fonts and metrics. 1312 1313@item -N 1314Don't allow newlines with @code{eqn} delimiters. This is the same as 1315the @option{-N} option in @code{geqn}. 1316 1317@item -S 1318Safer mode. Pass the @option{-S} option to @code{gpic} and disable the 1319@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 1320requests. For security reasons, this is enabled by default. 1321 1322@item -U 1323Unsafe mode. Reverts to the old unsafe behaviour. 1324 1325@item -a 1326@vindex .A 1327Generate an @acronym{ASCII} approximation of the typeset output. The 1328read-only register @code{.A} is then set to@w{ }1. @xref{Built-in 1329Registers}. A typical example is 1330 1331@Example 1332groff -a -man -Tdvi troff.man | less 1333@endExample 1334 1335@noindent 1336which shows how lines are broken for the DVI device. Note that this 1337option is rather useless today since graphic output devices are 1338available virtually everywhere. 1339 1340@item -b 1341Print a backtrace with each warning or error message. This backtrace 1342should help track down the cause of the error. The line numbers given 1343in the backtrace may not always be correct: @code{gtroff} can get 1344confused by @code{as} or @code{am} requests while counting line numbers. 1345 1346@item -i 1347Read the standard input after all the named input files have been 1348processed. 1349 1350@item -w@var{name} 1351Enable warning @var{name}. Available warnings are described in 1352@ref{Debugging}. Multiple @option{-w} options are allowed. 1353 1354@item -W@var{name} 1355Inhibit warning @var{name}. Multiple @option{-W} options are allowed. 1356 1357@item -E 1358Inhibit all error messages. 1359 1360@item -C 1361Enable compatibility mode. @xref{Implementation Differences}, for the 1362list of incompatibilities between @code{groff} and traditional Unix 1363@code{troff}. 1364 1365@item -d@var{cs} 1366@itemx -d@var{name}=s 1367Define @var{c} or @var{name} to be a string @var{s}. @var{c} must be a 1368one-letter name; @var{name} can be of arbitrary length. All string 1369assignments happen before loading any macro file (including the start-up 1370file). 1371 1372@item -f@var{fam} 1373Use @var{fam} as the default font family. @xref{Font Families}. 1374 1375@item -m@var{name} 1376Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches 1377for this in its macro directories. If it isn't found, it tries 1378@file{tmac.@var{name}} (and searches in the same directories). 1379 1380@c XXX document local and system macro dirs 1381 1382@item -n@var{num} 1383Number the first page @var{num}. 1384 1385@item -o@var{list} 1386@vindex .P 1387Output only pages in @var{list}, which is a comma-separated list of page 1388ranges; @samp{@var{n}} means print page @var{n}, @samp{@var{m}-@var{n}} 1389means print every page between @var{m} and @var{n}, @samp{-@var{n}} 1390means print every page up to @var{n}, @samp{@var{n}-} means print every 1391page beginning with @var{n}. @code{gtroff} exits after printing the 1392last page in the list. All the ranges are inclusive on both ends. 1393 1394Within @code{gtroff}, this information can be extracted with the 1395@samp{.P} register. @xref{Built-in Registers}. 1396 1397If your document restarts page numbering at the beginning of each 1398chapter, then @code{gtroff} prints the specified page range for each 1399chapter. 1400 1401@item -r@var{cn} 1402@itemx -r@var{name}=@var{n} 1403Set number register @var{c} or @var{name} to the value @var{n}. @var{c} 1404must be a one-letter name; @var{name} can be of arbitrary length. 1405@var{n} can be any @code{gtroff} numeric expression. All register 1406assignments happen before loading any macro file (including the start-up 1407file). 1408 1409@item -F@var{dir} 1410Search @file{@var{dir}} for subdirectories @file{dev@var{name}} 1411(@var{name} is the name of the device), for the @file{DESC} file, and 1412for font files before looking in the standard directories. 1413 1414@item -M@var{dir} 1415Search directory @file{@var{dir}} for macro files before the standard 1416directories. 1417 1418@item -I@var{dir} 1419This option is as described in @ref{gsoelim}. It implies the 1420@option{-s} option. 1421@end table 1422 1423 1424@c ===================================================================== 1425 1426@node Environment, Invocation Examples, Groff Options, Invoking groff 1427@section Environment 1428@cindex environment variables 1429@cindex variables in environment 1430 1431There are also several environment variables (of the operating system, 1432not within @code{gtroff}) which can modify the behavior of @code{groff}. 1433 1434@table @code 1435@item GROFF_COMMAND_PREFIX 1436@tindex GROFF_COMMAND_PREFIX, environment variable 1437If this is set to @var{X}, then @code{groff} runs @code{@var{X}troff} 1438instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 1439@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 1440apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 1441@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 1442 1443@c XXX document default values 1444 1445@item GROFF_TMAC_PATH 1446@tindex GROFF_TMAC_PATH, environment variable 1447A colon-separated list of directories in which to search for macro files 1448(before the default directories are tried). 1449 1450@c XXX document local and system macro dirs 1451 1452@item GROFF_TYPESETTER 1453@tindex GROFF_TYPESETTER, environment variable 1454The default output device. 1455 1456@item GROFF_FONT_PATH 1457@tindex GROFF_FONT_PATH, environment variable 1458A colon-separated list of directories in which to search for the 1459@code{dev}@var{name} directory (before the default directories are 1460tried). 1461 1462@item GROFF_BIN_PATH 1463@tindex GROFF_BIN_PATH, environment variable 1464This search path, followed by @code{PATH}, is used for commands executed 1465by @code{groff}. 1466 1467@item GROFF_TMPDIR 1468@tindex GROFF_TMPDIR, environment variable 1469@tindex TMPDIR, environment variable 1470The directory in which @code{groff} creates temporary files. If this is 1471not set and @env{TMPDIR} is set, temporary files are created in that 1472directory. Otherwise temporary files are created in a system-dependent 1473default directory (on Unix and GNU/Linux systems, this is usually 1474@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 1475@code{post-grohtml} can create temporary files in this directory. 1476@end table 1477 1478Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 1479rather than colons, to separate the directories in the lists described 1480above. 1481 1482 1483@c ===================================================================== 1484 1485@node Invocation Examples, , Environment, Invoking groff 1486@section Invocation Examples 1487@cindex invocation examples 1488@cindex examples of invocation 1489 1490This section lists several common uses of @code{groff} and the 1491corresponding command lines. 1492 1493@Example 1494groff file 1495@endExample 1496 1497@noindent 1498This command processes @file{file} without a macro package or a 1499preprocessor. The output device is the default, @samp{ps}, and the 1500output is sent to @code{stdout}. 1501 1502@Example 1503groff -t -mandoc -Tascii file | less 1504@endExample 1505 1506@noindent 1507This is basically what a call to the @code{man} program does. 1508@code{gtroff} processes the manual page @file{file} with the 1509@file{mandoc} macro file (which in turn either calls the @file{man} or 1510the @file{mdoc} macro package), using the @code{tbl} preprocessor and 1511the @acronym{ASCII} output device. Finally, the @code{less} pager 1512displays the result. 1513 1514@Example 1515groff -X -m me file 1516@endExample 1517 1518@noindent 1519Preview @file{file} with @code{gxditview}, using the @file{me} macro 1520package. Since no @option{-T} option is specified, use the default 1521device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 1522@w{@samp{-me}}; the latter is an anachronism from the early days of 1523@acronym{UNIX}.@footnote{The same is true for the other main macro 1524packages that come with @code{groff}: @file{man}, @file{mdoc}, 1525@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 1526for example, to load @file{trace.tmac}, either @samp{-mtrace} or 1527@w{@samp{-m trace}} must be used.} 1528 1529@Example 1530groff -man -rD1 -z file 1531@endExample 1532 1533@noindent 1534Check @file{file} with the @file{man} macro package, forcing 1535double-sided printing -- don't produce any output. 1536 1537@menu 1538* grog:: 1539@end menu 1540 1541@c --------------------------------------------------------------------- 1542 1543@node grog, , Invocation Examples, Invocation Examples 1544@subsection @code{grog} 1545 1546@pindex grog 1547@code{grog} reads files, guesses which of the @code{groff} preprocessors 1548and/or macro packages are required for formatting them, and prints the 1549@code{groff} command including those options on the standard output. It 1550generates one or more of the options @option{-e}, @option{-man}, 1551@option{-me}, @option{-mm}, @option{-ms}, @option{-mdoc}, 1552@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 1553@option{-s}, and @option{-t}. 1554 1555A special file name @file{-} refers to the standard input. Specifying 1556no files also means to read the standard input. Any specified options 1557are included in the printed command. No space is allowed between 1558options and their arguments. The only options recognized are 1559@option{-C} (which is also passed on) to enable compatibility mode, and 1560@option{-v} (if it is the only parameter) to print the version number. 1561 1562For example, 1563 1564@Example 1565grog -Tdvi paper.ms 1566@endExample 1567 1568@noindent 1569guesses the appropriate command to print @file{paper.ms} and then prints 1570it to the command line after adding the @option{-Tdvi} option. For 1571direct execution, enclose the call to @code{grog} in backquotes at the 1572@acronym{UNIX} shell prompt: 1573 1574@Example 1575`grog -Tdvi paper.ms` > paper.dvi 1576@endExample 1577 1578@noindent 1579As seen in the example, it is still necessary to redirect the output to 1580something meaningful (i.e.@: either a file or a pager program like 1581@code{less}). 1582 1583 1584 1585@c ===================================================================== 1586@c ===================================================================== 1587 1588@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 1589@chapter Tutorial for Macro Users 1590@cindex tutorial for macro users 1591@cindex macros, tutorial for users 1592@cindex user's tutorial for macros 1593@cindex user's macro tutorial 1594 1595Most users tend to use a macro package to format their papers. This 1596means that the whole breadth of @code{groff} is not necessary for most 1597people. This chapter covers the material needed to efficiently use a 1598macro package. 1599 1600@menu 1601* Basics:: 1602* Common Features:: 1603@end menu 1604 1605 1606@c ===================================================================== 1607 1608@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1609@section Basics 1610@cindex basics of macros 1611@cindex macro basics 1612 1613This section covers some of the basic concepts necessary to understand 1614how to use a macro package.@footnote{This section is derived from 1615@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.} 1616References are made throughout to more detailed information, if desired. 1617 1618@code{gtroff} reads an input file prepared by the user and outputs a 1619formatted document suitable for publication or framing. The input 1620consists of text, or words to be printed, and embedded commands 1621(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 1622format the output. For more detail on this, see @ref{Embedded 1623Commands}. 1624 1625The word @dfn{argument} is used in this chapter to mean a word or number 1626which appears on the same line as a request, and which modifies the 1627meaning of that request. For example, the request 1628 1629@Example 1630.sp 1631@endExample 1632 1633@noindent 1634spaces one line, but 1635 1636@Example 1637.sp 4 1638@endExample 1639 1640@noindent 1641spaces four lines. The number@w{ }4 is an argument to the @code{sp} 1642request which says to space four lines instead of one. Arguments are 1643separated from the request and from each other by spaces (@emph{no} 1644tabs). More details on this can be found in @ref{Request Arguments}. 1645 1646The primary function of @code{gtroff} is to collect words from input 1647lines, fill output lines with those words, justify the right-hand margin 1648by inserting extra spaces in the line, and output the result. For 1649example, the input: 1650 1651@Example 1652Now is the time 1653for all good men 1654to come to the aid 1655of their party. 1656Four score and seven 1657years ago,... 1658@endExample 1659 1660@noindent 1661is read, packed onto output lines, and justified to produce: 1662 1663@quotation 1664Now is the time for all good men to come to the aid of their party. 1665Four score and seven years ago,... 1666@end quotation 1667 1668@cindex break 1669@cindex line break 1670Sometimes a new output line should be started even though the current 1671line is not yet full; for example, at the end of a paragraph. To do 1672this it is possible to cause a @dfn{break}, which starts a new output 1673line. Some requests cause a break automatically, as normally do blank 1674input lines and input lines beginning with a space. 1675 1676Not all input lines are text to be formatted. Some input lines are 1677requests which describe how to format the text. Requests always have a 1678period (@samp{.}) or an apostrophe (@samp{'}) as the first character of 1679the input line. 1680 1681The text formatter also does more complex things, such as automatically 1682numbering pages, skipping over page boundaries, putting footnotes in the 1683correct place, and so forth. 1684 1685Here are a few hints for preparing text for input to @code{gtroff}. 1686 1687@itemize @bullet 1688@item 1689First, keep the input lines short. Short input lines are easier to 1690edit, and @code{gtroff} packs words onto longer lines anyhow. 1691 1692@item 1693In keeping with this, it is helpful to begin a new line after every 1694comma or phrase, since common corrections are to add or delete sentences 1695or phrases. 1696 1697@item 1698End each sentence with two spaces -- or better, start each sentence on a 1699new line. @code{gtroff} recognizes characters that usually end a 1700sentence, and inserts sentence space accordingly. 1701 1702@item 1703Do not hyphenate words at the end of lines -- @code{gtroff} is smart 1704enough to hyphenate words as needed, but is not smart enough to take 1705hyphens out and join a word back together. Also, words such as 1706``mother-in-law'' should not be broken over a line, since then a space 1707can occur where not wanted, such as ``@w{mother- in}-law''. 1708@end itemize 1709 1710@rqindex ls 1711@cindex double spacing 1712@cindex spacing 1713@code{gtroff} double spaces output text automatically if you use the 1714request @w{@samp{.ls 2}}. Reactivate single spaced mode by typing 1715@w{@samp{.ls 1}}. 1716 1717A number of requests allow to change the way the output looks, 1718sometimes called the @dfn{layout} of the output page. Most of these 1719requests adjust the placing of @dfn{white space} (blank lines or 1720spaces). 1721 1722@cindex new page 1723The @samp{.bp} request starts a new page, causing a line break. 1724 1725@cindex blank line 1726@cindex empty line 1727@cindex line, empty 1728The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank 1729space. @var{N}@w{ }can be omitted (meaning skip a single line) or can 1730be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for 1731@var{N}@w{ }centimeters). For example, the input: 1732 1733@Example 1734.sp 1.5i 1735My thoughts on the subject 1736.sp 1737@endExample 1738 1739@noindent 1740leaves one and a half inches of space, followed by the line ``My 1741thoughts on the subject'', followed by a single blank line (more 1742measurement units are available, see @ref{Measurements}). 1743 1744@rqindex ce 1745@cindex centering lines 1746@cindex lines, centering 1747Text lines can be centered by using the @code{ce} request. The line 1748after @code{ce} is centered (horizontally) on the page. To center more 1749than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1750of lines to center), followed by the @var{N}@w{ }lines. To center many 1751lines without counting them, type: 1752 1753@Example 1754.ce 1000 1755lines to center 1756.ce 0 1757@endExample 1758 1759@noindent 1760The @w{@samp{.ce 0}} request tells @code{groff} to center zero more 1761lines, in other words, stop centering. 1762 1763@rqindex br 1764@cindex line break 1765@cindex break 1766All of these requests cause a break; that is, they always start a new 1767line. To start a new line without performing any other action, use 1768@code{br}. 1769 1770 1771@c ===================================================================== 1772 1773@node Common Features, , Basics, Tutorial for Macro Users 1774@section Common Features 1775@cindex common features 1776@cindex features, common 1777 1778@code{gtroff} provides very low-level operations for formatting a 1779document. There are many common routine operations which are done in 1780all documents. These common operations are written into @dfn{macros} 1781and collected into a @dfn{macro package}. 1782 1783All macro packages provide certain common capabilities which fall into 1784the following categories. 1785 1786@menu 1787* Paragraphs:: 1788* Sections and Chapters:: 1789* Headers and Footers:: 1790* Page Layout Adjustment:: 1791* Displays:: 1792* Footnotes and Annotations:: 1793* Table of Contents:: 1794* Indices:: 1795* Paper Formats:: 1796* Multiple Columns:: 1797* Font and Size Changes:: 1798* Predefined Strings:: 1799* Preprocessor Support:: 1800* Configuration and Customization:: 1801@end menu 1802 1803@c --------------------------------------------------------------------- 1804 1805@node Paragraphs, Sections and Chapters, Common Features, Common Features 1806@subsection Paragraphs 1807@cindex paragraphs 1808 1809One of the most common and most used capability is starting a 1810paragraph. There are a number of different types of paragraphs, any 1811of which can be initiated with macros supplied by the macro package. 1812Normally, paragraphs start with a blank line and the first line 1813indented, like the text in this manual. There are also block style 1814paragraphs, which omit the indentation: 1815 1816@Example 1817Some men look at constitutions with sanctimonious 1818reverence, and deem them like the ark of the covenant, too 1819sacred to be touched. 1820@endExample 1821 1822@noindent 1823And there are also indented paragraphs which begin with a tag or label 1824at the margin and the remaining text indented. 1825 1826@example 1827@group 1828one This is the first paragraph. Notice how the first 1829 line of the resulting paragraph lines up with the 1830 other lines in the paragraph. 1831@end group 1832@group 1833longlabel 1834 This paragraph had a long label. The first 1835 character of text on the first line does not line up 1836 with the text on second and subsequent lines, 1837 although they line up with each other. 1838@end group 1839@end example 1840 1841A variation of this is a bulleted list. 1842 1843@c XXX description 1844 1845@c --------------------------------------------------------------------- 1846 1847@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 1848@subsection Sections and Chapters 1849 1850Most macro packages supply some form of section headers. The simplest 1851kind is simply the heading on a line by itself in bold type. Others 1852supply automatically numbered section heading or different heading 1853styles at different levels. Some, more sophisticated, macro packages 1854supply macros for starting chapters and appendices. 1855 1856@c --------------------------------------------------------------------- 1857 1858@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 1859@subsection Headers and Footers 1860 1861Every macro package gives some way to manipulate the headers and footers 1862(or @dfn{titles}) on each page. Some packages allow for different ones 1863on the even and odd pages (for material printed in a book form). 1864 1865The titles are called three-part titles, that is, there is a 1866left-justified part, a centered part, and a right-justified part. An 1867automatically generated page number may be put in any of these fields 1868with the @samp{%} character (see @ref{Page Layout}, for more details). 1869 1870@c --------------------------------------------------------------------- 1871 1872@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 1873@subsection Page Layout 1874 1875Most macro packages let the user specify top and bottom margins and 1876other details about the appearance of the printed pages. 1877 1878@c --------------------------------------------------------------------- 1879 1880@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 1881@subsection Displays 1882@cindex displays 1883 1884Displays are sections of text to be set off from the body of the paper. 1885Major quotes, tables, and figures are types of displays, as are all the 1886examples used in this document. 1887 1888@cindex quotes, major 1889@cindex major quotes 1890@dfn{Major quotes} are quotes which are several lines long, and hence 1891are set in from the rest of the text without quote marks around them. 1892 1893@cindex list 1894A @dfn{list} is an indented, single spaced, unfilled display. Lists 1895should be used when the material to be printed should not be filled and 1896justified like normal text, such as columns of figures or the examples 1897used in this paper. 1898 1899@cindex keep 1900A @dfn{keep} is a display of lines which are kept on a single page if 1901possible. An example for a keep might be a diagram. Keeps differ from 1902lists in that lists may be broken over a page boundary whereas keeps are 1903not. 1904 1905@cindex keep, floating 1906@cindex floating keep 1907Floating keeps move relative to the text. Hence, they are good for 1908things which are referred to by name, such as ``See figure@w{ }3''. A 1909floating keep appears at the bottom of the current page if it fits; 1910otherwise, it appears at the top of the next page. Meanwhile, the 1911surrounding text `flows' around the keep, thus leaving no blank areas. 1912 1913@c --------------------------------------------------------------------- 1914 1915@node Footnotes and Annotations, Table of Contents, Displays, Common Features 1916@subsection Footnotes and Annotations 1917@cindex footnotes 1918@cindex annotations 1919 1920There are a number of requests to save text for later printing. 1921 1922@dfn{Footnotes} are printed at the bottom of the current page. 1923 1924@cindex delayed text 1925@dfn{Delayed text} is very similar to a footnote except that it is 1926printed when called for explicitly. This allows a list of references to 1927appear (for example) at the end of each chapter, as is the convention in 1928some disciplines. 1929 1930Most macro packages which supply this functionality also supply a means 1931of automatically numbering either type of annotation. 1932 1933@c --------------------------------------------------------------------- 1934 1935@node Table of Contents, Indices, Footnotes and Annotations, Common Features 1936@subsection Table of Contents 1937@cindex table of contents 1938@cindex contents, table of 1939 1940@dfn{Tables of contents} are a type of delayed text having a tag 1941(usually the page number) attached to each entry after a row of dots. 1942The table accumulates throughout the paper until printed, usually after 1943the paper has ended. Many macro packages provide the ability to have 1944several tables of contents (e.g.@: a standard table of contents, a list 1945of tables, etc). 1946 1947@c --------------------------------------------------------------------- 1948 1949@node Indices, Paper Formats, Table of Contents, Common Features 1950@subsection Indices 1951@cindex index, in macro package 1952 1953While some macro packages use the term @dfn{index}, none actually 1954provide that functionality. The facilities they call indices are 1955actually more appropriate for tables of contents. 1956 1957@c --------------------------------------------------------------------- 1958 1959@node Paper Formats, Multiple Columns, Indices, Common Features 1960@subsection Paper Formats 1961@cindex paper formats 1962 1963Some macro packages provide stock formats for various kinds of 1964documents. Many of them provide a common format for the title and 1965opening pages of a technical paper. The @file{mm} macros in particular 1966provide formats for letters and memoranda. 1967 1968@c --------------------------------------------------------------------- 1969 1970@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 1971@subsection Multiple Columns 1972 1973Some macro packages (but not @file{man}) provide the ability to have two 1974or more columns on a page. 1975 1976@c --------------------------------------------------------------------- 1977 1978@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 1979@subsection Font and Size Changes 1980 1981The built-in font and size functions are not always intuitive, so all 1982macro packages provide macros to make these operations simpler. 1983 1984@c --------------------------------------------------------------------- 1985 1986@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 1987@subsection Predefined Strings 1988 1989Most macro packages provide various predefined strings for a variety of 1990uses; examples are sub- and superscripts, printable dates, quotes and 1991various special characters. 1992 1993@c --------------------------------------------------------------------- 1994 1995@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 1996@subsection Preprocessor Support 1997 1998All macro packages provide support for the various preprocessors and may 1999extend their functionality. 2000 2001For example, all macro packages mark tables (which are processed with 2002@code{gtbl}) by placing them between @code{.TS} and @code{.TE} macros. 2003The @file{ms} macro package has an option, @code{.TS@w{}H}, that prints 2004a caption at the top of a new page (when the table is too long to fit on 2005a single page). 2006 2007@c --------------------------------------------------------------------- 2008 2009@node Configuration and Customization, , Preprocessor Support, Common Features 2010@subsection Configuration and Customization 2011 2012Some macro packages provide means of customizing many of the details of 2013how the package behaves. This ranges from setting the default type size 2014to changing the appearance of section headers. 2015 2016 2017 2018@c ===================================================================== 2019@c ===================================================================== 2020 2021@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 2022@chapter Macro Packages 2023@cindex macro packages 2024@cindex packages, macros 2025 2026This chapter documents the main macro packages that come with 2027@code{groff}. 2028 2029@menu 2030* man:: 2031* mdoc:: 2032* ms:: 2033* me:: 2034* mm:: 2035@end menu 2036 2037 2038@c ===================================================================== 2039 2040@node man, mdoc, Macro Packages, Macro Packages 2041@section @file{man} 2042@cindex @file{man} 2043@cindex manual pages 2044@pindex an.tmac 2045@pindex man.tmac 2046@pindex man-old.tmac 2047 2048This is the most popular and probably the most important macro package 2049of @code{groff}. It is easy to use, and a vast majority of manual pages 2050are based on it. 2051 2052@menu 2053* Man options:: 2054* Man usage:: 2055* Man font macros:: 2056* Miscellaneous man macros:: 2057* Predefined man strings:: 2058* Preprocessors in man pages:: 2059@end menu 2060 2061@c --------------------------------------------------------------------- 2062 2063@node Man options, Man usage, man, man 2064@subsection Options 2065 2066The command line format for using the @file{man} macros with 2067@code{groff} is: 2068 2069@Example 2070groff -m man [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ] 2071 [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ] 2072@endExample 2073 2074@noindent 2075It is possible to use @samp{-man} instead of @w{@samp{-m man}}. 2076 2077@table @code 2078@item -rcR=1 2079This option (the default if a tty output device is used) creates a 2080single, very long page instead of multiple pages. Use @code{-rcR=0} 2081to disable it. 2082 2083@item -rC1 2084If more than one manual page is given on the command line, number the 2085pages continuously, rather than starting each at@w{ }1. 2086 2087@item -rD1 2088Double-sided printing. Footers for even and odd pages are formatted 2089differently. 2090 2091@item -rP@var{nnn} 2092Page numbering starts with @var{nnn} rather than with@w{ }1. 2093 2094@item -rS@var{xx} 2095Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base 2096document font size instead of the default value of@w{ }10@dmn{pt}. 2097 2098@item -rX@var{nnn} 2099After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 2100@var{nnn}c, etc. For example, the option @option{-rX2} produces the 2101following page numbers: 1, 2, 2a, 2b, 2c, etc. 2102@end table 2103 2104@c --------------------------------------------------------------------- 2105 2106@node Man usage, Man font macros, Man options, man 2107@subsection Usage 2108@cindex @code{man} macros 2109@cindex macros for manual pages 2110 2111@pindex man.local 2112This section describes the available macros for manual pages. For 2113further customization, put additional macros and requests into the file 2114@file{man.local} which is loaded immediately after the @file{man} 2115package. 2116 2117@Defmac {TH, title section [@Var{extra1}] [@Var{extra2}] [@Var{extra3}]} 2118Set the title of the man page to @var{title} and the section to 2119@var{section}, which must have a value between 1 and@w{ }8. The value 2120of @var{section} may also have a string appended, e.g.@: @samp{.pm}, 2121to indicate a specific subsection of the man pages. 2122 2123Both @var{title} and @var{section} are positioned at the left and right 2124in the header line (with @var{section} in parentheses immediately 2125appended to @var{title}. @var{extra1} is positioned in the middle of 2126the footer line. @var{extra2} is positioned at the left in the footer 2127line (or at the left on even pages and at the right on odd pages if 2128double-sided printing is active). @var{extra3} is centered in the 2129header line. 2130 2131For @acronym{HTML} output, headers and footers are completely suppressed. 2132 2133Additionally, this macro starts a new page; the new line number is@w{ }1 2134again (except if the @option{-rC1} option is given on the command line) 2135-- this feature is intended only for formatting multiple man pages; a 2136single man page should contain exactly one @code{TH} macro at the 2137beginning of the file. 2138@endDefmac 2139 2140@Defmac {SH, [@Var{heading}]} 2141Set up an unnumbered section heading sticking out to the left. Prints 2142out all the text following @code{SH} up to the end of the line (or the 2143text in the next line if there is no argument to @code{SH}) in bold 2144face, one size larger than the base document size. Additionally, the 2145left margin for the following text is reset to its default value. 2146@endDefmac 2147 2148@Defmac {SS, [@Var{heading}]} 2149Set up an unnumbered (sub)section heading. Prints out all the text 2150following @code{SS} up to the end of the line (or the text in the next 2151line if there is no argument to @code{SS}) in bold face, at the same 2152size as the base document size. Additionally, the left margin for the 2153following text is reset to its default value. 2154@endDefmac 2155 2156@Defmac {TP, [@Var{nnn}]} 2157Set up an indented paragraph with label. The indentation is set to 2158@var{nnn} if that argument is supplied (the default unit is @samp{n} 2159if omitted), otherwise it is set to the default indentation value. 2160 2161The first line of text following this macro is interpreted as a string 2162to be printed flush-left, as it is appropriate for a label. It is not 2163interpreted as part of a paragraph, so there is no attempt to fill the 2164first line with text from the following input lines. Nevertheless, if 2165the label is not as wide as the indentation, then the paragraph starts 2166at the same line (but indented), continuing on the following lines. 2167If the label is wider than the indentation, then the descriptive part 2168of the paragraph begins on the line following the label, entirely 2169indented. Note that neither font shape nor font size of the label is 2170set to a default value; on the other hand, the rest of the text has 2171default font settings. 2172@endDefmac 2173 2174@Defmac {LP} 2175@Defmacx {PP} 2176@Defmacx {P} 2177These macros are mutual aliases. Any of them causes a line break at 2178the current position, followed by a vertical space downwards by the 2179amount specified by the @code{PD} macro. The font size and shape are 2180reset to the default value (10@dmn{pt} roman). Finally, the current 2181left margin is restored. 2182@endDefmac 2183 2184@Defmac {IP, [@Var{designator}] [@Var{nnn}]} 2185Set up an indented paragraph, using @var{designator} as a tag to mark 2186its beginning. The indentation is set to @var{nnn} if that argument 2187is supplied (default unit is @samp{n}), otherwise the default 2188indentation value is used. Font size and face of the paragraph (but 2189not the designator) are reset to their default values. To start an 2190indented paragraph with a particular indentation but without a 2191designator, use @samp{""} (two double quotes) as the first argument of 2192@code{IP}. 2193 2194For example, to start a paragraph with bullets as the designator and 21954@dmn{en} indentation, write 2196 2197@Example 2198.IP \(bu 4 2199@endExample 2200@endDefmac 2201 2202@cindex hanging indentation, in manual pages 2203@Defmac {HP, [@Var{nnn}]} 2204Set up a paragraph with hanging left indentation. The indentation is 2205set to @var{nnn} if that argument is supplied (default unit is 2206@samp{n}), otherwise the default indentation value is used. Font size 2207and face are reset to their default values. 2208@endDefmac 2209 2210@cindex left margin, how to move, in manual pages 2211@Defmac {RS, [@Var{nnn}]} 2212Move the left margin to the right by the value @var{nnn} if specified 2213(default unit is @samp{n}); otherwise the default indentation value is 2214used. Calls to the @code{RS} macro can be nested. 2215@endDefmac 2216 2217@Defmac {RE, [@Var{nnn}]} 2218Move the left margin back to level @var{nnn}; if no argument is given, 2219it moves one level back. The first level (i.e., no call to @code{RS} 2220yet) has number@w{ }1, and each call to @code{RS} increases the level 2221by@w{ }1. 2222@endDefmac 2223 2224@maindex SH 2225@maindex SS 2226@maindex TP 2227@maindex LP 2228@maindex PP 2229@maindex P 2230@maindex IP 2231@maindex HP 2232To summarize, the following macros cause a line break with the insertion 2233of vertical space (which amount can be changed with the @code{PD} 2234macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 2235@code{P}), @code{IP}, and @code{HP}. 2236 2237@maindex RS 2238@maindex RE 2239The macros @code{RS} and @code{RE} also cause a break but do not insert 2240vertical space. 2241 2242@c --------------------------------------------------------------------- 2243 2244@node Man font macros, Miscellaneous man macros, Man usage, man 2245@subsection Macros to set fonts 2246@cindex fonts in manual pages 2247@cindex @code{man}, how to set fonts 2248 2249The standard font is roman; the default text size is 10@w{ }point. 2250 2251@Defmac {SM, [@Var{text}]} 2252Set the text on the same line or the text on the next line in a font 2253that is one point size smaller than the default font. 2254@endDefmac 2255 2256@cindex boldface, in manual pages 2257@Defmac {SB, [@Var{text}]} 2258Set the text on the same line or the text on the next line in boldface 2259font, one point size smaller than the default font. 2260@endDefmac 2261 2262@Defmac {BI, text} 2263Set its arguments alternately in bold face and italic. Thus, 2264 2265@Example 2266.BI this "word and" that 2267@endExample 2268 2269@noindent 2270would set ``this'' and ``that'' in bold face, and ``word and'' in 2271italics. 2272@endDefmac 2273 2274@Defmac {IB, text} 2275Set its arguments alternately in italic and bold face. 2276@endDefmac 2277 2278@Defmac {RI, text} 2279Set its arguments alternately in roman and italic. 2280@endDefmac 2281 2282@Defmac {IR, text} 2283Set its arguments alternately in italic and roman. 2284@endDefmac 2285 2286@Defmac {BR, text} 2287Set its arguments alternately in bold face and roman. 2288@endDefmac 2289 2290@Defmac {RB, text} 2291Set its arguments alternately in roman and bold face. 2292@endDefmac 2293 2294@Defmac {R, [@Var{text}]} 2295Set @var{text} in roman font. If no text is present on the line where 2296the macro is called, then the text of the next line appears in roman. 2297This is the default font to which text is returned at the end of 2298processing of the other macros. 2299@endDefmac 2300 2301@Defmac {B, [@Var{text}]} 2302Set @var{text} in bold face. If no text is present on the line where 2303the macro is called, then the text of the next line appears in bold 2304face. 2305@endDefmac 2306 2307@cindex italic, in manual pages 2308@Defmac {I, [@Var{text}]} 2309Set @var{text} in italic. If no text is present on the line where the 2310macro is called, then the text of the next line appears in italic. 2311@endDefmac 2312 2313@c --------------------------------------------------------------------- 2314 2315@node Miscellaneous man macros, Predefined man strings, Man font macros, man 2316@subsection Miscellaneous macros 2317 2318@pindex grohtml 2319@cindex @file{man}, default indentation 2320@cindex default indentation, @file{man} 2321The default indentation is 7.2@dmn{n} for all output devices except for 2322@code{grohtml} which ignores indentation. 2323 2324@maindex TH 2325@cindex tab stops, in manual pages 2326@Defmac {DT} 2327Set tabs every 0.5@w{ }inches. Since this macro is always called 2328during a @code{TH} request, it makes sense to call it only if the tab 2329positions have been changed. 2330@endDefmac 2331 2332@cindex empty space before a paragraph, in manual pages 2333@Defmac {PD, [@Var{nnn}]} 2334Adjust the empty space before a new paragraph (or section). The 2335optional argument gives the amount of space (default unit is 2336@samp{v}); without parameter, the value is reset to its default value 2337(1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise). 2338@endDefmac 2339 2340@maindex SH 2341@maindex SS 2342@maindex TP 2343@maindex LP 2344@maindex PP 2345@maindex P 2346@maindex IP 2347@maindex HP 2348This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 2349well as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2350 2351@c --------------------------------------------------------------------- 2352 2353@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 2354@subsection Predefined strings 2355 2356The following strings are defined: 2357 2358@Defstr {*S} 2359Switch back to the default font size. 2360@endDefstr 2361 2362@Defstr {*R} 2363The `registered' sign. 2364@endDefstr 2365 2366@Defstr {Tm} 2367The `trademark' sign. 2368@endDefstr 2369 2370@glindex lq 2371@glindex rq 2372@Defstr {lq} 2373@Defstrx {rq} 2374Left and right quote. This is equal to @code{\(lq} and @code{\(rq}, 2375respectively. 2376@endDefstr 2377 2378@c --------------------------------------------------------------------- 2379 2380@node Preprocessors in man pages, , Predefined man strings, man 2381@subsection Preprocessors in @file{man} pages 2382 2383@cindex preprocessor, calling convention 2384@cindex calling convention of preprocessors 2385If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 2386become common usage to make the first line of the man page look like 2387this: 2388 2389@Example 2390.\" @var{word} 2391@endExample 2392 2393@pindex geqn@r{, invocation in manual pages} 2394@pindex grefer@r{, invocation in manual pages} 2395@pindex gtbl@r{, invocation in manual pages} 2396@pindex man@r{, invocation of preprocessors} 2397@noindent 2398Note the single space character after the double quote. @var{word} 2399consists of letters for the needed preprocessors: @samp{e} for 2400@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 2401Modern implementations of the @code{man} program read this first line 2402and automatically call the right preprocessor(s). 2403 2404 2405@c ===================================================================== 2406 2407@node mdoc, ms, man, Macro Packages 2408@section @file{mdoc} 2409@cindex @file{mdoc} 2410 2411@c XXX documentation 2412 2413 2414@c ===================================================================== 2415 2416@node ms, me, mdoc, Macro Packages 2417@section @file{ms} 2418@cindex @file{ms} 2419 2420@c XXX documentation 2421 2422 2423@c ===================================================================== 2424 2425@node me, mm, ms, Macro Packages 2426@section @file{me} 2427@cindex @file{me} 2428 2429@c XXX documentation 2430 2431 2432@c ===================================================================== 2433 2434@node mm, , me, Macro Packages 2435@section @file{mm} 2436@cindex @file{mm} 2437 2438@c XXX documentation 2439 2440 2441 2442@c ===================================================================== 2443@c ===================================================================== 2444 2445@node gtroff Reference, Preprocessors, Macro Packages, Top 2446@chapter @code{gtroff} Reference 2447@cindex reference, @code{gtroff} 2448@cindex @code{gtroff} reference 2449 2450This chapter covers @strong{all} of the facilities of @code{gtroff}. 2451Users of macro packages may skip it if not interested in details. 2452 2453 2454@menu 2455* Text:: 2456* Input Conventions:: 2457* Measurements:: 2458* Expressions:: 2459* Identifiers:: 2460* Embedded Commands:: 2461* Registers:: 2462* Manipulating Filling and Adjusting:: 2463* Manipulating Hyphenation:: 2464* Manipulating Spacing:: 2465* Tabs and Fields:: 2466* Character Translations:: 2467* Troff and Nroff Mode:: 2468* Line Layout:: 2469* Page Layout:: 2470* Page Control:: 2471* Fonts:: 2472* Sizes:: 2473* Strings:: 2474* Conditionals and Loops:: 2475* Writing Macros:: 2476* Page Motions:: 2477* Drawing Requests:: 2478* Traps:: 2479* Diversions:: 2480* Environments:: 2481* Suppressing output:: 2482* I/O:: 2483* Postprocessor Access:: 2484* Miscellaneous:: 2485* Gtroff Internals:: 2486* Debugging:: 2487* Implementation Differences:: 2488* Summary:: 2489@end menu 2490 2491 2492@c ===================================================================== 2493 2494@node Text, Input Conventions, gtroff Reference, gtroff Reference 2495@section Text 2496@cindex text, @code{gtroff} processing 2497 2498@code{gtroff} input files contain text with control commands 2499interspersed throughout. But, even without control codes, @code{gtroff} 2500still does several things with the input text: 2501 2502@itemize @bullet 2503@item 2504filling and adjusting 2505 2506@item 2507adding additional space after sentences 2508 2509@item 2510hyphenating 2511 2512@item 2513inserting implicit line breaks 2514@end itemize 2515 2516@menu 2517* Filling and Adjusting:: 2518* Hyphenation:: 2519* Sentences:: 2520* Tab Stops:: 2521* Implicit Line Breaks:: 2522@end menu 2523 2524@c --------------------------------------------------------------------- 2525 2526@node Filling and Adjusting, Hyphenation, Text, Text 2527@subsection Filling and Adjusting 2528@cindex filling 2529@cindex adjusting 2530 2531When @code{gtroff} reads text, it collects words from the input and fits 2532as many of them together on one output line as it can. This is known as 2533@dfn{filling}. 2534 2535@cindex leading spaces 2536@cindex spaces, leading and trailing 2537@cindex extra spaces 2538@cindex trailing spaces 2539Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 2540it. This means it widens the spacing between words until the text 2541reaches the right margin (in the default adjustment mode). Extra spaces 2542between words are preserved, but spaces at the end of lines are ignored. 2543Spaces at the front of a line cause a @dfn{break} (breaks are 2544explained in @ref{Implicit Line Breaks}) 2545 2546@xref{Manipulating Filling and Adjusting}. 2547 2548@c --------------------------------------------------------------------- 2549 2550@node Hyphenation, Sentences, Filling and Adjusting, Text 2551@subsection Hyphenation 2552@cindex hyphenation 2553 2554Since the odds are not great for finding a set of words, for every 2555output line, which fit nicely on a line without inserting excessive 2556amounts of space between words, @code{gtroff} hyphenates words so 2557that it can justify lines without inserting too much space between 2558words. It uses an internal hyphenation algorithm (a simplified version 2559of the algorithm used within @TeX{}) to indicate which words can be 2560hyphenated and how to do so. When a word is hyphenated, the first part 2561of the word is added to the current filled line being output (with 2562an attached hyphen), and the other portion is added to the next 2563line to be filled. 2564 2565@xref{Manipulating Hyphenation}. 2566 2567@c --------------------------------------------------------------------- 2568 2569@node Sentences, Tab Stops, Hyphenation, Text 2570@subsection Sentences 2571@cindex sentences 2572 2573Although it is often debated, some typesetting rules say there should be 2574different amounts of space after various punctuation marks. For 2575example, the @cite{Chicago typsetting manual} says that a period at the 2576end of a sentence should have twice as much space following it as would 2577a comma or a period as part of an abbreviation. 2578 2579@c XXX exact citation of Chicago manual 2580 2581@cindex sentence space 2582@cindex space between sentences 2583@cindex french-spacing 2584@code{gtroff} does this by flagging certain characters (normally 2585@samp{!}, @samp{?}, and @samp{.}) as @dfn{end of sentence} characters. 2586When @code{gtroff} encounters one of these characters at the end of a 2587line, it appends a normal space followed by a @dfn{sentence space} in 2588the formatted output. (This justifies one of the conventions mentioned 2589in @ref{Input Conventions}.) 2590 2591@cindex transparent characters 2592@cindex character, transparent 2593@glindex dg 2594@glindex rq 2595@cindex " 2596@cindex ' 2597@cindex ) 2598@cindex ] 2599@cindex * 2600In addition, the following characters or glyphs are treated 2601transparently while handling end of sentence characters: @samp{"}, 2602@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}. 2603 2604See the @code{cflags} request in @ref{Using Symbols}, for more details. 2605 2606@esindex \& 2607To prevent the insertion of extra space after an end of sentence 2608character (at the end of a line), append @code{\&}. 2609 2610@c --------------------------------------------------------------------- 2611 2612@node Tab Stops, Implicit Line Breaks, Sentences, Text 2613@subsection Tab Stops 2614@cindex tab stops 2615@cindex stops, tabulator 2616@cindex tab character 2617@cindex character, tabulator 2618 2619@cindex @acronym{EBCDIC} encoding 2620@code{gtroff} translates @dfn{tabulator characters}, also called 2621@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 2622@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 2623tabulator stop. These tab stops are initially located every half inch 2624across the page. Using this, simple tables can be made easily. 2625However, it can often be deceptive as the appearance (and width) of the 2626text on a terminal and the results from @code{gtroff} can vary greatly. 2627 2628Also, a possible sticking point is that lines beginning with tab 2629characters are still filled, again producing unexpected results. 2630For example, the following input 2631 2632@multitable {12345678} {12345678} {12345678} {12345678} 2633@item 2634@tab 1 @tab 2 @tab 3 2635@item 2636@tab @tab 4 @tab 5 2637@end multitable 2638 2639@noindent 2640produces 2641 2642@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 2643@item 2644@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 2645@end multitable 2646 2647@xref{Tabs and Fields}. 2648 2649@c --------------------------------------------------------------------- 2650 2651@node Implicit Line Breaks, , Tab Stops, Text 2652@subsection Implicit Line Breaks 2653@cindex implicit line breaks 2654@cindex implicit breaks of lines 2655@cindex line, implicit breaks 2656@cindex break, implicit 2657@cindex line break 2658 2659An important concept in @code{gtroff} is the @dfn{break}. When a break 2660occurs, @code{gtroff} outputs the partially filled line 2661(unjustified), and resumes collecting and filling text on the next output 2662line. 2663 2664@cindex blank line 2665@cindex empty line 2666@cindex line, blank 2667@cindex blank line macro 2668@rqindex blm 2669There are several ways to cause a break in @code{gtroff}. A blank 2670line not only causes a break, but it also outputs a one line vertical 2671space (effectively a blank line). Note that this behaviour can be 2672modified with the blank line macro request @code{blm}. 2673 2674@c XXX xref for blm 2675 2676@cindex fill mode 2677@cindex mode, fill 2678A line that begins with a space causes a break and the space is 2679output at the beginning of the next line. Note that this space isn't 2680adjusted, even in fill mode. 2681 2682The end of file also causes a break -- otherwise the last line of 2683the document may vanish! 2684 2685Certain requests also cause breaks, implicitly or explicitly. This is 2686discussed in @ref{Manipulating Filling and Adjusting}. 2687 2688 2689@c ===================================================================== 2690 2691@node Input Conventions, Measurements, Text, gtroff Reference 2692@section Input Conventions 2693@cindex input conventions 2694@cindex conventions for input 2695 2696Since @code{gtroff} does filling automatically, it is traditional in 2697@code{groff} not to try and type things in as nicely formatted 2698paragraphs. These are some conventions commonly used when typing 2699@code{gtroff} text: 2700 2701@itemize @bullet 2702@item 2703Break lines after punctuation, particularly at the end of a sentence 2704and in other logical places. Keep separate phrases on lines by 2705themselves, as entire phrases are often added or deleted when editing. 2706 2707@item 2708Try to keep lines less than 40-60@w{ }characters, to allow space for 2709inserting more text. 2710 2711@item 2712Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 2713don't try using spaces to get proper indentation). 2714@end itemize 2715 2716 2717@c ===================================================================== 2718 2719@node Measurements, Expressions, Input Conventions, gtroff Reference 2720@section Measurements 2721@cindex measurements 2722 2723@cindex units of measurement 2724@cindex basic units 2725@cindex machine units 2726@cindex measurement units 2727@cindex @code{u} unit 2728@cindex unit, @code{u} 2729@code{gtroff} (like many other programs) requires numeric parameters to 2730specify various measurements. Most numeric parameters@footnote{those 2731that specify vertical or horizontal motion or a type size} may have a 2732@dfn{measurement unit} attached. These units are specified as a single 2733character which immediately follows the number or expression. Each of 2734these units are understood, by @code{gtroff}, to be a multiple of its 2735@dfn{basic unit}. So, whenever a different measurement unit is 2736specified @code{gtroff} converts this into its @dfn{basic units}. This 2737basic unit, represented by a @samp{u}, is a device dependent measurement 2738which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 2739inch. The values may be given as fractional numbers; however, 2740fractional basic units are always rounded to integers. 2741 2742Some of the measurement units are completely independent of any of the 2743current settings (e.g.@: type size) of @code{gtroff}. 2744 2745@table @code 2746@item i 2747@cindex inch 2748@cindex @code{i} unit 2749@cindex unit, @code{i} 2750Inches. An antiquated measurement unit still in use in certain 2751backwards countries with incredibly low-cost computer equipment. One 2752inch is equal to@w{ }2.54@dmn{cm}. 2753 2754@item c 2755@cindex centimeter 2756@cindex @code{c} unit 2757@cindex unit, @code{c} 2758Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}. 2759 2760@item p 2761@cindex points 2762@cindex @code{p} unit 2763@cindex unit, @code{p} 2764Points. This is a typesetter's measurement used for measure type size. 2765It is 72@w{ }points to an inch. 2766 2767@item P 2768@cindex pica 2769@cindex @code{P} unit 2770@cindex unit, @code{P} 2771Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and 277212@w{ }points to a pica). 2773 2774@item s 2775@itemx z 2776@cindex @code{s} unit 2777@cindex unit, @code{s} 2778@cindex @code{z} unit 2779@cindex unit, @code{z} 2780@xref{Fractional Type Sizes}, for a discussion of these units. 2781@end table 2782 2783The other measurements understood by @code{gtroff} depend on 2784settings currently in effect in @code{gtroff}. These are very useful 2785for specifying measurements which should look proper with any size of 2786text. 2787 2788@table @code 2789@item m 2790@cindex em unit 2791@cindex @code{m} unit 2792@cindex unit, @code{m} 2793Ems. This unit is equal to the current font size in points. So called 2794because it is @emph{approximately} the width of the letter@w{ }@samp{m} 2795in the current font. 2796 2797@item n 2798@cindex en unit 2799@cindex @code{n} unit 2800@cindex unit, @code{n} 2801Ens. This is half of an em. 2802 2803@item v 2804@cindex vertical space 2805@cindex space, vertical 2806@cindex @code{v} unit 2807@cindex unit, @code{v} 2808Vertical space. This is equivalent to the current line spacing. 2809@xref{Sizes}, for more information about this. 2810 2811@item M 2812@cindex @code{M} unit 2813@cindex unit, @code{M} 2814100ths of an em. 2815@end table 2816 2817@menu 2818* Default Units:: 2819@end menu 2820 2821@c --------------------------------------------------------------------- 2822 2823@node Default Units, , Measurements, Measurements 2824@subsection Default Units 2825@cindex default units 2826@cindex units, default 2827 2828Many requests take a default unit. While this can be helpful at times, 2829it can cause strange errors in some expressions. For example, the line 2830length request expects em units. Here are several attempts to get a 2831line length of 3.5@w{ }inches and their results: 2832 2833@Example 28343.5i @result{} 3.5i 28357/2 @result{} 0i 28367/2i @result{} 0i 28377i/2 @result{} 0.1i 28387i/2u @result{} 3.5i 2839@endExample 2840 2841@noindent 2842Everything is converted to basic units first. In the above example it 2843is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{ 2844}10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2 2845is first handled as 7@dmn{i}/2@dmn{m}, then converted to 28461680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 28470.1@dmn{i}. 2848 2849@cindex measurements, specifying safely 2850Thus, the safest way to specify measurements is to always 2851attach a scaling indicator. If you want to multiply or divide by a 2852certain scalar value, use @samp{u} as the unit for that value. 2853 2854 2855@c ===================================================================== 2856 2857@node Expressions, Identifiers, Measurements, gtroff Reference 2858@section Expressions 2859@cindex expressions 2860 2861@code{gtroff} has most arithmetic operators common to other languages: 2862 2863@c XXX more details; examples 2864 2865@itemize @bullet 2866@item 2867@cindex arithmetic operators 2868@cindex operators, arithmetic 2869@opindex + 2870@opindex - 2871@opindex / 2872@opindex * 2873@opindex % 2874Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 2875(division), @samp{*} (multiplication), @samp{%} (modulo). 2876 2877@code{gtroff} only provides integer arithmetic. The internal type used 2878for computing results is @samp{int}, which is usually a 32@dmn{bit} 2879signed integer. 2880 2881@item 2882@cindex comparison operators 2883@cindex operators, comparison 2884@opindex < 2885@opindex > 2886@opindex >= 2887@opindex <= 2888@opindex = 2889@opindex == 2890Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 2891(less than or equal), @samp{>=} (greater than or equal), @samp{=} 2892(equal), @samp{==} (the same as @samp{=}). 2893 2894@item 2895@cindex logical operators 2896@cindex operators, logical 2897@opindex & 2898@opindex : 2899Logical: @samp{&} (logical and), @samp{:} (logical or). 2900 2901@item 2902@cindex unary operators 2903@cindex operators, unary 2904@opindex - 2905@opindex + 2906@opindex ! 2907@rqindex if 2908@rqindex while 2909@cindex @code{if}, and the @samp{!} operator 2910@cindex @code{while}, and the @samp{!} operator 2911Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 2912(just for completeness; does nothing in expressions), @samp{!} (logical 2913not; this works only within @code{if} and @code{while} requests). See 2914below for the use of unary operators in motion requests. 2915 2916@item 2917@cindex extremum operators 2918@cindex operators, extremum 2919@opindex >? 2920@opindex <? 2921Extrema: @samp{>?} (maximum), @samp{<?} (minimum). For example, 2922@samp{5>?3} yields@w{ }@samp{5}. 2923 2924@c XXX add examples 2925 2926@item 2927@cindex scaling operator 2928@cindex operator, scaling 2929Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as 2930the default scaling indicator. If @var{c} is missing, ignore scaling 2931indicators in the evaluation of @var{e}. 2932@end itemize 2933 2934@cindex parentheses 2935@cindex order of evaluation in expressions 2936@cindex expression, order of evaluation 2937@opindex ( 2938@opindex ) 2939Parentheses may be used as in any other language. However, in 2940@code{gtroff} they are necessary to ensure order of evaluation. 2941@code{gtroff} has no operator precedence; expressions are evaluated left 2942to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 2943parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 2944expected. 2945 2946@opindex +@r{, and page motion} 2947@opindex -@r{, and page motion} 2948@opindex |@r{, and page motion} 2949@cindex motion operators 2950@cindex operators, motion 2951For many requests which cause a motion on the page, the unary operators 2952work differently. The @samp{+} and @samp{-} operators then indicate a 2953motion relative to the current position (down or up, respectively), and 2954the @samp{|} operator indicates an absolute position on the page or 2955input line. 2956@c XXX xref 2957@samp{+} and @samp{-} are also treated differently by the following 2958requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 2959@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 2960@code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus 2961signs indicate increments and decrements. 2962 2963@c XXX add more xref 2964@xref{Setting Registers}. 2965 2966@cindex space characters in expressions 2967@cindex expressions and space characters 2968Due to the way arguments are parsed, spaces are not allowed in 2969expressions, unless the entire expression is surrounded by parentheses. 2970 2971@xref{Request Arguments}, and @ref{Conditionals and Loops}. 2972 2973 2974@c ===================================================================== 2975 2976@node Identifiers, Embedded Commands, Expressions, gtroff Reference 2977@section Identifiers 2978@cindex identifiers 2979 2980Like any other language, @code{gtroff} has rules for properly formed 2981@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 2982almost any printable character, with the exception of the following 2983characters: 2984 2985@itemize @bullet 2986@item 2987@cindex whitespace characters 2988@cindex newline character 2989@cindex character, whitespace 2990Whitespace characters (spaces, tabs, and newlines). 2991 2992@item 2993@cindex character, backspace 2994@cindex backspace character 2995@cindex @acronym{EBCDIC} encoding of backspace 2996Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{ 2997}@code{0x16}) and character code @code{0x01}. 2998 2999@item 3000@cindex invalid input characters 3001@cindex input characters, invalid 3002@cindex characters, invalid input 3003@cindex unicode 3004The following input characters are invalid and are ignored if 3005@code{groff} runs on a machine based on @acronym{ASCII}, causing a 3006warning message of type @samp{input} (see @ref{Debugging}, for more 3007details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 3008@code{0x80}-@code{0x9F}. 3009 3010And here are the invalid input characters if @code{groff} runs on an 3011@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 3012@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 3013@code{0x30}-@code{0x3F}. 3014 3015Currently, some of these reserved codepoints are used internally, thus 3016making it non-trivial to extend @code{gtroff} to cover Unicode or other 3017character sets and encodings which use characters of these ranges. 3018 3019Note that invalid characters are removed before parsing; an 3020identifier @code{foo}, followed by an invalid character, followed by 3021@code{bar} is treated as @code{foobar}. 3022@end itemize 3023 3024For example, any of the following is valid. 3025 3026@Example 3027br 3028PP 3029(l 3030end-list 3031@@_ 3032@endExample 3033 3034@rqindex ] 3035@noindent 3036Note that identifiers longer than two characters with a closing bracket 3037(@samp{]}) in its name can't be accessed with escape sequences which 3038expect an identifier as a parameter. For example, @samp{\[foo]]} 3039accesses the glyph @samp{foo}, followed by @samp{]}, whereas 3040@samp{\C'foo]'} really asks for glyph @samp{foo]}. 3041 3042@c XXX xref 3043 3044@Defesc {\\A, ', ident, '} 3045Test whether an identifier @var{ident} is valid in @code{gtroff}. It 3046expands to the character@w{ }1 or@w{ }0 according to whether its 3047argument (usually delimited by quotes) is or is not acceptable as the 3048name of a string, macro, diversion, number register, environment, or 3049font. It returns@w{ }0 if no argument is given. This is useful for 3050looking up user input in some sort of associative table. 3051 3052@Example 3053\A'end-list' 3054 @result{} 1 3055@endExample 3056@endDefesc 3057 3058@xref{Escapes}, for details on parameter delimiting characters. 3059 3060@c XXX add xrefs above 3061 3062Identifiers in @code{gtroff} can be any length, but, in some contexts, 3063@code{gtroff} needs to be told where identifiers end and text begins 3064(and in different ways depending on their length): 3065 3066@rqindex ( 3067@rqindex [ 3068@rqindex ] 3069@itemize @bullet 3070@item 3071Single character. 3072 3073@item 3074Two characters. Must be prefixed with @samp{(} in some situations. 3075 3076@item 3077Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 3078and@w{ }@samp{]} in some situations. Any length identifier can be put 3079in brackets. 3080@end itemize 3081 3082@cindex undefined identifiers 3083@cindex indentifiers, undefined 3084Unlike many other programming languages, undefined identifiers are 3085silently ignored or expanded to nothing. 3086When @code{gtroff} finds an undefined identifier, it emits a 3087warning then: 3088 3089@itemize @bullet 3090@item 3091If the identifier is a string, macro, or diversion, 3092@code{gtroff} defines it as empty. 3093 3094@item 3095If the identifier is a number register, @code{gtroff} 3096defines it with a value of@w{ }0. 3097@end itemize 3098 3099@xref{Warnings}. 3100 3101@c XXX info about common identifier pool for strings and macros. 3102 3103@xref{Interpolating Registers}, and @ref{Strings}. 3104 3105 3106@c ===================================================================== 3107 3108@node Embedded Commands, Registers, Identifiers, gtroff Reference 3109@section Embedded Commands 3110@cindex embedded commands 3111@cindex commands, embedded 3112 3113Most documents need more functionality beyond filling, adjusting and 3114implicit line breaking. In order to gain further functionality, 3115@code{gtroff} allows commands to be embedded into the text, in two ways. 3116 3117The first is a @dfn{request} which takes up an entire line, and does 3118some large-scale operation (e.g.@: break lines, start new pages). 3119 3120The other is an @dfn{escape} which can be embedded anywhere in the text, 3121or even as an argument to a request. 3122@c XXX (Not always?) 3123Escapes generally do more minor operations like sub- and superscripts, 3124print a symbol, etc. 3125 3126@menu 3127* Requests:: 3128* Macros:: 3129* Escapes:: 3130@end menu 3131 3132@c --------------------------------------------------------------------- 3133 3134@node Requests, Macros, Embedded Commands, Embedded Commands 3135@subsection Requests 3136@cindex requests 3137 3138@cindex control character 3139@cindex character, control 3140@cindex no-break control character 3141@cindex character, no-break control 3142@cindex control character, no-break 3143@rqindex ' 3144@rqindex . 3145A request line begins with a control character, which is either a single 3146quote (@samp{'}, the @dfn{no-break control character}) or a period 3147(@samp{.}, the normal @dfn{control character}). These can be changed; 3148see @ref{Character Translations}, for details. After this there may be 3149optional tabs or spaces followed by an identifier which is the name of 3150the request. This may be followed by any number of space-separated 3151arguments (@emph{no} tabs here). 3152 3153@cindex structuring source code of documents or macro packages 3154@cindex documents, structuring the source code 3155@cindex macro packages, strucuring the source code 3156Since a control character followed by whitespace only is ignored, it 3157is common practice to use this feature for structuring the source code 3158of documents or macro packages. 3159 3160@Example 3161.de foo 3162. tm This is foo. 3163.. 3164. 3165. 3166.de bar 3167. tm This is bar. 3168.. 3169@endExample 3170 3171@cindex blank line 3172@cindex blank line macro 3173@rqindex blm 3174Another possibility is to use the blank line macro request @code{blm} 3175by assigning an empty macro to it. 3176 3177@Example 3178.de do-nothing 3179.. 3180.blm do-nothing \" activate blank line macro 3181 3182.de foo 3183. tm This is foo. 3184.. 3185 3186 3187.de bar 3188. tm This is bar. 3189.. 3190 3191.blm \" deactivate blank line macro 3192@endExample 3193 3194@c XXX xref to blm 3195 3196@cindex zero width space character 3197@cindex character, zero width space 3198@cindex space character, zero width 3199@esindex \& 3200@cindex @code{\&}, escaping control characters 3201To begin a line with a control character without it being interpreted, 3202precede it with @code{\&}. This represents a zero width space, which 3203means it does not affect the output. 3204 3205In most cases the period is used as a control character. Several 3206requests cause a break implicitly; using the single quote control 3207character prevents this. 3208 3209@menu 3210* Request Arguments:: 3211@end menu 3212 3213@node Request Arguments, , Requests, Requests 3214@subsubsection Request Arguments 3215@cindex request arguments 3216@cindex arguments to requests 3217 3218Arguments to requests (and macros) are processed much like the shell: 3219The line is split into arguments according to spaces. An argument 3220which is intended to contain spaces can either be enclosed in double 3221quotes, or have the spaces @dfn{escaped} with backslashes. 3222 3223Here are a few examples: 3224 3225@Example 3226.uh The Mouse Problem 3227.uh "The Mouse Problem" 3228.uh The\ Mouse\ Problem 3229@endExample 3230 3231@esindex \~ 3232@esindex \@key{SP} 3233@noindent 3234The first line is the @code{uh} macro being called with 3 arguments, 3235@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 3236same effect of calling the @code{uh} macro with one argument, @samp{The 3237Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 3238is ``classical'' in the sense that it can be found in most @code{troff} 3239documents. Nevertheless, it is not optimal in all situations, since 3240@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 3241can't stretch. @code{gtroff} provides a different command @code{\~} to 3242insert a stretchable, non-breaking space.} 3243 3244@cindex @code{"}, as a macro argument 3245@cindex double quote, as a macro argument 3246A double quote which isn't preceded by a space doesn't start a macro 3247argument. If not closing a string, it is printed literally. 3248 3249For example, 3250 3251@Example 3252.xxx a" "b c" "de"fg" 3253@endExample 3254 3255@noindent 3256has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 3257 3258@rqindex ds 3259Duoble quotes in the @code{ds} request are handled differently. 3260@xref{Strings}, for more details. 3261 3262@c --------------------------------------------------------------------- 3263 3264@node Macros, Escapes, Requests, Embedded Commands 3265@subsection Macros 3266@cindex macros 3267 3268@code{gtroff} has a @dfn{macro} facility for defining a series of lines 3269which can be invoked by name. They are called in the same manner as 3270requests -- arguments also may be passed in the same manner. 3271 3272@xref{Writing Macros}, and @ref{Request Arguments}. 3273 3274@c --------------------------------------------------------------------- 3275 3276@node Escapes, , Macros, Embedded Commands 3277@subsection Escapes 3278@cindex escapes 3279 3280Escapes may occur anywhere in the input to @code{gtroff}. They usually 3281begin with a backslash and are followed by a single character which 3282indicates the function to be performed. The escape character can be 3283changed; see @ref{Character Translations}. 3284 3285@rqindex ( 3286@rqindex [ 3287@rqindex ] 3288Escape sequences which require an identifier as a parameter accept three 3289possible syntax forms. 3290 3291@itemize @bullet 3292@item 3293The next single character is the identifier. 3294 3295@item 3296If this single character is an opening parenthesis, take the following 3297two characters as the identifier. Note that there is no closing 3298parenthesis after the identifier. 3299 3300@item 3301If this single character is an opening bracket, take all characters 3302until a closing bracket as the identifier. 3303@end itemize 3304 3305@noindent 3306Examples: 3307 3308@Example 3309\fB 3310\n(XX 3311\*[TeX] 3312@endExample 3313 3314@rqindex ' 3315@cindex argument delimiting characters 3316@cindex characters, argument delimiting 3317@cindex delimiting characters for arguments 3318Other escapes may require several arguments and/or some special format. 3319In such cases the argument is traditionally enclosed in single quotes 3320(and quotes are always used in this manual for the definitions of escape 3321sequences). The enclosed text is then processed according to what that 3322escape expects. Example: 3323 3324@Example 3325\l'1.5i\(bu' 3326@endExample 3327 3328@esindex \o 3329@esindex \b 3330@esindex \X 3331Note that the quote character can be replaced with any other character 3332which does not occur in the argument (even a newline or a space 3333character) in the following escapes: @code{\o}, @code{\b}, and 3334@code{\X}. This makes e.g. 3335 3336@Example 3337A caf 3338\o 3339e\' 3340 3341 3342in Paris 3343 @result{} A caf@'e in Paris 3344@endExample 3345 3346@noindent 3347possible, but it is better not to use this feature to avoid confusion. 3348 3349@esindex \% 3350@esindex \@key{SP} 3351@esindex \| 3352@esindex \^ 3353@esindex \@{ 3354@esindex \@} 3355@esindex \' 3356@esindex \` 3357@esindex \- 3358@esindex \_ 3359@esindex \! 3360@esindex \? 3361@esindex \@@ 3362@esindex \) 3363@esindex \/ 3364@esindex \, 3365@esindex \& 3366@esindex \~ 3367@esindex \0 3368@esindex \a 3369@esindex \c 3370@esindex \d 3371@esindex \e 3372@esindex \E 3373@esindex \p 3374@esindex \r 3375@esindex \t 3376@esindex \u 3377The following escapes sequences (which are handled similarly to 3378characters since they don't take a parameter) are also allowed as 3379delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 3380@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 3381@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 3382@code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e}, 3383@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't 3384use these if possible. 3385 3386@esindex \A 3387@esindex \Z 3388@esindex \C 3389@esindex \w 3390No newline characters as delimiters are allowed in the following 3391escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}. 3392 3393@esindex \D 3394@esindex \h 3395@esindex \H 3396@esindex \l 3397@esindex \L 3398@esindex \N 3399@esindex \R 3400@esindex \s 3401@esindex \S 3402@esindex \v 3403@esindex \x 3404Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 3405@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and 3406@code{\x} can't use the following characters as delimiters: 3407 3408@itemize @bullet 3409@item 3410@cindex numbers 3411@cindex digits 3412The digits @code{0}-@code{9}. 3413 3414@item 3415@cindex operators 3416@opindex + 3417@opindex - 3418@opindex / 3419@opindex * 3420@opindex % 3421@opindex < 3422@opindex > 3423@opindex = 3424@opindex & 3425@opindex : 3426@opindex ( 3427@opindex ) 3428@opindex . 3429The (single-character) operators @samp{+-/*%<>=&:().}. 3430 3431@item 3432@cindex space character 3433@cindex character, space 3434@cindex tab character 3435@cindex character, tab 3436@cindex newline character 3437@cindex character, newline 3438The space, tab, and newline characters. 3439 3440@item 3441@esindex \% 3442@esindex \@{ 3443@esindex \@} 3444@esindex \' 3445@esindex \` 3446@esindex \- 3447@esindex \_ 3448@esindex \! 3449@esindex \@@ 3450@esindex \/ 3451@esindex \c 3452@esindex \e 3453@esindex \p 3454All escape sequences except @code{\%}, @code{\@{}, @code{\@}}, 3455@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 3456@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 3457@end itemize 3458 3459@esindex \\ 3460@esindex \e 3461@esindex \E 3462To have a backslash (actually, the current escape character) appear in the 3463output several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 3464These are very similar, and only differ with respect to being used in 3465macros or diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for 3466more information. 3467 3468@c XXX explanation of \E 3469 3470@xref{Identifiers}, and @ref{Character Translations}. 3471 3472@menu 3473* Comments:: 3474@end menu 3475 3476@node Comments, , Escapes, Escapes 3477@subsubsection Comments 3478@cindex comments 3479 3480Probably one of the most@footnote{Unfortunately, this is a lie. But 3481hopefully future @code{gtroff} hackers will believe it @code{:-)}} 3482common forms of escapes is the comment. 3483 3484@Defesc {\\", , , } 3485Start a comment. Everything to the end of the input line is ignored. 3486 3487This may sound simple, but it can be tricky to keep the comments from 3488interfering with the appearance of the final output. 3489 3490@rqindex ds 3491@rqindex as 3492If the escape is to the right of some text or a request, that portion 3493of the line is ignored, but the space leading up to it is noticed by 3494@code{gtroff}. This only affects the @code{.ds} and @code{.as} 3495request. 3496 3497@cindex tabs before comments 3498@cindex comments, lining up with tabs 3499One possibly irritating idiosyncracy is that tabs must not be used to 3500line up comments. Tabs are not treated as white space between the 3501request and macro arguments. 3502 3503@cindex undefined request 3504@cindex request, undefined 3505A comment on a line by itself is treated as a blank line, because 3506after eliminating the comment, that is all that remains: 3507 3508@Example 3509Test 3510\" comment 3511Test 3512@endExample 3513 3514@noindent 3515produces 3516 3517@Example 3518Test 3519 3520Test 3521@endExample 3522 3523To avoid this, it is common to start the line with @code{.\"} which 3524causes the line to be treated as an undefined request and thus ignored 3525completely. 3526 3527@rqindex ' 3528Another commenting scheme seen sometimes is three consecutive single 3529quotes (@code{'''}) at the beginning of a line. This works, but 3530@code{gtroff} gives a warning about an undefined macro (namely 3531@code{''}), which is harmless, but irritating. 3532@endDefesc 3533 3534@Defesc {\\#, , , } 3535To avoid all this, @code{gtroff} has a new comment mechanism using the 3536@code{\#} escape. This escape works the same as @code{\"} except that 3537the newline is also ignored: 3538 3539@Example 3540Test 3541\# comment 3542Test 3543@endExample 3544 3545@noindent 3546produces 3547 3548@Example 3549Test Test 3550@endExample 3551 3552@noindent 3553as expected. 3554@endDefesc 3555 3556@Defreq {ig, yy} 3557Ignore all input until @code{gtroff} encounters the macro named 3558@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not 3559specified). This is useful for commenting out large blocks of text: 3560 3561@Example 3562text text text... 3563.ig 3564This is part of a large block 3565of text that has been 3566temporarily(?) commented out. 3567 3568We can restore it simply by removing 3569the .ig request and the ".." at the 3570end of the block. 3571.. 3572More text text text... 3573@endExample 3574 3575@noindent 3576produces 3577 3578@Example 3579text text text@dots{} More text text text@dots{} 3580@endExample 3581 3582@noindent 3583Note that the commented-out block of text does not 3584cause a break. 3585 3586The input is read in copy-mode; auto-incremented registers @emph{are} 3587affected (@pxref{Auto-increment}). 3588@endDefreq 3589 3590 3591@c ===================================================================== 3592 3593@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 3594@section Registers 3595@cindex registers 3596 3597Numeric variables in @code{gtroff} are called @dfn{registers}. There 3598are a number of built-in registers, supplying anything from the date to 3599details of formatting parameters. 3600 3601@xref{Identifiers}, for details on register identifiers. 3602 3603@menu 3604* Setting Registers:: 3605* Interpolating Registers:: 3606* Auto-increment:: 3607* Assigning Formats:: 3608* Built-in Registers:: 3609@end menu 3610 3611@c --------------------------------------------------------------------- 3612 3613@node Setting Registers, Interpolating Registers, Registers, Registers 3614@subsection Setting Registers 3615@cindex setting registers 3616@cindex registers, setting 3617 3618Define or set registers using the @code{nr} request or the 3619@code{\R} escape. 3620 3621@Defreq {nr, ident value} 3622@Defescx {\\R, ', ident value, '} 3623Set number register @var{ident} to @var{value}. If @var{ident} 3624doesn't exist, @code{gtroff} creates it. 3625 3626The argument to @code{\R} usually has to be enclosed in quotes. 3627@xref{Escapes}, for details on parameter delimiting characters. 3628@endDefreq 3629 3630For example, the following two lines are equivalent: 3631 3632@Example 3633.nr a 1 3634\R'a 1' 3635@endExample 3636 3637Both @code{nr} and @code{\R} have two additional special forms to 3638increment or decrement a register. 3639 3640@Defreq {nr, ident @t{+}@Var{value}} 3641@Defreqx {nr, ident @t{-}@Var{value}} 3642@Defescx {\\R, ', ident @t{+}@Var{value}, '} 3643@Defescx {\\R, ', ident @t{-}@Var{value}, '} 3644Increment (decrement) register @var{ident} by @var{value}. 3645 3646@Example 3647.nr a 1 3648.nr a +1 3649\na 3650 @result{} 2 3651@endExample 3652 3653@cindex negating register values 3654To assign the negated value of a register to another register, some care 3655must be taken to get the desired result: 3656 3657@Example 3658.nr a 7 3659.nr b 3 3660.nr a -\nb 3661\na 3662 @result{} 4 3663.nr a (-\nb) 3664\na 3665 @result{} -3 3666@endExample 3667 3668@noindent 3669The surrounding parentheses prevent the interpretation of the minus sign 3670as a decrementing operator. An alternative is to start the assignment 3671with a @samp{0}: 3672 3673@Example 3674.nr a 7 3675.nr b -3 3676.nr a \nb 3677\na 3678 @result{} 4 3679.nr a 0\nb 3680\na 3681 @result{} -3 3682@endExample 3683@endDefreq 3684 3685@Defreq {rr, ident} 3686Remove number register @var{ident}. If @var{ident} doesn't exist, the 3687request is ignored. 3688@endDefreq 3689 3690@Defreq {rnn, ident1 ident2} 3691Rename number register @var{ident1} to @var{ident2}. If either 3692@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 3693@endDefreq 3694 3695@Defreq {aln, ident1 ident2} 3696Create an alias @var{ident1} for a number register @var{ident2}. The 3697new name and the old name are exactly equivalent. If @var{ident1} is 3698undefined, a warning of type @samp{reg} is generated, and the request 3699is ignored. @xref{Debugging}, for information about warnings. 3700@endDefreq 3701 3702@c --------------------------------------------------------------------- 3703 3704@node Interpolating Registers, Auto-increment, Setting Registers, Registers 3705@subsection Interpolating Registers 3706@cindex interpolating registers 3707@cindex registers, interpolating 3708 3709Numeric registers can be accessed via the @code{\n} escape. 3710 3711@cindex nested assignments 3712@cindex assignments, nested 3713@cindex indirect assignments 3714@cindex assignments, indirect 3715@Defesc {\\n, , i, } 3716@Defescx {\\n, @lparen{}, id, } 3717@Defescx {\\n, @lbrack{}, ident, @rbrack} 3718Interpolate number register with name @var{ident} (one-character name 3719@var{i}, two-character name @var{id}). This means that the value of 3720the register is expanded in-place while @code{gtroff} is parsing the 3721input line. Nested assignments (also called indirect assignments) are 3722possible. 3723 3724@Example 3725.nr a 5 3726.nr as \na+\na 3727\n(as 3728 @result{} 10 3729@endExample 3730 3731@Example 3732.nr a1 5 3733.nr ab 6 3734.ds str b 3735.ds num 1 3736\n[a\n[num]] 3737 @result{} 5 3738\n[a\*[str]] 3739 @result{} 6 3740@endExample 3741@endDefesc 3742 3743@c --------------------------------------------------------------------- 3744 3745@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 3746@subsection Auto-increment 3747@cindex auto-increment 3748@cindex increment, automatic 3749 3750Number registers can also be auto-incremented and auto-decremented. 3751The increment or decrement value can be specified with a third 3752argument to the @code{nr} request or @code{\R} escape. 3753 3754@esindex \R 3755@Defreq {nr, ident value incr} 3756Set number register @var{ident} to @var{value}; the increment for 3757auto-incrementing is set to @var{incr}. Note that the @code{\R} 3758escape doesn't support this notation. 3759@endDefreq 3760 3761To activate auto-incrementing, the escape @code{\n} has a special 3762syntax form. 3763 3764@Defesc {\\n, +, i, } 3765@Defescx {\\n, -, i, } 3766@Defescx {\\n, @lparen{}+, id, } 3767@Defescx {\\n, @lparen{}-, id, } 3768@Defescx {\\n, +@lparen{}, id, } 3769@Defescx {\\n, -@lparen{}, id, } 3770@Defescx {\\n, @lbrack{}+, ident, @rbrack{}} 3771@Defescx {\\n, @lbrack{}-, ident, @rbrack{}} 3772@Defescx {\\n, +@lbrack{}, ident, @rbrack{}} 3773@Defescx {\\n, -@lbrack{}, ident, @rbrack{}} 3774Before interpolating, increment or decrement @var{ident} 3775(one-character name @var{i}, two-character name @var{id}) by the 3776auto-increment value as specified with the @code{nr} request (or the 3777@code{\R} escape). If no auto-increment value has been specified, 3778these syntax forms are identical to @code{\n}. 3779@endDefesc 3780 3781For example, 3782 3783@Example 3784.nr a 0 1 3785.nr xx 0 5 3786.nr foo 0 -2 3787\n+a, \n+a, \n+a, \n+a, \n+a 3788.br 3789\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 3790.br 3791\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 3792@endExample 3793 3794@noindent 3795produces 3796 3797@Example 37981, 2, 3, 4, 5 3799-5, -10, -15, -20, -25 3800-2, -4, -6, -8, -10 3801@endExample 3802 3803@cindex increment value without changing the register 3804To change the increment value without changing the value of a register 3805(@var{a} in the example), the following can be used: 3806 3807@Example 3808.nr a \na 10 3809@endExample 3810 3811@c --------------------------------------------------------------------- 3812 3813@node Assigning Formats, Built-in Registers, Auto-increment, Registers 3814@subsection Assigning Formats 3815@cindex assigning formats 3816@cindex formats, assigning 3817 3818When a register is used in the text of an input file (as opposed to 3819part of an expression), it is textually replaced (or interpolated) 3820with a representation of that number. This output format can be 3821changed to a variety of formats (numbers, Roman numerals, etc.). This 3822is done using the @code{af} request. 3823 3824@Defreq {af, ident format} 3825Change the output format of a number register. The first argument 3826@var{ident} is the name of the number register to be changed, and the 3827second argument @var{format} is the output format. The following 3828output formats are available: 3829 3830@table @code 3831@item 1 3832Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{ 3833}@enddots{} 3834 3835@item 0@dots{}0 3836Decimal numbers with as many digits as specified. So, @samp{00} would 3837result in printing numbers as 01, 02, 03,@w{ }@enddots{} 3838 3839In fact, any digit instead of zero will do; @code{gtroff} only counts 3840how many digits are specified. As a consequence, @code{af}'s default 3841format @samp{1} could be specified as @samp{0} also (and exactly this is 3842returned by the @code{\g} escape, see below). 3843 3844@item I 3845@cindex Roman numerals 3846@cindex numerals, Roman 3847Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{} 3848 3849@item i 3850Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{} 3851 3852@item A 3853Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{} 3854 3855@item a 3856Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{} 3857@end table 3858 3859Omitting the number register format causes a warning of type 3860@samp{missing}. @xref{Debugging}, for more details. Specifying a 3861nonexistent format causes an error. 3862 3863The following example produces @samp{10, X, j, 010}: 3864 3865@Example 3866.nr a 10 3867.af a 1 \" the default format 3868\na, 3869.af a I 3870\na, 3871.af a a 3872\na, 3873.af a 001 3874\na 3875@endExample 3876 3877@cindex Roman numerals, maximum and minimum 3878@cindex maximum values of Roman numerals 3879@cindex minimum values of Roman numerals 3880The largest number representable for the @samp{i} and @samp{I} formats 3881is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 3882and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 3883@code{gtroff}. Currently, the correct glyphs of Roman numeral five 3884thousand and Roman numeral ten thousand (Unicode code points 3885@code{U+2182} and @code{U+2181}, respectively) are not available. 3886 3887If @var{ident} doesn't exist, it is created. 3888 3889@cindex read-only register, changing format 3890@cindex changing format, read-only register 3891Changing the output format of a read-only register causes an error. It 3892is necessary to first copy the register's value to a writeable register, 3893then apply the @code{af} request to this other register. 3894@endDefreq 3895 3896@cindex format of register 3897@cindex register, format 3898@Defesc {\\g, , i, } 3899@Defescx {\\g, @lparen{}, id, } 3900@Defescx {\\g, @lbrack{}, ident, @rbrack{}} 3901Return the current format of the specified register @var{ident} 3902(one-character name @var{i}, two-character name @var{id}). For 3903example, @samp{\ga} after the previous example would produce the 3904string @samp{000}. If the register hasn't been defined yet, nothing 3905is returned. 3906@endDefesc 3907 3908@c --------------------------------------------------------------------- 3909 3910@node Built-in Registers, , Assigning Formats, Registers 3911@subsection Built-in Registers 3912@cindex built-in registers 3913@cindex registers, built-in 3914 3915The following lists some built-in registers which are not described 3916elsewhere in this manual. Any register which begins with a @samp{.} is 3917read-only. A complete listing of all built-in registers can be found in 3918@ref{Register Index}. 3919 3920@table @code 3921@item .H 3922@cindex horizontal resolution register 3923@cindex resolution, horizontal, register 3924@vindex .H 3925Horizontal resolution in basic units. 3926 3927@item .V 3928@cindex vertical resolution register 3929@cindex resolution, vertical, register 3930@vindex .V 3931Vertical resolution in basic units. 3932 3933@item dw 3934@cindex day of the week register 3935@cindex date, day of the week register 3936@vindex dw 3937Day of the week (1-7). 3938 3939@item dy 3940@cindex day of the month register 3941@cindex date, day of the month register 3942@vindex dy 3943Day of the month (1-31). 3944 3945@item mo 3946@cindex month of the year register 3947@cindex date, month of the year register 3948@vindex mo 3949Current month (1-12). 3950 3951@item year 3952@cindex date, year register 3953@cindex year, current, register 3954@vindex year 3955The current year. 3956 3957@item yr 3958@vindex yr 3959The current year minus@w{ }1900. Unfortunately, the documentation of 3960@acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It 3961incorrectly claimed that @code{yr} contains the last two digits of the 3962year. That claim has never been true of either traditional @code{troff} 3963or GNU @code{troff}. Old @code{troff} input that looks like this: 3964 3965@Example 3966'\" The following line stopped working after 1999 3967This document was formatted in 19\n(yr. 3968@endExample 3969 3970@noindent 3971can be corrected as follows: 3972 3973@Example 3974This document was formatted in \n[year]. 3975@endExample 3976 3977@noindent 3978or, to be portable to older @code{troff} versions, as follows: 3979 3980@Example 3981.nr y4 1900+\n(yr 3982This document was formatted in \n(y4. 3983@endExample 3984 3985@item .c 3986@vindex .c 3987@itemx c. 3988@vindex c. 3989@cindex input line number register 3990@cindex line number, input, register 3991The current @emph{input} line number. Register @samp{.c} is read-only, 3992whereas @samp{c.} (a @code{gtroff} extension) is writable also, 3993affecting both @samp{.c} and @samp{c.}. 3994 3995@item ln 3996@vindex ln 3997@rqindex nm 3998@cindex output line number register 3999@cindex line number, output, register 4000The current @emph{output} line number after a call to the @code{nm} 4001request to activate line numbering. 4002 4003@xref{Miscellaneous}, for more information about line numbering. 4004 4005@item .x 4006@vindex .x 4007@cindex major version number register 4008@cindex version number, major, register 4009The major version number. For example, if the version number is@w{ 4010}1.03 then @code{.x} contains@w{ }@samp{1}. 4011 4012@item .y 4013@vindex .y 4014@cindex minor version number register 4015@cindex version number, minor, register 4016The minor version number. For example, if the version number is@w{ 4017}1.03 then @code{.y} contains@w{ }@samp{03}. 4018 4019@item .Y 4020@vindex .Y 4021@cindex revision number register 4022The revision number of @code{groff}. 4023 4024@item .g 4025@vindex .g 4026@cindex @code{gtroff} identification register 4027@cindex GNU-specific register 4028Always@w{ }1. Macros should use this to determine whether they are 4029running under GNU @code{troff}. 4030 4031@item .A 4032@vindex .A 4033@cindex @acronym{ASCII} approximation output register 4034If the command line option @option{-a} is used to produce an 4035@acronym{ASCII} approximation of the output, this is set to@w{ }1, zero 4036otherwise. @xref{Groff Options}. 4037 4038@item .P 4039@vindex .P 4040This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current 4041page is actually being printed, i.e., if the @option{-o} option is being 4042used to only print selected pages. @xref{Groff Options}, for more 4043information. 4044 4045@item .T 4046@vindex .T 4047If @code{gtroff} is called with the @option{-T} command line option, the 4048number register @code{.T} is set to@w{ }1, and zero otherwise. 4049@xref{Groff Options}. 4050 4051@stindex .T 4052@cindex output device register 4053Additionally, @code{gtroff} predefines a single read-write string 4054register @code{.T} which contains the current output device (for 4055example, @samp{latin1} or @samp{ps}). 4056@end table 4057 4058 4059@c ===================================================================== 4060 4061@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 4062@section Manipulating Filling and Adjusting 4063@cindex manipulating filling and adjusting 4064@cindex filling and adjusting, manipulating 4065@cindex adjusting and filling, manipulating 4066@cindex justifying text 4067@cindex text, justifying 4068 4069@cindex break 4070@cindex line break 4071@rqindex bp 4072@rqindex ce 4073@rqindex cf 4074@rqindex fi 4075@rqindex fl 4076@rqindex in 4077@rqindex nf 4078@rqindex rj 4079@rqindex sp 4080@rqindex ti 4081@rqindex trf 4082Various ways of causing @dfn{breaks} were given in @ref{Implicit Line 4083Breaks}. The @code{br} request likewise causes a break. Several 4084other requests also cause breaks, but implicitly. These are 4085@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 4086@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 4087 4088@Defreq {br, } 4089Break the current line, i.e., the input collected so far is emitted 4090without adjustment. 4091 4092If the no-break control character is used, @code{gtroff} suppresses 4093the break: 4094 4095@Example 4096a 4097'br 4098b 4099 @result{} a b 4100@endExample 4101@endDefreq 4102 4103Initially, @code{gtroff} fills and adjusts text to both margins. 4104Filling can be disabled via the @code{nf} request and re-enabled with 4105the @code{fi} request. 4106 4107@cindex fill mode 4108@cindex mode, fill 4109@Defreq {fi, } 4110@Defregx {.u} 4111Activate fill mode (which is the default). This request implicitly 4112enables adjusting; it also inserts a break in the text currently being 4113filled. The read-only number register @code{.u} is set to@w{ }1. 4114 4115The fill mode status is associated with the current environment 4116(@pxref{Environments}). 4117@endDefreq 4118 4119@cindex no-fill mode 4120@cindex mode, no-fill 4121@Defreq {nf, } 4122Activate no-fill mode. Input lines are output as-is, retaining line 4123breaks and ignoring the current line length. This command implicitly 4124disables adjusting; it also causes a break. The number register 4125@code{.u} is set to@w{ }0. 4126 4127The fill mode status is associated with the current environment 4128(@pxref{Environments}). 4129@endDefreq 4130 4131@Defreq {ad, [@Var{mode}]} 4132@Defregx {.j} 4133Set adjusting mode. 4134 4135Activation and deactivation of adjusting is done implicitly with 4136calls to the @code{fi} or @code{nf} requests. 4137 4138@var{mode} can have one of the following values: 4139 4140@table @code 4141@item l 4142@cindex ragged-right 4143Adjust text to the left margin. This produces what is traditionally 4144called ragged-right text. 4145 4146@item r 4147@cindex ragged-left 4148Adjust text to the right margin, producing ragged-left text. 4149 4150@item c 4151@cindex centered text 4152@rqindex ce 4153Center filled text. This is different to the @code{ce} request which 4154only centers text without filling. 4155 4156@item b 4157@itemx n 4158Justify to both margins. This is the default used by @code{gtroff}. 4159@end table 4160 4161With no argument, @code{gtroff} adjusts lines in the same way it did 4162before adjusting was deactivated (with a call to @code{na}, for 4163example). 4164 4165@Example 4166text 4167.ad r 4168text 4169.ad c 4170text 4171.na 4172text 4173.ad \" back to centering 4174text 4175@endExample 4176 4177@cindex current adjustment mode register 4178The current adjustment mode is available in the read-only number 4179register @code{.j}; it can be stored and subsequently used to set 4180adjustment. 4181 4182The adjustment mode status is associated with the current environment 4183(@pxref{Environments}). 4184@endDefreq 4185 4186@Defreq {na, } 4187Disable adjusting. This request won't change the current adjustment 4188mode: A subsequent call to @code{ad} uses the previous adjustment 4189setting. 4190 4191The adjustment mode status is associated with the current environment 4192(@pxref{Environments}). 4193@endDefreq 4194 4195@Defesc {\\p, , , } 4196Adjust the current line and cause a break. 4197 4198In most cases this produces very ugly results, since @code{gtroff} 4199doesn't have a sophisticated paragraph building algorithm (as @TeX{} 4200have, for example); instead, @code{gtroff} fills and adjusts a paragraph 4201line by line: 4202 4203@Example 4204 This is an uninteresting sentence. 4205 This is an uninteresting sentence.\p 4206 This is an uninteresting sentence. 4207@endExample 4208 4209@noindent 4210is formatted as 4211 4212@Example 4213 This is an uninteresting sentence. This is an 4214 uninteresting sentence. 4215 This is an uninteresting sentence. 4216@endExample 4217@endDefesc 4218 4219@cindex word space size 4220@cindex size of word space 4221@cindex space between words 4222@cindex sentence space size 4223@cindex size of sentence space 4224@cindex space between sentences 4225@Defreq {ss, word_space_size [@Var{sentence_space_size}]} 4226@Defregx {.ss} 4227@Defregx {.sss} 4228Change the minimum size of a space between filled words. It takes its 4229units as one twelfth of the space width parameter for the current 4230font. Initially both the @var{word_space_size} and 4231@var{sentence_space_size} are@w{ }12. 4232 4233@cindex fill mode 4234@cindex mode, fill 4235If two arguments are given to the @code{ss} request, the second 4236argument sets the sentence space size. If the second argument is not 4237given, sentence space size is set to @var{word_space_size}. The 4238sentence space size is used in two circumstances: If the end of a 4239sentence occurs at the end of a line in fill mode, then both an 4240inter-word space and a sentence space are added; if two spaces follow 4241the end of a sentence in the middle of a line, then the second space 4242is a sentence space. If a second argument is never given to the 4243@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 4244same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 4245in @acronym{UNIX} @code{troff}, a sentence should always be followed 4246by either a newline or two spaces. 4247 4248The read-only number registers @code{.ss} and @code{.sss} hold the 4249values of the parameters set by the first and second arguments of the 4250@code{ss} request. 4251 4252The word space and sentence space values are associated with the current 4253environment (@pxref{Environments}). 4254 4255Contrary to traditional Unix @code{troff}, this request is @emph{not} 4256ignored if a tty output device is used; the given values are then 4257rounded down to a multiple of@w{ }12. 4258 4259@c XXX xref implementation differences 4260 4261The request is ignored if there is no parameter. 4262@endDefreq 4263 4264@cindex centering lines 4265@cindex lines, centering 4266@Defreq {ce, [@Var{nnn}]} 4267@Defregx {.ce} 4268Center text. While the @w{@samp{.ad c}} request also centers text, 4269it fills the text as well. @code{ce} does not fill the 4270text it affects. This request causes a break. 4271 4272The following example demonstrates the differences. 4273Here the input: 4274 4275@Example 4276.ll 4i 4277.ce 1000 4278This is a small text fragment which shows the differences 4279between the `.ce' and the `.ad c' request. 4280.ce 0 4281 4282.ad c 4283This is a small text fragment which shows the differences 4284between the `.ce' and the `.ad c' request. 4285@endExample 4286 4287@noindent 4288And here the result: 4289 4290@Example 4291 This is a small text fragment which 4292 shows the differences 4293between the `.ce' and the `.ad c' request. 4294 4295 This is a small text fragment which 4296shows the differences between the `.ce' 4297 and the `.ad c' request. 4298@endExample 4299 4300With no arguments, @code{ce} centers the next line of text. @var{nnn} 4301specifies the number of lines to be centered. If the argument is zero 4302or negative, centering is disabled. 4303 4304@rqindex ll 4305@rqindex in 4306@rqindex ti 4307The basic length for centering text is the line length (as set with the 4308@code{ll} request) minus the indentation (as set with the @code{in} 4309request). Temporary indentation is ignored. 4310 4311As can be seen in the previous example, it is a common idiom to turn 4312on centering for a large number of lines, and to turn off centering 4313after text to be centered. This is useful for any request which takes 4314a number of lines as an argument. 4315 4316The @code{.ce} read-only number register contains the number of lines 4317remaining to be centered, as set by the @code{ce} request. 4318@endDefreq 4319 4320@cindex justifying text 4321@cindex text, justifying 4322@cindex right-justifying 4323@Defreq {rj, [@Var{nnn}]} 4324@Defregx {.rj} 4325Justify unfilled text to the right margin. Arguments are identical to 4326the @code{ce} request. The @code{.rj} read-only number register is 4327the number of lines to be right-justified as set by the @code{rj} 4328request. This request causes a break. 4329@endDefreq 4330 4331 4332@c ===================================================================== 4333 4334@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 4335@section Manipulating Hyphenation 4336@cindex manipulating hyphenation 4337@cindex hyphenation, manipulating 4338 4339As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words. 4340There are a number of ways to influence hyphenation. 4341 4342@Defreq {hy, [@Var{mode}]} 4343@Defregx {.hy} 4344Enable hyphenation. The request has an optional numeric argument, 4345@var{mode}, to restrict hyphenation if necessary: 4346 4347@table @code 4348@item 1 4349The default argument if @var{mode} is omitted. Hyphenate without 4350restrictions. This is also the start-up value of @code{gtroff}. 4351 4352@item 2 4353Do not hyphenate the last word on a page or column. 4354 4355@item 4 4356Do not hyphenate the last two characters of a word. 4357 4358@item 8 4359Do not hyphenate the first two characters of a word. 4360@end table 4361 4362Values in the previous table are additive. For example, the value@w{ 4363}12 causes @code{gtroff} to neither hyphenate the last two nor the first 4364two characters of a word. 4365 4366@cindex hyphenation restrictions register 4367The current hyphenation restrictions can be found in the read-only 4368number register @samp{.hy}. 4369 4370The hyphenation mode is associated with the current environment 4371(@pxref{Environments}). 4372@endDefreq 4373 4374@Defreq {nh, } 4375Disable hyphenation (i.e., set the hyphenation mode to zero). Note 4376that the hyphenation mode of the last call to @code{hy} is not 4377remembered. 4378 4379The hyphenation mode is associated with the current environment 4380(@pxref{Environments}). 4381@endDefreq 4382 4383@esindex \% 4384@cindex explicit hyphens 4385@cindex hyphen, explicit 4386@cindex consecutive hyphenated lines 4387@cindex lines, consecutive hyphenated 4388@cindex hyphenated lines, consecutive 4389@Defreq {hlm, [@Var{nnn}]} 4390@Defregx {.hlm} 4391@Defregx {.hlc} 4392Set the maximum number of consecutive hyphenated lines to @var{nnn}. 4393If this number is negative, there is no maximum. The default value 4394is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated 4395with the current environment (@pxref{Environments}). Only lines 4396output from a given environment count towards the maximum associated 4397with that environment. Hyphens resulting from @code{\%} are counted; 4398explicit hyphens are not. 4399 4400The current setting of @code{hlm} is available in the @code{.hlm} 4401read-only number register. Also the number of immediately preceding 4402consecutive hyphenated lines are available in the read-only number 4403register @samp{.hlc}. 4404@endDefreq 4405 4406@Defreq {hw, word1 word2 @dots{}} 4407Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 4408words must be given with hyphens at the hyphenation points. For 4409example: 4410 4411@Example 4412.hw in-sa-lub-rious 4413@endExample 4414 4415@noindent 4416Besides the space character, any character whose hyphenation code value 4417is zero can be used to separate the arguments of @code{hw} (see the 4418documentation for the @code{hcode} request below for more information). 4419In addition, this request can be used more than once. 4420 4421Hyphenation exceptions specified with the @code{hw} request are 4422associated with the current hyphenation language; it causes an error 4423if there is no current hyphenation language. 4424 4425This request is ignored if there is no parameter. 4426 4427In old versions of @code{troff} there was a limited amount of space to 4428store such information; fortunately, with @code{gtroff}, this is no 4429longer a restriction. 4430@endDefreq 4431 4432@cindex hyphenation character 4433@cindex character, hyphenation 4434@cindex disabling hyphenation 4435@cindex hyphenation, disabling 4436@Defesc {\\%, , , } 4437To tell @code{gtroff} how to hyphenate words on the fly, use the 4438@code{\%} escape, also known as the @dfn{hyphenation character}. 4439Preceding a word with this character prevents it from being 4440hyphenated; putting it inside a word indicates to @code{gtroff} that 4441the word may be hyphenated at that point. Note that this mechanism 4442only affects that one occurrence of the word; to change the 4443hyphenation of a word for the entire document, use the @code{hw} 4444request. 4445@endDefesc 4446 4447@Defreq {hc, [@Var{char}]} 4448Change the hyphenation character to @var{char}. This character then 4449works the same as the @code{\%} escape, and thus, no longer appears in 4450the output. Without an argument, @code{hc} resets the hyphenation 4451character to be @code{\%} (the default) only. 4452 4453The hyphenation character is associated with the current environment 4454(@pxref{Environments}). 4455@endDefreq 4456 4457@cindex hyphenation patterns 4458@cindex patterns for hyphenation 4459@Defreq {hpf, pattern_file} 4460Read in a file of hyphenation patterns. This file is searched for in 4461the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 4462searched for if the @option{-m@var{name}} option is specified. 4463 4464It should have the same format as the argument to the @code{\patterns} 4465primitive in @TeX{} (without using @TeX{}'s macro expansion); the 4466letters appearing in this file are interpreted as hyphenation codes. A 4467@samp{%} character in the patterns file introduces a comment that 4468continues to the end of the line. 4469 4470If no @code{hpf} request is specified (either in the document or in a 4471macro package), @code{gtroff} won't hyphenate at all. 4472 4473@rqindex hla 4474@pindex troffrc 4475@pindex troffrc-end 4476@pindex hyphen.us 4477The set of hyphenation patterns is associated with the current language 4478set by the @code{hla} request. The @code{hpf} request is usually 4479invoked by the @file{troffrc} or @file{troffrc-end} file; by default, 4480@file{troffrc} loads hyphenation patterns for American English (in file 4481@file{hyphen.us}). 4482 4483Invoking @code{hpf} causes an error if there is no current hyphenation 4484language. 4485@endDefreq 4486 4487@cindex hyphenation code 4488@cindex code, hyphenation 4489@Defreq {hcode, c1 code1 c2 code2 @dots{}} 4490Set the hyphenation code of character @var{c1} to @var{code1}, that of 4491@var{c2} to @var{code2}, etc. A hyphenation code must be a single 4492input character (not a special character) other than a digit or a 4493space. Initially each lower-case letter (@samp{a}-@samp{z}) has its 4494hyphenation set to itself, and each upper-case letter 4495(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case 4496version of itself. 4497 4498This request is ignored if it has no parameter. 4499@endDefreq 4500 4501@cindex hyphenation margin 4502@cindex margin for hyphenation 4503@rqindex ad 4504@Defreq {hym, [@Var{length}]} 4505@Defregx {.hym} 4506Set the (right) hyphenation margin to @var{length}. If the current 4507adjustment mode is not @samp{b} or@w{ }@samp{n}, the line is not 4508hyphenated if it is shorter than @var{length}. Without an argument, 4509the hyphenation margin is reset to its default value, which is@w{ }0. 4510The default scaling indicator for this request is@w{ }@code{m}. The 4511hyphenation margin is associated with the current environment 4512(@pxref{Environments}). 4513 4514A negative argument resets the hyphenation margin to zero, emitting 4515a warning of type @samp{range}. 4516 4517@cindex current hyphenation margin register 4518The current hyphenation margin is available in the @code{.hym} read-only 4519number register. 4520@endDefreq 4521 4522@cindex hyphenation space 4523@rqindex ad 4524@Defreq {hys, [@Var{hyphenation_space}]} 4525@Defregx {.hys} 4526Set the hyphenation space to @var{hyphenation_space}. If the current 4527adjustment mode is @samp{b} or@w{ }@samp{n}, don't hyphenate the line 4528if it can be justified by adding no more than @var{hyphenation_space} 4529extra space to each word space. Without argument, the hyphenation 4530space is set to its default value, which is@w{ }0. The default 4531scaling indicator for this request is@w{ }@code{m}. The hyphenation 4532space is associated with the current environment 4533(@pxref{Environments}). 4534 4535A negative argument resets the hyphenation space to zero, emitting a 4536warning of type @samp{range}. 4537 4538@cindex current hyphenation space register 4539The current hyphenation space is available in the @code{.hys} read-only 4540number register. 4541@endDefreq 4542 4543@cindex soft hyphen character 4544@cindex character, soft hyphen 4545@glindex hy 4546@rqindex char 4547@rqindex tr 4548@Defreq {shc, [@Var{char}]} 4549Set the soft hyphen character to @var{char}. If the argument is 4550omitted, the soft hyphen character is set to the default character 4551@code{\(hy} (this is the start-up value of @code{gtroff} also). The 4552soft hyphen character is the character that is inserted when a word is 4553hyphenated at a line break. If the soft hyphen character does not 4554exist in the font of the character immediately preceding a potential 4555break point, then the line is not broken at that point. Neither 4556definitions (specified with the @code{char} request) nor translations 4557(specified with the @code{tr} request) are considered when finding the 4558soft hyphen character. 4559@endDefreq 4560 4561@rqindex hpf 4562@rqindex hw 4563@pindex troffrc 4564@pindex troffrc-end 4565@Defreq {hla, language} 4566@Defregx {.hla} 4567Set the current hyphenation language to the string @var{language}. 4568Hyphenation exceptions specified with the @code{hw} request and 4569hyphenation patterns specified with the @code{hpf} request are both 4570associated with the current hyphenation language. The @code{hla} 4571request is usually invoked by the @file{troffrc} or the 4572@file{troffrc-end} files; @file{troffrc} sets the default language to 4573@samp{us}. 4574 4575@cindex current hyphenation language register 4576The current hyphenation language is available as a string in the 4577read-only number register @samp{.hla}. 4578 4579@Example 4580.ds curr_language \n[.hla] 4581\*[curr_language] 4582 @result{} us 4583@endExample 4584@endDefreq 4585 4586 4587@c ===================================================================== 4588 4589@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 4590@section Manipulating Spacing 4591@cindex manipulating spacing 4592@cindex spacing, manipulating 4593 4594@Defreq {sp, [@Var{distance}]} 4595Space downwards @var{distance}. With no argument it advances 1@w{ 4596}line. A negative argument causes @code{gtroff} to move up the page 4597the specified distance. If the argument is preceded by a @samp{|} 4598then @code{gtroff} moves that distance from the top of the page. This 4599request causes a line break. The default scaling indicator is@w{ 4600}@code{v}. 4601@endDefreq 4602 4603@cindex double-spacing 4604@Defreq {ls, [@Var{nnn}]} 4605@Defregx {.L} 4606Output @w{@var{nnn}@minus{}1} blank lines after each line of text. 4607With no argument, @code{gtroff} uses the previous value before the 4608last @code{ls} call. 4609 4610@Example 4611.ls 2 \" This causes double-spaced output 4612.ls 3 \" This causes triple-spaced output 4613.ls \" Again double spaced 4614@endExample 4615 4616The line spacing is associated with the current environment 4617(@pxref{Environments}). 4618 4619@cindex current line spacing register 4620The read-only number register @code{.L} contains the current line 4621spacing setting. 4622@endDefreq 4623 4624@c XXX document \n[nl] 4625@c XXX document \n[nl] == -1 if vertical position is zero 4626 4627@Defesc {\\x, ', spacing, '} 4628@Defregx {.a} 4629Sometimes, extra vertical spacing is only needed occasionally, e.g.@: 4630to allow space for a tall construct (like an equation). The @code{\x} 4631escape does this. The escape is given a numerical argument, usually 4632enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 4633is@w{ }@code{v}. If this number is positive extra vertical space is 4634inserted below the current line. A negative number adds space above. 4635If this escape is used multiple times on the same line, the maximum of 4636the values is used. 4637 4638@xref{Escapes}, for details on parameter delimiting characters. 4639 4640@cindex extra vertical line space register 4641The @code{.a} read-only number register contains the most recent 4642(nonnegative) extra vertical line space. 4643 4644@c XXX 4645@ignore 4646@Example 4647... example of inline equation ... 4648@endExample 4649@end ignore 4650@endDefesc 4651 4652@rqindex sp 4653@cindex no-space mode 4654@cindex mode, no-space 4655@cindex blank lines, disabling 4656@cindex lines, blank, disabling 4657@Defreq {ns, } 4658@Defregx {.ns} 4659Enable @dfn{no-space mode}. In this mode, spacing (either via 4660@code{sp} or via blank lines) is disabled. The @code{bp} request to 4661advance to the next page is also disabled, except if it is accompanied 4662by a page number (see @ref{Page Control}, for more information). This 4663mode ends when actual text is output or the @code{rs} request is 4664encountered. The read-only number register @code{.ns} is set to@w{ }1. 4665 4666This request is useful for macros which want to avoid that subsequent 4667macros inadvertently insert some vertical space before the text starts 4668(for example, to set up the first paragraph after a section header). 4669 4670@c XXX xref 4671@endDefreq 4672 4673@Defreq {rs, } 4674Disable no-space mode. 4675 4676@c XXX xref 4677@endDefreq 4678 4679 4680@c ===================================================================== 4681 4682@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 4683@section Tabs and Fields 4684@cindex tabs and fields 4685@cindex fields and tabs 4686 4687@cindex @acronym{EBCDIC} encoding of a tab 4688A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{ 4689}5) causes a horizontal movement to the next tab stop (much 4690like it did on a typewriter). 4691 4692@Defesc {\\t, , , } 4693This escape is a non-interpreted tab character. In copy mode 4694(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 4695@endDefesc 4696 4697@Defreq {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 4698@Defregx {.tabs} 4699Change tab stop positions. This request takes a series of tab 4700specifiers as arguments (optionally divided into two groups with the 4701letter @samp{T}) which indicate where each tab stop is to be 4702(overriding any previous settings). 4703 4704Tab stops can be specified absolutely, i.e., as the distance from the 4705left margin. For example, the following sets 6@w{ }tab stops every 4706one inch. 4707 4708@Example 4709.ta 1i 2i 3i 4i 5i 6i 4710@endExample 4711 4712Tab stops can also be specified using a leading @samp{+} 4713which means that the specified tab stop is set relative to 4714the previous tab stop. For example, the following is equivalent to the 4715previous example. 4716 4717@Example 4718.ta 1i +1i +1i +1i +1i +1i 4719@endExample 4720 4721@code{gtroff} supports an extended syntax to specify repeat values after 4722the @samp{T} mark (these values are always taken as relative) -- this is 4723the usual way to specify tabs set at equal intervals. The following is, 4724yet again, the same as the previous examples. It does even more since 4725it defines an infinite number of tab stops separated by one inch. 4726 4727@Example 4728.ta T 1i 4729@endExample 4730 4731Now we are ready to interpret the full syntax given at the beginning: 4732Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 4733tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 4734and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 4735@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 4736 4737Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 473820c 23c 28c 30c @dots{}}. 4739 4740The material in each tab column (i.e., the column between two tab stops) 4741may be justified to the right or left or centered in the column. This 4742is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 4743specifier. The default justification is @samp{L}. Example: 4744 4745@Example 4746.ta 1i 2iC 2iR 4747@endExample 4748 4749Some notes: 4750 4751@itemize @bullet 4752@item 4753The default unit of the @code{ta} request is @samp{m}. 4754 4755@item 4756A tab stop is converted into a non-breakable horizontal movement which 4757can be neither stretched nor squeezed. For example, 4758 4759@Example 4760.ds foo a\tb\tc 4761.ta T 5i 4762\*[foo] 4763@endExample 4764 4765@noindent 4766creates a single line which is a bit longer than 10@w{ }inches (a string 4767is used to show exactly where the tab characters are). Now consider the 4768following: 4769 4770@Example 4771.ds bar a\tb b\tc 4772.ta T 5i 4773\*[bar] 4774@endExample 4775 4776@noindent 4777@code{gtroff} first converts the tab stops of the line into unbreakable 4778horizontal movements, then splits the line after the second @samp{b} 4779(assuming a sufficiently short line length). Usually, this isn't what 4780the user wants. 4781 4782@item 4783Superfluous tabs (i.e., tab characters which do not correspond to a tab 4784stop) are ignored except the first one which delimits the characters 4785belonging to the last tab stop for right-justifying or centering. 4786Consider the following example 4787 4788@Example 4789.ds Z foo\tbar\tfoo 4790.ds ZZ foo\tbar\tfoobar 4791.ds ZZZ foo\tbar\tfoo\tbar 4792.ta 2i 4iR 4793\*[Z] 4794.br 4795\*[ZZ] 4796.br 4797\*[ZZZ] 4798.br 4799@endExample 4800 4801@noindent 4802which produces the following output: 4803 4804@Example 4805foo bar foo 4806foo bar foobar 4807foo bar foobar 4808@endExample 4809 4810@noindent 4811The first line right-justifies the second `foo' relative to the tab 4812stop. The second line right-justifies `foobar'. The third line finally 4813right-justifies only `foo' because of the additional tab character which 4814marks the end of the string belonging to the last defined tab stop. 4815 4816@item 4817Tab stops are associated with the current environment 4818(@pxref{Environments}). 4819 4820@item 4821Calling @code{ta} without an argument removes all tab stops. 4822 4823@item 4824@cindex tab stops, for tty output devices 4825The start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. This value 4826is used even for tty output devices (contrary to @acronym{UNIX} 4827@code{nroff} which has tab stops preset every 0.8@dmn{i}). 4828 4829@c XXX xref implementation differences 4830@end itemize 4831 4832@cindex current tab settings register 4833The read-only number register @code{.tabs} contains a string 4834representation of the current tab settings suitable for use as an 4835argument to the @code{ta} request. 4836 4837@Example 4838.ds tab-string \n[.tabs] 4839\*[tab-string] 4840 @result{} T120u 4841@endExample 4842@endDefreq 4843 4844@cindex tab repetition character 4845@cindex character, tab repetition 4846@Defreq {tc, [@Var{fill-char}]} 4847Normally @code{gtroff} fills the space to the next tab stop with 4848whitespace. This can be changed with the @code{tc} request. With no 4849argument @code{gtroff} reverts to using whitespace, which is the 4850default. The value of this @dfn{tab repetition} character is 4851associated with the current environment (@pxref{Environments}). 4852@endDefreq 4853 4854@menu 4855* Leaders:: 4856* Fields:: 4857@end menu 4858 4859@c --------------------------------------------------------------------- 4860 4861@node Leaders, Fields, Tabs and Fields, Tabs and Fields 4862@subsection Leaders 4863@cindex leaders 4864 4865Sometimes it may may be desirable to use the @code{tc} request to fill a 4866particular tab stop with a given character (for example dots in a table 4867of contents), but also normal tab stops on the rest of the line. For 4868this @code{gtroff} provides an alternate tab mechanism, called 4869@dfn{leaders} which does just that. 4870 4871@cindex leader character 4872A leader character (character code@w{ }1) behaves similarly to a tab 4873character: It moves to the next tab stop. The only difference is that 4874for this movement, the fill character defaults to a period character and 4875not to space. 4876 4877@Defesc {\\a, , , } 4878This escape is a non-interpreted leader character. In copy mode 4879(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 4880character. 4881@endDefesc 4882 4883@cindex leader repetition character 4884@cindex character, leader repetition 4885@Defreq {lc, [@Var{fill-char}]} 4886Declare the leader character. Without an argument, leaders act the 4887same as tabs (i.e., using whitespace for filling). @code{gtroff}'s 4888start-up value is @samp{.}. The value of this @dfn{leader repetition} 4889character is associated with the current environment 4890(@pxref{Environments}). 4891@endDefreq 4892 4893@cindex table of contents 4894@cindex contents, table of 4895For a table of contents, to name an example, tab stops may be defined so 4896that the section number is one tab stop, the title is the second with 4897the remaining space being filled with a line of dots, and then the page 4898number slightly separated from the dots. 4899 4900@Example 4901.ds entry 1.1\tFoo\a\t12 4902.lc . 4903.ta 1i 5i +.25i 4904\*[entry] 4905@endExample 4906 4907@noindent 4908This produces 4909 4910@Example 49111.1 Foo.......................................... 12 4912@endExample 4913 4914@c --------------------------------------------------------------------- 4915 4916@node Fields, , Leaders, Tabs and Fields 4917@subsection Fields 4918@cindex fields 4919 4920@cindex field delimiting character 4921@cindex delimiting character for fields 4922@cindex character, field delimiting 4923@cindex field padding character 4924@cindex padding character for fields 4925@cindex character, field padding 4926@dfn{Fields} are a more general way of laying out tabular data. A field 4927is defined as the data between a pair of @dfn{delimiting characters}. 4928It contains substrings which are separated by @dfn{padding characters}. 4929The width of a field is the distance on the @emph{input} line from the 4930position where the field starts to the next tab stop. A padding 4931character inserts stretchable space similar to @TeX{}'s @code{\hss} 4932command (thus it can even be negative) to make the sum of all substring 4933lengths plus the stretchable space equal to the field width. If more 4934than one padding character is inserted, the available space is evenly 4935distributed among them. 4936 4937@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 4938Define a delimiting and a padding character for fields. If the latter 4939is missing, the padding character defaults to a space character. If 4940there is no argument at all, the field mechanism is disabled (which is 4941the default). Note that contrary to e.g.@: the tab repetition 4942character, delimiting and padding characters are not associated to the 4943current environment (@pxref{Environments}). 4944 4945Example: 4946 4947@Example 4948.fc # ^ 4949.ta T 3i 4950#foo^bar^smurf# 4951.br 4952#foo^^bar^smurf# 4953@endExample 4954 4955@noindent 4956and here the result: 4957 4958@Example 4959foo bar smurf 4960foo bar smurf 4961@endExample 4962@endDefreq 4963 4964 4965@c ===================================================================== 4966 4967@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 4968@section Character Translations 4969@cindex character translations 4970@cindex translations of characters 4971 4972@rqindex . 4973@rqindex ' 4974@cindex control character 4975@cindex character, control 4976@cindex no-break control character 4977@cindex character, no-break control 4978@cindex control character, no-break 4979The control character (@samp{.}) and the no-break control character 4980(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 4981respectively. 4982 4983@Defreq {cc, [@Var{c}]} 4984Set the control character to @var{c}. With no argument the default 4985control character @samp{.} is restored. The value of the control 4986character is associated with the current environment 4987(@pxref{Environments}). 4988@endDefreq 4989 4990@Defreq {c2, [@Var{c}]} 4991Set the no-break control character to @var{c}. With no argument the 4992default control character @samp{'} is restored. The value of the 4993no-break control character is associated with the current environment 4994(@pxref{Environments}). 4995@endDefreq 4996 4997@esindex \\ 4998@Defreq {eo, } 4999Disable the escape mechanism completely. After executing this 5000request, the backslash character @samp{\} no longer starts an escape 5001sequence. 5002 5003This request can be very helpful in writing macros since it is not 5004necessary then to double the escape character. Here an example: 5005 5006@Example 5007.\" This is a simplified version of the 5008.\" .BR request from the man macro package 5009.eo 5010.de BR 5011. ds result \& 5012. while (\n[.$] >= 2) \@{\ 5013. as result \fB\$1\fR\$2 5014. shift 2 5015. \@} 5016. if \n[.$] .as result \fB\$1 5017\*[result] 5018. ft R 5019.. 5020.ec 5021@endExample 5022@endDefreq 5023 5024@cindex escape character 5025@cindex character, escape 5026@Defreq {ec, [@Var{c}]} 5027Set the escape character to @var{c}. With no argument the default 5028escape character @samp{\} is restored. It can be also used to 5029re-enable the escape mechanism after an @code{eo} request. 5030 5031Note that changing the escape character globally will likely break 5032macro packages since @code{gtroff} has no mechanism (like @TeX{}) to 5033`intern' macros, i.e., to convert a macro definition into an internal 5034form which is independent of its representation. If a macro is 5035called, it is executed literally. 5036@endDefreq 5037 5038@Defesc {\\e, , , } 5039This escape sequence prints the current escape character (which is the 5040backslash character @samp{\} by default). 5041@endDefesc 5042 5043A @dfn{translation} is a mapping of an input character to an output 5044character. The default mappings are given in the font definition files 5045for the specific output device (@pxref{Font Files}); all mappings (both 5046with @code{tr} and in the font definition files) occur at output time, 5047i.e., the input character gets assigned the metric information of the 5048mapped output character. 5049 5050@Defreq {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 5051Translate character @var{a} to @var{b}, character @var{c} to @var{d}, 5052etc. If there is an odd number of arguments, the last one is 5053translated to the space character. 5054 5055Some notes: 5056 5057@itemize @bullet 5058@item 5059@esindex \( 5060@esindex \[ 5061@esindex \' 5062@esindex \` 5063@esindex \- 5064@esindex \_ 5065@esindex \C 5066@esindex \N 5067@rqindex char 5068@cindex special character 5069@cindex character, special 5070@cindex numbered character 5071@cindex character, numbered 5072Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 5073@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 5074characters defined with the @code{char} request, and numbered characters 5075(@code{\N'@var{xxx}'}) can be translated also. 5076 5077@item 5078@esindex \e 5079The @code{\e} escape can be translated also. 5080 5081@item 5082@esindex \% 5083@esindex \~ 5084Characters can be mapped onto the @code{\%} and @code{\~} escapes (but 5085@code{\%} and @code{\~} can't be mapped onto another character). 5086 5087@item 5088@cindex backspace character 5089@cindex character, backspace 5090@cindex leader character 5091@cindex character, leader 5092@cindex newline character 5093@cindex character, newline 5094@cindex tab character 5095@cindex character, tab 5096@esindex \a 5097@esindex \t 5098The following characters can't be translated: space (with one exception, 5099see below), backspace, newline, leader (and @code{\a}), tab (and 5100@code{\t}). 5101 5102@item 5103@rqindex shc 5104Translations are not considered for finding the soft hyphen character 5105set with the @code{shc} request. 5106 5107@item 5108@esindex \& 5109The character pair @samp{@var{c}\&} (this is an arbitrary character@w{ 5110}@var{c} followed by the zero width space character) maps this 5111character to nothing. 5112 5113@Example 5114.tr a\& 5115foo bar 5116 @result{} foo br 5117@endExample 5118 5119@noindent 5120It is even possible to map the space character to nothing: 5121 5122@Example 5123.tr aa \& 5124foo bar 5125 @result{} foobar 5126@endExample 5127 5128@noindent 5129As shown in the example, the space character can't be the first 5130character pair as an argument of @code{tr}. Additionally, it is not 5131possible to map the space character to any other character; requests 5132like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 5133 5134If justification is active, lines are justified in spite of the 5135`empty' space character (but there is no minimal distance, i.e.@: the 5136space character, between words). 5137 5138@item 5139After an output character has been constructed (this happens at the 5140moment immediately before the character is appended to an output 5141character list, either by direct output, in a macro, diversion, or 5142string), it is no longer affected by @code{tr}. 5143 5144@c XXX xref 5145 5146@item 5147Without an argument, the @code{tr} request is ignored. 5148@end itemize 5149@endDefreq 5150 5151@esindex \! 5152@cindex @code{\!}, and @code{trnt} 5153@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 5154@code{trnt} is the same as the @code{tr} request except that the 5155translations do not apply to text that is transparently throughput 5156into a diversion with @code{\!}. @xref{Diversions}, for more 5157information. 5158 5159For example, 5160 5161@Example 5162.tr ab 5163.di x 5164\!.tm a 5165.di 5166.x 5167@endExample 5168 5169@noindent 5170prints @samp{b} to the standard error stream; if @code{trnt} is used 5171instead of @code{tr} it prints @samp{a}. 5172@endDefreq 5173 5174 5175@c ===================================================================== 5176 5177@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 5178@section Troff and Nroff Mode 5179@cindex troff mode 5180@cindex mode, troff 5181@cindex nroff mode 5182@cindex mode, nroff 5183 5184Originally, @code{nroff} and @code{troff} were two separate programs, 5185the former for tty output, the latter for everything else. With GNU 5186@code{troff}, both programs are merged into one executable, sending 5187its output to a device driver (@code{grotty} for tty devices, 5188@code{grops} for @sc{PostScript}, etc.) which interprets the 5189intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 5190it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 5191since the differences are hardcoded. For GNU @code{troff}, this 5192distinction is not appropriate because @code{gtroff} simply takes the 5193information given in the font files for a particular device without 5194handling requests specially if a tty output device is used. 5195 5196Usually, a macro package can be used with all output devices. 5197Nevertheless, it is sometimes necessary to make a distinction between 5198tty and non-tty devices: @code{gtroff} provides two built-in 5199conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 5200@code{while} requests to decide whether @code{gtroff} shall behave 5201like @code{nroff} or like @code{troff}. 5202 5203@pindex troffrc 5204@pindex troffrc-end 5205@Defreq {troff, } 5206Make the @samp{t} built-in condition true (and the @samp{n} built-in 5207condition false) for @code{if}, @code{ie}, and @code{while} 5208conditional requests. This is the default if @code{gtroff} 5209(@emph{not} @code{groff}) is started with the @option{-R} switch to 5210avoid loading of the start-up files @file{troffrc} and 5211@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 5212mode if the output device is not a tty (e.g.@: `ps'). 5213@endDefreq 5214 5215@pindex tty.tmac 5216@Defreq {nroff, } 5217Make the @samp{n} built-in condition true (and the @samp{t} built-in 5218condition false) for @code{if}, @code{ie}, and @code{while} 5219conditional requests. This is the default if @code{gtroff} uses a tty 5220output device; the code for switching to nroff mode is in the file 5221@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 5222@endDefreq 5223 5224@xref{Conditionals and Loops}, for more details on built-in 5225conditions. 5226 5227@c XXX move the following to grotty section 5228 5229@pindex less 5230@cindex Teletype 5231@cindex ISO 6249 SGR 5232@cindex terminal control sequences 5233@cindex control sequences, for terminals 5234For tty output devices, underlining is done by emitting sequences of 5235@samp{_} and @samp{\b} (the backspace character) before the actual 5236character. Literally, this is printing an underline character, then 5237moving back one character position, and printing the actual character 5238at the same position as the underline character (similar to a 5239typewriter). Usually, a modern terminal can't interpret this (and the 5240original Teletype machines for which this sequence was appropriate are 5241no longer in use). You need a pager program like @code{less} which 5242translates this into ISO 6429 SGR sequences to control terminals. 5243 5244@c ===================================================================== 5245 5246@node Line Layout, Page Layout, Troff and Nroff Mode, gtroff Reference 5247@section Line Layout 5248@cindex line layout 5249@cindex layout, line 5250 5251@cindex dimensions, line 5252@cindex line dimensions 5253The following drawing shows the dimensions which @code{gtroff} uses for 5254placing a line of output onto the page. They are labeled with the 5255request which manipulates each dimension. 5256 5257@Example 5258 -->| in |<-- 5259 |<-----------ll------------>| 5260 +----+----+----------------------+----+ 5261 | : : : | 5262 +----+----+----------------------+----+ 5263 -->| po |<-- 5264 |<--------paper width---------------->| 5265@endExample 5266 5267@noindent 5268These dimensions are: 5269 5270@ftable @code 5271@item po 5272@cindex left margin 5273@cindex margin, left 5274@cindex page offset 5275@cindex offset, page 5276@dfn{Page offset} -- this is the leftmost position of text on the final 5277output, defining the @dfn{left margin}. 5278 5279@item in 5280@cindex indentation 5281@cindex line indentation 5282@dfn{Indentation} -- this is the distance from the left margin where 5283text is printed. 5284 5285@item ll 5286@cindex line length 5287@cindex length of line 5288@dfn{Line length} -- this is the distance from the left margin to right 5289margin. 5290@end ftable 5291 5292@c XXX improve example 5293 5294@Example 5295.in +.5i 5296.ll -.5i 5297A bunch of really boring text which should 5298be indented from both margins. 5299Replace me with a better (and more) example! 5300.in -.5i 5301.ll +.5i 5302@endExample 5303 5304@pindex troffrc 5305@Defreq {po, [@Var{offset}]} 5306@Defreqx {po, @t{+}@Var{offset}} 5307@Defreqx {po, @t{-}@Var{offset}} 5308@Defregx {.o} 5309Set horizontal page offset to @var{offset} (or increment or decrement 5310the current value by @var{offset}). Note that this request does not 5311cause a break, so changing the page offset in the middle of text being 5312filled may not yield the expected result. The initial value is 53131@dmn{i}. For tty output devices, it is set to 0 in the startup file 5314@file{troffrc}; the default scaling indicator is@w{ }@code{m} (and 5315not@w{ }@code{v} as incorrectly documented in the original 5316@acronym{UNIX} troff manual). 5317 5318The current page offset can be found in the read-only number register 5319@samp{.o}. 5320 5321If @code{po} is called without an argument, the page offset is reset to 5322the previous value before the last call to @code{po}. 5323 5324@Example 5325.po 3i 5326\n[.o] 5327 @result{} 720 5328.po -1i 5329\n[.o] 5330 @result{} 480 5331.po 5332\n[.o] 5333 @result{} 720 5334@endExample 5335@endDefreq 5336 5337@Defreq {in, [@Var{indent}]} 5338@Defreqx {in, @t{+}@Var{indent}} 5339@Defreqx {in, @t{-}@Var{indent}} 5340@Defregx {.i} 5341Set indentation to @var{indent} (or increment or decrement the 5342current value by @var{indent}). This request causes a break. 5343Initially, there is no indentation. 5344 5345If @code{in} is called without an argument, the indentation is reset to 5346the previous value before the last call to @code{in}. The default 5347scaling indicator is@w{ }@code{m}. 5348 5349The indentation is associated with the current environment. 5350 5351If a negative indentation value is specified (which is not allowed), 5352@code{gtroff} emits a warning of type @samp{range} and sets the 5353indentation to zero. 5354 5355The effect of @code{in} is delayed until a partially collected line (if 5356it exists) is output. A temporary indent value is reset to zero also. 5357 5358The current indentation (as set by @code{in}) can be found in the 5359read-only number register @samp{.i}. 5360@endDefreq 5361 5362@Defreq {ti, offset} 5363@Defreqx {ti, @t{+}@Var{offset}} 5364@Defreqx {ti, @t{-}@Var{offset}} 5365@Defregx {.in} 5366Temporarily indent the next output line by @var{offset}. If an 5367increment or decrement value is specified, adjust the temporary 5368indentation relative to the value set by the @code{in} request. 5369 5370This request causes a break; its value is associated with the current 5371environment. The default scaling indicator is@w{ }@code{m}. A call 5372of @code{ti} without an argument is ignored. 5373 5374If the total indentation value is negative (which is not allowed), 5375@code{gtroff} emits a warning of type @samp{range} and sets the 5376temporary indentation to zero. `Total indentation' is either 5377@var{offset} if specified as an absolute value, or the temporary plus 5378normal indentation, if @var{offset} is given as a relative value. 5379 5380The effect of @code{ti} is delayed until a partially collected line (if 5381it exists) is output. 5382 5383The read-only number register @code{.in} is the indentation that applies 5384to the current output line. 5385 5386The difference between @code{.i} and @code{.in} is that the latter takes 5387into account whether a partially collected line still uses the old 5388indentation value or a temporary indentation value is active. 5389@endDefreq 5390 5391@Defreq {ll, [@Var{length}]} 5392@Defreqx {ll, @t{+}@Var{length}} 5393@Defreqx {ll, @t{-}@Var{length}} 5394@Defregx {.l} 5395@Defregx {.ll} 5396Set the line length to @var{length} (or increment or decrement the 5397current value by @var{length}). Initially, the line length is set to 53986.5@dmn{i}. The effect of @code{ll} is delayed until a partially 5399collected line (if it exists) is output. The default scaling 5400indicator is@w{ }@code{m}. 5401 5402If @code{ll} is called without an argument, the line length is reset to 5403the previous value before the last call to @code{ll}. If a negative 5404line length is specified (which is not allowed), @code{gtroff} emits a 5405warning of type @samp{range} and sets the line length to zero. 5406 5407The line length is associated with the current environment. 5408 5409@cindex current line length register 5410The current line length (as set by @code{ll}) can be found in the 5411read-only number register @samp{.l}. The read-only number register 5412@code{.ll} is the line length that applies to the current output line. 5413 5414Similar to @code{.i} and @code{.in}, the difference between @code{.l} 5415and @code{.ll} is that the latter takes into account whether a partially 5416collected line still uses the old line length value. 5417@endDefreq 5418 5419 5420@c ===================================================================== 5421 5422@node Page Layout, Page Control, Line Layout, gtroff Reference 5423@section Page Layout 5424@cindex page layout 5425@cindex layout, page 5426 5427@code{gtroff} provides some very primitive operations for controlling 5428page layout. 5429 5430@cindex page length 5431@cindex length of page 5432@Defreq {pl, [@Var{length}]} 5433@Defreqx {pl, @t{+}@Var{length}} 5434@Defreqx {pl, @t{-}@Var{length}} 5435@Defregx {.p} 5436Set the @dfn{page length} to @var{length} (or increment or decrement 5437the current value by @var{length}). This is the length of the 5438physical output page. The default scaling indicator is@w{ }@code{v}. 5439 5440@cindex current page length register 5441The current setting can be found in the read-only number register 5442@samp{.p}. 5443 5444@cindex top margin 5445@cindex margin, top 5446@cindex bottom margin 5447@cindex margin, bottom 5448Note that this only specifies the size of the page, not the top and 5449bottom margins. Those are not set by @code{gtroff} directly. 5450@xref{Traps}, for further information on how to do this. 5451 5452Negative @code{pl} values are possible also, but not very useful: No 5453trap is sprung, and each line is output on a single page (thus 5454suppressing all vertical spacing). 5455 5456If no argument or an invalid argument is given, @code{pl} sets the page 5457length to 11@dmn{i}. 5458@endDefreq 5459 5460@cindex headers 5461@cindex footers 5462@cindex titles 5463@code{gtroff} provides several operations which help in setting up top 5464and bottom titles (or headers and footers). 5465 5466@cindex title line 5467@cindex three-part title 5468@cindex page number character 5469@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 5470Print a @dfn{title line}. It consists of three parts: a left 5471justified portion, a centered portion, and a right justified portion. 5472The argument separator @samp{'} can be replaced with any character not 5473occurring in the title line. The @samp{%} character is replaced with 5474the current page number. This character can be changed with the 5475@code{pc} request (see below). 5476 5477Without argument, @code{tl} is ignored. 5478 5479Some notes: 5480 5481@itemize @bullet 5482@item 5483A title line is not restricted to the top or bottom of a page. 5484 5485@item 5486@code{tl} prints the title line immediately, ignoring a partially filled 5487line (which stays untouched). 5488 5489@item 5490It is not an error to omit closing delimiters. For example, 5491@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 5492title line with the left justified word @samp{foo}; the centered and 5493right justfied parts are empty. 5494 5495@item 5496Any modifications to the current environment within @code{tl} (e.g.@: 5497changing the font or font size) are undone after processing @code{tl}. 5498 5499@item 5500@code{tl} accepts the same parameter delimiting characters as the 5501@code{\A} escape; see @ref{Escapes}. 5502@end itemize 5503@endDefreq 5504 5505@cindex length of title line 5506@cindex title line, length 5507@cindex current title line length register 5508@Defreq {lt, [@Var{length}]} 5509@Defreqx {lt, @t{+}@Var{length}} 5510@Defreqx {lt, @t{-}@Var{length}} 5511@Defregx {.lt} 5512The title line is printed using its own line length, which is 5513specified (or incremented or decremented) with the @code{lt} request. 5514Initially, the title line length is set to 6.5@dmn{i}. If a negative 5515line length is specified (which is not allowed), @code{gtroff} emits a 5516warning of type @samp{range} and sets the title line length to zero. 5517The default scaling indicator is@w{ }@code{m}. If @code{lt} is called 5518without an argument, the title length is reset to the previous value 5519before the last call to @code{lt}. 5520 5521The current setting of this is available in the @code{.lt} read-only 5522number register; it is associated with the current environment 5523(@pxref{Environments}). 5524 5525@endDefreq 5526 5527@cindex page number 5528@cindex number, page 5529@Defreq {pn, page} 5530@Defreqx {pn, @t{+}@Var{page}} 5531@Defreqx {pn, @t{-}@Var{page}} 5532@Defregx {.pn} 5533Change (increase or decrease) the page number of the @emph{next} page. 5534The only argument is the page number; the request is ignored without a 5535parameter. 5536 5537The read-only number register @code{.pn} contains the number of the next 5538page: either the value set by a @code{pn} request, or the number of the 5539current page plus@w{ }1. 5540@endDefreq 5541 5542@cindex current page number register 5543@Defreg {%} 5544A read-write register holding the current page number. 5545@endDefreg 5546 5547@cindex changing the page number character 5548@cindex page number character, changing 5549@vindex % 5550@Defreq {pc, [@Var{char}]} 5551Change the page number character (used by the @code{tl} request) to a 5552different character. With no argument, this mechanism is disabled. 5553Note that this doesn't affect the number register @code{%}. 5554@endDefreq 5555 5556@xref{Traps}. 5557 5558 5559@c ===================================================================== 5560 5561@node Page Control, Fonts, Page Layout, gtroff Reference 5562@section Page Control 5563@cindex page control 5564@cindex control, page 5565 5566@rqindex pn 5567@cindex new page 5568@Defreq {bp, [@Var{page}]} 5569@Defreqx {bp, @t{+}@Var{page}} 5570@Defreqx {bp, @t{-}@Var{page}} 5571Stop processing the current page and move to the next page. This 5572request causes a break. It can also take an argument to set 5573(increase, decrease) the page number of the next page. The only 5574difference between @code{bp} and @code{pn} is that @code{pn} does not 5575cause a break or actually eject a page. 5576 5577@Example 5578.de newpage \" define macro 5579'bp \" begin page 5580'sp .5i \" vertical space 5581.tl 'left top'center top'right top' \" title 5582'sp .3i \" vertical space 5583.. \" end macro 5584@endExample 5585 5586@cindex top-level diversion 5587@cindex diversion, top-level 5588@code{bp} has no effect if not called within the top-level diversion 5589(@pxref{Diversions}). 5590@endDefreq 5591 5592@cindex orphan line 5593@Defreq {ne, [@Var{space}]} 5594It is often necessary to force a certain amount of space before a new 5595page occurs. This is most useful to make sure that there is not a 5596single @dfn{orphan} line left at the bottom of a page. The @code{ne} 5597request ensures that there is a certain distance, specified by the 5598first argument, before the next page is triggered (see @ref{Traps}, 5599for further information). The default unit for @code{ne} is @samp{v}; 5600the default value of @var{space} is@w{ }1@dmn{v} if no argument is 5601given. 5602 5603For example, to make sure that no fewer than 2@w{ }lines get orphaned, 5604do the following before each paragraph: 5605 5606@Example 5607.ne 2 5608text text text 5609@endExample 5610@endDefreq 5611 5612@rqindex os 5613@rqindex ne 5614@Defreq {sv, [@Var{space}]} 5615@code{sv} is similar to the @code{ne} request; it reserves the 5616specified amount of vertical space. If the desired amount of space 5617exists before the next trap (bottom page boundary), the space is 5618output immediately (ignoring a partial filled line which stays 5619untouched). If there is not enough space, it is stored for later 5620output via the @code{os} request. The default value is@w{ }1@dmn{v} 5621if no argument is given; the default unit is @samp{v}. 5622@endDefreq 5623 5624 5625@c ===================================================================== 5626 5627@node Fonts, Sizes, Page Control, gtroff Reference 5628@section Fonts 5629@cindex fonts 5630 5631@code{gtroff} can switch fonts at any point in the text. 5632 5633The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 5634These are Times Roman, Italic, Bold, and Bold Italic. For non-tty 5635devices, there is also at least one symbol font which contains various 5636special symbols (Greek, mathematics). 5637 5638@menu 5639* Changing Fonts:: 5640* Font Families:: 5641* Font Positions:: 5642* Using Symbols:: 5643* Special Fonts:: 5644* Artificial Fonts:: 5645* Ligatures and Kerning:: 5646@end menu 5647 5648@c --------------------------------------------------------------------- 5649 5650@node Changing Fonts, Font Families, Fonts, Fonts 5651@subsection Changing Fonts 5652@cindex changing fonts 5653@cindex fonts, changing 5654 5655@rqindex sty 5656@rqindex fam 5657@kindex styles 5658@kindex family 5659@pindex DESC 5660@Defreq {ft, [@Var{font}]} 5661@Defescx {\\f, , f, } 5662@Defescx {\\f, @lparen{}, fn, } 5663@Defescx {\\f, @lbrack{}, font, @rbrack} 5664The @code{ft} request and the @code{\f} escape change the current font 5665to @var{font} (one-character name @var{f}, two-character name 5666@var{fn}). 5667 5668If @var{font} is a style name (as set with the @code{sty} request or 5669with the @code{styles} command in the @file{DESC} file), use it within 5670the current font family (as set with the @code{fam} request or with 5671the @code{family} command in the @file{DESC} file). 5672 5673@cindex previous font 5674@cindex font, previous 5675With no argument or using @samp{P} as an argument, @code{.ft} switches 5676to the previous font. Use @code{\fP} or @code{\f[P]} to do this with 5677the escape. 5678 5679Fonts are generally specified as upper-case strings, which are usually 56801@w{ }to 4 characters representing an abbreviation or acronym of the 5681font name. This is no limitation, just a convention. 5682 5683The example below produces two identical lines. 5684 5685@Example 5686eggs, bacon, 5687.ft B 5688spam 5689.ft 5690and sausage. 5691 5692eggs, bacon, \fBspam\fP and sausage. 5693@endExample 5694 5695@xref{Font Positions}, for an alternative syntax. 5696@endDefreq 5697 5698@rqindex ft 5699@rqindex ul 5700@rqindex bd 5701@esindex \f 5702@rqindex cs 5703@rqindex tkf 5704@rqindex special 5705@rqindex fspecial 5706@rqindex fp 5707@rqindex code 5708@Defreq {ftr, f [@Var{g}]} 5709Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named 5710@var{f} is referred to in a @code{\f} escape sequence, or in the 5711@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 5712@code{special}, @code{fspecial}, @code{fp}, or @code{code} requests, 5713font@w{ }@var{g} is used. If @var{g} is missing or equal to @var{f} 5714the translation is undone. 5715@endDefreq 5716 5717@c --------------------------------------------------------------------- 5718 5719@node Font Families, Font Positions, Changing Fonts, Fonts 5720@subsection Font Families 5721@cindex font families 5722@cindex families, font 5723@cindex font styles 5724@cindex styles, font 5725 5726Due to the variety of fonts available, @code{gtroff} has added the 5727concept of @dfn{font families} and @dfn{font styles}. The fonts are 5728specified as the concatenation of the font family and style. Specifying 5729a font without the family part causes @code{gtroff} to use that style of 5730the current family. 5731 5732@cindex postscript fonts 5733@cindex fonts, postscript 5734Currently, only @sc{PostScript} fonts are set up to this mechanism. 5735By default, @code{gtroff} uses the Times family with the four styles 5736@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 5737 5738This way, it is possible to use the basic four fonts and to select a 5739different font family on the command line (@pxref{Groff Options}). 5740 5741@Defreq {fam, [@Var{family}]} 5742@Defregx {.fam} 5743Switch font family to @var{family}. If no argument is given, switch 5744back to the previous font family. The current font family is available 5745in the read-only number register @samp{.fam} (this is a string-valued 5746register); it is associated with the current environment. 5747 5748@Example 5749spam, 5750.fam H \" helvetica family 5751spam, \" used font is family H + style R = HR 5752.ft B \" family H + style B = font HB 5753spam, 5754.fam T \" times family 5755spam, \" used font is family T + style B = TB 5756.ft AR \" font AR (not a style) 5757baked beans, 5758.ft R \" family T + style R = font TR 5759and spam. 5760@endExample 5761@endDefreq 5762 5763@rqindex cs 5764@rqindex bd 5765@rqindex tkf 5766@rqindex uf 5767@rqindex fspecial 5768@Defreq {sty, n style} 5769Associate @var{style} with font position@w{ }@var{n}. A font position 5770can be associated either with a font or with a style. The current 5771font is the index of a font position and so is also either a font or a 5772style. When it is a style, the font that is actually used is the font 5773the name of which is the concatenation of the name of the current 5774family and the name of the current style. For example, if the current 5775font is@w{ }1 and font position@w{ }1 is associated with style@w{ 5776}@samp{R} and the current font family is@w{ }@samp{T}, then font 5777@samp{TR} will be used. If the current font is not a style, then the 5778current family is ignored. When the requests @code{cs}, @code{bd}, 5779@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, then 5780they will instead be applied to the member of the current family 5781corresponding to that style. 5782 5783@var{n} must be a non-negative integer value. 5784 5785@pindex DESC 5786@kindex styles 5787The default family can be set with the @option{-f} option 5788(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 5789file controls which font positions (if any) are initially associated 5790with styles rather than fonts. For example, the default setting for 5791@sc{PostScript} fonts 5792 5793@Example 5794styles R I B BI 5795@endExample 5796 5797@noindent 5798is equivalent to 5799 5800@Example 5801.sty 1 R 5802.sty 2 I 5803.sty 3 B 5804.sty 4 BI 5805@endExample 5806 5807@code{.fam} always checks whether the current font position is valid; 5808this can give surprising results if the current font position is 5809associated with a style. 5810 5811In the following example, we want to access the @sc{PostScript} font 5812@code{FooBar} from the font family @code{Foo}: 5813 5814@Example 5815.sty \n[.fp] Bar 5816.fam Foo 5817 @result{} warning: can't find font `FooR' 5818@endExample 5819 5820@noindent 5821The default font position at start-up is@w{ }1; for the 5822@sc{PostScript} device, this is associated with style @samp{R}, so 5823@code{gtroff} tries to open @code{FooR}. 5824 5825A solution to this problem is to use a dummy font like the following: 5826 5827@Example 5828.fp 0 dummy TR \" set up dummy font at position 0 5829.sty \n[.fp] Bar \" register style `Bar' 5830.ft 0 \" switch to font at position 0 5831.fam Foo \" activate family `Foo' 5832.ft Bar \" switch to font `FooBar' 5833@endExample 5834 5835@xref{Font Positions}. 5836@endDefreq 5837 5838@c --------------------------------------------------------------------- 5839 5840@node Font Positions, Using Symbols, Font Families, Fonts 5841@subsection Font Positions 5842@cindex font positions 5843@cindex positions, font 5844 5845For the sake of old phototypesetters and compatibility with old versions 5846of @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 5847on which various fonts are mounted. 5848 5849@Defreq {fp, pos font [@Var{external-name}]} 5850@Defregx {.f} 5851@Defregx {.fp} 5852Mount font @var{font} at position @var{pos} (which must be a 5853non-negative integer). This numeric position can then be referred to 5854with font changing commands. When @code{gtroff} starts it is using 5855font position@w{ }1 (which must exist; position@w{ }0 is unused 5856usually at start-up). 5857 5858@cindex current font position register 5859The current font in use, as a font position, is available in the 5860read-only number register @samp{.f}. This can be useful to remember the 5861current font for later recall. It is associated with the current 5862environment (@pxref{Environments}). 5863 5864@Example 5865.nr save-font \n[.f] 5866.ft B 5867... text text text ... 5868.ft \n[save-font] 5869@endExample 5870 5871@cindex next free font position register 5872The number of the next free font position is available in the read-only 5873number register @samp{.fp}. This is useful when mounting a new font, 5874like so: 5875 5876@Example 5877.fp \n[.fp] NEATOFONT 5878@endExample 5879 5880@pindex DESC@r{, and font mounting} 5881Fonts not listed in the @file{DESC} file are automatically mounted on 5882the next available font position when they are referenced. If a font 5883is to be mounted explicitly with the @code{fp} request on an unused 5884font position, it should be mounted on the first unused font position, 5885which can be found in the @code{.fp} register. Although @code{gtroff} 5886does not enforce this strictly, it is not allowed to mount a font at a 5887position whose number is much greater (approx.@: 1000 positions) than 5888that of any currently used position. 5889 5890The @code{fp} request has an optional third argument. This argument 5891gives the external name of the font, which is used for finding the font 5892description file. The second argument gives the internal name of the 5893font which is used to refer to the font in @code{gtroff} after it has 5894been mounted. If there is no third argument then the internal name is 5895used as the external name. This feature makes it possible to use 5896fonts with long names in compatibility mode. 5897@endDefreq 5898 5899Both the @code{ft} request and the @code{\f} escape have alternative 5900syntax forms to access font positions. 5901 5902@rqindex sty 5903@rqindex fam 5904@kindex styles 5905@kindex family 5906@pindex DESC 5907@Defreq {ft, nnn} 5908@Defescx {\\f, , n, } 5909@Defescx {\\f, @lparen{}, nn, } 5910@Defescx {\\f, @lbrack{}, nnn, @rbrack} 5911Change the current font position to @var{nnn} (one-digit position 5912@var{n}, two-digit position @var{nn}), which must be a non-negative 5913integer. 5914 5915If @var{nnn} is associated with a style (as set with the @code{sty} 5916request or with the @code{styles} command in the @file{DESC} file), use 5917it within the current font family (as set with the @code{fam} request or 5918with the @code{family} command in the @file{DESC} file). 5919 5920@Example 5921this is font 1 5922.ft 2 5923this is font 2 5924.ft \" switch back to font 1 5925.ft 3 5926this is font 3 5927.ft 5928this is font 1 again 5929@endExample 5930 5931@xref{Changing Fonts}, for the standard syntax form. 5932@endDefreq 5933 5934@c --------------------------------------------------------------------- 5935 5936@node Using Symbols, Special Fonts, Font Positions, Fonts 5937@subsection Using Symbols 5938@cindex using symbols 5939@cindex symbols, using 5940 5941@cindex glyph 5942@cindex character 5943@cindex ligature 5944A @dfn{glyph} is a graphical representation of a @dfn{character}. 5945While a character is an abstract entity containing semantic 5946information, a glyph is something which can be actually seen on screen 5947or paper. It is possible that a character has multiple glyph 5948representation forms (for example, the character `A' can be either 5949written in a roman or an italic font, yielding two different glyphs); 5950sometimes more than one character maps to a single glyph (this is a 5951@dfn{ligature} -- the most common is `fi'). 5952 5953@c XXX 5954 5955Please note that currently the distinction between glyphs and 5956characters in this reference is not clearly carried out. This will be 5957improved eventually in the next revision. 5958 5959@cindex symbol 5960@cindex special fonts 5961@kindex fonts 5962@pindex DESC 5963@rqindex fspecial 5964A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 5965glyph names of a particular font are defined in its font file. If the 5966user requests a glyph not available in this font, @code{gtroff} looks 5967up an ordered list of @dfn{special fonts}. By default, the 5968@sc{PostScript} output device supports the two special fonts @samp{SS} 5969(slanted symbols) and @samp{S} (symbols) (the former is looked up 5970before the latter). Other output devices use different names for 5971special fonts. Fonts mounted with the @code{fonts} keyword in the 5972@file{DESC} file are globally available. To install additional 5973special fonts locally (i.e.@: for a particular font), use the 5974@code{fspecial} request. 5975 5976@xref{Font Files}, and @ref{Special Fonts}, for more details. 5977 5978@Defesc {\\, @lparen{}, nm, } 5979@Defescx {\\, @lbrack{}, name, @rbrack} 5980Insert a symbol @var{name} (two-character name @var{nm}). There is no 5981special syntax for one-character names -- the natural form 5982@samp{\@var{n}} would collide with escapes. 5983 5984If @var{name} is undefined, a warning of type @samp{char} is generated, 5985and the escape is ignored. @xref{Debugging}, for information about 5986warnings. 5987 5988The list of available symbols is device dependent; see @ref{Glyph Name 5989Index} for some of them discussed in this reference. 5990 5991@c XXX list of common symbols 5992@endDefesc 5993 5994@Defesc {\\C, ', xxx, '} 5995Typeset the character named @var{xxx}. Normally it is more convenient 5996to use @code{\[@var{xxx}]}, but @code{\C} has the advantage that it is 5997compatible with newer versions of @code{ditroff} and is available in 5998compatibility mode. 5999@endDefesc 6000 6001@rqindex char 6002@cindex unicode 6003@Defesc {\\N, ', n, '} 6004Typeset the character with code@w{ }@var{n} in the current font (this 6005is @strong{not} the input character code). @var{n} can be any 6006integer. Most devices only have characters with codes between 0 6007and@w{ }255; the Unicode output device uses codes in the range 60080--65535. If the current font does not contain a character with that 6009code, special fonts are @emph{not} searched. The @code{\N} escape 6010sequence can be conveniently used in conjunction with the @code{char} 6011request: 6012 6013@Example 6014.char \[phone] \f[ZD]\N'37' 6015@endExample 6016 6017@noindent 6018@pindex DESC 6019@cindex unnamed characters 6020@cindex characters, unnamed 6021The code of each character is given in the fourth column in the font 6022description file after the @code{charset} command. It is possible to 6023include unnamed characters in the font description file by using a 6024name of @samp{---}; the @code{\N} escape sequence is the only way to 6025use these. 6026@endDefesc 6027 6028@c XXX should be `glyph', not `character' 6029 6030@cindex character properties 6031@cindex properties of characters 6032@Defreq {cflags, n c1 c2 @dots{}} 6033Each character has certain properties associated with it. These 6034properties can be modified with the @code{cflags} request. The first 6035argument is the the sum of the desired flags and the remaining 6036arguments are the characters to have those properties. It is possible 6037to omit the spaces between the characters. 6038 6039@table @code 6040@item 1 6041@cindex end of sentence characters 6042@cindex characters, end of sentence 6043the character ends sentences (initially characters @samp{.?!} have this 6044property) 6045 6046@item 2 6047@cindex hyphenating characters 6048@cindex characters, hyphenation 6049lines can be broken before the character (initially no characters have 6050this property) 6051 6052@item 4 6053@glindex hy 6054@glindex em 6055lines can be broken after the character (initially the characters 6056@samp{-\(hy\(em} have this property) 6057 6058@item 8 6059@cindex overlapping characters 6060@cindex characters, overlapping 6061@glindex ul 6062@glindex rn 6063@glindex ru 6064the character overlaps horizontally (initially the characters 6065@samp{\(ul\(rn\(ru} have this property) 6066 6067@item 16 6068@glindex br 6069the character overlaps vertically (initially character @samp{\(br} has 6070this property) 6071 6072@item 32 6073@cindex transparent characters 6074@cindex character, transparent 6075@cindex ' 6076@cindex " 6077@cindex ] 6078@cindex ) 6079@cindex * 6080@glindex dg 6081@glindex rq 6082an end of sentence character followed by any number of characters with 6083this property is treated as the end of a sentence if followed by a 6084newline or two spaces; in other words the character is 6085@dfn{transparent} for the purposes of end of sentence recognition -- 6086this is the same as having a zero space factor in @TeX{} (initially 6087characters @samp{"')]*\(dg\(rq} have this property). 6088@end table 6089@endDefreq 6090 6091@cindex defining characters 6092@cindex characters, defining 6093@cindex creating new characters 6094@cindex escape character 6095@cindex character, escape 6096@rqindex tr 6097@rqindex cp 6098@rqindex rc 6099@rqindex lc 6100@esindex \l 6101@esindex \L 6102@esindex \& 6103@esindex \e 6104@rqindex hcode 6105@Defreq {char, c [@Var{string}]} 6106Define a new character@w{ }@var{c} to be @var{string} (which can be 6107empty). Every time character@w{ }@var{c} needs to be printed, 6108@var{string} is processed in a temporary environment and the result is 6109wrapped up into a single object. Compatibility mode is turned off and 6110the escape character is set to @samp{\} while @var{string} is being 6111processed. Any emboldening, constant spacing or track kerning is 6112applied to this object rather than to individual characters in 6113@var{string}. A character defined by this request can be used just 6114like a normal character provided by the output device. In particular, 6115other characters can be translated to it with the @code{tr} request; 6116it can be made the leader character by the @code{lc} request; repeated 6117patterns can be drawn with the character using the @code{\l} and 6118@code{\L} escape sequences; words containing the character can be 6119hyphenated correctly, if the @code{hcode} request is used to give the 6120character a hyphenation code. There is a special anti-recursion 6121feature: Use of character within the character's definition is handled 6122like normal characters not defined with @code{char}. 6123@endDefreq 6124 6125@cindex removing character definition 6126@cindex character, removing definition 6127@Defreq {rchar, c1 c2 @dots{}} 6128Remove the definitions of characters @var{c1}, @var{c2},@w{ 6129}@enddots{} This undoes the effect of a @code{char} request. 6130 6131It is possible to omit the whitespace between arguments. 6132@endDefreq 6133 6134@xref{Special Characters}. 6135 6136@c --------------------------------------------------------------------- 6137 6138@node Special Fonts, Artificial Fonts, Using Symbols, Fonts 6139@subsection Special Fonts 6140@cindex special fonts 6141@cindex fonts, special 6142 6143@c XXX 6144 6145To be written. 6146 6147@c --------------------------------------------------------------------- 6148 6149@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts 6150@subsection Artificial Fonts 6151@cindex artificial fonts 6152@cindex fonts, artificial 6153 6154There are a number of requests for artificially creating fonts. These 6155are largely vestiges of the days when output devices did not have a 6156wide variety of fonts, and when @code{nroff} and @code{troff} were 6157separate programs. These are no longer necessary in GNU 6158@code{troff}. Nevertheless, they are supported. 6159 6160@cindex underlining 6161@Defreq {ul, [@Var{lines}]} 6162The @code{ul} request normally underlines subsequent lines if a tty 6163output device is used. Otherwise, the lines are printed in italics 6164(only the term `underlined' is used in the following). The single 6165argument is the number of input lines to be underlined; with no 6166argument, the next line is underlined. If @var{lines} is zero or 6167negative, stop the effects of @code{ul} (if it was active). Requests 6168and empty lines do not count for computing the number of underlined 6169input lines, even if they produce some output like @code{tl}. Lines 6170inserted by macros (e.g.@: invoked by a trap) do count. 6171 6172At the beginning of @code{ul}, the current font is stored and the 6173underline font is activated. Within the span of a @code{ul} request, 6174it is possible to change fonts, but after the last line affected by 6175@code{ul} the saved font is restored. 6176 6177@cindex underline font 6178@cindex font, for underlining 6179@rqindex uf 6180This command is associated with the current environment. The 6181underline font can be changed with the @code{uf} request. 6182 6183@c XXX @xref should be changed to grotty 6184 6185@xref{Troff and Nroff Mode}, for a discussion how underlining is 6186implemented in for tty output devices, and which problems can arise. 6187 6188The @code{ul} request does not underline spaces. 6189@endDefreq 6190 6191@cindex continuous underlining 6192@cindex underlining, continuous 6193@Defreq {cu, [@Var{lines}]} 6194The @code{cu} request is similar to @code{ul} but underlines spaces as 6195well (if a tty output device is used). 6196@endDefreq 6197 6198@cindex underline font 6199@cindex font for underlining 6200@rqindex ul 6201@rqindex cu 6202@Defreq {uf, font} 6203Set the underline font (globally) used by @code{ul} and @code{cu}. By 6204default, this is the font at position@w{ }2. @var{font} can be either 6205a non-negative font position or the name of a font. 6206@endDefreq 6207 6208@cindex imitating bold face 6209@cindex bold face, imitating 6210@Defreq {bd, font [@Var{offset}]} 6211@Defreqx {bd, font1 font2 [@Var{offset}]} 6212@Defregx {.b} 6213Artificially create a bold font by printing each character twice, 6214slightly offset. 6215 6216Two syntax forms are available. 6217 6218@itemize @bullet 6219@item 6220Imitate a bold font unconditionally. The first argument specifies the 6221font to embolden, and the second is the number of basic units, minus 6222one, by which the two characters is offset. If the second argument is 6223missing, emboldening is turned off. 6224 6225@var{font} can be either a non-negative font position or the name of a 6226font. 6227 6228@var{offset} is available in the @code{.b} read-only register if a 6229special font is active; in the @code{bd} request, its default unit is 6230@samp{u}. 6231 6232@rqindex fspecial 6233@kindex special 6234@cindex embolding of special fonts 6235@cindex special fonts, emboldening 6236@item 6237Imitate a bold form conditionally. Embolden @var{font1} by 6238@var{offset} only if font @var{font2} is the current font. This 6239command can be issued repeatedly to set up different emboldening 6240values for different current fonts. If the second argument is 6241missing, emboldening is turned off for this particular current font. 6242 6243This affects special fonts only (either set up with the @code{special} 6244command in font files or with the @code{fspecial} request). 6245@end itemize 6246@endDefreq 6247 6248@cindex constant character space mode 6249@cindex mode for constant character space 6250@cindex character, constant space 6251@rqindex ps 6252@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 6253Switch to and from constant character space mode. If activated, the 6254width of every character is @math{@var{width}/36} ems. The em size is 6255given absolutely by @var{em-size}; if this argument is missing, the em 6256value is taken from the current font size (as set with the @code{ps} 6257request) when the font is effectively in use. Without second and 6258third argument, constant character space mode is deactivated. 6259 6260Default unit for @var{em-size} is @samp{z}; @var{width} is an integer. 6261@endDefreq 6262 6263@c --------------------------------------------------------------------- 6264 6265@node Ligatures and Kerning, , Artificial Fonts, Fonts 6266@subsection Ligatures and Kerning 6267@cindex ligatures and kerning 6268@cindex kerning and ligatures 6269 6270Ligatures are groups of characters that are run together. For 6271example, the letters `f' and `i' can form a ligature `fi' as in the 6272word `file'. This produces a cleaner look (albeit subtle) to the 6273printed output. Usually, ligatures are not available in fonts for tty 6274output devices. 6275 6276Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 6277typesetter that was the target of AT&T @code{troff} also supported 6278`ff', `ffi', and `ffl' ligatures. Advanced typesetters or `expert' 6279fonts may include ligatures for `ft' and `ct', although GNU 6280@code{troff} does not support these (yet). 6281 6282@cindex ligatures enabled register 6283@Defreq {lg, [@Var{flag}]} 6284@Defregx {.lg} 6285The ligature mechanism can be switched on or off with the @code{lg} 6286request; if the parameter is non-zero or missing, ligatures are 6287enabled, otherwise disabled. Default is on. The current ligature 6288mode can be found in the read-only number register @code{.lg} (set to 62891 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise). 6290 6291Setting the ligature mode to@w{ }2 enables the two-character ligatures 6292(fi, fl, and ff) and disables the three-character ligatures (ffi and 6293ffl). 6294@endDefreq 6295 6296@dfn{Pairwise kerning} is another subtle typesetting mechanism that 6297modifies the distance between a character pair to improve readability. 6298In most cases (but not always) the distance is decreased. 6299@ifnotinfo 6300For example, compare the combination of the letters `V' and `A'. With 6301kerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 6302@end ifnotinfo 6303Typewriter-like fonts and fonts for terminals where all characters 6304have the same width don't use kerning. 6305 6306@cindex kerning enabled register 6307@Defreq {kern, [@Var{flag}]} 6308@Defregx {.kern} 6309Kerning can be activated with the @code{kern} request. If the 6310parameter is non-zero or missing, enable pairwise kerning, otherwise 6311disable it. The read-only number register @code{.kern} is set to@w{ 6312}1 if pairwise kerning is enabled, 0@w{ }otherwise. 6313 6314@cindex zero width space character 6315@cindex character, zero width space 6316@cindex space character, zero width 6317If the font description file contains pairwise kerning information, 6318characters from that font are kerned. Kerning between two characters 6319can be inhibited by placing @code{\&} between them: @samp{V\&A}. 6320 6321@xref{Font File Format}. 6322@endDefreq 6323 6324@cindex track kerning 6325@cindex kerning, track 6326@dfn{Track kerning} expands or reduces the space between characters. 6327This can be handy, for example, if you need to squeeze a long word 6328onto a single line or spread some text to fill a narrow column. It 6329must be used with great care since it is usually considered bad 6330typography if the reader notices the effect. 6331 6332@Defreq {tkf, f s1 n1 s2 n2} 6333Enable track kerning for font@w{ }@var{f}. If the current font is@w{ 6334}@var{f} the width of every character is increased by an amount 6335between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 6336the current point size is less than or equal to @var{s1} the width is 6337increased by @var{n1}; if it is greater than or equal to @var{s2} the 6338width is increased by @var{n2}; if the point size is greater than or 6339equal to @var{s1} and less than or equal to @var{s2} the increase in 6340width is a linear function of the point size. 6341 6342The default unit is @samp{z} for @var{s1} and @var{s2}, @samp{p} for 6343@var{n1} and @var{n2}. 6344@endDefreq 6345 6346Sometimes, when typesetting letters of different fonts, more or less 6347space at such boundaries are needed. There are two escapes to help 6348with this. 6349 6350@cindex italic correction 6351@cindex correction, italic 6352@cindex correction between italic and roman character 6353@cindex roman character, correction after italic character 6354@cindex italic character, correction before roman character 6355@Defesc {\\/, , , } 6356Increase the width of the preceding character so that the spacing 6357between that character and the following character is correct if the 6358following character is a roman character. For example, if an 6359italic@w{ }@code{f} is immediately followed by a roman right 6360parenthesis, then in many fonts the top right portion of the @code{f} 6361overlaps the top left of the right parenthesis. Use this escape 6362sequence whenever an italic character is immediately followed by a 6363roman character without any intervening space. This small amount of 6364space is also called @dfn{italic correction}. 6365 6366@iftex 6367@example 6368@group 6369\f[I]f\f[R]) 6370 @result{} {@it f}@r{)} 6371\f[I]f\/\f[R]) 6372 @result{} @i{f}@r{)} 6373@end group 6374@end example 6375@end iftex 6376@endDefesc 6377 6378@cindex left italic correction 6379@cindex correction, left italic 6380@cindex roman character, correction before italic character 6381@cindex italic character, correction after roman character 6382@Defesc {\\\,, , , } 6383Modify the spacing of the following character so that the spacing 6384between that character and the preceding character is correct if the 6385preceding character is a roman character. Use this escape sequence 6386whenever a roman character is immediately followed by an italic 6387character without any intervening space. In analogy to above, this 6388space could be called @dfn{left italic correction}, but this term 6389isn't used widely. 6390 6391@iftex 6392@example 6393@group 6394q\f[I]f 6395 @result{} @r{q}@i{f} 6396q\,\f[I]f 6397 @result{} @r{q}@math{@ptexcomma}@i{f} 6398@end group 6399@end example 6400@end iftex 6401@endDefesc 6402 6403@Defesc {\\&, , , } 6404Insert a zero-width character, which is invisible. Its intended use 6405is to stop interaction of a character with its surrounding. 6406 6407@itemize @bullet 6408@item 6409It prevents the insertion of extra space after an end of sentence 6410character. 6411 6412@Example 6413Test. 6414Test. 6415 @result{} Test. Test. 6416Test.\& 6417Test. 6418 @result{} Test. Test. 6419@endExample 6420 6421@item 6422It prevents interpretation of a control character at the beginning of 6423an input line. 6424 6425@Example 6426.Test 6427 @result{} warning: `Test' not defined 6428\&.Test 6429 @result{} .Test 6430@endExample 6431 6432@item 6433It prevents kerning between two characters. 6434 6435@ifnotinfo 6436@example 6437@group 6438VA 6439 @result{} @r{VA} 6440V\&A 6441 @result{} @r{V@w{}A} 6442@end group 6443@end example 6444@end ifnotinfo 6445 6446@item 6447It is needed to map an arbitrary character to nothing in the @code{tr} 6448request (@pxref{Character Translations}). 6449@end itemize 6450@endDefesc 6451 6452 6453@c ===================================================================== 6454 6455@node Sizes, Strings, Fonts, gtroff Reference 6456@section Sizes 6457@cindex sizes 6458 6459@cindex baseline 6460@cindex type size 6461@cindex size of type 6462@cindex vertical spacing 6463@cindex spacing, vertical 6464@code{gtroff} uses two dimensions with each line of text, type size 6465and vertical spacing. The @dfn{type size} is approximately the height 6466of the tallest character.@footnote{This is usually the parenthesis. 6467Note that in most cases the real dimensions of the glyphs in a font 6468are @emph{not} related to its type size! For example, the standard 6469@sc{PostScript} font families `Times Roman', `Helvetica', and 6470`Courier' can't be used together at 10@dmn{pt}; to get acceptable 6471output, the size of `Helvetica' has to be reduced by one point, and 6472the size of `Courier' must be increased by one point.} @dfn{Vertical 6473spacing} is the amount of space @code{gtroff} allows for a line of 6474text; normally, this is about 20%@w{ }larger than the current type 6475size. Ratios smaller than this can result in hard-to-read text; 6476larger than this, it spreads the text out more vertically (useful for 6477term papers). By default, @code{gtroff} uses 10@w{ }point type on 647812@w{ }point spacing. 6479 6480@cindex leading 6481The difference between type size and vertical spacing is known, by 6482typesetters, as @dfn{leading}. 6483 6484@menu 6485* Changing Type Sizes:: 6486* Fractional Type Sizes:: 6487@end menu 6488 6489@c --------------------------------------------------------------------- 6490 6491@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 6492@subsection Changing Type Sizes 6493@cindex changing type sizes 6494@cindex type sizes, changing 6495 6496@Defreq {ps, [@Var{size}]} 6497@Defreqx {ps, @t{+}@Var{size}} 6498@Defreqx {ps, @t{-}@Var{size}} 6499@Defescx {\\s, , size, } 6500@Defregx {.s} 6501Use the @code{ps} request or the @code{\s} escape to change (increase, 6502decrease) the type size (in points). Specify @var{size} as either an 6503absolute point size, or as a relative change from the current size. 6504The size@w{ }0, or no argument, goes back to the previous size. 6505 6506Default unit of @code{size} is @samp{z}. If @code{size} is zero or 6507negative, it is set to 1@dmn{u}. 6508 6509The read-only number register @code{.s} returns the point size in 6510points as a decimal fraction. This is a string. To get the point 6511size in scaled points, use the @code{.ps} register instead. 6512 6513@code{.s} is associated with the current environment 6514(@pxref{Environments}). 6515 6516@Example 6517snap, snap, 6518.ps +2 6519grin, grin, 6520.ps +2 6521wink, wink, \s+2nudge, nudge,\s+8 say no more! 6522.ps 10 6523@endExample 6524 6525The @code{\s} escape may be called in a variety of ways. Much like 6526other escapes there must be a way to determine where the argument ends 6527and the text begins. Any of the following forms are valid: 6528 6529@table @code 6530@item \s@var{n} 6531Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 65320 or in the range 4 to@w{ }39. 6533 6534@item \s+@var{n} 6535@itemx \s-@var{n} 6536Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{ 6537}must be exactly one digit. 6538 6539@item \s(@var{nn} 6540Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly 6541two digits. 6542 6543@item \s+(@var{nn} 6544@itemx \s-(@var{nn} 6545@itemx \s(+@var{nn} 6546@itemx \s(-@var{nn} 6547Increase or decrease the point size by @var{nn}@w{ }points. @var{nn} 6548must be exactly two digits. 6549@end table 6550 6551@xref{Fractional Type Sizes}, for yet another syntactical form of 6552using the @code{\s} escape. 6553 6554Some devices may only have certain permissible sizes, in which case 6555@code{gtroff} rounds to the nearest permissible size. 6556@endDefreq 6557 6558@cindex current type size register 6559@cindex current vertical spacing register 6560@Defreq {vs, [@Var{space}]} 6561@Defreqx {vs, @t{+}@Var{space}} 6562@Defreqx {vs, @t{-}@Var{space}} 6563@Defregx {.v} 6564Change (increase, decrease) the vertical spacing by @var{space}. The 6565default unit is @samp{p}. 6566 6567If @code{vs} is called without an argument, the vertical spacing is 6568reset to the previous value before the last call to @code{vs}. 6569 6570@vindex .V 6571@code{gtroff} creates a warning of type @samp{range} if @var{space} is 6572zero or negative; the vertical spacing is then set to the vertical 6573resolution (as given in the @code{.V} register). 6574 6575The read-only number register @code{.v} contains the current vertical 6576spacing; it is associated with the current environment 6577(@pxref{Environments}). 6578@endDefreq 6579 6580@c XXX example 6581 6582@ignore 6583@Example 6584... .sz macro example?? ... 6585@endExample 6586@end ignore 6587 6588@c --------------------------------------------------------------------- 6589 6590@node Fractional Type Sizes, , Changing Type Sizes, Sizes 6591@subsection Fractional Type Sizes 6592@cindex fractional type sizes 6593@cindex type sizes, fractional 6594 6595@cindex @code{s} unit 6596@cindex unit, @code{s} 6597@cindex @code{z} unit 6598@cindex unit, @code{z} 6599@rqindex ps 6600@rqindex cs 6601@rqindex tkf 6602@esindex \H 6603@esindex \s 6604A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 6605where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by 6606default). There is a new scale indicator @samp{z} which has the 6607effect of multiplying by @var{sizescale}. Requests and escape 6608sequences in @code{gtroff} interpret arguments that represent a point 6609size as being in units of scaled points, but they evaluate each such 6610argument using a default scale indicator of @samp{z}. Arguments 6611treated in this way are the argument to the @code{ps} request, the 6612third argument to the @code{cs} request, the second and fourth 6613arguments to the @code{tkf} request, the argument to the @code{\H} 6614escape sequence, and those variants of the @code{\s} escape sequence 6615that take a numeric expression as their argument (see below). 6616 6617For example, suppose @var{sizescale} is@w{ }1000; then a scaled point 6618is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 6619equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 662010250@w{ }scaled points, which is equal to 10.25@w{ }points. 6621 6622@code{gtroff} disallows the use of the @samp{z} scale indicator in 6623instances where it would make no sense, such as a numeric 6624expression whose default scale indicator was neither @samp{u} nor 6625@samp{z}. Similarly it would make 6626no sense to use a scaling indicator other than @samp{z} or @samp{u} in a 6627numeric expression whose default scale indicator was @samp{z}, and so 6628@code{gtroff} disallows this as well. 6629 6630There is also new scale indicator @samp{s} which multiplies by the 6631number of units in a scaled point. So, for example, @samp{\n[.ps]s} is 6632equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 6633scale indicators. 6634 6635@vindex .s 6636@Defreg {.ps} 6637A read-only number register returning the point size in scaled points. 6638 6639@code{.ps} is associated with the current environment 6640(@pxref{Environments}). 6641@endDefreg 6642 6643@cindex last-requested point size register 6644@cindex point size, last-requested 6645@vindex .ps 6646@vindex .s 6647@Defreg {.psr} 6648@Defregx {.sr} 6649The last-requested point size in scaled points is contained in the 6650@code{.psr} read-only number register. The last requested point size 6651in points as a decimal fraction can be found in @code{.sr}. This is a 6652string-valued read-only number register. 6653 6654Note that the requested point sizes are device-independent, whereas 6655the values returned by the @code{.ps} and @code{.s} registers are not. 6656For example, if a point size of 11@dmn{pt} is requested for a DVI 6657device, 10.95@dmn{pt} are actually used (as specified in the 6658@file{DESC} file). 6659 6660Both registers are associated with the current environment 6661(@pxref{Environments}). 6662@endDefreg 6663 6664The @code{\s} escape has the following syntax for working with 6665fractional type sizes: 6666 6667@table @code 6668@item \s[@var{n}] 6669@itemx \s'@var{n}' 6670Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric 6671expression with a default scale indicator of @samp{z}. 6672 6673@item \s[+@var{n}] 6674@itemx \s[-@var{n}] 6675@itemx \s+[@var{n}] 6676@itemx \s-[@var{n}] 6677@itemx \s'+@var{n}' 6678@itemx \s'-@var{n}' 6679@itemx \s+'@var{n}' 6680@itemx \s-'@var{n}' 6681Increase or or decrease the point size by @var{n} scaled points; 6682@var{n} is a numeric expression with a default scale indicator of 6683@samp{z}. 6684@end table 6685 6686@xref{Font Files}. 6687 6688 6689@c ===================================================================== 6690 6691@node Strings, Conditionals and Loops, Sizes, gtroff Reference 6692@section Strings 6693@cindex strings 6694 6695@code{gtroff} has string variables, which are entirely for user 6696convenience (i.e.@: there are no built-in strings exept @code{.T}, but 6697even this is a read-write string variable). 6698 6699@cindex string interpolation 6700@cindex string expansion 6701@cindex interpolation of strings 6702@cindex expansion of strings 6703@Defreq {ds, name [@Var{string}]} 6704@Defescx {\\*, , n, } 6705@Defescx {\\*, @lparen{}, nm, } 6706@Defescx {\\*, @lbrack{}, name, @rbrack{}} 6707Define and access a string variable @var{name} (one-character name 6708@var{n}, two-character name @var{nm}). If @var{name} already exists, 6709@code{ds} overwrites the previous definition. 6710 6711Example: 6712 6713@Example 6714.ds UX \s-1UNIX\s0\u\s-3tm\s0\d 6715. 6716The \*(UX Operating System 6717@endExample 6718 6719The @code{\*} escape @dfn{interpolates} (expands in-place) a 6720previously-defined string variable. To be more precise, the stored 6721string is pushed onto the input stack which is then parsed by 6722@code{gtroff}. Similar to number registers, it is possible to nest 6723strings, i.e. a string variables can be called within string 6724variables. 6725 6726If the string named by the @code{\*} does not exist, it is defined as 6727empty, and a warning of type @samp{mac} is emitted (see 6728@ref{Debugging}, for more details). 6729 6730@cindex comments, with @code{ds} 6731@strong{Caution:} Unlike other requests, the second argument to the 6732@code{ds} request takes up the entire line including trailing spaces. 6733This means that comments on a line with such a request can introduce 6734unwanted space into a string. 6735 6736@Example 6737.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 6738@endExample 6739 6740@noindent 6741Instead the comment should be put on another line or have the comment 6742escape adjacent with the end of the string. 6743 6744@Example 6745.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 6746@endExample 6747 6748@cindex trailing quotes 6749@cindex quotes, trailing 6750@cindex leading spaces with @code{ds} 6751@cindex spaces with @code{ds} 6752To produce leading space the string can be started with a double 6753quote. No trailing quote is needed; in fact, any trailing quote is 6754included in your string. 6755 6756@Example 6757.ds sign " Yours in a white wine sauce, 6758@endExample 6759 6760@esindex \@key{RET} 6761@cindex multi-line strings 6762@cindex strings, multi-line 6763@cindex newline character in strings, escaping 6764@cindex escaping newline characters in strings 6765Strings are not limited to a single line of text. A string can span 6766several lines by escaping the newlines with a backslash. The 6767resulting string is stored @emph{without} the newlines. 6768 6769@Example 6770.ds foo lots and lots \ 6771of text are on these \ 6772next several lines 6773@endExample 6774 6775It is not possible to have real newlines in a string. 6776 6777@cindex name space of macros and strings 6778@cindex macros, shared name space with strings 6779@cindex strings, shared name space with macros 6780Strings, macros, and diversions (and boxes) share the same name space. 6781Internally, even the same mechanism is used to store them. This has 6782some interesting consequences. For example, it is possible to call a 6783macro with string syntax and vice versa. 6784 6785@Example 6786.de xxx 6787a funny test. 6788.. 6789This is \*[xxx] 6790 @result{} This is a funny test. 6791 6792.ds yyy a funny test 6793This is 6794.yyy 6795 @result{} This is a funny test. 6796@endExample 6797 6798Diversions and boxes can be also called with string syntax. It is not 6799possible to pass arguments to a macro if called with @code{\*}. 6800 6801Another consequence is that you can copy one-line diversions or boxes 6802to a string. 6803 6804@Example 6805.di xxx 6806a \fItest\fR 6807.br 6808.di 6809.ds yyy This is \*[xxx]\c 6810\*[yyy]. 6811 @result{} @r{This is a }@i{test}. 6812@endExample 6813 6814@noindent 6815As the previous example shows, it is possible to store formatted 6816output in strings. The @code{\c} escape prevents the insertion of an 6817additional blank line in the output. 6818 6819Copying diversions longer than a single output line produces 6820unexpected results. 6821 6822@Example 6823.di xxx 6824a funny 6825.br 6826test 6827.br 6828.di 6829.ds yyy This is \*[xxx]\c 6830\*[yyy]. 6831 @result{} test This is a funny. 6832@endExample 6833 6834Usually, it is not predictable whether a diversion contains one or 6835more output lines, so this mechanism should be avoided. With 6836@acronym{UNIX} @code{troff}, this was the only solution to strip off a 6837final newline from a diversion. Another disadvantage is that the 6838spaces in the copied string are already formatted, making them 6839unstretchable. This can cause ugly results. 6840 6841@rqindex chop 6842@rqindex unformat 6843A clean solution to this problem is available in GNU @code{troff}, 6844using the requests @code{chop} to remove the final newline of a 6845diversion, and @code{unformat} to make the horizontal spaces 6846stretchable again. 6847 6848@Example 6849.box xxx 6850a funny 6851.br 6852test 6853.br 6854.box 6855.chop xxx 6856.unformat xxx 6857This is \*[xxx]. 6858 @result{} This is a funny test. 6859@endExample 6860 6861@xref{Gtroff Internals}, for more information. 6862@endDefreq 6863 6864@cindex appending to strings 6865@cindex strings, appending 6866@Defreq {as, name [@Var{string}]} 6867The @code{as} request is similar to @code{ds} but appends @var{string} 6868to the string stored as @var{name} instead of redefining it. If 6869@var{name} doesn't exist yet, it is created. 6870 6871@Example 6872.as sign " with shallots, onions and garlic, 6873@endExample 6874@endDefreq 6875 6876Rudimentary string manipulation routines are given with the next two 6877requests. 6878 6879@cindex substring 6880@Defreq {substring, str n1 [@Var{n2}]} 6881Replace the string in register@w{ }@var{str} with the substring 6882defined by the indices @var{n1} and@w{ }@var{n2}. The first character 6883in the string has index one. If @var{n2} is omitted, it is taken to 6884be equal to the string's length. If the index value @var{n1} or 6885@var{n2} is negative or zero, it is counted from the end of the 6886string, going backwards: The last character has index@w{ }0, the 6887character before the last character has index@w{ }@minus{}1, etc. 6888 6889@Example 6890.ds xxx abcdefgh 6891.substring xxx 2 -3 6892\*[xxx] 6893 @result{} bcde 6894@endExample 6895@endDefreq 6896 6897@cindex length of a string 6898@cindex string, length of 6899@Defreq {length, reg str} 6900Compute the length of @var{str} and returns it in the number 6901register@w{ }@var{reg}. If @var{reg} doesn't exist, it is created. 6902 6903@Example 6904.ds xxx abcdefgh 6905.length yyy xxx 6906\n[yyy] 6907 @result{} 8 6908@endExample 6909@endDefreq 6910 6911@cindex rename request 6912@cindex rename macro 6913@cindex rename string 6914@Defreq {rn, xx yy} 6915Rename the request, macro, or string @var{xx} to @var{yy}. 6916@endDefreq 6917 6918@cindex remove request 6919@cindex remove macro 6920@cindex remove string 6921@Defreq {rm, xx} 6922Remove the request, macro, or string @var{xx}. @code{gtroff} treats 6923subsequent invocations as if the object had never been defined. 6924@endDefreq 6925 6926@cindex alias 6927@Defreq {als, new old} 6928Create an alias named @var{new} for the request, string, macro, or 6929diversion object named @var{old}. The new name and the old name are 6930exactly equivalent (it is similar to a hard rather than a soft 6931link). If @var{old} is undefined, @code{gtroff} generates a warning of 6932type @samp{mac} and ignores the request. 6933@endDefreq 6934 6935@Defreq {chop, xx} 6936Remove (chop) the last character from the macro, string, or diversion 6937named @var{xx}. This is useful for removing the newline from the end 6938of diversions that are to be interpolated as strings. This command 6939can be used repeatedly; see @ref{Gtroff Internals}, for details on 6940nodes inserted by @code{gtroff} automatically. 6941@endDefreq 6942 6943@xref{Identifiers}, and @ref{Comments}. 6944 6945 6946@c ===================================================================== 6947 6948@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 6949@section Conditionals and Loops 6950@cindex conditionals and loops 6951@cindex loops and conditionals 6952 6953@menu 6954* Operators in Conditionals:: 6955* if-else:: 6956* while:: 6957@end menu 6958 6959@c --------------------------------------------------------------------- 6960 6961@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 6962@subsection Operators in Conditionals 6963 6964@rqindex if 6965@rqindex while 6966@cindex @code{if}, operators to use with it 6967@cindex @code{while}, operators to use with it 6968In @code{if} and @code{while} requests, there are several more 6969operators available: 6970 6971@table @code 6972@item e 6973@itemx o 6974True if the current page is even or odd numbered (respectively). 6975 6976@item n 6977@rqindex nroff 6978True if the document is being processed in nroff mode (i.e., the 6979@code{.nroff} command has been issued). 6980 6981@item t 6982@rqindex troff 6983True if the document is being processed in troff mode (i.e., the 6984@code{.troff} command has been issued). 6985 6986@item v 6987Always false. 6988 6989@item '@var{xxx}'@var{yyy}' 6990True if the string @var{xxx} is equal to the string @var{yyy}. Other 6991characters can be used in place of the single quotes; the same set of 6992delimiters as for the @code{\D} escape is used (@pxref{Escapes}). 6993@code{gtroff} formats the strings before being compared: 6994 6995@Example 6996.ie "|"\fR|\fP" \ 6997true 6998.el \ 6999false 7000 @result{} true 7001@endExample 7002 7003@noindent 7004The resulting motions, character sizes, and fonts have to 7005match,@footnote{The created output nodes must be identical. 7006@xref{Gtroff Internals}.} and not the individual motion, size, and 7007font requests. In the previous example, @samp{|} and @samp{\fR|\fP} 7008both result in a roman @samp{|} character with the same point size and 7009at the same location on the page, so the strings are equal. If 7010@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result 7011would be ``false'' because (the first) @samp{|} produces an italic 7012@samp{|} rather than a roman one. 7013 7014@item r @var{xxx} 7015True if there is a number register named @var{xxx}. 7016 7017@item d @var{xxx} 7018True if there is a string, macro, diversion, or request named @var{xxx}. 7019 7020@item c @var{ch} 7021@rqindex char 7022True if there is a character @var{ch} available; @var{ch} is either an 7023@acronym{ASCII} character or a special character (@code{\(@var{ch}} or 7024@code{\[@var{ch}]}); the condition is also true if @var{ch} has been 7025defined by the @code{char} request. 7026@end table 7027 7028Note that these operators can't be combined with other operators like 7029@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 7030between the exclamation mark and the operator) can be used to negate 7031the result. 7032 7033@Example 7034.nr xxx 1 7035.ie !r xxx \ 7036true 7037.el \ 7038false 7039 @result{} false 7040@endExample 7041 7042A whitespace after @samp{!} always evaluates to zero (this bizarre 7043behaviour is due to compatibility with @acronym{UNIX} @code{troff}). 7044 7045@Example 7046.nr xxx 1 7047.ie ! r xxx \ 7048true 7049.el \ 7050false 7051 @result{} r xxx true 7052@endExample 7053 7054It is possible to omit the whitespace before the argument to the 7055@samp{r}, @samp{d}, and @samp{c} operators. 7056 7057@xref{Expressions}. 7058 7059@c --------------------------------------------------------------------- 7060 7061@node if-else, while, Operators in Conditionals, Conditionals and Loops 7062@subsection if-else 7063@cindex if-else 7064 7065@code{gtroff} has if-then-else constructs like other languages, although 7066the formatting can be painful. 7067 7068@Defreq {if, expr anything} 7069Evaluate the expression @var{expr}, and executes @var{anything} (the 7070remainder of the line) if @var{expr} evaluates to non-zero (true). 7071@var{anything} is interpreted as though it was on a line by itself 7072(except that leading spaces are swallowed). @xref{Expressions}, for 7073more info. 7074 7075@Example 7076.nr xxx 1 7077.nr yyy 2 7078.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 7079 @result{} true 7080@endExample 7081@endDefreq 7082 7083@c XXX .nop request 7084 7085@Defreq {ie, expr anything} 7086@Defreqx {el, anything} 7087Use the @code{ie} and @code{el} requests to write an if-then-else. 7088The first request is the `if' part and the latter is the `else' part. 7089 7090@Example 7091.ie n .ls 2 \" double spacing in nroff 7092.el .ls 1 \" single spacing in troff 7093@endExample 7094@endDefreq 7095 7096@c this is a bug in makeinfo: you can't have `@{' as an argument 7097@c to deffn 7098 7099@esindex \@{ 7100@esindex \@} 7101@c @Defesc {\\@@@{, , , } 7102@c @Defescx {\\@@@}, , , } 7103In many cases, an if (or if-else) construct needs to execute more than 7104one request. This can be done using the @code{\@{} and @code{\@}} 7105escapes. The following example shows the possible ways to use these 7106escapes (note the position of the opening and closing braces). 7107 7108@Example 7109.ie t \@{\ 7110. ds lq `` 7111. ds rq '' 7112.\@} 7113.el \ 7114.\@{\ 7115. ds lq " 7116. ds rq "\@} 7117@endExample 7118@c @endDefesc 7119 7120@xref{Expressions}. 7121 7122@c --------------------------------------------------------------------- 7123 7124@node while, , if-else, Conditionals and Loops 7125@subsection while 7126@cindex while 7127 7128@code{gtroff} provides a looping construct using the @code{while} 7129request, which is used much like the @code{if} (and related) requests. 7130 7131@Defreq {while, expr anything} 7132Evaluate the expression @var{expr}, and repeatedly execute 7133@var{anything} (the remainder of the line) until @var{expr} evaluates 7134to@w{ }0. 7135 7136@Example 7137.nr a 0 1 7138.while (\na < 9) \@{\ 7139\n+a, 7140.\@} 7141\n+a 7142 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 7143@endExample 7144 7145Some remarks. 7146 7147@rqindex de 7148@itemize @bullet 7149@item 7150The body of a @code{while} request is treated like the body of a 7151@code{de} request: @code{gtroff} temporarily stores it in a macro 7152which is deleted after the loop has been exited. It can considerably 7153slow down a macro if the body of the @code{while} request (within the 7154macro) is large. Each time the macro is executed, the @code{while} 7155body is parsed and stored again as a temporary macro. 7156 7157@Example 7158.de xxx 7159. nr num 10 7160. while (\\n[num] > 0) \@{\ 7161. \" many lines of code 7162. nr num -1 7163. \@} 7164.. 7165@endExample 7166 7167@cindex recursive macros 7168@cindex macros, recursive 7169@noindent 7170The traditional and ofter better solution (@acronym{UNIX} @code{troff} 7171doesn't have the @code{while} request) is to use a recursive macro 7172instead which is parsed only once during its definition. 7173 7174@Example 7175.de yyy 7176. if (\\n[num] > 0) \@{\ 7177. \" many lines of code 7178. nr num -1 7179. yyy 7180. \@} 7181.. 7182. 7183.de xxx 7184. nr num 10 7185. yyy 7186.. 7187@endExample 7188 7189@noindent 7190Note that the number of available recursion levels is set to@w{ }1000 7191(this is a compile-time constant value of @code{gtroff}). 7192 7193@item 7194The closing brace of a @code{while} body must end a line. 7195 7196@Example 7197.if 1 \@{\ 7198. nr a 0 1 7199. while (\n[a] < 10) \@{\ 7200. nop \n+[a] 7201.\@}\@} 7202 @result{} unbalanced \@{ \@} 7203@endExample 7204@end itemize 7205@endDefreq 7206 7207@rqindex while 7208@cindex @code{break}, in a @code{while} loop 7209@cindex @code{continue}, in a @code{while} loop 7210@Defreq {break, } 7211Break out of a @code{while} loop. Be sure not to confuse this with 7212the @code{br} request (causing a line break). 7213@endDefreq 7214 7215@Defreq {continue, } 7216Finishes the current iteration of a @code{while} loop, immediately 7217restarting the next iteration. 7218@endDefreq 7219 7220@xref{Expressions}. 7221 7222 7223@c ===================================================================== 7224 7225@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 7226@section Writing Macros 7227@cindex writing macros 7228@cindex macros, writing 7229 7230A @dfn{macro} is a collection of text and embedded commands which can 7231be invoked multiple times. Use macros to define common operations. 7232 7233@Defreq {de, name [@Var{end}]} 7234Define a new macro named @var{name}. @code{gtroff} copies subsequent 7235lines (starting with the next one) into an internal buffer until it 7236encounters the line @samp{..} (two dots). The optional second 7237argument to @code{de} changes this to a macro to @samp{.@var{end}}. 7238 7239Note that no leading whitespace is allowed in the line containing the 7240ending token (either @samp{..} or the macro @samp{.@var{end}}). 7241 7242Here a small example macro called @samp{P} which causes a break and 7243inserts some vertical space. It could be used to separate paragraphs. 7244 7245@Example 7246.de P 7247. br 7248. sp .8v 7249.. 7250@endExample 7251 7252@c XXX add info about macro definitions in macros. 7253 7254@c XXX give example for end macro. 7255 7256@c XXX add info about indirect macro calls: 7257@c 7258@c .de xxx 7259@c from yyy\c 7260@c .. 7261@c 7262@c test \*[xxx] test 7263@c => test from yyy test 7264 7265@c XXX info about common identifier pool for strings, macros, and 7266@c diversions. 7267@endDefreq 7268 7269@cindex appending, to a macro 7270@Defreq {am, xx} 7271Works similarly to @code{de} except it appends onto the macro named 7272@var{xx}. So, to make the previously defined @samp{P} macro actually 7273do indented instead of block paragraphs, add the necessary code to the 7274existing macro like this: 7275 7276@Example 7277.am P 7278.ti +5n 7279.. 7280@endExample 7281@endDefreq 7282 7283@cindex alias 7284@Defreq {als, new old} 7285Create an alias named @var{new} for the request, string, macro, or 7286diversion object named @var{old}. The new name and the old name are 7287exactly equivalent (it is similar to a hard rather than a soft 7288link). If @var{old} is undefined, @code{gtroff} generates a warning of 7289type @samp{mac} and ignores the request. 7290 7291The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, 7292and @code{as} requests only create a new object if the name 7293of the macro, diversion or string diversion is currently 7294undefined or if it is defined to be a request; normally 7295they modify the value of an existing object. 7296@endDefreq 7297 7298@menu 7299* Copy-in Mode:: 7300* Parameters:: 7301@end menu 7302 7303@c --------------------------------------------------------------------- 7304 7305@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 7306@subsection Copy-in Mode 7307@cindex copy-in mode 7308@cindex mode, copy-in 7309 7310@esindex \n 7311@esindex \$ 7312@esindex \* 7313@esindex \\ 7314@esindex \@key{RET} 7315@cindex @code{\n}, when reading text for a macro 7316@cindex @code{\$}, when reading text for a macro 7317@cindex @code{\*}, when reading text for a macro 7318@cindex @code{\\}, when reading text for a macro 7319@cindex \@key{RET}, when reading text for a macro 7320When @code{gtroff} reads in the text for a macro or diversion, it copies 7321the text (including request lines, but excluding escapes) into an 7322internal buffer. Escapes are converted into an internal form, 7323except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 7324@code{\@key{RET}} which are evaluated and inserted into the text where 7325the escape was located. This is known as @dfn{copy-in} mode or 7326@dfn{copy} mode. 7327 7328What this means is that you can specify when these escapes are to be 7329evaluated (either at copy-in time or at the time of use) by insulating 7330the escapes with an extra backslash. Compare this to the @code{\def} 7331and @code{\edef} commands in @TeX{}. 7332 7333The following example prints the numbers 20 and@w{ }10: 7334 7335@Example 7336.nr x 20 7337.de y 7338.nr x 10 7339\&\nx 7340\&\\nx 7341.. 7342.y 7343@endExample 7344 7345@c --------------------------------------------------------------------- 7346 7347@node Parameters, , Copy-in Mode, Writing Macros 7348@subsection Parameters 7349@cindex parameters 7350 7351@vindex .$ 7352The arguments to a macro can be examined using a variety of escapes. 7353The number of arguments is available in the @code{.$} number register. 7354Any individual argument can be retrieved with one of the following 7355escapes: 7356 7357@cindex copy-in mode, and macro arguments 7358@Defesc {\\$, n, , } 7359@Defescx {\\$, @lparen{}, nn, } 7360@Defescx {\\$, @lbrack{}, nnn, @rbrack{}} 7361The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and 7362@code{\$[@var{nnn}]} retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or 7363@var{nnn}@dmn{th} argument. As usual, the first form only accepts a 7364single number (larger than zero), the second a two-digit number (larger 7365or equal to@w{ }10), and the third any positive integer value (larger 7366than zero). Macros can have an unlimited number of arguments. Note 7367that due to copy-in mode, use two backslashes on these in actual use to 7368prevent interpolation until the macro is actually invoked. 7369@endDefesc 7370 7371@Defreq {shift, [@Var{n}]} 7372Shifts the arguments 1@w{ }position, or as 7373many positions as specified by its argument. After executing this 7374request, argument@w{ }@var{i} becomes argument @var{i}-@var{n}; 7375arguments 1 to@w{ }@var{n} are no longer available. Shifting by 7376negative amounts is currently undefined. 7377@endDefreq 7378 7379@Defesc {\\$*, , , } 7380@Defescx {\\$@@, , , } 7381In some cases it is convenient to use all of the arguments at once (for 7382example, to pass the arguments along to another macro). The @code{\$*} 7383escape concatenates all the arguments separated by spaces. A 7384similar escape is @code{\$@@}, which concatenates all the 7385arguments with each surrounded by double quotes, and separated by 7386spaces. 7387@endDefesc 7388 7389@rqindex als 7390@cindex @code{als}, use with @code{\$0} 7391@Defesc {\\$0, , , } 7392The name used to invoke the current macro. 7393The @code{als} request can make a macro have more than one name. 7394 7395@Example 7396.de vl 7397.ie \\n(.$=1 .ds Vl Pre-Release Version 7398.el .ds Vl Version \\$3, \\$4. 7399.. 7400@endExample 7401 7402@noindent 7403This would be called as 7404 7405@Example 7406.vl $Id: groff.texinfo,v 1.77 2001/05/07 13:36:24 wlemb Exp $ 7407@endExample 7408@endDefesc 7409 7410@xref{Request Arguments}. 7411 7412 7413@c ===================================================================== 7414 7415@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 7416@section Page Motions 7417@cindex page motions 7418@cindex motions, page 7419 7420@cindex @code{sp}, as vertical page motion 7421@Defreq {sp, [@Var{len}]} 7422Motions up and down the page can be done with the @code{sp} request. 7423However, this causes a break so that the actual effect is to move to the 7424left margin and then to the specified location. 7425@endDefreq 7426 7427@Defreq {mk, [@Var{reg}]} 7428@Defreqx {rt, reg} 7429The request @code{mk} can be used to mark a location on a page, for 7430movement to later. This request takes a register name as an argument in 7431which to store the current page location. With no argument it 7432stores the location in an internal register. The results of this can be 7433used later by the @code{rt} or the @code{sp} request. The @code{rt} 7434request returns @emph{upwards} to the location given in the register 7435name given as an argument; with no argument it returns to the 7436location marked with the @code{mk} request. 7437 7438@c XXX example 7439@ignore 7440@Example 7441... dual column example ... 7442@endExample 7443@end ignore 7444@endDefreq 7445 7446The following escapes give fine control of movements about the page. 7447 7448@cindex vertical motion 7449@cindex motion, vertical 7450@Defesc {\\v, ', e, '} 7451The @code{\v'@var{e}'} escape enables arbitrary vertical motion from the 7452current location on the page. The argument@w{ }@var{e} specifies the 7453distance to move; positive is downwards and negative upwards. The 7454default unit for this escape @samp{v}. Beware, however, that 7455@code{gtroff} continues text processing at the point where the motion 7456ends, so you should always balance motions to avoid interference with 7457text processing. 7458@endDefesc 7459 7460There are some special case escapes for vertical motion. 7461 7462@ftable @code 7463@item \r 7464move upwards@w{ }1@dmn{v}. 7465 7466@item \u 7467move upwards@w{ }.5@dmn{v}. 7468 7469@item \d 7470move down@w{ }.5@dmn{v}. 7471@end ftable 7472 7473@cindex inserting horizontal space 7474@cindex horizontal space 7475@cindex space, horizontal 7476@Defesc {\\h, ', e, '} 7477The @code{\h'@var{e}'} escape provides horizontal motions. The 7478expression@w{ }@var{e} indicates how far to move: positive is rightwards 7479and negative leftwards. 7480@c XXX Is there a default unit for this? 7481@endDefesc 7482 7483There are a number of special case escapes for horizontal motion: 7484 7485@ftable @code 7486@item \@key{SP} 7487An unbreakable and unpaddable (i.e.@: not expanded during filling) 7488space. (Note: This is a backslash followed by a space.) 7489 7490@item \~ 7491An unbreakable space that stretches like a normal inter-word space 7492when a line is adjusted. 7493 7494@item \| 7495A 1/6@dmn{th} em space. Ignored for tty output devices (rounded to 7496zero). 7497 7498@item \^ 7499A 1/12@dmn{th} em space. Ignored for tty output devices (rounded to 7500zero). 7501 7502@item \0 7503A space the size of a digit. 7504 7505@item \& 7506@cindex zero width space character 7507@cindex character, zero width space 7508@cindex space character, zero width 7509A zero width space. 7510 7511@item \) 7512Like @code{\&} except that it behaves like a character declared with the 7513@code{cflags} request to be transparent for the purposes of end of 7514sentence recognition. 7515@end ftable 7516 7517The following string sets the @TeX{} logo: 7518 7519@Example 7520.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 7521@endExample 7522 7523@cindex width escape 7524@cindex escape, width 7525@Defesc {\\w, ', text, '} 7526Used as @code{\w'@var{text}'}, 7527returns the width of the specified @var{text} in basic units. 7528This allows horizontal movement based on the width of some 7529arbitrary text (e.g.@: given as an argument to a macro). 7530 7531@c XXX example 7532 7533@ignore 7534@Example 7535... strlen example ... 7536@endExample 7537@end ignore 7538 7539Font changes may occur in @var{text} which don't affect current 7540settings. 7541 7542After use, @code{\w} sets several registers: 7543 7544@table @code 7545@item st 7546@itemx sb 7547@vindex st 7548@vindex sb 7549The highest and lowest point, respectively, in @var{text}. 7550 7551@item rst 7552@itemx rsb 7553@vindex rst 7554@vindex rsb 7555Like the @code{st} and @code{sb} registers, but takes account of the 7556heights and depths of characters. 7557 7558@item ct 7559@vindex ct 7560Defines the kinds of characters occurring in @var{text}: 7561 7562@table @asis 7563@item 0 7564only short characters, no descenders or tall characters. 7565 7566@item 1 7567at least one descender. 7568 7569@item 2 7570at least one tall character. 7571 7572@item 3 7573at least one each of a descender and a tall character. 7574@end table 7575 7576@item ssc 7577@vindex ssc 7578The amount of horizontal space (possibly negative) that should be added 7579to the last character before a subscript. 7580 7581@item skw 7582@vindex skw 7583How far to right of the center of the last character in the @code{\w} 7584argument, the center of an accent from a roman font should be placed 7585over that character. 7586@end table 7587@endDefesc 7588 7589@Defesc {\\k, ', x, '} 7590Stores the current horizontal position in register @var{x}. 7591Use this, for example, to return to the beginning of a string 7592for highlighting or other decoration. 7593@endDefesc 7594 7595@Defreg {.k} 7596A read-only number register containing the current horizontal output 7597position. 7598@endDefreg 7599 7600@c XXX documentation 7601 7602 7603@c ===================================================================== 7604 7605@node Drawing Requests, Traps, Page Motions, gtroff Reference 7606@section Drawing Requests 7607@cindex drawing requests 7608@cindex requests for drawing 7609 7610@code{gtroff} provides a number of ways to draw lines and other figures 7611on the page. Used in combination with the page motion commands (see 7612@ref{Page Motions}, for more info), a wide variety of figures can be 7613drawn. However, for complex drawings these operations can be quite 7614cumbersome, and it may be wise to use graphic preprocessors like 7615@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 7616information. 7617 7618All drawing is done via escapes. 7619 7620@cindex drawing horizontal lines 7621@cindex horizontal line, drawing 7622@cindex line, horizontal, drawing 7623@Defesc {\\l, ', l c, '} 7624Draws a line rightwards from the current 7625location. The full syntax for this escape is: 7626 7627@Example 7628\l'@var{l}@var{c}' 7629@endExample 7630 7631@noindent 7632where @var{l} is the length of the line to be drawn, starting at the 7633current location; positive numbers draw to the right, and negative 7634numbers draw towards the left. This can also be specified absolutely 7635(i.e.@: with a leading @samp{|}) which draws back to the beginning 7636of the line. 7637 7638@cindex underscore character 7639@cindex character, underscore 7640@cindex line drawing character 7641@cindex character for line drawing 7642The optional second parameter @var{c} is a character to draw the line 7643with. If this second argument is not specified, @code{gtroff} uses 7644the underscore character. 7645 7646@cindex zero width space character 7647@cindex character, zero width space 7648@cindex space character, zero width 7649@esindex \& 7650To separate the two arguments (to prevent @code{gtroff} from 7651interpreting a drawing character as a scaling indicator) use @code{\&}. 7652 7653Here a small useful example: 7654 7655@Example 7656.de box 7657\(br\\$*\(br\l'|0\(rn'\l'|0\(ul' 7658.. 7659@endExample 7660 7661@opindex | 7662@noindent 7663Note that this works by outputting a box rule (a vertical line), then 7664the text given as an argument and then another box rule. Then the line 7665drawing escapes both draw from the current location to the beginning of 7666the @emph{input} line. 7667@endDefesc 7668 7669@cindex drawing vertical lines 7670@cindex vertical line drawing 7671@cindex line, vertical, drawing 7672@cindex line drawing character 7673@cindex character for line drawing 7674@cindex box rule character 7675@cindex character, box rule 7676@Defesc {\\L, ', l c, '} 7677Draws vertical lines. Its parameters are 7678similar to the @code{\l} escape. The 7679movement is downwards for positive values, 7680and upwards for negative values. The 7681default character is the box rule character. As with the vertical 7682motion escapes, text processing blindly continues where the line 7683ends. 7684 7685@c XXX example 7686 7687@ignore 7688@Example 7689...box macro... 7690@endExample 7691@end ignore 7692@endDefesc 7693 7694@Defesc {\\D, ', command arg @dots{}, '} 7695The @code{\D} escape provides a variety of drawing functions. 7696While the previous escapes work on a character device, these 7697escapes do not. 7698 7699@table @code 7700@item \D'l @var{dx} @var{dy}' 7701Draw a line from the current location to the relative point specified by 7702(@var{dx},@var{dy}). 7703 7704@c XXX example 7705 7706@ignore 7707@Example 7708...revised box macro... 7709@endExample 7710@end ignore 7711 7712@item \D'c @var{d}' 7713@cindex circle drawing 7714@cindex drawing a circle 7715Draw a circle with a diameter of @var{d} with the leftmost point at the 7716current position. 7717 7718@item \D'C @var{d}' 7719Draw a solid circle with the same parameters as an outlined circle. 7720 7721@item \D'e @var{dx} @var{dy}' 7722@cindex drawing an ellipse 7723@cindex ellipse drawing 7724Draw an ellipse with a horizontal diameter of @var{dx} and a vertical 7725diameter of @var{dy} with the leftmost point at the current position. 7726 7727@item \D'E @var{dx} @var{dy}' 7728Draw a solid ellipse with the same parameters as an outlined ellipse. 7729 7730@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 7731@cindex arc drawing 7732@cindex drawing an arc 7733Draw an arc clockwise from the current location through the two 7734specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}). 7735 7736@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7737@cindex drawing a spline 7738@cindex spline drawing 7739Draw a spline from the current location to (@var{dx1},@var{dy1}) and 7740then to (@var{dx2},@var{dy2}), and so on. 7741 7742@item \D'f @var{n}' 7743@cindex gray shading 7744@cindex shading 7745@cindex shades for filling objects 7746Set the shade of gray to be used for filling solid objects to@w{ 7747}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 7748corresponds solid white and 1000 to solid black, and values in between 7749correspond to intermediate shades of gray. This applies only to solid 7750circles, solid ellipses and solid polygons. By default, a level of@w{ 7751}1000 is used. 7752 7753@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7754@cindex drawing a polygon 7755@cindex polygon drawing 7756Draw a polygon from the current location to (@var{dx1},@var{dy1}) and 7757then to (@var{dx2},@var{dy2}) and so on. When the specified data points 7758are exhausted, a line is drawn back to the starting point. 7759 7760@c XXX example 7761 7762@ignore 7763@Example 7764... box example (yes, again)... 7765@endExample 7766@end ignore 7767 7768@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7769Draw a solid polygon with the same parameters as an outlined polygon. 7770 7771@c XXX example 7772 7773@ignore 7774@Example 7775... shaded box example ... 7776@endExample 7777@end ignore 7778 7779@item \D't @var{n}' 7780@cindex line thickness 7781@cindex thickness of lines 7782Set the current line thickness to @var{n} machine units. A value of 7783zero selects the smallest available line thickness. A negative value 7784makes the line thickness proportional to the current point size (this is 7785the default behaviour of @code{ditroff}). 7786@end table 7787@endDefesc 7788 7789@cindex pile, character 7790@cindex character pile 7791@Defesc {\\b, ', string, '} 7792@dfn{Piles} a sequence of characters 7793vertically, and centers it vertically on the current line. Use it 7794to build large brackets and braces. 7795 7796@Example 7797\b'\(lt\(bv\(lk\(bv\(lb' 7798@endExample 7799@endDefesc 7800 7801@xref{Drawing Functions}. 7802 7803 7804@c ===================================================================== 7805 7806@node Traps, Diversions, Drawing Requests, gtroff Reference 7807@section Traps 7808@cindex traps 7809 7810@dfn{Traps} are locations, which, when reached, call a specified 7811macro. These traps can occur at a given location on the page, at a 7812given location in the current diversion, after a certain number of input 7813lines or at the end of input. 7814 7815@menu 7816* Page Location Traps:: 7817* Diversion Traps:: 7818* Input Line Traps:: 7819* End-of-input Traps:: 7820@end menu 7821 7822@c --------------------------------------------------------------------- 7823 7824@node Page Location Traps, Diversion Traps, Traps, Traps 7825@subsection Page Location Traps 7826@cindex page location traps 7827@cindex traps, page location 7828 7829@dfn{Page location traps} perform an action when @code{gtroff} 7830reaches a certain vertical location on the page. Page location 7831traps have a variety of purposes, including: 7832 7833@itemize 7834@item 7835setting headers and footers 7836 7837@item 7838setting body text in multiple columns 7839 7840@item 7841setting footnotes 7842@end itemize 7843 7844@cindex vertical position trap enable register 7845@Defreq {vpt, flag} 7846@Defregx {.vpt} 7847Enables vertical position traps if @var{flag} is non-zero, or disables 7848them otherwise. Vertical position traps are traps set by the @code{wh} 7849or @code{dt} requests. Traps set by the @code{it} request are not 7850vertical position traps. The parameter that controls whether vertical 7851position traps are enabled is global. Initially vertical position traps 7852are enabled. The current setting of this is available in the 7853@code{.vpt} read-only number register. 7854@endDefreq 7855 7856@Defreq {wh, dist macro} 7857Sets a page location trap. Positive values for @var{dist} set 7858the trap relative to the top of the page; negative values set 7859the trap relative to the bottom of the page. 7860 7861@var{macro} is the name of the macro to execute when the 7862trap is sprung. 7863 7864@cindex page headers 7865@cindex page footers 7866@cindex headers 7867@cindex footers 7868The following is a simple example of how many macro packages 7869set headers and footers. 7870 7871@Example 7872.de hd \" Page header 7873'sp .5i 7874.tl 'Title''date' 7875'sp .3i 7876.. 7877.de fo \" Page footer 7878'sp 1v 7879.tl ''%'' 7880'bp 7881.. 7882.wh 0 hd \" trap at top of the page 7883.wh -1i fo \" trap one inch from bottom 7884@endExample 7885@endDefreq 7886 7887@cindex distance to next trap 7888@cindex trap, distance 7889@Defreg {.t} 7890A read-only number register holding the distance to the next trap. 7891@endDefreg 7892 7893@cindex changing trap location 7894@cindex trap, changing location 7895@Defreq {ch, dist macro} 7896Changes the location of a trap. 7897The first argument is the name of the macro to be invoked at 7898the trap, and the second argument is the new location for the trap 7899(note that the parameters are specified the opposite of the @code{.wh} request). 7900This is useful for building up footnotes in a diversion to allow more 7901space at the bottom of the page for them. 7902 7903@c XXX 7904 7905@ignore 7906@Example 7907... (simplified) footnote example ... 7908@endExample 7909@end ignore 7910@endDefreq 7911 7912@Defreg {.ne} 7913The read-only number register @code{.ne} contains the amount of space 7914that was needed in the last @code{ne} request that caused a trap to be 7915sprung. Useful in conjunction with the @code{.trunc} register. 7916@xref{Page Control}, for more information. 7917@endDefreg 7918 7919@rqindex ne 7920@cindex @code{ne}, and the @code{.trunc} register 7921@Defreg {.trunc} 7922A read-only register containing the amount of vertical space truncated 7923by the most recently sprung vertical position trap, or, if the trap was 7924sprung by an @code{ne} request, minus the amount of vertical motion 7925produced by the @code{ne} request. In other words, at the point a trap 7926is sprung, it represents the difference of what the vertical position 7927would have been but for the trap, and what the vertical position 7928actually is. 7929@endDefreg 7930 7931@c --------------------------------------------------------------------- 7932 7933@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 7934@subsection Diversion Traps 7935@cindex diversion traps 7936@cindex traps, diversion 7937 7938@vindex .t 7939@cindex @code{.t}, and diversions 7940@Defreq {dt, dist macro} 7941Sets a trap @emph{within} a diversion. 7942@var{dist} is the first argument is the location of the trap 7943(identical to the @code{.wh} request) 7944and @var{macro} is the name of the macro to be invoked. The 7945number register @code{.t} still works within diversions. 7946@xref{Diversions}, for more information. 7947@endDefreq 7948 7949@c --------------------------------------------------------------------- 7950 7951@node Input Line Traps, End-of-input Traps, Diversion Traps, Traps 7952@subsection Input Line Traps 7953@cindex input line traps 7954@cindex traps, input line 7955 7956@Defreq {it, n macro} 7957Sets an input line trap. 7958@var{n} is the number of lines of input which may be read before 7959@dfn{springing} the trap, @var{macro} is the macro to be invoked. 7960Request lines are not counted as input lines. 7961 7962For example, one possible use is to have a macro which prints the 7963next @var{n}@w{ }lines in a bold font. 7964 7965@Example 7966.de B 7967.it \\$1 B-end 7968.ft B 7969.. 7970.de B-end 7971.ft R 7972.. 7973@endExample 7974@endDefreq 7975 7976@c --------------------------------------------------------------------- 7977 7978@node End-of-input Traps, , Input Line Traps, Traps 7979@subsection End-of-input Traps 7980@cindex end-of-input traps 7981@cindex traps, end-of-input 7982 7983@Defreq {em, macro} 7984Sets a trap at the end of input. The @var{macro} 7985specified is executed after the last line of the 7986input file has been processed. 7987 7988For example, if the document had to have a section at the bottom of the 7989last page for someone to approve it, the @code{em} request could be 7990used. 7991 7992@Example 7993.de approval 7994.ne 5v 7995.sp |(\\n(.t-6v) 7996.in +4i 7997.lc _ 7998.br 7999Approved:\t\a 8000.sp 8001Date:\t\t\a 8002.. 8003.em approval 8004@endExample 8005@endDefreq 8006 8007 8008@c ===================================================================== 8009 8010@node Diversions, Environments, Traps, gtroff Reference 8011@section Diversions 8012@cindex diversions 8013 8014In @code{gtroff} it is possible to @dfn{divert} text into a named 8015storage area. Due to the similarity to defining macros it is sometimes 8016said to be stored in a macro. This is used for saving text for output 8017at a later time, which is useful for keeping blocks of text on the same 8018page, footnotes, tables of contents and indices. 8019 8020@c XXX describe top-level diversion 8021@c XXX index entry for top-level diversion 8022 8023@Defreq {di, macro} 8024@Defreqx {da, macro} 8025Begins a diversion. Like the @code{de} 8026request, it takes an argument of a macro name to divert subsequent text 8027into. The @code{da} macro appends to an existing diversion. 8028 8029@code{di} or @code{da} without an argument ends the diversion. 8030 8031@c XXX example 8032 8033@ignore 8034@Example 8035... end-note example ... 8036@endExample 8037@end ignore 8038@endDefreq 8039 8040@vindex nl 8041@vindex .h 8042@cindex nested diversions 8043@cindex diversion, nested 8044@Defreg {.z} 8045@Defregx {.d} 8046Diversions may be nested. The read-only number register @code{.z} 8047contains the name of the current diversion (this is a string-valued 8048register). The read-only number register @code{.d} contains the current 8049vertical place in the diversion. If not in a diversion it is the same 8050as the register @code{nl}. 8051@endDefreg 8052 8053@c XXX more info 8054 8055@Defreg {.h} 8056The @dfn{high-water mark} on the current page. It corresponds to the 8057text baseline of the lowest line on the page. This is a read-only 8058register. 8059@endDefreg 8060 8061@Defreg {dn} 8062@Defregx {dl} 8063After completing a diversion, the read-write number registers @code{dn} 8064and @code{dl} contain the vertical and horizontal size of the diversion. 8065 8066@example 8067@group 8068.\" Center text both horizontally & vertically 8069.de (c 8070.br 8071.nf 8072.di @@c 8073.. 8074@end group 8075@group 8076.de )c 8077.br 8078.di 8079.nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v) 8080.sp \\n(@@su 8081.ce 1000 8082.nf 8083.@c 8084.br 8085.ce 0 8086.sp \\n(@@su 8087.br 8088.fi 8089.rr @@s 8090.. 8091@end group 8092@end example 8093@endDefreg 8094 8095@cindex transparent output 8096@cindex output, transparent 8097@Defesc {\\!, , , } 8098@Defescx {\\?, , @Var{anything}, \\?} 8099Prevents requests, macros and escapes from being 8100interpreted when read into a diversion. This takes the given text 8101and @dfn{transparently} embeds it into the diversion. This is useful for 8102macros which shouldn't be invoked until the diverted text is actually 8103output. 8104 8105@c XXX anything is read in copy mode. (what about \! ??) 8106 8107The @code{\!} escape transparently embeds text up to 8108and including the end of the line. 8109The @code{\?} escape transparently embeds text until the next 8110occurrence of the @code{\?} escape. For example: 8111 8112@Example 8113\?@var{anything}\? 8114@endExample 8115 8116@noindent 8117@var{anything} may not contain newlines; use @code{\!} to embed 8118newlines in a diversion. The escape sequence @code{\?} is also 8119recognized in copy mode and turned into a single internal code; it is 8120this code that terminates anything. Thus the following example 8121prints@w{ }4. 8122 8123@Example 8124.nr x 1 8125.nf 8126.di d 8127\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 8128.di 8129.nr x 2 8130.di e 8131.d 8132.di 8133.nr x 3 8134.di f 8135.e 8136.di 8137.nr x 4 8138.f 8139@endExample 8140@endDefesc 8141 8142@cindex unformatting diversions 8143@cindex diversion, unformatting 8144@Defreq {asciify, div} 8145@dfn{Unformats} the diversion specified by @var{div} 8146in such a way that @acronym{ASCII} and space characters that 8147were formatted and diverted are treated like ordinary input 8148characters when the diversion is reread. It can be also used for gross 8149hacks; for example, the following sets register @code{n} to@w{ }1. 8150 8151@Example 8152.tr @@. 8153.di x 8154@@nr n 1 8155.br 8156.di 8157.tr @@@@ 8158.asciify x 8159.x 8160@endExample 8161 8162@xref{Copy-in Mode}. 8163@endDefreq 8164 8165 8166@c ===================================================================== 8167 8168@node Environments, Suppressing output, Diversions, gtroff Reference 8169@section Environments 8170@cindex environments 8171 8172It happens frequently that some text should be printed in a certain 8173format regardless of what may be in effect at the time, for example, in 8174a trap invoked macro to print headers and footers. To solve this 8175@code{gtroff} processes text in @dfn{environments}. An 8176environment contains most of the parameters that control text 8177processing. It is possible to switch amongst these environments; by 8178default @code{gtroff} processes text in environment@w{ }0. The 8179following is the information kept in an environment. 8180 8181@itemize @bullet 8182@item 8183font parameters (size, family, style, character height and slant, space 8184and sentence space size) 8185 8186@item 8187page parameters (line length, title length, vertical spacing, 8188line spacing, indentation, line numbering, hyphenation data) 8189 8190@item 8191fill and adjust mode 8192 8193@item 8194tab stops, tab and leader characters, escape character, no-break and 8195hyphen indicators, margin character data 8196 8197@item 8198partially collected lines 8199@end itemize 8200 8201These environments may be given arbitrary names (see @ref{Identifiers}, 8202for more info). Old versions of @code{troff} only had environments 8203named @samp{0}, @samp{1} and@w{ }@samp{2}. 8204 8205@cindex switch environments 8206@cindex current environment number/name register 8207@Defreq {ev, env} 8208@Defregx {.ev} 8209Switches to another environment. The argument @var{env} is the name of 8210the environment to switch to. With no argument, @code{gtroff} switches 8211back to the previous environment. There is no limit on the number of 8212named environments; they are created the first time that they are 8213referenced. The @code{.ev} read-only register contains the name or 8214number of the current environment. This is a string-valued register. 8215 8216Note that a call to @code{ev} (with argument) pushes the previously 8217active environment onto a stack. If, say, environments @samp{foo}, 8218@samp{bar}, and @samp{zap} are called (in that order), the first 8219@code{ev} request without parameter switches back to environment 8220@samp{bar} (which is popped off the stack), and a second call 8221switches back to environment @samp{foo}. 8222 8223@c XXX example 8224 8225@ignore 8226@Example 8227... page break macro, revised ... 8228@endExample 8229@end ignore 8230 8231Here is an example: 8232 8233@Example 8234.ev footnote-env 8235.fam N 8236.ps 6 8237.vs 8 8238.ll -.5i 8239.ev 8240 8241... 8242 8243.ev footnote-env 8244\(dg Note the large, friendly letters. 8245.ev 8246@endExample 8247@endDefreq 8248 8249@cindex copy environment 8250@Defreq {evc, env} 8251Copies the environment @var{env} into the current environment. 8252@endDefreq 8253 8254 8255@c ===================================================================== 8256 8257@node Suppressing output, I/O, Environments, gtroff Reference 8258@section Suppressing output 8259@cindex suppressing output 8260 8261@Defesc {\\O, , num, } 8262Disables or enables output depending on the value of @var{num}: 8263 8264@table @samp 8265@item \O0 8266Disable any ditroff glyphs from being emitted to the device driver. 8267 8268@item \O1 8269Enable output of glyphs. 8270@end table 8271 8272@vindex opminx 8273@vindex opminy 8274@vindex opmaxx 8275@vindex opmaxy 8276@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 8277@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 8278@xref{Register Index}. These four registers mark the top left and 8279bottom right hand corners of a box which encompasses all written glyphs. 8280 8281The following two forms of @code{\O} are specific to @code{grohtml}. 8282 8283@table @samp 8284@item \O2 8285Disable any ditroff glyphs from being emitted to the device driver. Also 8286write out to @code{stderr} the page number and four registers encompassing 8287the glyphs previously written since the last call to @code{\O}. 8288 8289@item \O3 8290Enable output of glyphs (the default). Also write out to @code{stderr} 8291the page number and four registers encompassing the glyphs previously 8292written since the last call to @code{\O}. 8293@end table 8294@endDefesc 8295 8296 8297@c ===================================================================== 8298 8299@node I/O, Postprocessor Access, Suppressing output, gtroff Reference 8300@section I/O 8301@cindex i/o 8302@cindex input and output requests 8303@cindex requests for input and output 8304@cindex output and input requests 8305 8306@code{gtroff} has several requests for including files: 8307 8308@cindex including a file 8309@cindex file inclusion 8310@Defreq {so, file} 8311Reads in the specified @var{file} and 8312includes it in place of the @code{so} request. This is quite useful for 8313large documents, e.g.@: keeping each chapter in a separate file. 8314@xref{gsoelim}, for more information. 8315@endDefreq 8316 8317@Defreq {mso, file} 8318Identical to the @code{so} request except that @code{gtroff} 8319searches for the specified 8320@var{file} in the same directories as macro files for the 8321the @option{-m} command line option. If the file name to be included 8322has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 8323to include @file{tmac.@var{name}} and vice versa. 8324@endDefreq 8325 8326@cindex transparent output 8327@cindex output, transparent 8328@Defreq {cf, file} 8329@Defreqx {trf, file} 8330Transparently outputs the contents of @var{file}. Each line is output 8331as it were preceded by @code{\!}; however, the lines are not subject to 8332copy mode interpretation. If the file does not end with a newline, then 8333a newline is added. For example, to define a macro@w{ }@code{x} 8334containing the contents of file@w{ }@file{f}, use 8335 8336@Example 8337.di x 8338.trf f 8339.di 8340@endExample 8341 8342The request @w{@code{.cf @var{filename}}}, when used in a diversion, 8343embeds an object in the diversion which, when reread, causes the 8344contents of @var{filename} to be transparently copied through to the 8345output. 8346 8347In @acronym{UNIX} @code{troff}, the contents of @var{filename} 8348is immediately copied through to the output regardless of whether there 8349is a current diversion; this behaviour is so anomalous that it must be 8350considered a bug. This request causes a line break. 8351 8352@rqindex trf 8353With @code{trf}, unlike @code{cf}, the file cannot contain characters 8354such as NUL that are not valid @code{gtroff} input characters 8355(@pxref{Identifiers}). This request causes a line break. 8356@endDefreq 8357 8358@Defreq {nx, } 8359Forces @code{gtroff} to continue processing of 8360the file specified as an argument. 8361@endDefreq 8362 8363@Defreq {rd, } 8364The @code{rd} request reads from standard input, and includes what is 8365read as though it were part of the input file. Text is read until a 8366blank line is encountered. 8367@endDefreq 8368 8369@cindex form letters 8370@cindex letters, form 8371Using the @code{nx} and @code{rd} requests, 8372it is easy to set up form letters. The form 8373letter template is constructed like this: 8374 8375@Example 8376.ce 8377\*(td 8378.sp 2 8379.nf 8380.rd 8381.sp 8382.rd 8383.fi 8384Body of letter. 8385.bp 8386.nx repeat.let 8387@endExample 8388 8389@rqindex ex 8390@noindent 8391When this is run, the following file should be redirected in. Note that 8392requests included in this file are executed as though they were part of 8393the form letter. The last block of input is the @code{ex} requests 8394which tells groff to stop processing. If this was not there, groff 8395would not know when to stop. 8396 8397@Example 8398Trent A. Fisher 8399708 NW 19th Av., #202 8400Portland, OR 97209 8401 8402Dear Trent, 8403 8404Len Adollar 84054315 Sierra Vista 8406San Diego, CA 92103 8407 8408Dear Mr. Adollar, 8409 8410.ex 8411@endExample 8412 8413@Defreq {pi, pipe} 8414Pipes the output of @code{gtroff} to the shell command(s) 8415specified by @var{pipe}. This request must occur before 8416@code{gtroff} has a chance to print anything. 8417@endDefreq 8418 8419@Defreq {sy, cmds} 8420@Defregx {systat} 8421In @dfn{unsafe} mode, executes the shell command(s) specified by 8422@var{cmds}. The output is not saved anyplace, so it is up to the user 8423to do so. 8424 8425@c XXX add info about safer and unsafe mode 8426 8427For example, the following example introduces the current time 8428into a document: 8429 8430@cindex time, current 8431@cindex current time 8432@pindex perl 8433@Example 8434.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 8435 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 8436.so /tmp/x\n[$$] 8437.sy rm /tmp/x\n[$$] 8438\nH:\nM:\nS 8439@endExample 8440 8441@noindent 8442Note that this works by having the @code{perl} script (run by @code{sy}) 8443print out the @code{nr} requests which set the number registers 8444@samp{H}, @samp{M} and @samp{S}, and then reads those commands in with 8445the @code{so} request. 8446 8447@cindex @code{system()} return value register 8448The @code{systat} read-write number register contains the return value 8449of the @code{system()} function executed by the last @code{sy} request. 8450@endDefreq 8451 8452@Defreq {open, stream file} 8453@Defreqx {opena, stream file} 8454Opens the specified @var{file} for writing and 8455associates the specified @var{stream} with it. 8456 8457The @code{opena} is like @code{open}, but if the file exists, append to 8458it instead of truncating it. 8459@endDefreq 8460 8461@cindex copy-in mode, and @code{write} requests 8462@cindex mode, copy-in, and @code{write} requests 8463@Defreq {write, stream data} 8464Writes to the file associated with the specified @var{stream}. 8465The stream must previously have 8466been the subject of an open request. The remainder of the line is 8467interpreted as the @code{ds} request reads its second argument: A 8468leading @samp{"} is stripped, and it is read in copy-in mode. 8469@endDefreq 8470 8471@Defreq {close, stream} 8472Closes the specified @var{stream}; 8473the stream is no longer an acceptable argument to the 8474@code{write} request. 8475 8476@c XXX example 8477 8478@ignore 8479@Example 8480... example of open write &c... 8481@endExample 8482@end ignore 8483@endDefreq 8484 8485@Defesc {\\V, ', xxx, '} 8486Interpolates the contents of the specified 8487environment variable, as returned by the function @code{getenv}. 8488Specify the argument to @code{\V} as an identifier, i.e.@: 8489@samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} 8490is interpreted in copy-in mode. 8491@endDefesc 8492 8493 8494@c ===================================================================== 8495 8496@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 8497@section Postprocessor Access 8498@cindex postprocessor access 8499@cindex access of postprocessor 8500 8501There are two escapes which give information directly to the 8502postprocessor. This is particularly useful for embedding 8503@sc{PostScript} into the final document. 8504 8505@Defesc {\\X, ', xxx, '} 8506Embeds its argument into the @code{gtroff} 8507output preceded with @w{@samp{x X}}. 8508@endDefesc 8509 8510@Defesc {\\Y, ', xxx, '} 8511The @code{\Y} escape is called with an identifier (i.e.@: 8512@code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is 8513approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the 8514contents of the string or macro @var{xxx} are not interpreted; also it 8515is permitted for @var{xxx} to have been defined as a macro and thus 8516contain newlines (it is not permitted for the argument to @code{\X} to 8517contain newlines). The inclusion of newlines requires an extension to 8518the @acronym{UNIX} @code{troff} output format, and confuses drivers 8519that do not know about this extension. 8520@endDefesc 8521 8522@xref{Output Devices}. 8523 8524 8525@c ===================================================================== 8526 8527@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 8528@section Miscellaneous 8529@cindex miscellaneous 8530 8531This section documents parts of @code{gtroff} which cannot (yet) be 8532categorized elsewhere in this manual. 8533 8534@cindex line numbers 8535@cindex numbers, line 8536@Defreq {nm, start inc space indent} 8537Prints line numbers in the left margin. 8538@var{start} is the line number of the @emph{next} 8539output line; this defaults to@w{ }1. @var{inc} indicates on 8540which lines numbers are printed, i.e.@: 5 means put line numbers on 8541every 5@w{ }lines; this defaults to@w{ }1. @var{space} is the 8542space to be left between the number and the text; this defaults to@w{ 8543}1. The fourth argument is the indentation of the line numbers. 8544Without arguments, line numbers are turned off. 8545@endDefreq 8546 8547@c XXX xref ln register 8548 8549@Defreq {nn, [@Var{skip}]} 8550Temporarily turns off line numbering. The 8551argument is the number of lines not to be numbered; this defaults 8552to@w{ }1. 8553 8554@c XXX (does this disable incrementing or display?) 8555 8556@c XXX example 8557 8558@ignore 8559@Example 8560... line numbering example ... 8561@endExample 8562@end ignore 8563@endDefreq 8564 8565@cindex margin characters 8566@cindex characters for margins 8567@Defreq {mc, char dist} 8568Prints margin characters to the right of the text. 8569The first argument is the character to be 8570printed, and the second argument is the distance away from the main body 8571text. With no arguments the margin characters are turned off. If this 8572occurs before a break, no margin character is printed. 8573 8574@pindex nrchbar 8575@pindex changebar 8576This is quite useful for indicating text that has changed, and, in fact, 8577there are programs available for doing this (they are called 8578@code{nrchbar} and @code{changebar} and can be found in any 8579@samp{comp.sources.unix} archive. 8580 8581@c XXX example 8582 8583@ignore 8584@Example 8585... margin char example ... 8586@endExample 8587@end ignore 8588@endDefreq 8589 8590@pindex soelim 8591@cindex multi-file documents 8592@cindex documents, multi-file 8593@Defreq {lf, line filename} 8594A debugging aid for 8595documents which are split into many files, then put together 8596with @code{soelim} and other preprocessors. The second argument is the 8597name of the file and the first argument is the input line number in 8598that file. This way @code{gtroff} can produce error messages which are 8599intelligible to the user. 8600 8601@c XXX example 8602 8603@ignore 8604@Example 8605... example of soelim'ed doc ... 8606@endExample 8607@end ignore 8608@endDefreq 8609 8610 8611@c ===================================================================== 8612 8613@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 8614@section @code{gtroff} Internals 8615 8616@cindex input token 8617@cindex token, input 8618@cindex output node 8619@cindex node, output 8620@code{gtroff} processes input in three steps. One or more input 8621characters are converted to an @dfn{input token}. Then, one or more 8622input tokens are converted to an @dfn{output node}. Finally, output 8623nodes are converted to the intermediate output language understood by 8624all output devices. 8625 8626For example, the input string @samp{fi\[:u]} is converted in a 8627character token @samp{f}, a character token @samp{i}, and a special 8628token @samp{:u} (representing u@w{ }umlaut). Later on, the character 8629tokens @samp{f} and @samp{i} are merged to a single output node 8630representing the ligature glyph @samp{fi}; the same happens with 8631@samp{:u}. All output glyph nodes are `processed' which means that 8632they are invariably associated with a given font, font size, advance 8633width, etc. During the formatting process, @code{gtroff} itself adds 8634various nodes to control the data flow. 8635 8636Macros, diversions, and strings collect elements in two chained lists: 8637a list of input tokens which have been passed unprocessed, and a list 8638of output nodes. Consider the following the diversion. 8639 8640@Example 8641.di xxx 8642a 8643\!b 8644c 8645.br 8646.di 8647@endExample 8648 8649@noindent 8650It contains these elements. 8651 8652@multitable {@i{vertical size node}} {token list} {element number} 8653@item node list @tab token list @tab element number 8654 8655@item @i{line start node} @tab --- @tab 1 8656@item @i{glyph node @code{a}} @tab --- @tab 2 8657@item @i{word space node} @tab --- @tab 3 8658@item --- @tab @code{b} @tab 4 8659@item --- @tab @code{\n} @tab 5 8660@item @i{glyph node @code{c}} @tab --- @tab 6 8661@item @i{vertical size node} @tab --- @tab 7 8662@item @i{vertical size node} @tab --- @tab 8 8663@item --- @tab @code{\n} @tab 9 8664@end multitable 8665 8666@esindex \v 8667@rqindex unformat 8668@noindent 8669Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two 8670(which are always present) specify the vertical extent of the last 8671line, possibly modified by @code{\v}. The @code{br} request finishes 8672the current partial line, inserting a newline input token which is 8673subsequently converted to a space when the diversion is reread. Note 8674that the word space node has a fixed width which isn't stretchable 8675anymore. To convert horizontal space nodes back to input tokens, use 8676the @code{unformat} request. 8677 8678Macros only contain elements in the token list (and the node list is 8679empty); diversions and strings can contain elements in both lists. 8680 8681 8682@c ===================================================================== 8683 8684@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 8685@section Debugging 8686@cindex debugging 8687 8688@code{gtroff} is not easy to debug, but there are some useful features 8689and strategies for debugging. 8690 8691@Defreq {tm, string} 8692Sends the @var{string} to the standard error stream; 8693this is very useful for printing debugging output among other things. 8694@endDefreq 8695 8696@cindex aborting 8697@Defreq {ab, [@Var{string}]} 8698Similar to the @code{tm} request, except that 8699it causes @code{gtroff} to stop processing. With no argument it 8700prints @samp{User Abort}. 8701@endDefreq 8702 8703@cindex @code{ex}, use in debugging 8704@cindex exiting 8705@Defreq {ex, } 8706The @code{ex} request also causes @code{gtroff} to stop processing 8707if encountered at the topmost level; see also @ref{I/O}. 8708@endDefreq 8709 8710When doing something involved it is useful to leave the debugging 8711statements in the code and have them turned on by a command line flag. 8712 8713@Example 8714.if \n(DB .tm debugging output 8715@endExample 8716 8717@noindent 8718To activate these statements say 8719 8720@Example 8721groff -rDB=1 file 8722@endExample 8723 8724@c XXX .tm1, .tmc requests 8725 8726If it is known in advance that there will be many errors and no useful 8727output, @code{gtroff} can be forced to suppress formatted output with 8728the @option{-z} flag. 8729 8730@cindex dumping symbol table 8731@cindex symbol table, dumping 8732@Defreq {pm, } 8733The @code{pm} request prints out the entire symbol table on @code{stderr}. 8734@endDefreq 8735 8736@cindex dumping number registers 8737@cindex number registers, dumping 8738@Defreq {pnr, } 8739Prints the names and contents of all 8740currently defined number registers on @code{stderr}. 8741@endDefreq 8742 8743@cindex dumping traps 8744@cindex traps, dumping 8745@Defreq {ptr, } 8746Prints the names and positions of all traps 8747(not including input line traps and diversion traps) on @code{stderr}. 8748Empty slots in the page trap list are printed as well, because they can 8749affect the priority of subsequently planted traps. 8750@endDefreq 8751 8752@cindex flush output 8753@cindex output, flush 8754@cindex interactive use of @code{gtroff} 8755@cindex @code{gtroff}, interactive use 8756@Defreq {fl, } 8757Instructs @code{gtroff} to flush its output 8758immediately. The intent is for interactive use. 8759@code{gtroff}; there is little other use for it. This 8760request causes a line break. 8761@endDefreq 8762 8763@cindex backtrace of input stack 8764@cindex input stack, backtrace 8765@Defreq {backtrace, } 8766The @code{backtrace} request prints a backtrace of the input stack 8767to the standard error stream. 8768@endDefreq 8769 8770@cindex warnings 8771@code{gtroff} has command line options for printing out more warnings 8772(@option{-w}) and for printing backtraces (@option{-b}) when a warning 8773or an error occurs. The most verbose level of warnings is @option{-ww}. 8774 8775@cindex level of warnings 8776@cindex warnings, level 8777@Defreq {warn, [@Var{flags}]} 8778@Defregx {.warn} 8779Controls the level of warnings checked for. The @var{flags} are the sum 8780of the numbers associated with each warning that is to be enabled; all 8781other warnings are disabled. The number associated with each warning is 8782listed below. For example, @w{@code{.warn 0}} disables all warnings, 8783and @w{@code{.warn 1}} disables all warnings except that about missing 8784characters. If an argument is not given, all warnings are enabled. 8785 8786The read-only number register @code{.warn} contains the current warning 8787level. 8788@endDefreq 8789 8790@menu 8791* Warnings:: 8792@end menu 8793 8794@c --------------------------------------------------------------------- 8795 8796@node Warnings, , Debugging, Debugging 8797@subsection Warnings 8798@cindex warnings 8799 8800The warnings that can be given to @code{gtroff} are divided into the 8801following categories. The name associated with each warning is used by 8802the @option{-w} and @option{-W} options; the number is used by the 8803@code{warn} request and by the @code{.warn} register. 8804 8805@table @samp 8806@item char 8807@itemx 1 8808Non-existent characters. This is enabled by default. 8809 8810@item number 8811@itemx 2 8812Invalid numeric expressions. This is enabled by default. 8813@xref{Expressions}. 8814 8815@item break 8816@itemx 4 8817@cindex fill mode 8818@cindex mode, fill 8819In fill mode, lines which could not be broken so that their length was 8820less than the line length. This is enabled by default. 8821 8822@item delim 8823@itemx 8 8824Missing or mismatched closing delimiters. 8825 8826@item el 8827@itemx 16 8828@rqindex ie 8829@rqindex el 8830Use of the @code{el} request with no matching @code{ie} request. 8831@xref{if-else}. 8832 8833@item scale 8834@itemx 32 8835Meaningless scaling indicators. 8836 8837@item range 8838@itemx 64 8839Out of range arguments. 8840 8841@item syntax 8842@itemx 128 8843Dubious syntax in numeric expressions. 8844 8845@item di 8846@itemx 256 8847@rqindex di 8848@rqindex da 8849@cindex @code{di}, debugging 8850@cindex @code{da}, debugging 8851Use of @code{di} or @code{da} without an argument when there is no 8852current diversion. 8853 8854@item mac 8855@itemx 512 8856@rqindex de 8857@c XXX more index entries 8858Use of undefined strings, macros and diversions. When an undefined 8859string, macro or diversion is used, that string is automatically defined 8860as empty. So, in most cases, at most one warning is given for each 8861name. 8862 8863@item reg 8864@itemx 1024 8865@rqindex nr 8866@c XXX more index entries 8867Use of undefined number registers. When an undefined number register is 8868used, that register is automatically defined to have a value of@w{ }0. 8869A definition is automatically made with a value of@w{ }0. So, in most 8870cases, at most one warning is given for use of a particular name. 8871 8872@item tab 8873@itemx 2048 8874Use of a tab character where a number was expected. 8875 8876@item right-brace 8877@itemx 4096 8878@esindex \@} 8879@cindex @code{\@}}, debugging 8880Use of @code{\@}} where a number was expected. 8881 8882@item missing 8883@itemx 8192 8884Requests that are missing non-optional arguments. 8885 8886@item input 8887@itemx 16384 8888Illegal input characters. 8889 8890@item escape 8891@itemx 32768 8892Unrecognized escape sequences. When an unrecognized escape sequence is 8893encountered, the escape character is ignored. 8894 8895@item space 8896@itemx 65536 8897@cindex compatibility mode 8898Missing space between a request or macro and its argument. This warning 8899is given when an undefined name longer than two characters is 8900encountered, and the first two characters of the name make a defined 8901name. The request or macro is not invoked. When this warning is 8902given, no macro is automatically defined. This is enabled by default. 8903This warning never occurs in compatibility mode. 8904 8905@item font 8906@itemx 131072 8907Non-existent fonts. This is enabled by default. 8908 8909@item all 8910All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 8911intended that this covers all warnings that are useful with traditional 8912macro packages. 8913 8914@item w 8915All warnings. 8916@end table 8917 8918 8919@c ===================================================================== 8920 8921@node Implementation Differences, Summary, Debugging, gtroff Reference 8922@section Implementation Differences 8923@cindex implementation differences 8924@cindex differences in implementation 8925@cindex incompatibilities with Unix @code{troff} 8926@cindex compatibility mode 8927@cindex mode, compatibility 8928 8929GNU @code{troff} has a number of features which cause incompatibilities 8930with documents written with old versions of @code{troff}. 8931 8932@cindex long names 8933@cindex names, long 8934Long names cause some incompatibilities. @acronym{UNIX} @code{troff} 8935interprets 8936 8937@Example 8938.dsabcd 8939@endExample 8940 8941@esindex \* 8942@esindex \n 8943@cindex @code{\*}, incompatibilities with Unix @code{troff} 8944@cindex @code{\n}, incompatibilities with Unix @code{troff} 8945@rqindex cp 8946@vindex .C 8947@noindent 8948as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 8949@code{troff} interprets this as a call of a macro named 8950@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 8951@code{\*[} or @code{\n[} as references to a string or number register 8952called @samp{[}. In GNU @code{troff}, however, this is normally 8953interpreted as the start of a long name. In compatibility mode GNU 8954@code{troff} interprets long names in the traditional way 8955(which means that they are not recognized as names). 8956Compatibility mode can be turned on with the @option{-C} command line 8957option, and turned on or off with the @code{cp} request. The number 8958register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{ 8959}otherwise. 8960 8961@esindex \A 8962@esindex \| 8963@esindex \^ 8964@esindex \& 8965@esindex \@{ 8966@esindex \@} 8967@esindex \@key{SP} 8968@esindex \' 8969@esindex \` 8970@esindex \- 8971@esindex \_ 8972@esindex \! 8973@esindex \% 8974@esindex \c 8975GNU @code{troff} does not allow the use of the escape sequences 8976@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 8977@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 8978@code{\%}, and @code{\c} in names of strings, macros, diversions, number 8979registers, fonts or environments; @acronym{UNIX} @code{troff} does. The 8980@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 8981avoiding use of these escape sequences in names. 8982 8983@cindex fractional point sizes 8984@cindex point sizes, fractional 8985@rqindex ps 8986@cindex @code{ps}, incompatibilities with Unix @code{troff} 8987Fractional point sizes cause one noteworthy incompatibility. In 8988@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 8989indicators and thus 8990 8991@Example 8992.ps 10u 8993@endExample 8994 8995@noindent 8996sets the point size to 10@w{ }points, whereas in GNU @code{troff} it 8997sets the point size to 10@w{ }scaled points. @xref{Fractional Type 8998Sizes}, for more information. 8999 9000@rqindex bd 9001@rqindex cs 9002@rqindex tkf 9003@rqindex tr 9004@rqindex fp 9005@cindex @code{bd}, incompatibilities with Unix @code{troff} 9006@cindex @code{cs}, incompatibilities with Unix @code{troff} 9007@cindex @code{tkf}, incompatibilities with Unix @code{troff} 9008@cindex @code{tr}, incompatibilities with Unix @code{troff} 9009@cindex @code{fp}, incompatibilities with Unix @code{troff} 9010@cindex input and output characters, compatibility with Unix 9011@cindex output characters, compatibility with Unix 9012@cindex characters, input and output, compatibility with Unix 9013In GNU @code{troff} there is a fundamental difference between 9014unformatted, input characters, and formatted, output characters. 9015Everything that affects how an output character is output is stored 9016with the character; once an output character has been constructed it is 9017unaffected by any subsequent requests that are executed, including 9018@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 9019Normally output characters are constructed from input characters at the 9020moment immediately before the character is added to the current output 9021line. Macros, diversions and strings are all, in fact, the same type of 9022object; they contain lists of input characters and output characters in 9023any combination. An output character does not behave like an input 9024character for the purposes of macro processing; it does not inherit any 9025of the special properties that the input character from which it was 9026constructed might have had. For example, 9027 9028@Example 9029.di x 9030\\\\ 9031.br 9032.di 9033.x 9034@endExample 9035 9036@esindex \e 9037@esindex \! 9038@esindex \? 9039@cindex @code{\e}, incompatibilities with Unix @code{troff} 9040@cindex @code{\!}, incompatibilities with Unix @code{troff} 9041@cindex @code{\?}, incompatibilities with Unix @code{troff} 9042@cindex transparent output, incompatibilities with Unix @code{troff} 9043@cindex output, transparent, incompatibilities with Unix @code{troff} 9044@noindent 9045prints @samp{\\} in GNU @code{troff}; each pair of input backslashes 9046is turned into one output backslash and the resulting output backslashes 9047are not interpreted as escape characters when they are reread. 9048@acronym{UNIX} @code{troff} would interpret them as escape characters 9049when they were reread and would end up printing one @samp{\}. The 9050correct way to obtain a printable backslash is to use the @code{\e} 9051escape sequence: This always prints a single instance of the current 9052escape character, regardless of whether or not it is used in a 9053diversion; it also works in both GNU @code{troff} and @acronym{UNIX} 9054@code{troff}. To store, for some reason, an escape sequence in a 9055diversion that will be interpreted when the diversion is reread, either 9056use the traditional @code{\!} transparent output facility, or, if this 9057is unsuitable, the new @code{\?} escape sequence. 9058 9059@c XXX .tl compatibility mode -> input stack level 9060@c XXX .if compatibility mode -> input stack level 9061 9062@xref{Diversions}, for more information. 9063 9064 9065@c ===================================================================== 9066 9067@node Summary, , Implementation Differences, gtroff Reference 9068@section Summary 9069@cindex summary 9070 9071@c XXX documentation 9072 9073 9074 9075@c ===================================================================== 9076@c ===================================================================== 9077 9078@node Preprocessors, Output Devices, gtroff Reference, Top 9079@chapter Preprocessors 9080@cindex preprocessors 9081 9082This chapter describes all preprocessors that come with @code{groff} or 9083which are freely available. 9084 9085@menu 9086* geqn:: 9087* gtbl:: 9088* gpic:: 9089* ggrn:: 9090* grap:: 9091* grefer:: 9092* gsoelim:: 9093@end menu 9094 9095 9096@c ===================================================================== 9097 9098@node geqn, gtbl, Preprocessors, Preprocessors 9099@section @code{geqn} 9100@cindex @code{eqn} 9101@cindex @code{geqn} 9102 9103@c XXX 9104 9105@menu 9106* Invoking geqn:: 9107@end menu 9108 9109@c --------------------------------------------------------------------- 9110 9111@node Invoking geqn, , geqn, geqn 9112@subsection Invoking @code{geqn} 9113@cindex invoking @code{geqn} 9114@cindex @code{geqn}, invoking 9115 9116@c XXX 9117 9118 9119@c ===================================================================== 9120 9121@node gtbl, gpic, geqn, Preprocessors 9122@section @code{gtbl} 9123@cindex @code{tbl} 9124@cindex @code{gtbl} 9125 9126@c XXX 9127 9128@menu 9129* Invoking gtbl:: 9130@end menu 9131 9132@c --------------------------------------------------------------------- 9133 9134@node Invoking gtbl, , gtbl, gtbl 9135@subsection Invoking @code{gtbl} 9136@cindex invoking @code{gtbl} 9137@cindex @code{gtbl}, invoking 9138 9139@c XXX 9140 9141 9142@c ===================================================================== 9143 9144@node gpic, ggrn, gtbl, Preprocessors 9145@section @code{gpic} 9146@cindex @code{pic} 9147@cindex @code{gpic} 9148 9149@c XXX 9150 9151@menu 9152* Invoking gpic:: 9153@end menu 9154 9155@c --------------------------------------------------------------------- 9156 9157@node Invoking gpic, , gpic, gpic 9158@subsection Invoking @code{gpic} 9159@cindex invoking @code{gpic} 9160@cindex @code{gpic}, invoking 9161 9162@c XXX 9163 9164 9165@c ===================================================================== 9166 9167@node ggrn, grap, gpic, Preprocessors 9168@section @code{ggrn} 9169@cindex @code{grn} 9170@cindex @code{ggrn} 9171 9172@c XXX 9173 9174@menu 9175* Invoking ggrn:: 9176@end menu 9177 9178@c --------------------------------------------------------------------- 9179 9180@node Invoking ggrn, , ggrn, ggrn 9181@subsection Invoking @code{ggrn} 9182@cindex invoking @code{ggrn} 9183@cindex @code{ggrn}, invoking 9184 9185@c XXX 9186 9187 9188@c ===================================================================== 9189 9190@node grap, grefer, ggrn, Preprocessors 9191@section @code{grap} 9192@cindex @code{grap} 9193 9194A free implementation of @code{grap}, written by Ted Faber, 9195is available as an extra package from the following address: 9196 9197@display 9198@url{http://www.lunabase.org/~faber/Vault/software/grap/} 9199@end display 9200 9201 9202@c ===================================================================== 9203 9204@node grefer, gsoelim, grap, Preprocessors 9205@section @code{grefer} 9206@cindex @code{refer} 9207@cindex @code{grefer} 9208 9209@c XXX 9210 9211@menu 9212* Invoking grefer:: 9213@end menu 9214 9215@c --------------------------------------------------------------------- 9216 9217@node Invoking grefer, , grefer, grefer 9218@subsection Invoking @code{grefer} 9219@cindex invoking @code{grefer} 9220@cindex @code{grefer}, invoking 9221 9222@c XXX 9223 9224 9225@c ===================================================================== 9226 9227@node gsoelim, , grefer, Preprocessors 9228@section @code{gsoelim} 9229@cindex @code{soelim} 9230@cindex @code{gsoelim} 9231 9232@c XXX 9233 9234@menu 9235* Invoking gsoelim:: 9236@end menu 9237 9238@c --------------------------------------------------------------------- 9239 9240@node Invoking gsoelim, , gsoelim, gsoelim 9241@subsection Invoking @code{gsoelim} 9242@cindex invoking @code{gsoelim} 9243@cindex @code{gsoelim}, invoking 9244 9245@c XXX 9246 9247 9248 9249@c ===================================================================== 9250@c ===================================================================== 9251 9252@node Output Devices, File formats, Preprocessors, Top 9253@chapter Output Devices 9254@cindex output devices 9255@cindex devices for output 9256 9257@c XXX 9258 9259@menu 9260* Special Characters:: 9261* grotty:: 9262* grops:: 9263* grodvi:: 9264* grolj4:: 9265* grolbp:: 9266* grohtml:: 9267* gxditview:: 9268@end menu 9269 9270 9271@c ===================================================================== 9272 9273@node Special Characters, grotty, Output Devices, Output Devices 9274@section Special Characters 9275@cindex special characters 9276@cindex characters, special 9277 9278@c XXX 9279 9280@xref{Font Files}. 9281 9282 9283@c ===================================================================== 9284 9285@node grotty, grops, Special Characters, Output Devices 9286@section @code{grotty} 9287@cindex @code{grotty} 9288 9289@c XXX 9290 9291@menu 9292* Invoking grotty:: 9293@end menu 9294 9295@c --------------------------------------------------------------------- 9296 9297@node Invoking grotty, , grotty, grotty 9298@subsection Invoking @code{grotty} 9299@cindex invoking @code{grotty} 9300@cindex @code{grotty}, invoking 9301 9302@c XXX 9303 9304 9305@c ===================================================================== 9306 9307@node grops, grodvi, grotty, Output Devices 9308@section @code{grops} 9309@cindex @code{grops} 9310 9311@c XXX 9312 9313@menu 9314* Invoking grops:: 9315* Embedding PostScript:: 9316@end menu 9317 9318@c --------------------------------------------------------------------- 9319 9320@node Invoking grops, Embedding PostScript, grops, grops 9321@subsection Invoking @code{grops} 9322@cindex invoking @code{grops} 9323@cindex @code{grops}, invoking 9324 9325@c XXX 9326 9327@c --------------------------------------------------------------------- 9328 9329@node Embedding PostScript, , Invoking grops, grops 9330@subsection Embedding @sc{PostScript} 9331@cindex embedding postscript 9332@cindex postscript, embedding 9333 9334@c XXX 9335 9336 9337@c ===================================================================== 9338 9339@node grodvi, grolj4, grops, Output Devices 9340@section @code{grodvi} 9341@cindex @code{grodvi} 9342 9343@c XXX 9344 9345@menu 9346* Invoking grodvi:: 9347@end menu 9348 9349@c --------------------------------------------------------------------- 9350 9351@node Invoking grodvi, , grodvi, grodvi 9352@subsection Invoking @code{grodvi} 9353@cindex invoking @code{grodvi} 9354@cindex @code{grodvi}, invoking 9355 9356@c XXX 9357 9358 9359@c ===================================================================== 9360 9361@node grolj4, grolbp, grodvi, Output Devices 9362@section @code{grolj4} 9363@cindex @code{grolj4} 9364 9365@c XXX 9366 9367@menu 9368* Invoking grolj4:: 9369@end menu 9370 9371@c --------------------------------------------------------------------- 9372 9373@node Invoking grolj4, , grolj4, grolj4 9374@subsection Invoking @code{grolj4} 9375@cindex invoking @code{grolj4} 9376@cindex @code{grolj4}, invoking 9377 9378@c XXX 9379 9380 9381@c ===================================================================== 9382 9383@node grolbp, grohtml, grolj4, Output Devices 9384@section @code{grolbp} 9385@cindex @code{grolbp} 9386 9387@c XXX 9388 9389@menu 9390* Invoking grolbp:: 9391@end menu 9392 9393@c --------------------------------------------------------------------- 9394 9395@node Invoking grolbp, , grolbp, grolbp 9396@subsection Invoking @code{grolbp} 9397@cindex invoking @code{grolbp} 9398@cindex @code{grolbp}, invoking 9399 9400@c XXX 9401 9402 9403@c ===================================================================== 9404 9405@node grohtml, gxditview, grolbp, Output Devices 9406@section @code{grohtml} 9407@cindex @code{grohtml} 9408 9409@c XXX 9410 9411@menu 9412* Invoking grohtml:: 9413@end menu 9414 9415@c --------------------------------------------------------------------- 9416 9417@node Invoking grohtml, , grohtml, grohtml 9418@subsection Invoking @code{grohtml} 9419@cindex invoking @code{grohtml} 9420@cindex @code{grohtml}, invoking 9421 9422@c XXX 9423 9424 9425@c ===================================================================== 9426 9427@node gxditview, , grohtml, Output Devices 9428@section @code{gxditview} 9429@cindex @code{gxditview} 9430 9431@c XXX 9432 9433@menu 9434* Invoking gxditview:: 9435@end menu 9436 9437@c --------------------------------------------------------------------- 9438 9439@node Invoking gxditview, , gxditview, gxditview 9440@subsection Invoking @code{gxditview} 9441@cindex invoking @code{gxditview} 9442@cindex @code{gxditview}, invoking 9443 9444@c XXX 9445@c X11's xditview 9446 9447 9448 9449@c ===================================================================== 9450@c ===================================================================== 9451 9452@node File formats, Installation, Output Devices, Top 9453@chapter File formats 9454@cindex file formats 9455@cindex formats, file 9456 9457@c XXX 9458 9459@menu 9460* gtroff Output:: 9461* Font Files:: 9462@end menu 9463 9464 9465@c ===================================================================== 9466 9467@node gtroff Output, Font Files, File formats, File formats 9468@section @code{gtroff} Output 9469@cindex @code{gtroff} output 9470@cindex output, @code{gtroff} 9471 9472This section describes the format output of GNU @code{troff}. The 9473output format used by GNU @code{troff} is very similar -- but 9474not identical -- to that used by 9475@acronym{UNIX} device-independent @code{troff} (@code{ditroff}). 9476 9477@menu 9478* Output Format:: 9479* Device Control:: 9480* Drawing Functions:: 9481* Line Continuation:: 9482@end menu 9483 9484@c --------------------------------------------------------------------- 9485 9486@node Output Format, Device Control, gtroff Output, gtroff Output 9487@subsection Output Format 9488@cindex output format 9489@cindex format of output 9490 9491@cindex 8-bit input 9492@cindex input, 8-bit 9493The output format is text based, as opposed to a binary format (like 9494@TeX{} DVI). The output format is @w{8-bit} clean, thus single 9495characters can have the eighth bit set, as can the names of fonts and 9496special characters. 9497 9498The output format consists of single command characters with attached 9499parameters which are separated from subsequent text by whitespace or a 9500newline. 9501 9502The names of characters and fonts can be of arbitrary length; drivers 9503should not assume that they are only two characters long (as 9504@code{ditroff} does). 9505 9506When a character is to be printed, that character is always in the 9507current font. Unlike @code{ditroff}, it is not necessary for drivers to 9508search special fonts to find a character. 9509 9510@table @code 9511@item H@var{n} 9512@c XXX 9513 9514@item V@var{n} 9515@c XXX 9516 9517@item h@var{n} 9518@c XXX 9519 9520@item v@var{n} 9521@c XXX 9522 9523@item c@var{n} 9524@c XXX 9525 9526@item C@var{n} 9527@c XXX 9528 9529@item @var{nn}@var{c} 9530@c XXX 9531 9532@item t@var{xxx} 9533@var{xxx} is any sequence of characters terminated by a space or a 9534newline; the first character should be printed at the current position, 9535the the current horizontal position should be increased by the width of 9536the first character, and so on for each character. The width of the 9537character is that given in the font file, appropriately scaled for the 9538current point size, and rounded so that it is a multiple of the 9539horizontal resolution. Special characters cannot be printed using this 9540command. 9541 9542@kindex tcommand 9543@pindex DESC@r{, and @code{tcommand}} 9544This command is only allowed if the @samp{tcommand} line is present in 9545the @file{DESC} file. 9546 9547@item u@var{n} @var{xxx} 9548This is same as the @samp{t} command except that after printing each 9549character, the current horizontal position is increased by the sum of 9550the width of that character and@w{ }@var{n}. 9551 9552This command is only allowed if the @samp{tcommand} line is present in 9553the @file{DESC} file. 9554 9555@item n@var{a}@var{b} 9556@c XXX 9557 9558@item p@var{n} 9559@c XXX 9560 9561@item s@var{n} 9562@kindex sizescale 9563@pindex DESC@r{, and @code{sizescale}} 9564The argument to the @samp{s} command is in scaled points (units of 9565points/@var{n}, where @var{n} is the argument to the @samp{sizescale} 9566command in the @file{DESC} file). 9567 9568@item f@var{n} 9569@item x @dots{} \n 9570Device control. 9571@c XXX more info 9572 9573@item D@var{c} @var{x}@dots{}\n 9574@c XXX 9575@end table 9576 9577@c --------------------------------------------------------------------- 9578 9579@node Device Control, Drawing Functions, Output Format, gtroff Output 9580@subsection Device Control 9581@cindex device control 9582@cindex control of devices 9583 9584The @samp{x} command is normally followed by a letter or word indicating 9585the function to perform, followed by white space separated arguments. 9586 9587The first argument can be abbreviated to the first letter. 9588 9589@table @code 9590@item x init 9591@c XXX 9592 9593@item x T 9594@c XXX 9595 9596@item x res @var{n} @var{h} @var{v} 9597@c XXX 9598 9599@item x H 9600@c XXX more info 9601The argument to the @w{@samp{x Height}} command is also in scaled 9602points. 9603@end table 9604 9605The first three output commands are guaranteed to be: 9606 9607@Example 9608x T device 9609x res n h v 9610x init 9611@endExample 9612 9613@noindent 9614For example, the input 9615 9616@Example 9617crunchy \fH\s+2frog\s0\fP!? 9618@endExample 9619 9620@noindent 9621produces 9622 9623@c XXX example 9624 9625@ignore 9626@Example 9627... sample output here ... 9628@endExample 9629@end ignore 9630 9631@c --------------------------------------------------------------------- 9632 9633@node Drawing Functions, Line Continuation, Device Control, gtroff Output 9634@subsection Drawing Functions 9635@cindex drawing functions 9636@cindex functions for drawing 9637 9638@pindex gpic 9639The @samp{D} drawing command has been extended. These extensions are 9640used by GNU @code{pic} only if the @option{-x} option is given. 9641 9642@xref{Drawing Requests}. 9643 9644@table @code 9645@c XXX ... 9646@item Df @var{n} 9647Set the shade of gray to be used for filling solid objects to@w{ 9648}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 9649corresponds solid white and 1000 to solid black, and values in between 9650correspond to intermediate shades of gray. This applies only to solid 9651circles, solid ellipses and solid polygons. By default, a level of@w{ 9652}1000 is used. Whatever color a solid object has, it should 9653completely obscure everything beneath it. A value greater than@w{ }1000 9654or less than@w{ }0 can also be used: this means fill with the shade of 9655gray that is currently being used for lines and text. Normally this 9656is black, but some drivers may provide a way of changing this. 9657 9658@item DC @var{d} 9659Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost 9660point at the current position. 9661 9662@item DE @var{dx} @var{dy} 9663Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a 9664vertical diameter of@w{ }@var{dy} with the leftmost point at the current 9665position. 9666 9667@item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn} 9668Draw a polygon with automatic closure. The first vertex is at the 9669current position, the second vertex at an offset (@var{dx1},@var{dy1}) 9670from the current position, the second vertex at an offset 9671(@var{dx2},@var{dy2}) from the first vertex, and so on up to the 9672@var{n}@dmn{th} vertex. At the moment, GNU @code{pic} only uses this 9673command to generate triangles and rectangles. 9674 9675@item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn} 9676Like @code{Dp} but draw a solid rather than outlined polygon. 9677 9678@item Dt @var{n} 9679@cindex line thickness 9680@cindex thickness of lines 9681Set the current line thickness to @var{n}@w{ }machine units. 9682Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness 9683proportional to the current point size; drivers should continue to do 9684this if no @code{Dt} command has been given, or if a @code{Dt} command 9685has been given with a negative value of@w{ }@var{n}. A zero value of@w{ 9686}@var{n} selects the smallest available line thickness. 9687@end table 9688 9689@esindex \D 9690A difficulty arises in how the current position should be changed after 9691the execution of these commands. This is not of great importance since 9692the code generated by GNU @code{pic} does not depend on this. Given a 9693drawing command of the form 9694 9695@Example 9696\D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}' 9697@endExample 9698 9699@esindex \w 9700@vindex st 9701@vindex sb 9702@noindent 9703where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or 9704@samp{~}, @acronym{UNIX} @code{troff} treats each x@w{ }value 9705as a horizontal quantity, and each y@w{ }value as a vertical 9706quantity; it assumes that the width of the drawn object is the sum of 9707all x@w{ }values, and that the height is the sum of all y@w{ }values. 9708(The assumption about the height can be seen by examining the @code{st} 9709and @code{sb} registers after using such a @code{D}@w{ }command in a 9710@code{\w} escape sequence.) This rule also holds for all the original 9711drawing commands with the exception of @code{De}. For the sake of 9712compatibility GNU @code{troff} also follows this rule, even though it 9713produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to 9714a lesser extent, @code{DE}@w{ }commands. Thus after executing a 9715@code{D}@w{ }command of the form 9716 9717@Example 9718D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn} 9719@endExample 9720 9721@noindent 9722the current position should be increased horizontally by the sum of all 9723x@w{ }values and vertically by the sum of all y@w{ }values. 9724 9725@c --------------------------------------------------------------------- 9726 9727@node Line Continuation, , Drawing Functions, gtroff Output 9728@subsection Line Continuation 9729@cindex line continuation in output commands 9730@cindex output commands, line continuation 9731 9732There is a continuation convention which permits the argument to the 9733@w{@samp{x X}} command to contain newlines: When outputting the argument 9734to the @w{@samp{x X}} command, GNU @code{troff} follows each newline 9735in the argument with a @samp{+} character (as usual, it terminates 9736the entire argument with a newline); thus if the line after the line 9737containing the @w{@samp{x X}} command starts with @samp{+}, then the 9738newline ending the line containing the @w{@samp{x X}} command should be 9739treated as part of the argument to the @w{@samp{x X}} command, the 9740@samp{+} should be ignored, and the part of the line following the 9741@samp{+} should be treated like the part of the line following the 9742@w{@samp{x X}} command. 9743 9744 9745@c ===================================================================== 9746 9747@node Font Files, , gtroff Output, File formats 9748@section Font Files 9749@cindex font files 9750@cindex files, font 9751 9752The @code{gtroff} font format is roughly a superset of the 9753@code{ditroff} font format. Unlike the @code{ditroff} font format, 9754there is no associated binary format; all files are text files. The 9755font files for device @var{name} are stored in a directory 9756@file{dev@var{name}}. There are two types of file: a device description 9757file called @file{DESC} and for each font@w{ }@var{f} a font file 9758called@w{ }@file{@var{f}}. 9759 9760@menu 9761* DESC File Format:: 9762* Font File Format:: 9763@end menu 9764 9765@c --------------------------------------------------------------------- 9766 9767@node DESC File Format, Font File Format, Font Files, Font Files 9768@subsection @file{DESC} File Format 9769@cindex @file{DESC} file format 9770@cindex font description file format 9771@cindex format of font description file 9772@pindex DESC@r{ file format} 9773 9774The @file{DESC} file can contain the following types of line: 9775 9776@table @code 9777@item res @var{n} 9778@kindex res 9779There are @var{n} machine units per inch. 9780 9781@item hor @var{n} 9782@kindex hor 9783The horizontal resolution is @var{n} machine units. 9784 9785@item vert @var{n} 9786@kindex vert 9787The vertical resolution is @var{n} machine units. 9788 9789@item sizescale @var{n} 9790@kindex sizescale 9791The scale factor for point sizes. By default this has a value of@w{ }1. 9792One scaled point is equal to one point/@var{n}. The arguments to the 9793@code{unitwidth} and @code{sizes} commands are given in scaled points. 9794@xref{Fractional Type Sizes}, for more information. 9795 9796@item unitwidth @var{n} 9797@kindex unitwidth 9798Quantities in the font files are given in machine units for fonts whose 9799point size is @var{n}@w{ }scaled points. 9800 9801@item tcommand 9802@kindex tcommand 9803This means that the postprocessor can handle the @samp{t} and @samp{u} 9804output commands. 9805 9806@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 9807@kindex sizes 9808This means that the device has fonts at @var{s1}, @var{s2}, @dots{} 9809@var{sn} scaled points. The list of sizes must be terminated by a@w{ 9810}0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The 9811list can extend over more than one line. 9812 9813@item styles @var{S1} @var{S2} @dots{} @var{Sm} 9814@kindex styles 9815The first @var{m}@w{ }font positions are associated with styles 9816@var{S1} @dots{} @var{Sm}. 9817 9818@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 9819@kindex fonts 9820Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 9821@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 9822styles. This command may extend over more than one line. A font name 9823of@var{ }0 means no font is mounted on the corresponding font position. 9824 9825@item family @var{fam} 9826@kindex family 9827The default font family is @var{fam}. 9828 9829@item charset 9830@kindex charset 9831This line and everything following in the file are ignored. It is 9832allowed for the sake of backwards compatibility. 9833@end table 9834 9835The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines 9836are mandatory. Other commands are ignored by @code{gtroff} but may be 9837used by postprocessors to store arbitrary information about the device 9838in the @file{DESC} file. 9839 9840@c XXX add other commands resp. xrefs to output devices 9841@c XXX add obsolete commands 9842 9843@c --------------------------------------------------------------------- 9844 9845@node Font File Format, , DESC File Format, Font Files 9846@subsection Font File Format 9847@cindex font file format 9848@cindex format of font files 9849 9850A font file has two sections. The first section is a sequence of lines 9851each containing a sequence of blank delimited words; the first word in 9852the line is a key, and subsequent words give a value for that key. 9853 9854@table @code 9855@item name @var{f} 9856@kindex name 9857The name of the font is@w{ }@var{f}. 9858 9859@item spacewidth @var{n} 9860@kindex spacewidth 9861The normal width of a space is@w{ }@var{n}. 9862 9863@item slant @var{n} 9864@kindex slant 9865The characters of the font have a slant of @var{n}@w{ }degrees. 9866(Positive means forward.) 9867 9868@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 9869@kindex ligatures 9870Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 9871possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 9872@samp{ffl}. For backwards compatibility, the list of ligatures may be 9873terminated with a@w{ }0. The list of ligatures may not extend over more 9874than one line. 9875 9876@item special 9877@kindex special 9878The font is special; this means that when a character is requested that 9879is not present in the current font, it is searched for in any 9880special fonts that are mounted. 9881@end table 9882 9883Other commands are ignored by @code{gtroff} but may be used by 9884postprocessors to store arbitrary information about the font in the font 9885file. 9886 9887@cindex comments in font files 9888@cindex font files, comments 9889@kindex # 9890The first section can contain comments which start with the @samp{#} 9891character and extend to the end of a line. 9892 9893The second section contains one or two subsections. It must contain a 9894@code{charset} subsection and it may also contain a @code{kernpairs} 9895subsection. These subsections can appear in any order. Each 9896subsection starts with a word on a line by itself. 9897 9898@kindex charset 9899The word @code{charset} starts the character set subsection. The 9900@code{charset} line is followed by a sequence of lines. Each line gives 9901information for one character. A line comprises a number of fields 9902separated by blanks or tabs. The format is 9903 9904@c XXX fix it for new HTML additions 9905 9906@Example 9907@var{name} @var{metrics} @var{type} @var{code} @var{comment} 9908@endExample 9909 9910@cindex 8-bit input 9911@cindex input, 8-bit 9912@esindex \N 9913@kindex --- 9914@noindent 9915@var{name} identifies the character: If @var{name} is a single 9916character@w{ }@var{c} then it corresponds to the @code{gtroff} input 9917character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is 9918a single character, then it corresponds to the @code{gtroff} input 9919character@w{ }\@var{c}; otherwise it corresponds to the groff input 9920character @samp{\[@var{name}]}. (If it is exactly two characters 9921@var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff} 9922supports 8-bit characters; however some utilities have difficulties with 9923eight-bit characters. For this reason, there is a convention that the 9924name @samp{char@var{n}} is equivalent to the single character whose code 9925is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the 9926character with code@w{ }163 which is the pounds sterling sign in @w{ISO 9927Latin-1} character set. The name @samp{---} is special and indicates 9928that the character is unnamed; such characters can only be used by means 9929of the @code{\N} escape sequence in @code{gtroff}. 9930 9931@c XXX input encodings vs. output encodings 9932 9933The @var{type} field gives the character type: 9934 9935@table @code 9936@item 1 9937the character has an descender, for example, `p'; 9938 9939@item 2 9940the character has an ascender, for example, `b'; 9941 9942@item 3 9943the character has both an ascender and a descender, for example, `('. 9944@end table 9945 9946The @var{code} field gives the code which the postprocessor uses to 9947print the character. The character can also be input to @code{gtroff} 9948using this code by means of the @code{\N} escape sequence. The code can 9949be any integer. If it starts with @samp{0} it is interpreted as 9950octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 9951hexadecimal. 9952 9953Anything on the line after the @var{code} field is ignored. 9954 9955The @var{metrics} field has the form: 9956 9957@Example 9958@var{width}[,@var{height}[,@var{depth}[,@var{italic_correction} 9959 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]] 9960@endExample 9961 9962@noindent 9963There must not be any spaces between these subfields (it has been split 9964here into two lines for better legibility only). Missing subfields are 9965assumed to be@w{ }0. The subfields are all decimal integers. Since 9966there is no associated binary format, these values are not required to 9967fit into a variable of type @samp{char} as they are in @code{ditroff}. 9968The @var{width} subfield gives the width of the character. The 9969@var{height} subfield gives the height of the character (upwards is 9970positive); if a character does not extend above the baseline, it should 9971be given a zero height, rather than a negative height. The @var{depth} 9972subfield gives the depth of the character, that is, the distance below 9973the lowest point below the baseline to which the character extends 9974(downwards is positive); if a character does not extend below above the 9975baseline, it should be given a zero depth, rather than a negative depth. 9976The @var{italic_correction} subfield gives the amount of space that 9977should be added after the character when it is immediately to be 9978followed by a character from a roman font. The 9979@var{left_italic_correction} subfield gives the amount of space that 9980should be added before the character when it is immediately to be 9981preceded by a character from a roman font. The 9982@var{subscript_correction} gives the amount of space that should be 9983added after a character before adding a subscript. This should be less 9984than the italic correction. 9985 9986A line in the @code{charset} section can also have the format 9987 9988@Example 9989@var{name} " 9990@endExample 9991 9992@noindent 9993This indicates that @var{name} is just another name for the character 9994mentioned in the preceding line. 9995 9996@kindex kernpairs 9997The word @code{kernpairs} starts the kernpairs section. This contains a 9998sequence of lines of the form: 9999 10000@Example 10001@var{c1} @var{c2} @var{n} 10002@endExample 10003 10004@noindent 10005This means that when character @var{c1} appears next to character 10006@var{c2} the space between them should be increased by@w{ }@var{n}. 10007Most entries in the kernpairs section have a negative value for@w{ 10008}@var{n}. 10009 10010 10011 10012@c ===================================================================== 10013@c ===================================================================== 10014 10015@node Installation, Request Index, File formats, Top 10016@chapter Installation 10017@cindex installation 10018 10019@c XXX 10020 10021 10022 10023@c ===================================================================== 10024@c ===================================================================== 10025 10026@node Request Index, Escape Index, Installation, Top 10027@chapter Request Index 10028 10029Requests appear without the leading control character (normally either 10030@samp{.} or @samp{'}). 10031 10032@printindex rq 10033 10034 10035 10036@c ===================================================================== 10037@c ===================================================================== 10038 10039@node Escape Index, Operator Index, Request Index, Top 10040@chapter Escape Index 10041 10042@printindex es 10043 10044 10045 10046@c ===================================================================== 10047@c ===================================================================== 10048 10049@node Operator Index, Register Index, Escape Index, Top 10050@chapter Operator Index 10051 10052@printindex op 10053 10054 10055 10056@c ===================================================================== 10057@c ===================================================================== 10058 10059@node Register Index, Macro Index, Operator Index, Top 10060@chapter Register Index 10061 10062@printindex vr 10063 10064 10065 10066@c ===================================================================== 10067@c ===================================================================== 10068 10069@node Macro Index, String Index, Register Index, Top 10070@chapter Macro Index 10071 10072@printindex ma 10073 10074 10075 10076@c ===================================================================== 10077@c ===================================================================== 10078 10079@node String Index, Glyph Name Index, Macro Index, Top 10080@chapter String Index 10081 10082@printindex st 10083 10084 10085 10086@c ===================================================================== 10087@c ===================================================================== 10088 10089@node Glyph Name Index, Font File Keyword Index, String Index, Top 10090@chapter Glyph Name Index 10091 10092A glyph name @code{xx} consisting of exactly two characters can be 10093accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 10094accessed as @samp{\[xxx]}. 10095 10096@printindex gl 10097 10098 10099 10100@c ===================================================================== 10101@c ===================================================================== 10102 10103@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 10104@chapter Font File Keyword Index 10105 10106@printindex ky 10107 10108 10109 10110@c ===================================================================== 10111@c ===================================================================== 10112 10113@node Program and File Index, Concept Index, Font File Keyword Index, Top 10114@chapter Program and File Index 10115 10116@printindex pg 10117 10118 10119 10120@c ===================================================================== 10121@c ===================================================================== 10122 10123@node Concept Index, , Program and File Index, Top 10124@chapter Concept Index 10125 10126@printindex cp 10127 10128 10129 10130@summarycontents 10131@contents 10132@bye 10133