groff.texinfo revision 75584
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, } 4658Enable @dfn{no-space mode}. In this mode, spacing (either via 4659@code{sp} or via blank lines) is disabled. The @code{bp} request to 4660advance to the next page is also disabled, except if it is accompanied 4661by a page number (see @ref{Page Control}, for more information). This 4662mode ends when actual text is output or the @code{rs} request is 4663encountered. 4664 4665@cindex top-level diversion 4666@cindex diversion, top-level 4667This request is useful for macros which want to avoid that subsequent 4668macros inadvertently insert some vertical space before the text starts 4669(for example, to set up the first paragraph after a section header). It 4670has no effect if not called within the top-level diversion 4671(@pxref{Diversions}). 4672 4673@c XXX xref 4674@endDefreq 4675 4676@cindex top-level diversion 4677@cindex diversion, top-level 4678@Defreq {rs, } 4679Disable no-space mode. It has no effect if not called within the 4680top-level diversion (@pxref{Diversions}). 4681 4682@c XXX xref 4683@endDefreq 4684 4685 4686@c ===================================================================== 4687 4688@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 4689@section Tabs and Fields 4690@cindex tabs and fields 4691@cindex fields and tabs 4692 4693@cindex @acronym{EBCDIC} encoding of a tab 4694A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{ 4695}5) causes a horizontal movement to the next tab stop (much 4696like it did on a typewriter). 4697 4698@Defesc {\\t, , , } 4699This escape is a non-interpreted tab character. In copy mode 4700(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 4701@endDefesc 4702 4703@Defreq {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 4704@Defregx {.tabs} 4705Change tab stop positions. This request takes a series of tab 4706specifiers as arguments (optionally divided into two groups with the 4707letter @samp{T}) which indicate where each tab stop is to be 4708(overriding any previous settings). 4709 4710Tab stops can be specified absolutely, i.e., as the distance from the 4711left margin. For example, the following sets 6@w{ }tab stops every 4712one inch. 4713 4714@Example 4715.ta 1i 2i 3i 4i 5i 6i 4716@endExample 4717 4718Tab stops can also be specified using a leading @samp{+} 4719which means that the specified tab stop is set relative to 4720the previous tab stop. For example, the following is equivalent to the 4721previous example. 4722 4723@Example 4724.ta 1i +1i +1i +1i +1i +1i 4725@endExample 4726 4727@code{gtroff} supports an extended syntax to specify repeat values after 4728the @samp{T} mark (these values are always taken as relative) -- this is 4729the usual way to specify tabs set at equal intervals. The following is, 4730yet again, the same as the previous examples. It does even more since 4731it defines an infinite number of tab stops separated by one inch. 4732 4733@Example 4734.ta T 1i 4735@endExample 4736 4737Now we are ready to interpret the full syntax given at the beginning: 4738Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 4739tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 4740and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 4741@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 4742 4743Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 474420c 23c 28c 30c @dots{}}. 4745 4746The material in each tab column (i.e., the column between two tab stops) 4747may be justified to the right or left or centered in the column. This 4748is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 4749specifier. The default justification is @samp{L}. Example: 4750 4751@Example 4752.ta 1i 2iC 2iR 4753@endExample 4754 4755Some notes: 4756 4757@itemize @bullet 4758@item 4759The default unit of the @code{ta} request is @samp{m}. 4760 4761@item 4762A tab stop is converted into a non-breakable horizontal movement which 4763can be neither stretched nor squeezed. For example, 4764 4765@Example 4766.ds foo a\tb\tc 4767.ta T 5i 4768\*[foo] 4769@endExample 4770 4771@noindent 4772creates a single line which is a bit longer than 10@w{ }inches (a string 4773is used to show exactly where the tab characters are). Now consider the 4774following: 4775 4776@Example 4777.ds bar a\tb b\tc 4778.ta T 5i 4779\*[bar] 4780@endExample 4781 4782@noindent 4783@code{gtroff} first converts the tab stops of the line into unbreakable 4784horizontal movements, then splits the line after the second @samp{b} 4785(assuming a sufficiently short line length). Usually, this isn't what 4786the user wants. 4787 4788@item 4789Superfluous tabs (i.e., tab characters which do not correspond to a tab 4790stop) are ignored except the first one which delimits the characters 4791belonging to the last tab stop for right-justifying or centering. 4792Consider the following example 4793 4794@Example 4795.ds Z foo\tbar\tfoo 4796.ds ZZ foo\tbar\tfoobar 4797.ds ZZZ foo\tbar\tfoo\tbar 4798.ta 2i 4iR 4799\*[Z] 4800.br 4801\*[ZZ] 4802.br 4803\*[ZZZ] 4804.br 4805@endExample 4806 4807@noindent 4808which produces the following output: 4809 4810@Example 4811foo bar foo 4812foo bar foobar 4813foo bar foobar 4814@endExample 4815 4816@noindent 4817The first line right-justifies the second `foo' relative to the tab 4818stop. The second line right-justifies `foobar'. The third line finally 4819right-justifies only `foo' because of the additional tab character which 4820marks the end of the string belonging to the last defined tab stop. 4821 4822@item 4823Tab stops are associated with the current environment 4824(@pxref{Environments}). 4825 4826@item 4827Calling @code{ta} without an argument removes all tab stops. 4828 4829@item 4830@cindex tab stops, for tty output devices 4831The start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. This value 4832is used even for tty output devices (contrary to @acronym{UNIX} 4833@code{nroff} which has tab stops preset every 0.8@dmn{i}). 4834 4835@c XXX xref implementation differences 4836@end itemize 4837 4838@cindex current tab settings register 4839The read-only number register @code{.tabs} contains a string 4840representation of the current tab settings suitable for use as an 4841argument to the @code{ta} request. 4842 4843@Example 4844.ds tab-string \n[.tabs] 4845\*[tab-string] 4846 @result{} T120u 4847@endExample 4848@endDefreq 4849 4850@cindex tab repetition character 4851@cindex character, tab repetition 4852@Defreq {tc, [@Var{fill-char}]} 4853Normally @code{gtroff} fills the space to the next tab stop with 4854whitespace. This can be changed with the @code{tc} request. With no 4855argument @code{gtroff} reverts to using whitespace, which is the 4856default. The value of this @dfn{tab repetition} character is 4857associated with the current environment (@pxref{Environments}). 4858@endDefreq 4859 4860@menu 4861* Leaders:: 4862* Fields:: 4863@end menu 4864 4865@c --------------------------------------------------------------------- 4866 4867@node Leaders, Fields, Tabs and Fields, Tabs and Fields 4868@subsection Leaders 4869@cindex leaders 4870 4871Sometimes it may may be desirable to use the @code{tc} request to fill a 4872particular tab stop with a given character (for example dots in a table 4873of contents), but also normal tab stops on the rest of the line. For 4874this @code{gtroff} provides an alternate tab mechanism, called 4875@dfn{leaders} which does just that. 4876 4877@cindex leader character 4878A leader character (character code@w{ }1) behaves similarly to a tab 4879character: It moves to the next tab stop. The only difference is that 4880for this movement, the fill character defaults to a period character and 4881not to space. 4882 4883@Defesc {\\a, , , } 4884This escape is a non-interpreted leader character. In copy mode 4885(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 4886character. 4887@endDefesc 4888 4889@cindex leader repetition character 4890@cindex character, leader repetition 4891@Defreq {lc, [@Var{fill-char}]} 4892Declare the leader character. Without an argument, leaders act the 4893same as tabs (i.e., using whitespace for filling). @code{gtroff}'s 4894start-up value is @samp{.}. The value of this @dfn{leader repetition} 4895character is associated with the current environment 4896(@pxref{Environments}). 4897@endDefreq 4898 4899@cindex table of contents 4900@cindex contents, table of 4901For a table of contents, to name an example, tab stops may be defined so 4902that the section number is one tab stop, the title is the second with 4903the remaining space being filled with a line of dots, and then the page 4904number slightly separated from the dots. 4905 4906@Example 4907.ds entry 1.1\tFoo\a\t12 4908.lc . 4909.ta 1i 5i +.25i 4910\*[entry] 4911@endExample 4912 4913@noindent 4914This produces 4915 4916@Example 49171.1 Foo.......................................... 12 4918@endExample 4919 4920@c --------------------------------------------------------------------- 4921 4922@node Fields, , Leaders, Tabs and Fields 4923@subsection Fields 4924@cindex fields 4925 4926@cindex field delimiting character 4927@cindex delimiting character for fields 4928@cindex character, field delimiting 4929@cindex field padding character 4930@cindex padding character for fields 4931@cindex character, field padding 4932@dfn{Fields} are a more general way of laying out tabular data. A field 4933is defined as the data between a pair of @dfn{delimiting characters}. 4934It contains substrings which are separated by @dfn{padding characters}. 4935The width of a field is the distance on the @emph{input} line from the 4936position where the field starts to the next tab stop. A padding 4937character inserts stretchable space similar to @TeX{}'s @code{\hss} 4938command (thus it can even be negative) to make the sum of all substring 4939lengths plus the stretchable space equal to the field width. If more 4940than one padding character is inserted, the available space is evenly 4941distributed among them. 4942 4943@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 4944Define a delimiting and a padding character for fields. If the latter 4945is missing, the padding character defaults to a space character. If 4946there is no argument at all, the field mechanism is disabled (which is 4947the default). Note that contrary to e.g.@: the tab repetition 4948character, delimiting and padding characters are not associated to the 4949current environment (@pxref{Environments}). 4950 4951Example: 4952 4953@Example 4954.fc # ^ 4955.ta T 3i 4956#foo^bar^smurf# 4957.br 4958#foo^^bar^smurf# 4959@endExample 4960 4961@noindent 4962and here the result: 4963 4964@Example 4965foo bar smurf 4966foo bar smurf 4967@endExample 4968@endDefreq 4969 4970 4971@c ===================================================================== 4972 4973@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 4974@section Character Translations 4975@cindex character translations 4976@cindex translations of characters 4977 4978@rqindex . 4979@rqindex ' 4980@cindex control character 4981@cindex character, control 4982@cindex no-break control character 4983@cindex character, no-break control 4984@cindex control character, no-break 4985The control character (@samp{.}) and the no-break control character 4986(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 4987respectively. 4988 4989@Defreq {cc, [@Var{c}]} 4990Set the control character to @var{c}. With no argument the default 4991control character @samp{.} is restored. The value of the control 4992character is associated with the current environment 4993(@pxref{Environments}). 4994@endDefreq 4995 4996@Defreq {c2, [@Var{c}]} 4997Set the no-break control character to @var{c}. With no argument the 4998default control character @samp{'} is restored. The value of the 4999no-break control character is associated with the current environment 5000(@pxref{Environments}). 5001@endDefreq 5002 5003@esindex \\ 5004@Defreq {eo, } 5005Disable the escape mechanism completely. After executing this 5006request, the backslash character @samp{\} no longer starts an escape 5007sequence. 5008 5009This request can be very helpful in writing macros since it is not 5010necessary then to double the escape character. Here an example: 5011 5012@Example 5013.\" This is a simplified version of the 5014.\" .BR request from the man macro package 5015.eo 5016.de BR 5017. ds result \& 5018. while (\n[.$] >= 2) \@{\ 5019. as result \fB\$1\fR\$2 5020. shift 2 5021. \@} 5022. if \n[.$] .as result \fB\$1 5023\*[result] 5024. ft R 5025.. 5026.ec 5027@endExample 5028@endDefreq 5029 5030@cindex escape character 5031@cindex character, escape 5032@Defreq {ec, [@Var{c}]} 5033Set the escape character to @var{c}. With no argument the default 5034escape character @samp{\} is restored. It can be also used to 5035re-enable the escape mechanism after an @code{eo} request. 5036 5037Note that changing the escape character globally will likely break 5038macro packages since @code{gtroff} has no mechanism (like @TeX{}) to 5039`intern' macros, i.e., to convert a macro definition into an internal 5040form which is independent of its representation. If a macro is 5041called, it is executed literally. 5042@endDefreq 5043 5044@Defesc {\\e, , , } 5045This escape sequence prints the current escape character (which is the 5046backslash character @samp{\} by default). 5047@endDefesc 5048 5049A @dfn{translation} is a mapping of an input character to an output 5050character. The default mappings are given in the font definition files 5051for the specific output device (@pxref{Font Files}); all mappings (both 5052with @code{tr} and in the font definition files) occur at output time, 5053i.e., the input character gets assigned the metric information of the 5054mapped output character. 5055 5056@Defreq {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 5057Translate character @var{a} to @var{b}, character @var{c} to @var{d}, 5058etc. If there is an odd number of arguments, the last one is 5059translated to the space character. 5060 5061Some notes: 5062 5063@itemize @bullet 5064@item 5065@esindex \( 5066@esindex \[ 5067@esindex \' 5068@esindex \` 5069@esindex \- 5070@esindex \_ 5071@esindex \C 5072@esindex \N 5073@rqindex char 5074@cindex special character 5075@cindex character, special 5076@cindex numbered character 5077@cindex character, numbered 5078Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 5079@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 5080characters defined with the @code{char} request, and numbered characters 5081(@code{\N'@var{xxx}'}) can be translated also. 5082 5083@item 5084@esindex \e 5085The @code{\e} escape can be translated also. 5086 5087@item 5088@esindex \% 5089@esindex \~ 5090Characters can be mapped onto the @code{\%} and @code{\~} escapes (but 5091@code{\%} and @code{\~} can't be mapped onto another character). 5092 5093@item 5094@cindex backspace character 5095@cindex character, backspace 5096@cindex leader character 5097@cindex character, leader 5098@cindex newline character 5099@cindex character, newline 5100@cindex tab character 5101@cindex character, tab 5102@esindex \a 5103@esindex \t 5104The following characters can't be translated: space (with one exception, 5105see below), backspace, newline, leader (and @code{\a}), tab (and 5106@code{\t}). 5107 5108@item 5109@rqindex shc 5110Translations are not considered for finding the soft hyphen character 5111set with the @code{shc} request. 5112 5113@item 5114@esindex \& 5115The character pair @samp{@var{c}\&} (this is an arbitrary character@w{ 5116}@var{c} followed by the zero width space character) maps this 5117character to nothing. 5118 5119@Example 5120.tr a\& 5121foo bar 5122 @result{} foo br 5123@endExample 5124 5125@noindent 5126It is even possible to map the space character to nothing: 5127 5128@Example 5129.tr aa \& 5130foo bar 5131 @result{} foobar 5132@endExample 5133 5134@noindent 5135As shown in the example, the space character can't be the first 5136character pair as an argument of @code{tr}. Additionally, it is not 5137possible to map the space character to any other character; requests 5138like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 5139 5140If justification is active, lines are justified in spite of the 5141`empty' space character (but there is no minimal distance, i.e.@: the 5142space character, between words). 5143 5144@item 5145After an output character has been constructed (this happens at the 5146moment immediately before the character is appended to an output 5147character list, either by direct output, in a macro, diversion, or 5148string), it is no longer affected by @code{tr}. 5149 5150@c XXX xref 5151 5152@item 5153Without an argument, the @code{tr} request is ignored. 5154@end itemize 5155@endDefreq 5156 5157@esindex \! 5158@cindex @code{\!}, and @code{trnt} 5159@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 5160@code{trnt} is the same as the @code{tr} request except that the 5161translations do not apply to text that is transparently throughput 5162into a diversion with @code{\!}. @xref{Diversions}, for more 5163information. 5164 5165For example, 5166 5167@Example 5168.tr ab 5169.di x 5170\!.tm a 5171.di 5172.x 5173@endExample 5174 5175@noindent 5176prints @samp{b} to the standard error stream; if @code{trnt} is used 5177instead of @code{tr} it prints @samp{a}. 5178@endDefreq 5179 5180 5181@c ===================================================================== 5182 5183@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 5184@section Troff and Nroff Mode 5185@cindex troff mode 5186@cindex mode, troff 5187@cindex nroff mode 5188@cindex mode, nroff 5189 5190Originally, @code{nroff} and @code{troff} were two separate programs, 5191the former for tty output, the latter for everything else. With GNU 5192@code{troff}, both programs are merged into one executable, sending 5193its output to a device driver (@code{grotty} for tty devices, 5194@code{grops} for @sc{PostScript}, etc.) which interprets the 5195intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 5196it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 5197since the differences are hardcoded. For GNU @code{troff}, this 5198distinction is not appropriate because @code{gtroff} simply takes the 5199information given in the font files for a particular device without 5200handling requests specially if a tty output device is used. 5201 5202Usually, a macro package can be used with all output devices. 5203Nevertheless, it is sometimes necessary to make a distinction between 5204tty and non-tty devices: @code{gtroff} provides two built-in 5205conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 5206@code{while} requests to decide whether @code{gtroff} shall behave 5207like @code{nroff} or like @code{troff}. 5208 5209@pindex troffrc 5210@pindex troffrc-end 5211@Defreq {troff, } 5212Make the @samp{t} built-in condition true (and the @samp{n} built-in 5213condition false) for @code{if}, @code{ie}, and @code{while} 5214conditional requests. This is the default if @code{gtroff} 5215(@emph{not} @code{groff}) is started with the @option{-R} switch to 5216avoid loading of the start-up files @file{troffrc} and 5217@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 5218mode if the output device is not a tty (e.g.@: `ps'). 5219@endDefreq 5220 5221@pindex tty.tmac 5222@Defreq {nroff, } 5223Make the @samp{n} built-in condition true (and the @samp{t} built-in 5224condition false) for @code{if}, @code{ie}, and @code{while} 5225conditional requests. This is the default if @code{gtroff} uses a tty 5226output device; the code for switching to nroff mode is in the file 5227@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 5228@endDefreq 5229 5230@xref{Conditionals and Loops}, for more details on built-in 5231conditions. 5232 5233@c XXX move the following to grotty section 5234 5235@pindex less 5236@cindex Teletype 5237@cindex ISO 6249 SGR 5238@cindex terminal control sequences 5239@cindex control sequences, for terminals 5240For tty output devices, underlining is done by emitting sequences of 5241@samp{_} and @samp{\b} (the backspace character) before the actual 5242character. Literally, this is printing an underline character, then 5243moving back one character position, and printing the actual character 5244at the same position as the underline character (similar to a 5245typewriter). Usually, a modern terminal can't interpret this (and the 5246original Teletype machines for which this sequence was appropriate are 5247no longer in use). You need a pager program like @code{less} which 5248translates this into ISO 6429 SGR sequences to control terminals. 5249 5250@c ===================================================================== 5251 5252@node Line Layout, Page Layout, Troff and Nroff Mode, gtroff Reference 5253@section Line Layout 5254@cindex line layout 5255@cindex layout, line 5256 5257@cindex dimensions, line 5258@cindex line dimensions 5259The following drawing shows the dimensions which @code{gtroff} uses for 5260placing a line of output onto the page. They are labeled with the 5261request which manipulates each dimension. 5262 5263@Example 5264 -->| in |<-- 5265 |<-----------ll------------>| 5266 +----+----+----------------------+----+ 5267 | : : : | 5268 +----+----+----------------------+----+ 5269 -->| po |<-- 5270 |<--------paper width---------------->| 5271@endExample 5272 5273@noindent 5274These dimensions are: 5275 5276@ftable @code 5277@item po 5278@cindex left margin 5279@cindex margin, left 5280@cindex page offset 5281@cindex offset, page 5282@dfn{Page offset} -- this is the leftmost position of text on the final 5283output, defining the @dfn{left margin}. 5284 5285@item in 5286@cindex indentation 5287@cindex line indentation 5288@dfn{Indentation} -- this is the distance from the left margin where 5289text is printed. 5290 5291@item ll 5292@cindex line length 5293@cindex length of line 5294@dfn{Line length} -- this is the distance from the left margin to right 5295margin. 5296@end ftable 5297 5298@c XXX improve example 5299 5300@Example 5301.in +.5i 5302.ll -.5i 5303A bunch of really boring text which should 5304be indented from both margins. 5305Replace me with a better (and more) example! 5306.in -.5i 5307.ll +.5i 5308@endExample 5309 5310@pindex troffrc 5311@Defreq {po, [@Var{offset}]} 5312@Defreqx {po, @t{+}@Var{offset}} 5313@Defreqx {po, @t{-}@Var{offset}} 5314@Defregx {.o} 5315Set horizontal page offset to @var{offset} (or increment or decrement 5316the current value by @var{offset}). Note that this request does not 5317cause a break, so changing the page offset in the middle of text being 5318filled may not yield the expected result. The initial value is 53191@dmn{i}. For tty output devices, it is set to 0 in the startup file 5320@file{troffrc}; the default scaling indicator is@w{ }@code{m} (and 5321not@w{ }@code{v} as incorrectly documented in the original 5322@acronym{UNIX} troff manual). 5323 5324The current page offset can be found in the read-only number register 5325@samp{.o}. 5326 5327If @code{po} is called without an argument, the page offset is reset to 5328the previous value before the last call to @code{po}. 5329 5330@Example 5331.po 3i 5332\n[.o] 5333 @result{} 720 5334.po -1i 5335\n[.o] 5336 @result{} 480 5337.po 5338\n[.o] 5339 @result{} 720 5340@endExample 5341@endDefreq 5342 5343@Defreq {in, [@Var{indent}]} 5344@Defreqx {in, @t{+}@Var{indent}} 5345@Defreqx {in, @t{-}@Var{indent}} 5346@Defregx {.i} 5347Set indentation to @var{indent} (or increment or decrement the 5348current value by @var{indent}). This request causes a break. 5349Initially, there is no indentation. 5350 5351If @code{in} is called without an argument, the indentation is reset to 5352the previous value before the last call to @code{in}. The default 5353scaling indicator is@w{ }@code{m}. 5354 5355The indentation is associated with the current environment. 5356 5357If a negative indentation value is specified (which is not allowed), 5358@code{gtroff} emits a warning of type @samp{range} and sets the 5359indentation to zero. 5360 5361The effect of @code{in} is delayed until a partially collected line (if 5362it exists) is output. A temporary indent value is reset to zero also. 5363 5364The current indentation (as set by @code{in}) can be found in the 5365read-only number register @samp{.i}. 5366@endDefreq 5367 5368@Defreq {ti, offset} 5369@Defreqx {ti, @t{+}@Var{offset}} 5370@Defreqx {ti, @t{-}@Var{offset}} 5371@Defregx {.in} 5372Temporarily indent the next output line by @var{offset}. If an 5373increment or decrement value is specified, adjust the temporary 5374indentation relative to the value set by the @code{in} request. 5375 5376This request causes a break; its value is associated with the current 5377environment. The default scaling indicator is@w{ }@code{m}. A call 5378of @code{ti} without an argument is ignored. 5379 5380If the total indentation value is negative (which is not allowed), 5381@code{gtroff} emits a warning of type @samp{range} and sets the 5382temporary indentation to zero. `Total indentation' is either 5383@var{offset} if specified as an absolute value, or the temporary plus 5384normal indentation, if @var{offset} is given as a relative value. 5385 5386The effect of @code{ti} is delayed until a partially collected line (if 5387it exists) is output. 5388 5389The read-only number register @code{.in} is the indentation that applies 5390to the current output line. 5391 5392The difference between @code{.i} and @code{.in} is that the latter takes 5393into account whether a partially collected line still uses the old 5394indentation value or a temporary indentation value is active. 5395@endDefreq 5396 5397@Defreq {ll, [@Var{length}]} 5398@Defreqx {ll, @t{+}@Var{length}} 5399@Defreqx {ll, @t{-}@Var{length}} 5400@Defregx {.l} 5401@Defregx {.ll} 5402Set the line length to @var{length} (or increment or decrement the 5403current value by @var{length}). Initially, the line length is set to 54046.5@dmn{i}. The effect of @code{ll} is delayed until a partially 5405collected line (if it exists) is output. The default scaling 5406indicator is@w{ }@code{m}. 5407 5408If @code{ll} is called without an argument, the line length is reset to 5409the previous value before the last call to @code{ll}. If a negative 5410line length is specified (which is not allowed), @code{gtroff} emits a 5411warning of type @samp{range} and sets the line length to zero. 5412 5413The line length is associated with the current environment. 5414 5415@cindex current line length register 5416The current line length (as set by @code{ll}) can be found in the 5417read-only number register @samp{.l}. The read-only number register 5418@code{.ll} is the line length that applies to the current output line. 5419 5420Similar to @code{.i} and @code{.in}, the difference between @code{.l} 5421and @code{.ll} is that the latter takes into account whether a partially 5422collected line still uses the old line length value. 5423@endDefreq 5424 5425 5426@c ===================================================================== 5427 5428@node Page Layout, Page Control, Line Layout, gtroff Reference 5429@section Page Layout 5430@cindex page layout 5431@cindex layout, page 5432 5433@code{gtroff} provides some very primitive operations for controlling 5434page layout. 5435 5436@cindex page length 5437@cindex length of page 5438@Defreq {pl, [@Var{length}]} 5439@Defreqx {pl, @t{+}@Var{length}} 5440@Defreqx {pl, @t{-}@Var{length}} 5441@Defregx {.p} 5442Set the @dfn{page length} to @var{length} (or increment or decrement 5443the current value by @var{length}). This is the length of the 5444physical output page. The default scaling indicator is@w{ }@code{v}. 5445 5446@cindex current page length register 5447The current setting can be found in the read-only number register 5448@samp{.p}. 5449 5450@cindex top margin 5451@cindex margin, top 5452@cindex bottom margin 5453@cindex margin, bottom 5454Note that this only specifies the size of the page, not the top and 5455bottom margins. Those are not set by @code{gtroff} directly. 5456@xref{Traps}, for further information on how to do this. 5457 5458Negative @code{pl} values are possible also, but not very useful: No 5459trap is sprung, and each line is output on a single page (thus 5460suppressing all vertical spacing). 5461 5462If no argument or an invalid argument is given, @code{pl} sets the page 5463length to 11@dmn{i}. 5464@endDefreq 5465 5466@cindex headers 5467@cindex footers 5468@cindex titles 5469@code{gtroff} provides several operations which help in setting up top 5470and bottom titles (or headers and footers). 5471 5472@cindex title line 5473@cindex three-part title 5474@cindex page number character 5475@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 5476Print a @dfn{title line}. It consists of three parts: a left 5477justified portion, a centered portion, and a right justified portion. 5478The argument separator @samp{'} can be replaced with any character not 5479occurring in the title line. The @samp{%} character is replaced with 5480the current page number. This character can be changed with the 5481@code{pc} request (see below). 5482 5483Without argument, @code{tl} is ignored. 5484 5485Some notes: 5486 5487@itemize @bullet 5488@item 5489A title line is not restricted to the top or bottom of a page. 5490 5491@item 5492@code{tl} prints the title line immediately, ignoring a partially filled 5493line (which stays untouched). 5494 5495@item 5496It is not an error to omit closing delimiters. For example, 5497@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 5498title line with the left justified word @samp{foo}; the centered and 5499right justfied parts are empty. 5500 5501@item 5502Any modifications to the current environment within @code{tl} (e.g.@: 5503changing the font or font size) are undone after processing @code{tl}. 5504 5505@item 5506@code{tl} accepts the same parameter delimiting characters as the 5507@code{\A} escape; see @ref{Escapes}. 5508@end itemize 5509@endDefreq 5510 5511@cindex length of title line 5512@cindex title line, length 5513@cindex current title line length register 5514@Defreq {lt, [@Var{length}]} 5515@Defreqx {lt, @t{+}@Var{length}} 5516@Defreqx {lt, @t{-}@Var{length}} 5517@Defregx {.lt} 5518The title line is printed using its own line length, which is 5519specified (or incremented or decremented) with the @code{lt} request. 5520Initially, the title line length is set to 6.5@dmn{i}. If a negative 5521line length is specified (which is not allowed), @code{gtroff} emits a 5522warning of type @samp{range} and sets the title line length to zero. 5523The default scaling indicator is@w{ }@code{m}. If @code{lt} is called 5524without an argument, the title length is reset to the previous value 5525before the last call to @code{lt}. 5526 5527The current setting of this is available in the @code{.lt} read-only 5528number register; it is associated with the current environment 5529(@pxref{Environments}). 5530 5531@endDefreq 5532 5533@cindex page number 5534@cindex number, page 5535@Defreq {pn, page} 5536@Defreqx {pn, @t{+}@Var{page}} 5537@Defreqx {pn, @t{-}@Var{page}} 5538@Defregx {.pn} 5539Change (increase or decrease) the page number of the @emph{next} page. 5540The only argument is the page number; the request is ignored without a 5541parameter. 5542 5543The read-only number register @code{.pn} contains the number of the next 5544page: either the value set by a @code{pn} request, or the number of the 5545current page plus@w{ }1. 5546@endDefreq 5547 5548@cindex current page number register 5549@Defreg {%} 5550A read-write register holding the current page number. 5551@endDefreg 5552 5553@cindex changing the page number character 5554@cindex page number character, changing 5555@vindex % 5556@Defreq {pc, [@Var{char}]} 5557Change the page number character (used by the @code{tl} request) to a 5558different character. With no argument, this mechanism is disabled. 5559Note that this doesn't affect the number register @code{%}. 5560@endDefreq 5561 5562@xref{Traps}. 5563 5564 5565@c ===================================================================== 5566 5567@node Page Control, Fonts, Page Layout, gtroff Reference 5568@section Page Control 5569@cindex page control 5570@cindex control, page 5571 5572@rqindex pn 5573@cindex new page 5574@Defreq {bp, [@Var{page}]} 5575@Defreqx {bp, @t{+}@Var{page}} 5576@Defreqx {bp, @t{-}@Var{page}} 5577Stop processing the current page and move to the next page. This 5578request causes a break. It can also take an argument to set 5579(increase, decrease) the page number of the next page. The only 5580difference between @code{bp} and @code{pn} is that @code{pn} does not 5581cause a break or actually eject a page. 5582 5583@Example 5584.de newpage \" define macro 5585'bp \" begin page 5586'sp .5i \" vertical space 5587.tl 'left top'center top'right top' \" title 5588'sp .3i \" vertical space 5589.. \" end macro 5590@endExample 5591 5592@cindex top-level diversion 5593@cindex diversion, top-level 5594@code{bp} has no effect if not called within the top-level diversion 5595(@pxref{Diversions}). 5596@endDefreq 5597 5598@cindex orphan line 5599@Defreq {ne, [@Var{space}]} 5600It is often necessary to force a certain amount of space before a new 5601page occurs. This is most useful to make sure that there is not a 5602single @dfn{orphan} line left at the bottom of a page. The @code{ne} 5603request ensures that there is a certain distance, specified by the 5604first argument, before the next page is triggered (see @ref{Traps}, 5605for further information). The default unit for @code{ne} is @samp{v}; 5606the default value of @var{space} is@w{ }1@dmn{v} if no argument is 5607given. 5608 5609For example, to make sure that no fewer than 2@w{ }lines get orphaned, 5610do the following before each paragraph: 5611 5612@Example 5613.ne 2 5614text text text 5615@endExample 5616@endDefreq 5617 5618@rqindex os 5619@rqindex ne 5620@Defreq {sv, [@Var{space}]} 5621@code{sv} is similar to the @code{ne} request; it reserves the 5622specified amount of vertical space. If the desired amount of space 5623exists before the next trap (bottom page boundary), the space is 5624output immediately (ignoring a partial filled line which stays 5625untouched). If there is not enough space, it is stored for later 5626output via the @code{os} request. The default value is@w{ }1@dmn{v} 5627if no argument is given; the default unit is @samp{v}. 5628@endDefreq 5629 5630 5631@c ===================================================================== 5632 5633@node Fonts, Sizes, Page Control, gtroff Reference 5634@section Fonts 5635@cindex fonts 5636 5637@code{gtroff} can switch fonts at any point in the text. 5638 5639The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 5640These are Times Roman, Italic, Bold, and Bold Italic. For non-tty 5641devices, there is also at least one symbol font which contains various 5642special symbols (Greek, mathematics). 5643 5644@menu 5645* Changing Fonts:: 5646* Font Families:: 5647* Font Positions:: 5648* Using Symbols:: 5649* Special Fonts:: 5650* Artificial Fonts:: 5651* Ligatures and Kerning:: 5652@end menu 5653 5654@c --------------------------------------------------------------------- 5655 5656@node Changing Fonts, Font Families, Fonts, Fonts 5657@subsection Changing Fonts 5658@cindex changing fonts 5659@cindex fonts, changing 5660 5661@rqindex sty 5662@rqindex fam 5663@kindex styles 5664@kindex family 5665@pindex DESC 5666@Defreq {ft, [@Var{font}]} 5667@Defescx {\\f, , f, } 5668@Defescx {\\f, @lparen{}, fn, } 5669@Defescx {\\f, @lbrack{}, font, @rbrack} 5670The @code{ft} request and the @code{\f} escape change the current font 5671to @var{font} (one-character name @var{f}, two-character name 5672@var{fn}). 5673 5674If @var{font} is a style name (as set with the @code{sty} request or 5675with the @code{styles} command in the @file{DESC} file), use it within 5676the current font family (as set with the @code{fam} request or with 5677the @code{family} command in the @file{DESC} file). 5678 5679@cindex previous font 5680@cindex font, previous 5681With no argument or using @samp{P} as an argument, @code{.ft} switches 5682to the previous font. Use @code{\fP} or @code{\f[P]} to do this with 5683the escape. 5684 5685Fonts are generally specified as upper-case strings, which are usually 56861@w{ }to 4 characters representing an abbreviation or acronym of the 5687font name. This is no limitation, just a convention. 5688 5689The example below produces two identical lines. 5690 5691@Example 5692eggs, bacon, 5693.ft B 5694spam 5695.ft 5696and sausage. 5697 5698eggs, bacon, \fBspam\fP and sausage. 5699@endExample 5700 5701@xref{Font Positions}, for an alternative syntax. 5702@endDefreq 5703 5704@rqindex ft 5705@rqindex ul 5706@rqindex bd 5707@esindex \f 5708@rqindex cs 5709@rqindex tkf 5710@rqindex special 5711@rqindex fspecial 5712@rqindex fp 5713@rqindex code 5714@Defreq {ftr, f [@Var{g}]} 5715Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named 5716@var{f} is referred to in a @code{\f} escape sequence, or in the 5717@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 5718@code{special}, @code{fspecial}, @code{fp}, or @code{code} requests, 5719font@w{ }@var{g} is used. If @var{g} is missing or equal to @var{f} 5720the translation is undone. 5721@endDefreq 5722 5723@c --------------------------------------------------------------------- 5724 5725@node Font Families, Font Positions, Changing Fonts, Fonts 5726@subsection Font Families 5727@cindex font families 5728@cindex families, font 5729@cindex font styles 5730@cindex styles, font 5731 5732Due to the variety of fonts available, @code{gtroff} has added the 5733concept of @dfn{font families} and @dfn{font styles}. The fonts are 5734specified as the concatenation of the font family and style. Specifying 5735a font without the family part causes @code{gtroff} to use that style of 5736the current family. 5737 5738@cindex postscript fonts 5739@cindex fonts, postscript 5740Currently, only @sc{PostScript} fonts are set up to this mechanism. 5741By default, @code{gtroff} uses the Times family with the four styles 5742@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 5743 5744This way, it is possible to use the basic four fonts and to select a 5745different font family on the command line (@pxref{Groff Options}). 5746 5747@Defreq {fam, [@Var{family}]} 5748@Defregx {.fam} 5749Switch font family to @var{family}. If no argument is given, switch 5750back to the previous font family. The current font family is available 5751in the read-only number register @samp{.fam} (this is a string-valued 5752register); it is associated with the current environment. 5753 5754@Example 5755spam, 5756.fam H \" helvetica family 5757spam, \" used font is family H + style R = HR 5758.ft B \" family H + style B = font HB 5759spam, 5760.fam T \" times family 5761spam, \" used font is family T + style B = TB 5762.ft AR \" font AR (not a style) 5763baked beans, 5764.ft R \" family T + style R = font TR 5765and spam. 5766@endExample 5767@endDefreq 5768 5769@rqindex cs 5770@rqindex bd 5771@rqindex tkf 5772@rqindex uf 5773@rqindex fspecial 5774@Defreq {sty, n style} 5775Associate @var{style} with font position@w{ }@var{n}. A font position 5776can be associated either with a font or with a style. The current 5777font is the index of a font position and so is also either a font or a 5778style. When it is a style, the font that is actually used is the font 5779the name of which is the concatenation of the name of the current 5780family and the name of the current style. For example, if the current 5781font is@w{ }1 and font position@w{ }1 is associated with style@w{ 5782}@samp{R} and the current font family is@w{ }@samp{T}, then font 5783@samp{TR} will be used. If the current font is not a style, then the 5784current family is ignored. When the requests @code{cs}, @code{bd}, 5785@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, then 5786they will instead be applied to the member of the current family 5787corresponding to that style. 5788 5789@var{n} must be a non-negative integer value. 5790 5791@pindex DESC 5792@kindex styles 5793The default family can be set with the @option{-f} option 5794(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 5795file controls which font positions (if any) are initially associated 5796with styles rather than fonts. For example, the default setting for 5797@sc{PostScript} fonts 5798 5799@Example 5800styles R I B BI 5801@endExample 5802 5803@noindent 5804is equivalent to 5805 5806@Example 5807.sty 1 R 5808.sty 2 I 5809.sty 3 B 5810.sty 4 BI 5811@endExample 5812 5813@code{.fam} always checks whether the current font position is valid; 5814this can give surprising results if the current font position is 5815associated with a style. 5816 5817In the following example, we want to access the @sc{PostScript} font 5818@code{FooBar} from the font family @code{Foo}: 5819 5820@Example 5821.sty \n[.fp] Bar 5822.fam Foo 5823 @result{} warning: can't find font `FooR' 5824@endExample 5825 5826@noindent 5827The default font position at start-up is@w{ }1; for the 5828@sc{PostScript} device, this is associated with style @samp{R}, so 5829@code{gtroff} tries to open @code{FooR}. 5830 5831A solution to this problem is to use a dummy font like the following: 5832 5833@Example 5834.fp 0 dummy TR \" set up dummy font at position 0 5835.sty \n[.fp] Bar \" register style `Bar' 5836.ft 0 \" switch to font at position 0 5837.fam Foo \" activate family `Foo' 5838.ft Bar \" switch to font `FooBar' 5839@endExample 5840 5841@xref{Font Positions}. 5842@endDefreq 5843 5844@c --------------------------------------------------------------------- 5845 5846@node Font Positions, Using Symbols, Font Families, Fonts 5847@subsection Font Positions 5848@cindex font positions 5849@cindex positions, font 5850 5851For the sake of old phototypesetters and compatibility with old versions 5852of @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 5853on which various fonts are mounted. 5854 5855@Defreq {fp, pos font [@Var{external-name}]} 5856@Defregx {.f} 5857@Defregx {.fp} 5858Mount font @var{font} at position @var{pos} (which must be a 5859non-negative integer). This numeric position can then be referred to 5860with font changing commands. When @code{gtroff} starts it is using 5861font position@w{ }1 (which must exist; position@w{ }0 is unused 5862usually at start-up). 5863 5864@cindex current font position register 5865The current font in use, as a font position, is available in the 5866read-only number register @samp{.f}. This can be useful to remember the 5867current font for later recall. It is associated with the current 5868environment (@pxref{Environments}). 5869 5870@Example 5871.nr save-font \n[.f] 5872.ft B 5873... text text text ... 5874.ft \n[save-font] 5875@endExample 5876 5877@cindex next free font position register 5878The number of the next free font position is available in the read-only 5879number register @samp{.fp}. This is useful when mounting a new font, 5880like so: 5881 5882@Example 5883.fp \n[.fp] NEATOFONT 5884@endExample 5885 5886@pindex DESC@r{, and font mounting} 5887Fonts not listed in the @file{DESC} file are automatically mounted on 5888the next available font position when they are referenced. If a font 5889is to be mounted explicitly with the @code{fp} request on an unused 5890font position, it should be mounted on the first unused font position, 5891which can be found in the @code{.fp} register. Although @code{gtroff} 5892does not enforce this strictly, it is not allowed to mount a font at a 5893position whose number is much greater (approx.@: 1000 positions) than 5894that of any currently used position. 5895 5896The @code{fp} request has an optional third argument. This argument 5897gives the external name of the font, which is used for finding the font 5898description file. The second argument gives the internal name of the 5899font which is used to refer to the font in @code{gtroff} after it has 5900been mounted. If there is no third argument then the internal name is 5901used as the external name. This feature makes it possible to use 5902fonts with long names in compatibility mode. 5903@endDefreq 5904 5905Both the @code{ft} request and the @code{\f} escape have alternative 5906syntax forms to access font positions. 5907 5908@rqindex sty 5909@rqindex fam 5910@kindex styles 5911@kindex family 5912@pindex DESC 5913@Defreq {ft, nnn} 5914@Defescx {\\f, , n, } 5915@Defescx {\\f, @lparen{}, nn, } 5916@Defescx {\\f, @lbrack{}, nnn, @rbrack} 5917Change the current font position to @var{nnn} (one-digit position 5918@var{n}, two-digit position @var{nn}), which must be a non-negative 5919integer. 5920 5921If @var{nnn} is associated with a style (as set with the @code{sty} 5922request or with the @code{styles} command in the @file{DESC} file), use 5923it within the current font family (as set with the @code{fam} request or 5924with the @code{family} command in the @file{DESC} file). 5925 5926@Example 5927this is font 1 5928.ft 2 5929this is font 2 5930.ft \" switch back to font 1 5931.ft 3 5932this is font 3 5933.ft 5934this is font 1 again 5935@endExample 5936 5937@xref{Changing Fonts}, for the standard syntax form. 5938@endDefreq 5939 5940@c --------------------------------------------------------------------- 5941 5942@node Using Symbols, Special Fonts, Font Positions, Fonts 5943@subsection Using Symbols 5944@cindex using symbols 5945@cindex symbols, using 5946 5947@cindex glyph 5948@cindex character 5949@cindex ligature 5950A @dfn{glyph} is a graphical representation of a @dfn{character}. 5951While a character is an abstract entity containing semantic 5952information, a glyph is something which can be actually seen on screen 5953or paper. It is possible that a character has multiple glyph 5954representation forms (for example, the character `A' can be either 5955written in a roman or an italic font, yielding two different glyphs); 5956sometimes more than one character maps to a single glyph (this is a 5957@dfn{ligature} -- the most common is `fi'). 5958 5959@c XXX 5960 5961Please note that currently the distinction between glyphs and 5962characters in this reference is not clearly carried out. This will be 5963improved eventually in the next revision. 5964 5965@cindex symbol 5966@cindex special fonts 5967@kindex fonts 5968@pindex DESC 5969@rqindex fspecial 5970A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 5971glyph names of a particular font are defined in its font file. If the 5972user requests a glyph not available in this font, @code{gtroff} looks 5973up an ordered list of @dfn{special fonts}. By default, the 5974@sc{PostScript} output device supports the two special fonts @samp{SS} 5975(slanted symbols) and @samp{S} (symbols) (the former is looked up 5976before the latter). Other output devices use different names for 5977special fonts. Fonts mounted with the @code{fonts} keyword in the 5978@file{DESC} file are globally available. To install additional 5979special fonts locally (i.e.@: for a particular font), use the 5980@code{fspecial} request. 5981 5982@xref{Font Files}, and @ref{Special Fonts}, for more details. 5983 5984@Defesc {\\, @lparen{}, nm, } 5985@Defescx {\\, @lbrack{}, name, @rbrack} 5986Insert a symbol @var{name} (two-character name @var{nm}). There is no 5987special syntax for one-character names -- the natural form 5988@samp{\@var{n}} would collide with escapes. 5989 5990If @var{name} is undefined, a warning of type @samp{char} is generated, 5991and the escape is ignored. @xref{Debugging}, for information about 5992warnings. 5993 5994The list of available symbols is device dependent; see @ref{Glyph Name 5995Index} for some of them discussed in this reference. 5996 5997@c XXX list of common symbols 5998@endDefesc 5999 6000@Defesc {\\C, ', xxx, '} 6001Typeset the character named @var{xxx}. Normally it is more convenient 6002to use @code{\[@var{xxx}]}, but @code{\C} has the advantage that it is 6003compatible with newer versions of @code{ditroff} and is available in 6004compatibility mode. 6005@endDefesc 6006 6007@rqindex char 6008@cindex unicode 6009@Defesc {\\N, ', n, '} 6010Typeset the character with code@w{ }@var{n} in the current font (this 6011is @strong{not} the input character code). @var{n} can be any 6012integer. Most devices only have characters with codes between 0 6013and@w{ }255; the Unicode output device uses codes in the range 60140--65535. If the current font does not contain a character with that 6015code, special fonts are @emph{not} searched. The @code{\N} escape 6016sequence can be conveniently used in conjunction with the @code{char} 6017request: 6018 6019@Example 6020.char \[phone] \f[ZD]\N'37' 6021@endExample 6022 6023@noindent 6024@pindex DESC 6025@cindex unnamed characters 6026@cindex characters, unnamed 6027The code of each character is given in the fourth column in the font 6028description file after the @code{charset} command. It is possible to 6029include unnamed characters in the font description file by using a 6030name of @samp{---}; the @code{\N} escape sequence is the only way to 6031use these. 6032@endDefesc 6033 6034@c XXX should be `glyph', not `character' 6035 6036@cindex character properties 6037@cindex properties of characters 6038@Defreq {cflags, n c1 c2 @dots{}} 6039Each character has certain properties associated with it. These 6040properties can be modified with the @code{cflags} request. The first 6041argument is the the sum of the desired flags and the remaining 6042arguments are the characters to have those properties. It is possible 6043to omit the spaces between the characters. 6044 6045@table @code 6046@item 1 6047@cindex end of sentence characters 6048@cindex characters, end of sentence 6049the character ends sentences (initially characters @samp{.?!} have this 6050property) 6051 6052@item 2 6053@cindex hyphenating characters 6054@cindex characters, hyphenation 6055lines can be broken before the character (initially no characters have 6056this property) 6057 6058@item 4 6059@glindex hy 6060@glindex em 6061lines can be broken after the character (initially the characters 6062@samp{-\(hy\(em} have this property) 6063 6064@item 8 6065@cindex overlapping characters 6066@cindex characters, overlapping 6067@glindex ul 6068@glindex rn 6069@glindex ru 6070the character overlaps horizontally (initially the characters 6071@samp{\(ul\(rn\(ru} have this property) 6072 6073@item 16 6074@glindex br 6075the character overlaps vertically (initially character @samp{\(br} has 6076this property) 6077 6078@item 32 6079@cindex transparent characters 6080@cindex character, transparent 6081@cindex ' 6082@cindex " 6083@cindex ] 6084@cindex ) 6085@cindex * 6086@glindex dg 6087@glindex rq 6088an end of sentence character followed by any number of characters with 6089this property is treated as the end of a sentence if followed by a 6090newline or two spaces; in other words the character is 6091@dfn{transparent} for the purposes of end of sentence recognition -- 6092this is the same as having a zero space factor in @TeX{} (initially 6093characters @samp{"')]*\(dg\(rq} have this property). 6094@end table 6095@endDefreq 6096 6097@cindex defining characters 6098@cindex characters, defining 6099@cindex creating new characters 6100@cindex escape character 6101@cindex character, escape 6102@rqindex tr 6103@rqindex cp 6104@rqindex rc 6105@rqindex lc 6106@esindex \l 6107@esindex \L 6108@esindex \& 6109@esindex \e 6110@rqindex hcode 6111@Defreq {char, c [@Var{string}]} 6112Define a new character@w{ }@var{c} to be @var{string} (which can be 6113empty). Every time character@w{ }@var{c} needs to be printed, 6114@var{string} is processed in a temporary environment and the result is 6115wrapped up into a single object. Compatibility mode is turned off and 6116the escape character is set to @samp{\} while @var{string} is being 6117processed. Any emboldening, constant spacing or track kerning is 6118applied to this object rather than to individual characters in 6119@var{string}. A character defined by this request can be used just 6120like a normal character provided by the output device. In particular, 6121other characters can be translated to it with the @code{tr} request; 6122it can be made the leader character by the @code{lc} request; repeated 6123patterns can be drawn with the character using the @code{\l} and 6124@code{\L} escape sequences; words containing the character can be 6125hyphenated correctly, if the @code{hcode} request is used to give the 6126character a hyphenation code. There is a special anti-recursion 6127feature: Use of character within the character's definition is handled 6128like normal characters not defined with @code{char}. 6129@endDefreq 6130 6131@cindex removing character definition 6132@cindex character, removing definition 6133@Defreq {rchar, c1 c2 @dots{}} 6134Remove the definitions of characters @var{c1}, @var{c2},@w{ 6135}@enddots{} This undoes the effect of a @code{char} request. 6136 6137It is possible to omit the whitespace between arguments. 6138@endDefreq 6139 6140@xref{Special Characters}. 6141 6142@c --------------------------------------------------------------------- 6143 6144@node Special Fonts, Artificial Fonts, Using Symbols, Fonts 6145@subsection Special Fonts 6146@cindex special fonts 6147@cindex fonts, special 6148 6149@c XXX 6150 6151To be written. 6152 6153@c --------------------------------------------------------------------- 6154 6155@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts 6156@subsection Artificial Fonts 6157@cindex artificial fonts 6158@cindex fonts, artificial 6159 6160There are a number of requests for artificially creating fonts. These 6161are largely vestiges of the days when output devices did not have a 6162wide variety of fonts, and when @code{nroff} and @code{troff} were 6163separate programs. These are no longer necessary in GNU 6164@code{troff}. Nevertheless, they are supported. 6165 6166@cindex underlining 6167@Defreq {ul, [@Var{lines}]} 6168The @code{ul} request normally underlines subsequent lines if a tty 6169output device is used. Otherwise, the lines are printed in italics 6170(only the term `underlined' is used in the following). The single 6171argument is the number of input lines to be underlined; with no 6172argument, the next line is underlined. If @var{lines} is zero or 6173negative, stop the effects of @code{ul} (if it was active). Requests 6174and empty lines do not count for computing the number of underlined 6175input lines, even if they produce some output like @code{tl}. Lines 6176inserted by macros (e.g.@: invoked by a trap) do count. 6177 6178At the beginning of @code{ul}, the current font is stored and the 6179underline font is activated. Within the span of a @code{ul} request, 6180it is possible to change fonts, but after the last line affected by 6181@code{ul} the saved font is restored. 6182 6183@cindex underline font 6184@cindex font, for underlining 6185@rqindex uf 6186This command is associated with the current environment. The 6187underline font can be changed with the @code{uf} request. 6188 6189@c XXX @xref should be changed to grotty 6190 6191@xref{Troff and Nroff Mode}, for a discussion how underlining is 6192implemented in for tty output devices, and which problems can arise. 6193 6194The @code{ul} request does not underline spaces. 6195@endDefreq 6196 6197@cindex continuous underlining 6198@cindex underlining, continuous 6199@Defreq {cu, [@Var{lines}]} 6200The @code{cu} request is similar to @code{ul} but underlines spaces as 6201well (if a tty output device is used). 6202@endDefreq 6203 6204@cindex underline font 6205@cindex font for underlining 6206@rqindex ul 6207@rqindex cu 6208@Defreq {uf, font} 6209Set the underline font (globally) used by @code{ul} and @code{cu}. By 6210default, this is the font at position@w{ }2. @var{font} can be either 6211a non-negative font position or the name of a font. 6212@endDefreq 6213 6214@cindex imitating bold face 6215@cindex bold face, imitating 6216@Defreq {bd, font [@Var{offset}]} 6217@Defreqx {bd, font1 font2 [@Var{offset}]} 6218@Defregx {.b} 6219Artificially create a bold font by printing each character twice, 6220slightly offset. 6221 6222Two syntax forms are available. 6223 6224@itemize @bullet 6225@item 6226Imitate a bold font unconditionally. The first argument specifies the 6227font to embolden, and the second is the number of basic units, minus 6228one, by which the two characters is offset. If the second argument is 6229missing, emboldening is turned off. 6230 6231@var{font} can be either a non-negative font position or the name of a 6232font. 6233 6234@var{offset} is available in the @code{.b} read-only register if a 6235special font is active; in the @code{bd} request, its default unit is 6236@samp{u}. 6237 6238@rqindex fspecial 6239@kindex special 6240@cindex embolding of special fonts 6241@cindex special fonts, emboldening 6242@item 6243Imitate a bold form conditionally. Embolden @var{font1} by 6244@var{offset} only if font @var{font2} is the current font. This 6245command can be issued repeatedly to set up different emboldening 6246values for different current fonts. If the second argument is 6247missing, emboldening is turned off for this particular current font. 6248 6249This affects special fonts only (either set up with the @code{special} 6250command in font files or with the @code{fspecial} request). 6251@end itemize 6252@endDefreq 6253 6254@cindex constant character space mode 6255@cindex mode for constant character space 6256@cindex character, constant space 6257@rqindex ps 6258@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 6259Switch to and from constant character space mode. If activated, the 6260width of every character is @math{@var{width}/36} ems. The em size is 6261given absolutely by @var{em-size}; if this argument is missing, the em 6262value is taken from the current font size (as set with the @code{ps} 6263request) when the font is effectively in use. Without second and 6264third argument, constant character space mode is deactivated. 6265 6266Default unit for @var{em-size} is @samp{z}; @var{width} is an integer. 6267@endDefreq 6268 6269@c --------------------------------------------------------------------- 6270 6271@node Ligatures and Kerning, , Artificial Fonts, Fonts 6272@subsection Ligatures and Kerning 6273@cindex ligatures and kerning 6274@cindex kerning and ligatures 6275 6276Ligatures are groups of characters that are run together. For 6277example, the letters `f' and `i' can form a ligature `fi' as in the 6278word `file'. This produces a cleaner look (albeit subtle) to the 6279printed output. Usually, ligatures are not available in fonts for tty 6280output devices. 6281 6282Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 6283typesetter that was the target of AT&T @code{troff} also supported 6284`ff', `ffi', and `ffl' ligatures. Advanced typesetters or `expert' 6285fonts may include ligatures for `ft' and `ct', although GNU 6286@code{troff} does not support these (yet). 6287 6288@cindex ligatures enabled register 6289@Defreq {lg, [@Var{flag}]} 6290@Defregx {.lg} 6291The ligature mechanism can be switched on or off with the @code{lg} 6292request; if the parameter is non-zero or missing, ligatures are 6293enabled, otherwise disabled. Default is on. The current ligature 6294mode can be found in the read-only number register @code{.lg} (set to 62951 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise). 6296 6297Setting the ligature mode to@w{ }2 enables the two-character ligatures 6298(fi, fl, and ff) and disables the three-character ligatures (ffi and 6299ffl). 6300@endDefreq 6301 6302@dfn{Pairwise kerning} is another subtle typesetting mechanism that 6303modifies the distance between a character pair to improve readability. 6304In most cases (but not always) the distance is decreased. 6305@ifnotinfo 6306For example, compare the combination of the letters `V' and `A'. With 6307kerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 6308@end ifnotinfo 6309Typewriter-like fonts and fonts for terminals where all characters 6310have the same width don't use kerning. 6311 6312@cindex kerning enabled register 6313@Defreq {kern, [@Var{flag}]} 6314@Defregx {.kern} 6315Kerning can be activated with the @code{kern} request. If the 6316parameter is non-zero or missing, enable pairwise kerning, otherwise 6317disable it. The read-only number register @code{.kern} is set to@w{ 6318}1 if pairwise kerning is enabled, 0@w{ }otherwise. 6319 6320@cindex zero width space character 6321@cindex character, zero width space 6322@cindex space character, zero width 6323If the font description file contains pairwise kerning information, 6324characters from that font are kerned. Kerning between two characters 6325can be inhibited by placing @code{\&} between them: @samp{V\&A}. 6326 6327@xref{Font File Format}. 6328@endDefreq 6329 6330@cindex track kerning 6331@cindex kerning, track 6332@dfn{Track kerning} expands or reduces the space between characters. 6333This can be handy, for example, if you need to squeeze a long word 6334onto a single line or spread some text to fill a narrow column. It 6335must be used with great care since it is usually considered bad 6336typography if the reader notices the effect. 6337 6338@Defreq {tkf, f s1 n1 s2 n2} 6339Enable track kerning for font@w{ }@var{f}. If the current font is@w{ 6340}@var{f} the width of every character is increased by an amount 6341between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 6342the current point size is less than or equal to @var{s1} the width is 6343increased by @var{n1}; if it is greater than or equal to @var{s2} the 6344width is increased by @var{n2}; if the point size is greater than or 6345equal to @var{s1} and less than or equal to @var{s2} the increase in 6346width is a linear function of the point size. 6347 6348The default unit is @samp{z} for @var{s1} and @var{s2}, @samp{p} for 6349@var{n1} and @var{n2}. 6350@endDefreq 6351 6352Sometimes, when typesetting letters of different fonts, more or less 6353space at such boundaries are needed. There are two escapes to help 6354with this. 6355 6356@cindex italic correction 6357@cindex correction, italic 6358@cindex correction between italic and roman character 6359@cindex roman character, correction after italic character 6360@cindex italic character, correction before roman character 6361@Defesc {\\/, , , } 6362Increase the width of the preceding character so that the spacing 6363between that character and the following character is correct if the 6364following character is a roman character. For example, if an 6365italic@w{ }@code{f} is immediately followed by a roman right 6366parenthesis, then in many fonts the top right portion of the @code{f} 6367overlaps the top left of the right parenthesis. Use this escape 6368sequence whenever an italic character is immediately followed by a 6369roman character without any intervening space. This small amount of 6370space is also called @dfn{italic correction}. 6371 6372@iftex 6373@example 6374@group 6375\f[I]f\f[R]) 6376 @result{} {@it f}@r{)} 6377\f[I]f\/\f[R]) 6378 @result{} @i{f}@r{)} 6379@end group 6380@end example 6381@end iftex 6382@endDefesc 6383 6384@cindex left italic correction 6385@cindex correction, left italic 6386@cindex roman character, correction before italic character 6387@cindex italic character, correction after roman character 6388@Defesc {\\\,, , , } 6389Modify the spacing of the following character so that the spacing 6390between that character and the preceding character is correct if the 6391preceding character is a roman character. Use this escape sequence 6392whenever a roman character is immediately followed by an italic 6393character without any intervening space. In analogy to above, this 6394space could be called @dfn{left italic correction}, but this term 6395isn't used widely. 6396 6397@iftex 6398@example 6399@group 6400q\f[I]f 6401 @result{} @r{q}@i{f} 6402q\,\f[I]f 6403 @result{} @r{q}@math{@ptexcomma}@i{f} 6404@end group 6405@end example 6406@end iftex 6407@endDefesc 6408 6409@Defesc {\\&, , , } 6410Insert a zero-width character, which is invisible. Its intended use 6411is to stop interaction of a character with its surrounding. 6412 6413@itemize @bullet 6414@item 6415It prevents the insertion of extra space after an end of sentence 6416character. 6417 6418@Example 6419Test. 6420Test. 6421 @result{} Test. Test. 6422Test.\& 6423Test. 6424 @result{} Test. Test. 6425@endExample 6426 6427@item 6428It prevents interpretation of a control character at the beginning of 6429an input line. 6430 6431@Example 6432.Test 6433 @result{} warning: `Test' not defined 6434\&.Test 6435 @result{} .Test 6436@endExample 6437 6438@item 6439It prevents kerning between two characters. 6440 6441@ifnotinfo 6442@example 6443@group 6444VA 6445 @result{} @r{VA} 6446V\&A 6447 @result{} @r{V@w{}A} 6448@end group 6449@end example 6450@end ifnotinfo 6451 6452@item 6453It is needed to map an arbitrary character to nothing in the @code{tr} 6454request (@pxref{Character Translations}). 6455@end itemize 6456@endDefesc 6457 6458 6459@c ===================================================================== 6460 6461@node Sizes, Strings, Fonts, gtroff Reference 6462@section Sizes 6463@cindex sizes 6464 6465@cindex baseline 6466@cindex type size 6467@cindex size of type 6468@cindex vertical spacing 6469@cindex spacing, vertical 6470@code{gtroff} uses two dimensions with each line of text, type size 6471and vertical spacing. The @dfn{type size} is approximately the height 6472of the tallest character.@footnote{This is usually the parenthesis. 6473Note that in most cases the real dimensions of the glyphs in a font 6474are @emph{not} related to its type size! For example, the standard 6475@sc{PostScript} font families `Times Roman', `Helvetica', and 6476`Courier' can't be used together at 10@dmn{pt}; to get acceptable 6477output, the size of `Helvetica' has to be reduced by one point, and 6478the size of `Courier' must be increased by one point.} @dfn{Vertical 6479spacing} is the amount of space @code{gtroff} allows for a line of 6480text; normally, this is about 20%@w{ }larger than the current type 6481size. Ratios smaller than this can result in hard-to-read text; 6482larger than this, it spreads the text out more vertically (useful for 6483term papers). By default, @code{gtroff} uses 10@w{ }point type on 648412@w{ }point spacing. 6485 6486@cindex leading 6487The difference between type size and vertical spacing is known, by 6488typesetters, as @dfn{leading}. 6489 6490@menu 6491* Changing Type Sizes:: 6492* Fractional Type Sizes:: 6493@end menu 6494 6495@c --------------------------------------------------------------------- 6496 6497@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 6498@subsection Changing Type Sizes 6499@cindex changing type sizes 6500@cindex type sizes, changing 6501 6502@Defreq {ps, [@Var{size}]} 6503@Defreqx {ps, @t{+}@Var{size}} 6504@Defreqx {ps, @t{-}@Var{size}} 6505@Defescx {\\s, , size, } 6506@Defregx {.s} 6507Use the @code{ps} request or the @code{\s} escape to change (increase, 6508decrease) the type size (in points). Specify @var{size} as either an 6509absolute point size, or as a relative change from the current size. 6510The size@w{ }0, or no argument, goes back to the previous size. 6511 6512Default unit of @code{size} is @samp{z}. If @code{size} is zero or 6513negative, it is set to 1@dmn{u}. 6514 6515The read-only number register @code{.s} returns the point size in 6516points as a decimal fraction. This is a string. To get the point 6517size in scaled points, use the @code{.ps} register instead. 6518 6519@code{.s} is associated with the current environment 6520(@pxref{Environments}). 6521 6522@Example 6523snap, snap, 6524.ps +2 6525grin, grin, 6526.ps +2 6527wink, wink, \s+2nudge, nudge,\s+8 say no more! 6528.ps 10 6529@endExample 6530 6531The @code{\s} escape may be called in a variety of ways. Much like 6532other escapes there must be a way to determine where the argument ends 6533and the text begins. Any of the following forms are valid: 6534 6535@table @code 6536@item \s@var{n} 6537Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 65380 or in the range 4 to@w{ }39. 6539 6540@item \s+@var{n} 6541@itemx \s-@var{n} 6542Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{ 6543}must be exactly one digit. 6544 6545@item \s(@var{nn} 6546Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly 6547two digits. 6548 6549@item \s+(@var{nn} 6550@itemx \s-(@var{nn} 6551@itemx \s(+@var{nn} 6552@itemx \s(-@var{nn} 6553Increase or decrease the point size by @var{nn}@w{ }points. @var{nn} 6554must be exactly two digits. 6555@end table 6556 6557@xref{Fractional Type Sizes}, for yet another syntactical form of 6558using the @code{\s} escape. 6559 6560Some devices may only have certain permissible sizes, in which case 6561@code{gtroff} rounds to the nearest permissible size. 6562@endDefreq 6563 6564@cindex current type size register 6565@cindex current vertical spacing register 6566@Defreq {vs, [@Var{space}]} 6567@Defreqx {vs, @t{+}@Var{space}} 6568@Defreqx {vs, @t{-}@Var{space}} 6569@Defregx {.v} 6570Change (increase, decrease) the vertical spacing by @var{space}. The 6571default unit is @samp{p}. 6572 6573If @code{vs} is called without an argument, the vertical spacing is 6574reset to the previous value before the last call to @code{vs}. 6575 6576@vindex .V 6577@code{gtroff} creates a warning of type @samp{range} if @var{space} is 6578zero or negative; the vertical spacing is then set to the vertical 6579resolution (as given in the @code{.V} register). 6580 6581The read-only number register @code{.v} contains the current vertical 6582spacing; it is associated with the current environment 6583(@pxref{Environments}). 6584@endDefreq 6585 6586@c XXX example 6587 6588@ignore 6589@Example 6590... .sz macro example?? ... 6591@endExample 6592@end ignore 6593 6594@c --------------------------------------------------------------------- 6595 6596@node Fractional Type Sizes, , Changing Type Sizes, Sizes 6597@subsection Fractional Type Sizes 6598@cindex fractional type sizes 6599@cindex type sizes, fractional 6600 6601@cindex @code{s} unit 6602@cindex unit, @code{s} 6603@cindex @code{z} unit 6604@cindex unit, @code{z} 6605@rqindex ps 6606@rqindex cs 6607@rqindex tkf 6608@esindex \H 6609@esindex \s 6610A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 6611where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by 6612default). There is a new scale indicator @samp{z} which has the 6613effect of multiplying by @var{sizescale}. Requests and escape 6614sequences in @code{gtroff} interpret arguments that represent a point 6615size as being in units of scaled points, but they evaluate each such 6616argument using a default scale indicator of @samp{z}. Arguments 6617treated in this way are the argument to the @code{ps} request, the 6618third argument to the @code{cs} request, the second and fourth 6619arguments to the @code{tkf} request, the argument to the @code{\H} 6620escape sequence, and those variants of the @code{\s} escape sequence 6621that take a numeric expression as their argument (see below). 6622 6623For example, suppose @var{sizescale} is@w{ }1000; then a scaled point 6624is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 6625equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 662610250@w{ }scaled points, which is equal to 10.25@w{ }points. 6627 6628@code{gtroff} disallows the use of the @samp{z} scale indicator in 6629instances where it would make no sense, such as a numeric 6630expression whose default scale indicator was neither @samp{u} nor 6631@samp{z}. Similarly it would make 6632no sense to use a scaling indicator other than @samp{z} or @samp{u} in a 6633numeric expression whose default scale indicator was @samp{z}, and so 6634@code{gtroff} disallows this as well. 6635 6636There is also new scale indicator @samp{s} which multiplies by the 6637number of units in a scaled point. So, for example, @samp{\n[.ps]s} is 6638equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 6639scale indicators. 6640 6641@vindex .s 6642@Defreg {.ps} 6643A read-only number register returning the point size in scaled points. 6644 6645@code{.ps} is associated with the current environment 6646(@pxref{Environments}). 6647@endDefreg 6648 6649@cindex last-requested point size register 6650@cindex point size, last-requested 6651@vindex .ps 6652@vindex .s 6653@Defreg {.psr} 6654@Defregx {.sr} 6655The last-requested point size in scaled points is contained in the 6656@code{.psr} read-only number register. The last requested point size 6657in points as a decimal fraction can be found in @code{.sr}. This is a 6658string-valued read-only number register. 6659 6660Note that the requested point sizes are device-independent, whereas 6661the values returned by the @code{.ps} and @code{.s} registers are not. 6662For example, if a point size of 11@dmn{pt} is requested for a DVI 6663device, 10.95@dmn{pt} are actually used (as specified in the 6664@file{DESC} file). 6665 6666Both registers are associated with the current environment 6667(@pxref{Environments}). 6668@endDefreg 6669 6670The @code{\s} escape has the following syntax for working with 6671fractional type sizes: 6672 6673@table @code 6674@item \s[@var{n}] 6675@itemx \s'@var{n}' 6676Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric 6677expression with a default scale indicator of @samp{z}. 6678 6679@item \s[+@var{n}] 6680@itemx \s[-@var{n}] 6681@itemx \s+[@var{n}] 6682@itemx \s-[@var{n}] 6683@itemx \s'+@var{n}' 6684@itemx \s'-@var{n}' 6685@itemx \s+'@var{n}' 6686@itemx \s-'@var{n}' 6687Increase or or decrease the point size by @var{n} scaled points; 6688@var{n} is a numeric expression with a default scale indicator of 6689@samp{z}. 6690@end table 6691 6692@xref{Font Files}. 6693 6694 6695@c ===================================================================== 6696 6697@node Strings, Conditionals and Loops, Sizes, gtroff Reference 6698@section Strings 6699@cindex strings 6700 6701@code{gtroff} has string variables, which are entirely for user 6702convenience (i.e.@: there are no built-in strings exept @code{.T}, but 6703even this is a read-write string variable). 6704 6705@cindex string interpolation 6706@cindex string expansion 6707@cindex interpolation of strings 6708@cindex expansion of strings 6709@Defreq {ds, name [@Var{string}]} 6710@Defescx {\\*, , n, } 6711@Defescx {\\*, @lparen{}, nm, } 6712@Defescx {\\*, @lbrack{}, name, @rbrack{}} 6713Define and access a string variable @var{name} (one-character name 6714@var{n}, two-character name @var{nm}). If @var{name} already exists, 6715@code{ds} overwrites the previous definition. 6716 6717Example: 6718 6719@Example 6720.ds UX \s-1UNIX\s0\u\s-3tm\s0\d 6721. 6722The \*(UX Operating System 6723@endExample 6724 6725The @code{\*} escape @dfn{interpolates} (expands in-place) a 6726previously-defined string variable. To be more precise, the stored 6727string is pushed onto the input stack which is then parsed by 6728@code{gtroff}. Similar to number registers, it is possible to nest 6729strings, i.e. a string variables can be called within string 6730variables. 6731 6732If the string named by the @code{\*} does not exist, it is defined as 6733empty, and a warning of type @samp{mac} is emitted (see 6734@ref{Debugging}, for more details). 6735 6736@cindex comments, with @code{ds} 6737@strong{Caution:} Unlike other requests, the second argument to the 6738@code{ds} request takes up the entire line including trailing spaces. 6739This means that comments on a line with such a request can introduce 6740unwanted space into a string. 6741 6742@Example 6743.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 6744@endExample 6745 6746@noindent 6747Instead the comment should be put on another line or have the comment 6748escape adjacent with the end of the string. 6749 6750@Example 6751.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 6752@endExample 6753 6754@cindex trailing quotes 6755@cindex quotes, trailing 6756@cindex leading spaces with @code{ds} 6757@cindex spaces with @code{ds} 6758To produce leading space the string can be started with a double 6759quote. No trailing quote is needed; in fact, any trailing quote is 6760included in your string. 6761 6762@Example 6763.ds sign " Yours in a white wine sauce, 6764@endExample 6765 6766@esindex \@key{RET} 6767@cindex multi-line strings 6768@cindex strings, multi-line 6769@cindex newline character in strings, escaping 6770@cindex escaping newline characters in strings 6771Strings are not limited to a single line of text. A string can span 6772several lines by escaping the newlines with a backslash. The 6773resulting string is stored @emph{without} the newlines. 6774 6775@Example 6776.ds foo lots and lots \ 6777of text are on these \ 6778next several lines 6779@endExample 6780 6781It is not possible to have real newlines in a string. 6782 6783@cindex name space of macros and strings 6784@cindex macros, shared name space with strings 6785@cindex strings, shared name space with macros 6786Strings, macros, and diversions (and boxes) share the same name space. 6787Internally, even the same mechanism is used to store them. This has 6788some interesting consequences. For example, it is possible to call a 6789macro with string syntax and vice versa. 6790 6791@Example 6792.de xxx 6793a funny test. 6794.. 6795This is \*[xxx] 6796 @result{} This is a funny test. 6797 6798.ds yyy a funny test 6799This is 6800.yyy 6801 @result{} This is a funny test. 6802@endExample 6803 6804Diversions and boxes can be also called with string syntax. It is not 6805possible to pass arguments to a macro if called with @code{\*}. 6806 6807Another consequence is that you can copy one-line diversions or boxes 6808to a string. 6809 6810@Example 6811.di xxx 6812a \fItest\fR 6813.br 6814.di 6815.ds yyy This is \*[xxx]\c 6816\*[yyy]. 6817 @result{} @r{This is a }@i{test}. 6818@endExample 6819 6820@noindent 6821As the previous example shows, it is possible to store formatted 6822output in strings. The @code{\c} escape prevents the insertion of an 6823additional blank line in the output. 6824 6825Copying diversions longer than a single output line produces 6826unexpected results. 6827 6828@Example 6829.di xxx 6830a funny 6831.br 6832test 6833.br 6834.di 6835.ds yyy This is \*[xxx]\c 6836\*[yyy]. 6837 @result{} test This is a funny. 6838@endExample 6839 6840Usually, it is not predictable whether a diversion contains one or 6841more output lines, so this mechanism should be avoided. With 6842@acronym{UNIX} @code{troff}, this was the only solution to strip off a 6843final newline from a diversion. Another disadvantage is that the 6844spaces in the copied string are already formatted, making them 6845unstretchable. This can cause ugly results. 6846 6847@rqindex chop 6848@rqindex unformat 6849A clean solution to this problem is available in GNU @code{troff}, 6850using the requests @code{chop} to remove the final newline of a 6851diversion, and @code{unformat} to make the horizontal spaces 6852stretchable again. 6853 6854@Example 6855.box xxx 6856a funny 6857.br 6858test 6859.br 6860.box 6861.chop xxx 6862.unformat xxx 6863This is \*[xxx]. 6864 @result{} This is a funny test. 6865@endExample 6866 6867@xref{Gtroff Internals}, for more information. 6868@endDefreq 6869 6870@cindex appending to strings 6871@cindex strings, appending 6872@Defreq {as, name [@Var{string}]} 6873The @code{as} request is similar to @code{ds} but appends @var{string} 6874to the string stored as @var{name} instead of redefining it. If 6875@var{name} doesn't exist yet, it is created. 6876 6877@Example 6878.as sign " with shallots, onions and garlic, 6879@endExample 6880@endDefreq 6881 6882Rudimentary string manipulation routines are given with the next two 6883requests. 6884 6885@cindex substring 6886@Defreq {substring, str n1 [@Var{n2}]} 6887Replace the string in register@w{ }@var{str} with the substring 6888defined by the indices @var{n1} and@w{ }@var{n2}. The first character 6889in the string has index one. If @var{n2} is omitted, it is taken to 6890be equal to the string's length. If the index value @var{n1} or 6891@var{n2} is negative or zero, it is counted from the end of the 6892string, going backwards: The last character has index@w{ }0, the 6893character before the last character has index@w{ }@minus{}1, etc. 6894 6895@Example 6896.ds xxx abcdefgh 6897.substring xxx 2 -3 6898\*[xxx] 6899 @result{} bcde 6900@endExample 6901@endDefreq 6902 6903@cindex length of a string 6904@cindex string, length of 6905@Defreq {length, reg str} 6906Compute the length of @var{str} and returns it in the number 6907register@w{ }@var{reg}. If @var{reg} doesn't exist, it is created. 6908 6909@Example 6910.ds xxx abcdefgh 6911.length yyy xxx 6912\n[yyy] 6913 @result{} 8 6914@endExample 6915@endDefreq 6916 6917@cindex rename request 6918@cindex rename macro 6919@cindex rename string 6920@Defreq {rn, xx yy} 6921Rename the request, macro, or string @var{xx} to @var{yy}. 6922@endDefreq 6923 6924@cindex remove request 6925@cindex remove macro 6926@cindex remove string 6927@Defreq {rm, xx} 6928Remove the request, macro, or string @var{xx}. @code{gtroff} treats 6929subsequent invocations as if the object had never been defined. 6930@endDefreq 6931 6932@cindex alias 6933@Defreq {als, new old} 6934Create an alias named @var{new} for the request, string, macro, or 6935diversion object named @var{old}. The new name and the old name are 6936exactly equivalent (it is similar to a hard rather than a soft 6937link). If @var{old} is undefined, @code{gtroff} generates a warning of 6938type @samp{mac} and ignores the request. 6939@endDefreq 6940 6941@Defreq {chop, xx} 6942Remove (chop) the last character from the macro, string, or diversion 6943named @var{xx}. This is useful for removing the newline from the end 6944of diversions that are to be interpolated as strings. This command 6945can be used repeatedly; see @ref{Gtroff Internals}, for details on 6946nodes inserted by @code{gtroff} automatically. 6947@endDefreq 6948 6949@xref{Identifiers}, and @ref{Comments}. 6950 6951 6952@c ===================================================================== 6953 6954@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 6955@section Conditionals and Loops 6956@cindex conditionals and loops 6957@cindex loops and conditionals 6958 6959@menu 6960* Operators in Conditionals:: 6961* if-else:: 6962* while:: 6963@end menu 6964 6965@c --------------------------------------------------------------------- 6966 6967@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 6968@subsection Operators in Conditionals 6969 6970@rqindex if 6971@rqindex while 6972@cindex @code{if}, operators to use with it 6973@cindex @code{while}, operators to use with it 6974In @code{if} and @code{while} requests, there are several more 6975operators available: 6976 6977@table @code 6978@item e 6979@itemx o 6980True if the current page is even or odd numbered (respectively). 6981 6982@item n 6983@rqindex nroff 6984True if the document is being processed in nroff mode (i.e., the 6985@code{.nroff} command has been issued). 6986 6987@item t 6988@rqindex troff 6989True if the document is being processed in troff mode (i.e., the 6990@code{.troff} command has been issued). 6991 6992@item v 6993Always false. 6994 6995@item '@var{xxx}'@var{yyy}' 6996True if the string @var{xxx} is equal to the string @var{yyy}. Other 6997characters can be used in place of the single quotes; the same set of 6998delimiters as for the @code{\D} escape is used (@pxref{Escapes}). 6999@code{gtroff} formats the strings before being compared: 7000 7001@Example 7002.ie "|"\fR|\fP" \ 7003true 7004.el \ 7005false 7006 @result{} true 7007@endExample 7008 7009@noindent 7010The resulting motions, character sizes, and fonts have to 7011match,@footnote{The created output nodes must be identical. 7012@xref{Gtroff Internals}.} and not the individual motion, size, and 7013font requests. In the previous example, @samp{|} and @samp{\fR|\fP} 7014both result in a roman @samp{|} character with the same point size and 7015at the same location on the page, so the strings are equal. If 7016@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result 7017would be ``false'' because (the first) @samp{|} produces an italic 7018@samp{|} rather than a roman one. 7019 7020@item r @var{xxx} 7021True if there is a number register named @var{xxx}. 7022 7023@item d @var{xxx} 7024True if there is a string, macro, diversion, or request named @var{xxx}. 7025 7026@item c @var{ch} 7027@rqindex char 7028True if there is a character @var{ch} available; @var{ch} is either an 7029@acronym{ASCII} character or a special character (@code{\(@var{ch}} or 7030@code{\[@var{ch}]}); the condition is also true if @var{ch} has been 7031defined by the @code{char} request. 7032@end table 7033 7034Note that these operators can't be combined with other operators like 7035@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 7036between the exclamation mark and the operator) can be used to negate 7037the result. 7038 7039@Example 7040.nr xxx 1 7041.ie !r xxx \ 7042true 7043.el \ 7044false 7045 @result{} false 7046@endExample 7047 7048A whitespace after @samp{!} always evaluates to zero (this bizarre 7049behaviour is due to compatibility with @acronym{UNIX} @code{troff}). 7050 7051@Example 7052.nr xxx 1 7053.ie ! r xxx \ 7054true 7055.el \ 7056false 7057 @result{} r xxx true 7058@endExample 7059 7060It is possible to omit the whitespace before the argument to the 7061@samp{r}, @samp{d}, and @samp{c} operators. 7062 7063@xref{Expressions}. 7064 7065@c --------------------------------------------------------------------- 7066 7067@node if-else, while, Operators in Conditionals, Conditionals and Loops 7068@subsection if-else 7069@cindex if-else 7070 7071@code{gtroff} has if-then-else constructs like other languages, although 7072the formatting can be painful. 7073 7074@Defreq {if, expr anything} 7075Evaluate the expression @var{expr}, and executes @var{anything} (the 7076remainder of the line) if @var{expr} evaluates to non-zero (true). 7077@var{anything} is interpreted as though it was on a line by itself 7078(except that leading spaces are swallowed). @xref{Expressions}, for 7079more info. 7080 7081@Example 7082.nr xxx 1 7083.nr yyy 2 7084.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 7085 @result{} true 7086@endExample 7087@endDefreq 7088 7089@c XXX .nop request 7090 7091@Defreq {ie, expr anything} 7092@Defreqx {el, anything} 7093Use the @code{ie} and @code{el} requests to write an if-then-else. 7094The first request is the `if' part and the latter is the `else' part. 7095 7096@Example 7097.ie n .ls 2 \" double spacing in nroff 7098.el .ls 1 \" single spacing in troff 7099@endExample 7100@endDefreq 7101 7102@c this is a bug in makeinfo: you can't have `@{' as an argument 7103@c to deffn 7104 7105@esindex \@{ 7106@esindex \@} 7107@c @Defesc {\\@@@{, , , } 7108@c @Defescx {\\@@@}, , , } 7109In many cases, an if (or if-else) construct needs to execute more than 7110one request. This can be done using the @code{\@{} and @code{\@}} 7111escapes. The following example shows the possible ways to use these 7112escapes (note the position of the opening and closing braces). 7113 7114@Example 7115.ie t \@{\ 7116. ds lq `` 7117. ds rq '' 7118.\@} 7119.el \ 7120.\@{\ 7121. ds lq " 7122. ds rq "\@} 7123@endExample 7124@c @endDefesc 7125 7126@xref{Expressions}. 7127 7128@c --------------------------------------------------------------------- 7129 7130@node while, , if-else, Conditionals and Loops 7131@subsection while 7132@cindex while 7133 7134@code{gtroff} provides a looping construct using the @code{while} 7135request, which is used much like the @code{if} (and related) requests. 7136 7137@Defreq {while, expr anything} 7138Evaluate the expression @var{expr}, and repeatedly execute 7139@var{anything} (the remainder of the line) until @var{expr} evaluates 7140to@w{ }0. 7141 7142@Example 7143.nr a 0 1 7144.while (\na < 9) \@{\ 7145\n+a, 7146.\@} 7147\n+a 7148 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 7149@endExample 7150 7151Some remarks. 7152 7153@rqindex de 7154@itemize @bullet 7155@item 7156The body of a @code{while} request is treated like the body of a 7157@code{de} request: @code{gtroff} temporarily stores it in a macro 7158which is deleted after the loop has been exited. It can considerably 7159slow down a macro if the body of the @code{while} request (within the 7160macro) is large. Each time the macro is executed, the @code{while} 7161body is parsed and stored again as a temporary macro. 7162 7163@Example 7164.de xxx 7165. nr num 10 7166. while (\\n[num] > 0) \@{\ 7167. \" many lines of code 7168. nr num -1 7169. \@} 7170.. 7171@endExample 7172 7173@cindex recursive macros 7174@cindex macros, recursive 7175@noindent 7176The traditional and ofter better solution (@acronym{UNIX} @code{troff} 7177doesn't have the @code{while} request) is to use a recursive macro 7178instead which is parsed only once during its definition. 7179 7180@Example 7181.de yyy 7182. if (\\n[num] > 0) \@{\ 7183. \" many lines of code 7184. nr num -1 7185. yyy 7186. \@} 7187.. 7188. 7189.de xxx 7190. nr num 10 7191. yyy 7192.. 7193@endExample 7194 7195@noindent 7196Note that the number of available recursion levels is set to@w{ }1000 7197(this is a compile-time constant value of @code{gtroff}). 7198 7199@item 7200The closing brace of a @code{while} body must end a line. 7201 7202@Example 7203.if 1 \@{\ 7204. nr a 0 1 7205. while (\n[a] < 10) \@{\ 7206. nop \n+[a] 7207.\@}\@} 7208 @result{} unbalanced \@{ \@} 7209@endExample 7210@end itemize 7211@endDefreq 7212 7213@rqindex while 7214@cindex @code{break}, in a @code{while} loop 7215@cindex @code{continue}, in a @code{while} loop 7216@Defreq {break, } 7217Break out of a @code{while} loop. Be sure not to confuse this with 7218the @code{br} request (causing a line break). 7219@endDefreq 7220 7221@Defreq {continue, } 7222Finishes the current iteration of a @code{while} loop, immediately 7223restarting the next iteration. 7224@endDefreq 7225 7226@xref{Expressions}. 7227 7228 7229@c ===================================================================== 7230 7231@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 7232@section Writing Macros 7233@cindex writing macros 7234@cindex macros, writing 7235 7236A @dfn{macro} is a collection of text and embedded commands which can 7237be invoked multiple times. Use macros to define common operations. 7238 7239@Defreq {de, name [@Var{end}]} 7240Define a new macro named @var{name}. @code{gtroff} copies subsequent 7241lines (starting with the next one) into an internal buffer until it 7242encounters the line @samp{..} (two dots). The optional second 7243argument to @code{de} changes this to a macro to @samp{.@var{end}}. 7244 7245Note that no leading whitespace is allowed in the line containing the 7246ending token (either @samp{..} or the macro @samp{.@var{end}}). 7247 7248Here a small example macro called @samp{P} which causes a break and 7249inserts some vertical space. It could be used to separate paragraphs. 7250 7251@Example 7252.de P 7253. br 7254. sp .8v 7255.. 7256@endExample 7257 7258@c XXX add info about macro definitions in macros. 7259 7260@c XXX give example for end macro. 7261 7262@c XXX add info about indirect macro calls: 7263@c 7264@c .de xxx 7265@c from yyy\c 7266@c .. 7267@c 7268@c test \*[xxx] test 7269@c => test from yyy test 7270 7271@c XXX info about common identifier pool for strings, macros, and 7272@c diversions. 7273@endDefreq 7274 7275@cindex appending, to a macro 7276@Defreq {am, xx} 7277Works similarly to @code{de} except it appends onto the macro named 7278@var{xx}. So, to make the previously defined @samp{P} macro actually 7279do indented instead of block paragraphs, add the necessary code to the 7280existing macro like this: 7281 7282@Example 7283.am P 7284.ti +5n 7285.. 7286@endExample 7287@endDefreq 7288 7289@cindex alias 7290@Defreq {als, new old} 7291Create an alias named @var{new} for the request, string, macro, or 7292diversion object named @var{old}. The new name and the old name are 7293exactly equivalent (it is similar to a hard rather than a soft 7294link). If @var{old} is undefined, @code{gtroff} generates a warning of 7295type @samp{mac} and ignores the request. 7296 7297The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, 7298and @code{as} requests only create a new object if the name 7299of the macro, diversion or string diversion is currently 7300undefined or if it is defined to be a request; normally 7301they modify the value of an existing object. 7302@endDefreq 7303 7304@menu 7305* Copy-in Mode:: 7306* Parameters:: 7307@end menu 7308 7309@c --------------------------------------------------------------------- 7310 7311@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 7312@subsection Copy-in Mode 7313@cindex copy-in mode 7314@cindex mode, copy-in 7315 7316@esindex \n 7317@esindex \$ 7318@esindex \* 7319@esindex \\ 7320@esindex \@key{RET} 7321@cindex @code{\n}, when reading text for a macro 7322@cindex @code{\$}, when reading text for a macro 7323@cindex @code{\*}, when reading text for a macro 7324@cindex @code{\\}, when reading text for a macro 7325@cindex \@key{RET}, when reading text for a macro 7326When @code{gtroff} reads in the text for a macro or diversion, it copies 7327the text (including request lines, but excluding escapes) into an 7328internal buffer. Escapes are converted into an internal form, 7329except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 7330@code{\@key{RET}} which are evaluated and inserted into the text where 7331the escape was located. This is known as @dfn{copy-in} mode or 7332@dfn{copy} mode. 7333 7334What this means is that you can specify when these escapes are to be 7335evaluated (either at copy-in time or at the time of use) by insulating 7336the escapes with an extra backslash. Compare this to the @code{\def} 7337and @code{\edef} commands in @TeX{}. 7338 7339The following example prints the numbers 20 and@w{ }10: 7340 7341@Example 7342.nr x 20 7343.de y 7344.nr x 10 7345\&\nx 7346\&\\nx 7347.. 7348.y 7349@endExample 7350 7351@c --------------------------------------------------------------------- 7352 7353@node Parameters, , Copy-in Mode, Writing Macros 7354@subsection Parameters 7355@cindex parameters 7356 7357@vindex .$ 7358The arguments to a macro can be examined using a variety of escapes. 7359The number of arguments is available in the @code{.$} number register. 7360Any individual argument can be retrieved with one of the following 7361escapes: 7362 7363@cindex copy-in mode, and macro arguments 7364@Defesc {\\$, n, , } 7365@Defescx {\\$, @lparen{}, nn, } 7366@Defescx {\\$, @lbrack{}, nnn, @rbrack{}} 7367The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and 7368@code{\$[@var{nnn}]} retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or 7369@var{nnn}@dmn{th} argument. As usual, the first form only accepts a 7370single number (larger than zero), the second a two-digit number (larger 7371or equal to@w{ }10), and the third any positive integer value (larger 7372than zero). Macros can have an unlimited number of arguments. Note 7373that due to copy-in mode, use two backslashes on these in actual use to 7374prevent interpolation until the macro is actually invoked. 7375@endDefesc 7376 7377@Defreq {shift, [@Var{n}]} 7378Shifts the arguments 1@w{ }position, or as 7379many positions as specified by its argument. After executing this 7380request, argument@w{ }@var{i} becomes argument @var{i}-@var{n}; 7381arguments 1 to@w{ }@var{n} are no longer available. Shifting by 7382negative amounts is currently undefined. 7383@endDefreq 7384 7385@Defesc {\\$*, , , } 7386@Defescx {\\$@@, , , } 7387In some cases it is convenient to use all of the arguments at once (for 7388example, to pass the arguments along to another macro). The @code{\$*} 7389escape concatenates all the arguments separated by spaces. A 7390similar escape is @code{\$@@}, which concatenates all the 7391arguments with each surrounded by double quotes, and separated by 7392spaces. 7393@endDefesc 7394 7395@rqindex als 7396@cindex @code{als}, use with @code{\$0} 7397@Defesc {\\$0, , , } 7398The name used to invoke the current macro. 7399The @code{als} request can make a macro have more than one name. 7400 7401@Example 7402.de vl 7403.ie \\n(.$=1 .ds Vl Pre-Release Version 7404.el .ds Vl Version \\$3, \\$4. 7405.. 7406@endExample 7407 7408@noindent 7409This would be called as 7410 7411@Example 7412.vl $Id: groff.texinfo,v 1.74 2001/04/16 14:47:18 wlemb Exp $ 7413@endExample 7414@endDefesc 7415 7416@xref{Request Arguments}. 7417 7418 7419@c ===================================================================== 7420 7421@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 7422@section Page Motions 7423@cindex page motions 7424@cindex motions, page 7425 7426@cindex @code{sp}, as vertical page motion 7427@Defreq {sp, [@Var{len}]} 7428Motions up and down the page can be done with the @code{sp} request. 7429However, this causes a break so that the actual effect is to move to the 7430left margin and then to the specified location. 7431@endDefreq 7432 7433@Defreq {mk, [@Var{reg}]} 7434@Defreqx {rt, reg} 7435The request @code{mk} can be used to mark a location on a page, for 7436movement to later. This request takes a register name as an argument in 7437which to store the current page location. With no argument it 7438stores the location in an internal register. The results of this can be 7439used later by the @code{rt} or the @code{sp} request. The @code{rt} 7440request returns @emph{upwards} to the location given in the register 7441name given as an argument; with no argument it returns to the 7442location marked with the @code{mk} request. 7443 7444@c XXX example 7445@ignore 7446@Example 7447... dual column example ... 7448@endExample 7449@end ignore 7450@endDefreq 7451 7452The following escapes give fine control of movements about the page. 7453 7454@cindex vertical motion 7455@cindex motion, vertical 7456@Defesc {\\v, ', e, '} 7457The @code{\v'@var{e}'} escape enables arbitrary vertical motion from the 7458current location on the page. The argument@w{ }@var{e} specifies the 7459distance to move; positive is downwards and negative upwards. The 7460default unit for this escape @samp{v}. Beware, however, that 7461@code{gtroff} continues text processing at the point where the motion 7462ends, so you should always balance motions to avoid interference with 7463text processing. 7464@endDefesc 7465 7466There are some special case escapes for vertical motion. 7467 7468@ftable @code 7469@item \r 7470move upwards@w{ }1@dmn{v}. 7471 7472@item \u 7473move upwards@w{ }.5@dmn{v}. 7474 7475@item \d 7476move down@w{ }.5@dmn{v}. 7477@end ftable 7478 7479@cindex inserting horizontal space 7480@cindex horizontal space 7481@cindex space, horizontal 7482@Defesc {\\h, ', e, '} 7483The @code{\h'@var{e}'} escape provides horizontal motions. The 7484expression@w{ }@var{e} indicates how far to move: positive is rightwards 7485and negative leftwards. 7486@c XXX Is there a default unit for this? 7487@endDefesc 7488 7489There are a number of special case escapes for horizontal motion: 7490 7491@ftable @code 7492@item \@key{SP} 7493An unbreakable and unpaddable (i.e.@: not expanded during filling) 7494space. (Note: This is a backslash followed by a space.) 7495 7496@item \~ 7497An unbreakable space that stretches like a normal inter-word space 7498when a line is adjusted. 7499 7500@item \| 7501A 1/6@dmn{th} em space. Ignored for tty output devices (rounded to 7502zero). 7503 7504@item \^ 7505A 1/12@dmn{th} em space. Ignored for tty output devices (rounded to 7506zero). 7507 7508@item \0 7509A space the size of a digit. 7510 7511@item \& 7512@cindex zero width space character 7513@cindex character, zero width space 7514@cindex space character, zero width 7515A zero width space. 7516 7517@item \) 7518Like @code{\&} except that it behaves like a character declared with the 7519@code{cflags} request to be transparent for the purposes of end of 7520sentence recognition. 7521@end ftable 7522 7523The following string sets the @TeX{} logo: 7524 7525@Example 7526.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 7527@endExample 7528 7529@cindex width escape 7530@cindex escape, width 7531@Defesc {\\w, ', text, '} 7532Used as @code{\w'@var{text}'}, 7533returns the width of the specified @var{text} in basic units. 7534This allows horizontal movement based on the width of some 7535arbitrary text (e.g.@: given as an argument to a macro). 7536 7537@c XXX example 7538 7539@ignore 7540@Example 7541... strlen example ... 7542@endExample 7543@end ignore 7544 7545Font changes may occur in @var{text} which don't affect current 7546settings. 7547 7548After use, @code{\w} sets several registers: 7549 7550@table @code 7551@item st 7552@itemx sb 7553@vindex st 7554@vindex sb 7555The highest and lowest point, respectively, in @var{text}. 7556 7557@item rst 7558@itemx rsb 7559@vindex rst 7560@vindex rsb 7561Like the @code{st} and @code{sb} registers, but takes account of the 7562heights and depths of characters. 7563 7564@item ct 7565@vindex ct 7566Defines the kinds of characters occurring in @var{text}: 7567 7568@table @asis 7569@item 0 7570only short characters, no descenders or tall characters. 7571 7572@item 1 7573at least one descender. 7574 7575@item 2 7576at least one tall character. 7577 7578@item 3 7579at least one each of a descender and a tall character. 7580@end table 7581 7582@item ssc 7583@vindex ssc 7584The amount of horizontal space (possibly negative) that should be added 7585to the last character before a subscript. 7586 7587@item skw 7588@vindex skw 7589How far to right of the center of the last character in the @code{\w} 7590argument, the center of an accent from a roman font should be placed 7591over that character. 7592@end table 7593@endDefesc 7594 7595@Defesc {\\k, ', x, '} 7596Stores the current horizontal position in register @var{x}. 7597Use this, for example, to return to the beginning of a string 7598for highlighting or other decoration. 7599@endDefesc 7600 7601@Defreg {.k} 7602A read-only number register containing the current horizontal output 7603position. 7604@endDefreg 7605 7606@c XXX documentation 7607 7608 7609@c ===================================================================== 7610 7611@node Drawing Requests, Traps, Page Motions, gtroff Reference 7612@section Drawing Requests 7613@cindex drawing requests 7614@cindex requests for drawing 7615 7616@code{gtroff} provides a number of ways to draw lines and other figures 7617on the page. Used in combination with the page motion commands (see 7618@ref{Page Motions}, for more info), a wide variety of figures can be 7619drawn. However, for complex drawings these operations can be quite 7620cumbersome, and it may be wise to use graphic preprocessors like 7621@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 7622information. 7623 7624All drawing is done via escapes. 7625 7626@cindex drawing horizontal lines 7627@cindex horizontal line, drawing 7628@cindex line, horizontal, drawing 7629@Defesc {\\l, ', l c, '} 7630Draws a line rightwards from the current 7631location. The full syntax for this escape is: 7632 7633@Example 7634\l'@var{l}@var{c}' 7635@endExample 7636 7637@noindent 7638where @var{l} is the length of the line to be drawn, starting at the 7639current location; positive numbers draw to the right, and negative 7640numbers draw towards the left. This can also be specified absolutely 7641(i.e.@: with a leading @samp{|}) which draws back to the beginning 7642of the line. 7643 7644@cindex underscore character 7645@cindex character, underscore 7646@cindex line drawing character 7647@cindex character for line drawing 7648The optional second parameter @var{c} is a character to draw the line 7649with. If this second argument is not specified, @code{gtroff} uses 7650the underscore character. 7651 7652@cindex zero width space character 7653@cindex character, zero width space 7654@cindex space character, zero width 7655@esindex \& 7656To separate the two arguments (to prevent @code{gtroff} from 7657interpreting a drawing character as a scaling indicator) use @code{\&}. 7658 7659Here a small useful example: 7660 7661@Example 7662.de box 7663\(br\\$*\(br\l'|0\(rn'\l'|0\(ul' 7664.. 7665@endExample 7666 7667@opindex | 7668@noindent 7669Note that this works by outputting a box rule (a vertical line), then 7670the text given as an argument and then another box rule. Then the line 7671drawing escapes both draw from the current location to the beginning of 7672the @emph{input} line. 7673@endDefesc 7674 7675@cindex drawing vertical lines 7676@cindex vertical line drawing 7677@cindex line, vertical, drawing 7678@cindex line drawing character 7679@cindex character for line drawing 7680@cindex box rule character 7681@cindex character, box rule 7682@Defesc {\\L, ', l c, '} 7683Draws vertical lines. Its parameters are 7684similar to the @code{\l} escape. The 7685movement is downwards for positive values, 7686and upwards for negative values. The 7687default character is the box rule character. As with the vertical 7688motion escapes, text processing blindly continues where the line 7689ends. 7690 7691@c XXX example 7692 7693@ignore 7694@Example 7695...box macro... 7696@endExample 7697@end ignore 7698@endDefesc 7699 7700@Defesc {\\D, ', command arg @dots{}, '} 7701The @code{\D} escape provides a variety of drawing functions. 7702While the previous escapes work on a character device, these 7703escapes do not. 7704 7705@table @code 7706@item \D'l @var{dx} @var{dy}' 7707Draw a line from the current location to the relative point specified by 7708(@var{dx},@var{dy}). 7709 7710@c XXX example 7711 7712@ignore 7713@Example 7714...revised box macro... 7715@endExample 7716@end ignore 7717 7718@item \D'c @var{d}' 7719@cindex circle drawing 7720@cindex drawing a circle 7721Draw a circle with a diameter of @var{d} with the leftmost point at the 7722current position. 7723 7724@item \D'C @var{d}' 7725Draw a solid circle with the same parameters as an outlined circle. 7726 7727@item \D'e @var{dx} @var{dy}' 7728@cindex drawing an ellipse 7729@cindex ellipse drawing 7730Draw an ellipse with a horizontal diameter of @var{dx} and a vertical 7731diameter of @var{dy} with the leftmost point at the current position. 7732 7733@item \D'E @var{dx} @var{dy}' 7734Draw a solid ellipse with the same parameters as an outlined ellipse. 7735 7736@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 7737@cindex arc drawing 7738@cindex drawing an arc 7739Draw an arc clockwise from the current location through the two 7740specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}). 7741 7742@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7743@cindex drawing a spline 7744@cindex spline drawing 7745Draw a spline from the current location to (@var{dx1},@var{dy1}) and 7746then to (@var{dx2},@var{dy2}), and so on. 7747 7748@item \D'f @var{n}' 7749@cindex gray shading 7750@cindex shading 7751@cindex shades for filling objects 7752Set the shade of gray to be used for filling solid objects to@w{ 7753}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 7754corresponds solid white and 1000 to solid black, and values in between 7755correspond to intermediate shades of gray. This applies only to solid 7756circles, solid ellipses and solid polygons. By default, a level of@w{ 7757}1000 is used. 7758 7759@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7760@cindex drawing a polygon 7761@cindex polygon drawing 7762Draw a polygon from the current location to (@var{dx1},@var{dy1}) and 7763then to (@var{dx2},@var{dy2}) and so on. When the specified data points 7764are exhausted, a line is drawn back to the starting point. 7765 7766@c XXX example 7767 7768@ignore 7769@Example 7770... box example (yes, again)... 7771@endExample 7772@end ignore 7773 7774@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7775Draw a solid polygon with the same parameters as an outlined polygon. 7776 7777@c XXX example 7778 7779@ignore 7780@Example 7781... shaded box example ... 7782@endExample 7783@end ignore 7784 7785@item \D't @var{n}' 7786@cindex line thickness 7787@cindex thickness of lines 7788Set the current line thickness to @var{n} machine units. A value of 7789zero selects the smallest available line thickness. A negative value 7790makes the line thickness proportional to the current point size (this is 7791the default behaviour of @code{ditroff}). 7792@end table 7793@endDefesc 7794 7795@cindex pile, character 7796@cindex character pile 7797@Defesc {\\b, ', string, '} 7798@dfn{Piles} a sequence of characters 7799vertically, and centers it vertically on the current line. Use it 7800to build large brackets and braces. 7801 7802@Example 7803\b'\(lt\(bv\(lk\(bv\(lb' 7804@endExample 7805@endDefesc 7806 7807@xref{Drawing Functions}. 7808 7809 7810@c ===================================================================== 7811 7812@node Traps, Diversions, Drawing Requests, gtroff Reference 7813@section Traps 7814@cindex traps 7815 7816@dfn{Traps} are locations, which, when reached, call a specified 7817macro. These traps can occur at a given location on the page, at a 7818given location in the current diversion, after a certain number of input 7819lines or at the end of input. 7820 7821@menu 7822* Page Location Traps:: 7823* Diversion Traps:: 7824* Input Line Traps:: 7825* End-of-input Traps:: 7826@end menu 7827 7828@c --------------------------------------------------------------------- 7829 7830@node Page Location Traps, Diversion Traps, Traps, Traps 7831@subsection Page Location Traps 7832@cindex page location traps 7833@cindex traps, page location 7834 7835@dfn{Page location traps} perform an action when @code{gtroff} 7836reaches a certain vertical location on the page. Page location 7837traps have a variety of purposes, including: 7838 7839@itemize 7840@item 7841setting headers and footers 7842 7843@item 7844setting body text in multiple columns 7845 7846@item 7847setting footnotes 7848@end itemize 7849 7850@cindex vertical position trap enable register 7851@Defreq {vpt, flag} 7852@Defregx {.vpt} 7853Enables vertical position traps if @var{flag} is non-zero, or disables 7854them otherwise. Vertical position traps are traps set by the @code{wh} 7855or @code{dt} requests. Traps set by the @code{it} request are not 7856vertical position traps. The parameter that controls whether vertical 7857position traps are enabled is global. Initially vertical position traps 7858are enabled. The current setting of this is available in the 7859@code{.vpt} read-only number register. 7860@endDefreq 7861 7862@Defreq {wh, dist macro} 7863Sets a page location trap. Positive values for @var{dist} set 7864the trap relative to the top of the page; negative values set 7865the trap relative to the bottom of the page. 7866 7867@var{macro} is the name of the macro to execute when the 7868trap is sprung. 7869 7870@cindex page headers 7871@cindex page footers 7872@cindex headers 7873@cindex footers 7874The following is a simple example of how many macro packages 7875set headers and footers. 7876 7877@Example 7878.de hd \" Page header 7879'sp .5i 7880.tl 'Title''date' 7881'sp .3i 7882.. 7883.de fo \" Page footer 7884'sp 1v 7885.tl ''%'' 7886'bp 7887.. 7888.wh 0 hd \" trap at top of the page 7889.wh -1i fo \" trap one inch from bottom 7890@endExample 7891@endDefreq 7892 7893@cindex distance to next trap 7894@cindex trap, distance 7895@Defreg {.t} 7896A read-only number register holding the distance to the next trap. 7897@endDefreg 7898 7899@cindex changing trap location 7900@cindex trap, changing location 7901@Defreq {ch, dist macro} 7902Changes the location of a trap. 7903The first argument is the name of the macro to be invoked at 7904the trap, and the second argument is the new location for the trap 7905(note that the parameters are specified the opposite of the @code{.wh} request). 7906This is useful for building up footnotes in a diversion to allow more 7907space at the bottom of the page for them. 7908 7909@c XXX 7910 7911@ignore 7912@Example 7913... (simplified) footnote example ... 7914@endExample 7915@end ignore 7916@endDefreq 7917 7918@Defreg {.ne} 7919The read-only number register @code{.ne} contains the amount of space 7920that was needed in the last @code{ne} request that caused a trap to be 7921sprung. Useful in conjunction with the @code{.trunc} register. 7922@xref{Page Control}, for more information. 7923@endDefreg 7924 7925@rqindex ne 7926@cindex @code{ne}, and the @code{.trunc} register 7927@Defreg {.trunc} 7928A read-only register containing the amount of vertical space truncated 7929by the most recently sprung vertical position trap, or, if the trap was 7930sprung by an @code{ne} request, minus the amount of vertical motion 7931produced by the @code{ne} request. In other words, at the point a trap 7932is sprung, it represents the difference of what the vertical position 7933would have been but for the trap, and what the vertical position 7934actually is. 7935@endDefreg 7936 7937@c --------------------------------------------------------------------- 7938 7939@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 7940@subsection Diversion Traps 7941@cindex diversion traps 7942@cindex traps, diversion 7943 7944@vindex .t 7945@cindex @code{.t}, and diversions 7946@Defreq {dt, dist macro} 7947Sets a trap @emph{within} a diversion. 7948@var{dist} is the first argument is the location of the trap 7949(identical to the @code{.wh} request) 7950and @var{macro} is the name of the macro to be invoked. The 7951number register @code{.t} still works within diversions. 7952@xref{Diversions}, for more information. 7953@endDefreq 7954 7955@c --------------------------------------------------------------------- 7956 7957@node Input Line Traps, End-of-input Traps, Diversion Traps, Traps 7958@subsection Input Line Traps 7959@cindex input line traps 7960@cindex traps, input line 7961 7962@Defreq {it, n macro} 7963Sets an input line trap. 7964@var{n} is the number of lines of input which may be read before 7965@dfn{springing} the trap, @var{macro} is the macro to be invoked. 7966Request lines are not counted as input lines. 7967 7968For example, one possible use is to have a macro which prints the 7969next @var{n}@w{ }lines in a bold font. 7970 7971@Example 7972.de B 7973.it \\$1 B-end 7974.ft B 7975.. 7976.de B-end 7977.ft R 7978.. 7979@endExample 7980@endDefreq 7981 7982@c --------------------------------------------------------------------- 7983 7984@node End-of-input Traps, , Input Line Traps, Traps 7985@subsection End-of-input Traps 7986@cindex end-of-input traps 7987@cindex traps, end-of-input 7988 7989@Defreq {em, macro} 7990Sets a trap at the end of input. The @var{macro} 7991specified is executed after the last line of the 7992input file has been processed. 7993 7994For example, if the document had to have a section at the bottom of the 7995last page for someone to approve it, the @code{em} request could be 7996used. 7997 7998@Example 7999.de approval 8000.ne 5v 8001.sp |(\\n(.t-6v) 8002.in +4i 8003.lc _ 8004.br 8005Approved:\t\a 8006.sp 8007Date:\t\t\a 8008.. 8009.em approval 8010@endExample 8011@endDefreq 8012 8013 8014@c ===================================================================== 8015 8016@node Diversions, Environments, Traps, gtroff Reference 8017@section Diversions 8018@cindex diversions 8019 8020In @code{gtroff} it is possible to @dfn{divert} text into a named 8021storage area. Due to the similarity to defining macros it is sometimes 8022said to be stored in a macro. This is used for saving text for output 8023at a later time, which is useful for keeping blocks of text on the same 8024page, footnotes, tables of contents and indices. 8025 8026@c XXX describe top-level diversion 8027@c XXX index entry for top-level diversion 8028 8029@Defreq {di, macro} 8030@Defreqx {da, macro} 8031Begins a diversion. Like the @code{de} 8032request, it takes an argument of a macro name to divert subsequent text 8033into. The @code{da} macro appends to an existing diversion. 8034 8035@code{di} or @code{da} without an argument ends the diversion. 8036 8037@c XXX example 8038 8039@ignore 8040@Example 8041... end-note example ... 8042@endExample 8043@end ignore 8044@endDefreq 8045 8046@vindex nl 8047@vindex .h 8048@cindex nested diversions 8049@cindex diversion, nested 8050@Defreg {.z} 8051@Defregx {.d} 8052Diversions may be nested. The read-only number register @code{.z} 8053contains the name of the current diversion (this is a string-valued 8054register). The read-only number register @code{.d} contains the current 8055vertical place in the diversion. If not in a diversion it is the same 8056as the register @code{nl}. 8057@endDefreg 8058 8059@c XXX more info 8060 8061@Defreg {.h} 8062The @dfn{high-water mark} on the current page. It corresponds to the 8063text baseline of the lowest line on the page. This is a read-only 8064register. 8065@endDefreg 8066 8067@Defreg {dn} 8068@Defregx {dl} 8069After completing a diversion, the read-write number registers @code{dn} 8070and @code{dl} contain the vertical and horizontal size of the diversion. 8071 8072@example 8073@group 8074.\" Center text both horizontally & vertically 8075.de (c 8076.br 8077.nf 8078.di @@c 8079.. 8080@end group 8081@group 8082.de )c 8083.br 8084.di 8085.nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v) 8086.sp \\n(@@su 8087.ce 1000 8088.nf 8089.@c 8090.br 8091.ce 0 8092.sp \\n(@@su 8093.br 8094.fi 8095.rr @@s 8096.. 8097@end group 8098@end example 8099@endDefreg 8100 8101@cindex transparent output 8102@cindex output, transparent 8103@Defesc {\\!, , , } 8104@Defescx {\\?, , @Var{anything}, \\?} 8105Prevents requests, macros and escapes from being 8106interpreted when read into a diversion. This takes the given text 8107and @dfn{transparently} embeds it into the diversion. This is useful for 8108macros which shouldn't be invoked until the diverted text is actually 8109output. 8110 8111@c XXX anything is read in copy mode. (what about \! ??) 8112 8113The @code{\!} escape transparently embeds text up to 8114and including the end of the line. 8115The @code{\?} escape transparently embeds text until the next 8116occurrence of the @code{\?} escape. For example: 8117 8118@Example 8119\?@var{anything}\? 8120@endExample 8121 8122@noindent 8123@var{anything} may not contain newlines; use @code{\!} to embed 8124newlines in a diversion. The escape sequence @code{\?} is also 8125recognized in copy mode and turned into a single internal code; it is 8126this code that terminates anything. Thus the following example 8127prints@w{ }4. 8128 8129@Example 8130.nr x 1 8131.nf 8132.di d 8133\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 8134.di 8135.nr x 2 8136.di e 8137.d 8138.di 8139.nr x 3 8140.di f 8141.e 8142.di 8143.nr x 4 8144.f 8145@endExample 8146@endDefesc 8147 8148@cindex unformatting diversions 8149@cindex diversion, unformatting 8150@Defreq {asciify, div} 8151@dfn{Unformats} the diversion specified by @var{div} 8152in such a way that @acronym{ASCII} and space characters that 8153were formatted and diverted are treated like ordinary input 8154characters when the diversion is reread. It can be also used for gross 8155hacks; for example, the following sets register @code{n} to@w{ }1. 8156 8157@Example 8158.tr @@. 8159.di x 8160@@nr n 1 8161.br 8162.di 8163.tr @@@@ 8164.asciify x 8165.x 8166@endExample 8167 8168@xref{Copy-in Mode}. 8169@endDefreq 8170 8171 8172@c ===================================================================== 8173 8174@node Environments, Suppressing output, Diversions, gtroff Reference 8175@section Environments 8176@cindex environments 8177 8178It happens frequently that some text should be printed in a certain 8179format regardless of what may be in effect at the time, for example, in 8180a trap invoked macro to print headers and footers. To solve this 8181@code{gtroff} processes text in @dfn{environments}. An 8182environment contains most of the parameters that control text 8183processing. It is possible to switch amongst these environments; by 8184default @code{gtroff} processes text in environment@w{ }0. The 8185following is the information kept in an environment. 8186 8187@itemize @bullet 8188@item 8189font parameters (size, family, style, character height and slant, space 8190and sentence space size) 8191 8192@item 8193page parameters (line length, title length, vertical spacing, 8194line spacing, indentation, line numbering, hyphenation data) 8195 8196@item 8197fill and adjust mode 8198 8199@item 8200tab stops, tab and leader characters, escape character, no-break and 8201hyphen indicators, margin character data 8202 8203@item 8204partially collected lines 8205@end itemize 8206 8207These environments may be given arbitrary names (see @ref{Identifiers}, 8208for more info). Old versions of @code{troff} only had environments 8209named @samp{0}, @samp{1} and@w{ }@samp{2}. 8210 8211@cindex switch environments 8212@cindex current environment number/name register 8213@Defreq {ev, env} 8214@Defregx {.ev} 8215Switches to another environment. The argument @var{env} is the name of 8216the environment to switch to. With no argument, @code{gtroff} switches 8217back to the previous environment. There is no limit on the number of 8218named environments; they are created the first time that they are 8219referenced. The @code{.ev} read-only register contains the name or 8220number of the current environment. This is a string-valued register. 8221 8222Note that a call to @code{ev} (with argument) pushes the previously 8223active environment onto a stack. If, say, environments @samp{foo}, 8224@samp{bar}, and @samp{zap} are called (in that order), the first 8225@code{ev} request without parameter switches back to environment 8226@samp{bar} (which is popped off the stack), and a second call 8227switches back to environment @samp{foo}. 8228 8229@c XXX example 8230 8231@ignore 8232@Example 8233... page break macro, revised ... 8234@endExample 8235@end ignore 8236 8237Here is an example: 8238 8239@Example 8240.ev footnote-env 8241.fam N 8242.ps 6 8243.vs 8 8244.ll -.5i 8245.ev 8246 8247... 8248 8249.ev footnote-env 8250\(dg Note the large, friendly letters. 8251.ev 8252@endExample 8253@endDefreq 8254 8255@cindex copy environment 8256@Defreq {evc, env} 8257Copies the environment @var{env} into the current environment. 8258@endDefreq 8259 8260 8261@c ===================================================================== 8262 8263@node Suppressing output, I/O, Environments, gtroff Reference 8264@section Suppressing output 8265@cindex suppressing output 8266 8267@Defesc {\\O, , num, } 8268Disables or enables output depending on the value of @var{num}: 8269 8270@table @samp 8271@item \O0 8272Disable any ditroff glyphs from being emitted to the device driver. 8273 8274@item \O1 8275Enable output of glyphs. 8276@end table 8277 8278@vindex opminx 8279@vindex opminy 8280@vindex opmaxx 8281@vindex opmaxy 8282@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 8283@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 8284@xref{Register Index}. These four registers mark the top left and 8285bottom right hand corners of a box which encompasses all written glyphs. 8286 8287The following two forms of @code{\O} are specific to @code{grohtml}. 8288 8289@table @samp 8290@item \O2 8291Disable any ditroff glyphs from being emitted to the device driver. Also 8292write out to @code{stderr} the page number and four registers encompassing 8293the glyphs previously written since the last call to @code{\O}. 8294 8295@item \O3 8296Enable output of glyphs (the default). Also write out to @code{stderr} 8297the page number and four registers encompassing the glyphs previously 8298written since the last call to @code{\O}. 8299@end table 8300@endDefesc 8301 8302 8303@c ===================================================================== 8304 8305@node I/O, Postprocessor Access, Suppressing output, gtroff Reference 8306@section I/O 8307@cindex i/o 8308@cindex input and output requests 8309@cindex requests for input and output 8310@cindex output and input requests 8311 8312@code{gtroff} has several requests for including files: 8313 8314@cindex including a file 8315@cindex file inclusion 8316@Defreq {so, file} 8317Reads in the specified @var{file} and 8318includes it in place of the @code{so} request. This is quite useful for 8319large documents, e.g.@: keeping each chapter in a separate file. 8320@xref{gsoelim}, for more information. 8321@endDefreq 8322 8323@Defreq {mso, file} 8324Identical to the @code{so} request except that @code{gtroff} 8325searches for the specified 8326@var{file} in the same directories as macro files for the 8327the @option{-m} command line option. If the file name to be included 8328has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 8329to include @file{tmac.@var{name}} and vice versa. 8330@endDefreq 8331 8332@cindex transparent output 8333@cindex output, transparent 8334@Defreq {cf, file} 8335@Defreqx {trf, file} 8336Transparently outputs the contents of @var{file}. Each line is output 8337as it were preceded by @code{\!}; however, the lines are not subject to 8338copy mode interpretation. If the file does not end with a newline, then 8339a newline is added. For example, to define a macro@w{ }@code{x} 8340containing the contents of file@w{ }@file{f}, use 8341 8342@Example 8343.di x 8344.trf f 8345.di 8346@endExample 8347 8348The request @w{@code{.cf @var{filename}}}, when used in a diversion, 8349embeds an object in the diversion which, when reread, causes the 8350contents of @var{filename} to be transparently copied through to the 8351output. 8352 8353In @acronym{UNIX} @code{troff}, the contents of @var{filename} 8354is immediately copied through to the output regardless of whether there 8355is a current diversion; this behaviour is so anomalous that it must be 8356considered a bug. This request causes a line break. 8357 8358@rqindex trf 8359With @code{trf}, unlike @code{cf}, the file cannot contain characters 8360such as NUL that are not valid @code{gtroff} input characters 8361(@pxref{Identifiers}). This request causes a line break. 8362@endDefreq 8363 8364@Defreq {nx, } 8365Forces @code{gtroff} to continue processing of 8366the file specified as an argument. 8367@endDefreq 8368 8369@Defreq {rd, } 8370The @code{rd} request reads from standard input, and includes what is 8371read as though it were part of the input file. Text is read until a 8372blank line is encountered. 8373@endDefreq 8374 8375@cindex form letters 8376@cindex letters, form 8377Using the @code{nx} and @code{rd} requests, 8378it is easy to set up form letters. The form 8379letter template is constructed like this: 8380 8381@Example 8382.ce 8383\*(td 8384.sp 2 8385.nf 8386.rd 8387.sp 8388.rd 8389.fi 8390Body of letter. 8391.bp 8392.nx repeat.let 8393@endExample 8394 8395@rqindex ex 8396@noindent 8397When this is run, the following file should be redirected in. Note that 8398requests included in this file are executed as though they were part of 8399the form letter. The last block of input is the @code{ex} requests 8400which tells groff to stop processing. If this was not there, groff 8401would not know when to stop. 8402 8403@Example 8404Trent A. Fisher 8405708 NW 19th Av., #202 8406Portland, OR 97209 8407 8408Dear Trent, 8409 8410Len Adollar 84114315 Sierra Vista 8412San Diego, CA 92103 8413 8414Dear Mr. Adollar, 8415 8416.ex 8417@endExample 8418 8419@Defreq {pi, pipe} 8420Pipes the output of @code{gtroff} to the shell command(s) 8421specified by @var{pipe}. This request must occur before 8422@code{gtroff} has a chance to print anything. 8423@endDefreq 8424 8425@Defreq {sy, cmds} 8426@Defregx {systat} 8427In @dfn{unsafe} mode, executes the shell command(s) specified by 8428@var{cmds}. The output is not saved anyplace, so it is up to the user 8429to do so. 8430 8431@c XXX add info about safer and unsafe mode 8432 8433For example, the following example introduces the current time 8434into a document: 8435 8436@cindex time, current 8437@cindex current time 8438@pindex perl 8439@Example 8440.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 8441 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 8442.so /tmp/x\n[$$] 8443.sy rm /tmp/x\n[$$] 8444\nH:\nM:\nS 8445@endExample 8446 8447@noindent 8448Note that this works by having the @code{perl} script (run by @code{sy}) 8449print out the @code{nr} requests which set the number registers 8450@samp{H}, @samp{M} and @samp{S}, and then reads those commands in with 8451the @code{so} request. 8452 8453@cindex @code{system()} return value register 8454The @code{systat} read-write number register contains the return value 8455of the @code{system()} function executed by the last @code{sy} request. 8456@endDefreq 8457 8458@Defreq {open, stream file} 8459@Defreqx {opena, stream file} 8460Opens the specified @var{file} for writing and 8461associates the specified @var{stream} with it. 8462 8463The @code{opena} is like @code{open}, but if the file exists, append to 8464it instead of truncating it. 8465@endDefreq 8466 8467@cindex copy-in mode, and @code{write} requests 8468@cindex mode, copy-in, and @code{write} requests 8469@Defreq {write, stream data} 8470Writes to the file associated with the specified @var{stream}. 8471The stream must previously have 8472been the subject of an open request. The remainder of the line is 8473interpreted as the @code{ds} request reads its second argument: A 8474leading @samp{"} is stripped, and it is read in copy-in mode. 8475@endDefreq 8476 8477@Defreq {close, stream} 8478Closes the specified @var{stream}; 8479the stream is no longer an acceptable argument to the 8480@code{write} request. 8481 8482@c XXX example 8483 8484@ignore 8485@Example 8486... example of open write &c... 8487@endExample 8488@end ignore 8489@endDefreq 8490 8491@Defesc {\\V, ', xxx, '} 8492Interpolates the contents of the specified 8493environment variable, as returned by the function @code{getenv}. 8494Specify the argument to @code{\V} as an identifier, i.e.@: 8495@samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} 8496is interpreted in copy-in mode. 8497@endDefesc 8498 8499 8500@c ===================================================================== 8501 8502@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 8503@section Postprocessor Access 8504@cindex postprocessor access 8505@cindex access of postprocessor 8506 8507There are two escapes which give information directly to the 8508postprocessor. This is particularly useful for embedding 8509@sc{PostScript} into the final document. 8510 8511@Defesc {\\X, ', xxx, '} 8512Embeds its argument into the @code{gtroff} 8513output preceded with @w{@samp{x X}}. 8514@endDefesc 8515 8516@Defesc {\\Y, ', xxx, '} 8517The @code{\Y} escape is called with an identifier (i.e.@: 8518@code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is 8519approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the 8520contents of the string or macro @var{xxx} are not interpreted; also it 8521is permitted for @var{xxx} to have been defined as a macro and thus 8522contain newlines (it is not permitted for the argument to @code{\X} to 8523contain newlines). The inclusion of newlines requires an extension to 8524the @acronym{UNIX} @code{troff} output format, and confuses drivers 8525that do not know about this extension. 8526@endDefesc 8527 8528@xref{Output Devices}. 8529 8530 8531@c ===================================================================== 8532 8533@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 8534@section Miscellaneous 8535@cindex miscellaneous 8536 8537This section documents parts of @code{gtroff} which cannot (yet) be 8538categorized elsewhere in this manual. 8539 8540@cindex line numbers 8541@cindex numbers, line 8542@Defreq {nm, start inc space indent} 8543Prints line numbers in the left margin. 8544@var{start} is the line number of the @emph{next} 8545output line; this defaults to@w{ }1. @var{inc} indicates on 8546which lines numbers are printed, i.e.@: 5 means put line numbers on 8547every 5@w{ }lines; this defaults to@w{ }1. @var{space} is the 8548space to be left between the number and the text; this defaults to@w{ 8549}1. The fourth argument is the indentation of the line numbers. 8550Without arguments, line numbers are turned off. 8551@endDefreq 8552 8553@c XXX xref ln register 8554 8555@Defreq {nn, [@Var{skip}]} 8556Temporarily turns off line numbering. The 8557argument is the number of lines not to be numbered; this defaults 8558to@w{ }1. 8559 8560@c XXX (does this disable incrementing or display?) 8561 8562@c XXX example 8563 8564@ignore 8565@Example 8566... line numbering example ... 8567@endExample 8568@end ignore 8569@endDefreq 8570 8571@cindex margin characters 8572@cindex characters for margins 8573@Defreq {mc, char dist} 8574Prints margin characters to the right of the text. 8575The first argument is the character to be 8576printed, and the second argument is the distance away from the main body 8577text. With no arguments the margin characters are turned off. If this 8578occurs before a break, no margin character is printed. 8579 8580@pindex nrchbar 8581@pindex changebar 8582This is quite useful for indicating text that has changed, and, in fact, 8583there are programs available for doing this (they are called 8584@code{nrchbar} and @code{changebar} and can be found in any 8585@samp{comp.sources.unix} archive. 8586 8587@c XXX example 8588 8589@ignore 8590@Example 8591... margin char example ... 8592@endExample 8593@end ignore 8594@endDefreq 8595 8596@pindex soelim 8597@cindex multi-file documents 8598@cindex documents, multi-file 8599@Defreq {lf, line filename} 8600A debugging aid for 8601documents which are split into many files, then put together 8602with @code{soelim} and other preprocessors. The second argument is the 8603name of the file and the first argument is the input line number in 8604that file. This way @code{gtroff} can produce error messages which are 8605intelligible to the user. 8606 8607@c XXX example 8608 8609@ignore 8610@Example 8611... example of soelim'ed doc ... 8612@endExample 8613@end ignore 8614@endDefreq 8615 8616 8617@c ===================================================================== 8618 8619@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 8620@section @code{gtroff} Internals 8621 8622@cindex input token 8623@cindex token, input 8624@cindex output node 8625@cindex node, output 8626@code{gtroff} processes input in three steps. One or more input 8627characters are converted to an @dfn{input token}. Then, one or more 8628input tokens are converted to an @dfn{output node}. Finally, output 8629nodes are converted to the intermediate output language understood by 8630all output devices. 8631 8632For example, the input string @samp{fi\[:u]} is converted in a 8633character token @samp{f}, a character token @samp{i}, and a special 8634token @samp{:u} (representing u@w{ }umlaut). Later on, the character 8635tokens @samp{f} and @samp{i} are merged to a single output node 8636representing the ligature glyph @samp{fi}; the same happens with 8637@samp{:u}. All output glyph nodes are `processed' which means that 8638they are invariably associated with a given font, font size, advance 8639width, etc. During the formatting process, @code{gtroff} itself adds 8640various nodes to control the data flow. 8641 8642Macros, diversions, and strings collect elements in two chained lists: 8643a list of input tokens which have been passed unprocessed, and a list 8644of output nodes. Consider the following the diversion. 8645 8646@Example 8647.di xxx 8648a 8649\!b 8650c 8651.br 8652.di 8653@endExample 8654 8655@noindent 8656It contains these elements. 8657 8658@multitable {@i{vertical size node}} {token list} {element number} 8659@item node list @tab token list @tab element number 8660 8661@item @i{line start node} @tab --- @tab 1 8662@item @i{glyph node @code{a}} @tab --- @tab 2 8663@item @i{word space node} @tab --- @tab 3 8664@item --- @tab @code{b} @tab 4 8665@item --- @tab @code{\n} @tab 5 8666@item @i{glyph node @code{c}} @tab --- @tab 6 8667@item @i{vertical size node} @tab --- @tab 7 8668@item @i{vertical size node} @tab --- @tab 8 8669@item --- @tab @code{\n} @tab 9 8670@end multitable 8671 8672@esindex \v 8673@rqindex unformat 8674@noindent 8675Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two 8676(which are always present) specify the vertical extent of the last 8677line, possibly modified by @code{\v}. The @code{br} request finishes 8678the current partial line, inserting a newline input token which is 8679subsequently converted to a space when the diversion is reread. Note 8680that the word space node has a fixed width which isn't stretchable 8681anymore. To convert horizontal space nodes back to input tokens, use 8682the @code{unformat} request. 8683 8684Macros only contain elements in the token list (and the node list is 8685empty); diversions and strings can contain elements in both lists. 8686 8687 8688@c ===================================================================== 8689 8690@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 8691@section Debugging 8692@cindex debugging 8693 8694@code{gtroff} is not easy to debug, but there are some useful features 8695and strategies for debugging. 8696 8697@Defreq {tm, string} 8698Sends the @var{string} to the standard error stream; 8699this is very useful for printing debugging output among other things. 8700@endDefreq 8701 8702@cindex aborting 8703@Defreq {ab, [@Var{string}]} 8704Similar to the @code{tm} request, except that 8705it causes @code{gtroff} to stop processing. With no argument it 8706prints @samp{User Abort}. 8707@endDefreq 8708 8709@cindex @code{ex}, use in debugging 8710@cindex exiting 8711@Defreq {ex, } 8712The @code{ex} request also causes @code{gtroff} to stop processing 8713if encountered at the topmost level; see also @ref{I/O}. 8714@endDefreq 8715 8716When doing something involved it is useful to leave the debugging 8717statements in the code and have them turned on by a command line flag. 8718 8719@Example 8720.if \n(DB .tm debugging output 8721@endExample 8722 8723@noindent 8724To activate these statements say 8725 8726@Example 8727groff -rDB=1 file 8728@endExample 8729 8730@c XXX .tm1, .tmc requests 8731 8732If it is known in advance that there will be many errors and no useful 8733output, @code{gtroff} can be forced to suppress formatted output with 8734the @option{-z} flag. 8735 8736@cindex dumping symbol table 8737@cindex symbol table, dumping 8738@Defreq {pm, } 8739The @code{pm} request prints out the entire symbol table on @code{stderr}. 8740@endDefreq 8741 8742@cindex dumping number registers 8743@cindex number registers, dumping 8744@Defreq {pnr, } 8745Prints the names and contents of all 8746currently defined number registers on @code{stderr}. 8747@endDefreq 8748 8749@cindex dumping traps 8750@cindex traps, dumping 8751@Defreq {ptr, } 8752Prints the names and positions of all traps 8753(not including input line traps and diversion traps) on @code{stderr}. 8754Empty slots in the page trap list are printed as well, because they can 8755affect the priority of subsequently planted traps. 8756@endDefreq 8757 8758@cindex flush output 8759@cindex output, flush 8760@cindex interactive use of @code{gtroff} 8761@cindex @code{gtroff}, interactive use 8762@Defreq {fl, } 8763Instructs @code{gtroff} to flush its output 8764immediately. The intent is for interactive use. 8765@code{gtroff}; there is little other use for it. This 8766request causes a line break. 8767@endDefreq 8768 8769@cindex backtrace of input stack 8770@cindex input stack, backtrace 8771@Defreq {backtrace, } 8772The @code{backtrace} request prints a backtrace of the input stack 8773to the standard error stream. 8774@endDefreq 8775 8776@cindex warnings 8777@code{gtroff} has command line options for printing out more warnings 8778(@option{-w}) and for printing backtraces (@option{-b}) when a warning 8779or an error occurs. The most verbose level of warnings is @option{-ww}. 8780 8781@cindex level of warnings 8782@cindex warnings, level 8783@Defreq {warn, [@Var{flags}]} 8784@Defregx {.warn} 8785Controls the level of warnings checked for. The @var{flags} are the sum 8786of the numbers associated with each warning that is to be enabled; all 8787other warnings are disabled. The number associated with each warning is 8788listed below. For example, @w{@code{.warn 0}} disables all warnings, 8789and @w{@code{.warn 1}} disables all warnings except that about missing 8790characters. If an argument is not given, all warnings are enabled. 8791 8792The read-only number register @code{.warn} contains the current warning 8793level. 8794@endDefreq 8795 8796@menu 8797* Warnings:: 8798@end menu 8799 8800@c --------------------------------------------------------------------- 8801 8802@node Warnings, , Debugging, Debugging 8803@subsection Warnings 8804@cindex warnings 8805 8806The warnings that can be given to @code{gtroff} are divided into the 8807following categories. The name associated with each warning is used by 8808the @option{-w} and @option{-W} options; the number is used by the 8809@code{warn} request and by the @code{.warn} register. 8810 8811@table @samp 8812@item char 8813@itemx 1 8814Non-existent characters. This is enabled by default. 8815 8816@item number 8817@itemx 2 8818Invalid numeric expressions. This is enabled by default. 8819@xref{Expressions}. 8820 8821@item break 8822@itemx 4 8823@cindex fill mode 8824@cindex mode, fill 8825In fill mode, lines which could not be broken so that their length was 8826less than the line length. This is enabled by default. 8827 8828@item delim 8829@itemx 8 8830Missing or mismatched closing delimiters. 8831 8832@item el 8833@itemx 16 8834@rqindex ie 8835@rqindex el 8836Use of the @code{el} request with no matching @code{ie} request. 8837@xref{if-else}. 8838 8839@item scale 8840@itemx 32 8841Meaningless scaling indicators. 8842 8843@item range 8844@itemx 64 8845Out of range arguments. 8846 8847@item syntax 8848@itemx 128 8849Dubious syntax in numeric expressions. 8850 8851@item di 8852@itemx 256 8853@rqindex di 8854@rqindex da 8855@cindex @code{di}, debugging 8856@cindex @code{da}, debugging 8857Use of @code{di} or @code{da} without an argument when there is no 8858current diversion. 8859 8860@item mac 8861@itemx 512 8862@rqindex de 8863@c XXX more index entries 8864Use of undefined strings, macros and diversions. When an undefined 8865string, macro or diversion is used, that string is automatically defined 8866as empty. So, in most cases, at most one warning is given for each 8867name. 8868 8869@item reg 8870@itemx 1024 8871@rqindex nr 8872@c XXX more index entries 8873Use of undefined number registers. When an undefined number register is 8874used, that register is automatically defined to have a value of@w{ }0. 8875A definition is automatically made with a value of@w{ }0. So, in most 8876cases, at most one warning is given for use of a particular name. 8877 8878@item tab 8879@itemx 2048 8880Use of a tab character where a number was expected. 8881 8882@item right-brace 8883@itemx 4096 8884@esindex \@} 8885@cindex @code{\@}}, debugging 8886Use of @code{\@}} where a number was expected. 8887 8888@item missing 8889@itemx 8192 8890Requests that are missing non-optional arguments. 8891 8892@item input 8893@itemx 16384 8894Illegal input characters. 8895 8896@item escape 8897@itemx 32768 8898Unrecognized escape sequences. When an unrecognized escape sequence is 8899encountered, the escape character is ignored. 8900 8901@item space 8902@itemx 65536 8903@cindex compatibility mode 8904Missing space between a request or macro and its argument. This warning 8905is given when an undefined name longer than two characters is 8906encountered, and the first two characters of the name make a defined 8907name. The request or macro is not invoked. When this warning is 8908given, no macro is automatically defined. This is enabled by default. 8909This warning never occurs in compatibility mode. 8910 8911@item font 8912@itemx 131072 8913Non-existent fonts. This is enabled by default. 8914 8915@item all 8916All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 8917intended that this covers all warnings that are useful with traditional 8918macro packages. 8919 8920@item w 8921All warnings. 8922@end table 8923 8924 8925@c ===================================================================== 8926 8927@node Implementation Differences, Summary, Debugging, gtroff Reference 8928@section Implementation Differences 8929@cindex implementation differences 8930@cindex differences in implementation 8931@cindex incompatibilities with Unix @code{troff} 8932@cindex compatibility mode 8933@cindex mode, compatibility 8934 8935GNU @code{troff} has a number of features which cause incompatibilities 8936with documents written with old versions of @code{troff}. 8937 8938@cindex long names 8939@cindex names, long 8940Long names cause some incompatibilities. @acronym{UNIX} @code{troff} 8941interprets 8942 8943@Example 8944.dsabcd 8945@endExample 8946 8947@esindex \* 8948@esindex \n 8949@cindex @code{\*}, incompatibilities with Unix @code{troff} 8950@cindex @code{\n}, incompatibilities with Unix @code{troff} 8951@rqindex cp 8952@vindex .C 8953@noindent 8954as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 8955@code{troff} interprets this as a call of a macro named 8956@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 8957@code{\*[} or @code{\n[} as references to a string or number register 8958called @samp{[}. In GNU @code{troff}, however, this is normally 8959interpreted as the start of a long name. In compatibility mode GNU 8960@code{troff} interprets long names in the traditional way 8961(which means that they are not recognized as names). 8962Compatibility mode can be turned on with the @option{-C} command line 8963option, and turned on or off with the @code{cp} request. The number 8964register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{ 8965}otherwise. 8966 8967@esindex \A 8968@esindex \| 8969@esindex \^ 8970@esindex \& 8971@esindex \@{ 8972@esindex \@} 8973@esindex \@key{SP} 8974@esindex \' 8975@esindex \` 8976@esindex \- 8977@esindex \_ 8978@esindex \! 8979@esindex \% 8980@esindex \c 8981GNU @code{troff} does not allow the use of the escape sequences 8982@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 8983@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 8984@code{\%}, and @code{\c} in names of strings, macros, diversions, number 8985registers, fonts or environments; @acronym{UNIX} @code{troff} does. The 8986@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 8987avoiding use of these escape sequences in names. 8988 8989@cindex fractional point sizes 8990@cindex point sizes, fractional 8991@rqindex ps 8992@cindex @code{ps}, incompatibilities with Unix @code{troff} 8993Fractional point sizes cause one noteworthy incompatibility. In 8994@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 8995indicators and thus 8996 8997@Example 8998.ps 10u 8999@endExample 9000 9001@noindent 9002sets the point size to 10@w{ }points, whereas in GNU @code{troff} it 9003sets the point size to 10@w{ }scaled points. @xref{Fractional Type 9004Sizes}, for more information. 9005 9006@rqindex bd 9007@rqindex cs 9008@rqindex tkf 9009@rqindex tr 9010@rqindex fp 9011@cindex @code{bd}, incompatibilities with Unix @code{troff} 9012@cindex @code{cs}, incompatibilities with Unix @code{troff} 9013@cindex @code{tkf}, incompatibilities with Unix @code{troff} 9014@cindex @code{tr}, incompatibilities with Unix @code{troff} 9015@cindex @code{fp}, incompatibilities with Unix @code{troff} 9016@cindex input and output characters, compatibility with Unix 9017@cindex output characters, compatibility with Unix 9018@cindex characters, input and output, compatibility with Unix 9019In GNU @code{troff} there is a fundamental difference between 9020unformatted, input characters, and formatted, output characters. 9021Everything that affects how an output character is output is stored 9022with the character; once an output character has been constructed it is 9023unaffected by any subsequent requests that are executed, including 9024@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 9025Normally output characters are constructed from input characters at the 9026moment immediately before the character is added to the current output 9027line. Macros, diversions and strings are all, in fact, the same type of 9028object; they contain lists of input characters and output characters in 9029any combination. An output character does not behave like an input 9030character for the purposes of macro processing; it does not inherit any 9031of the special properties that the input character from which it was 9032constructed might have had. For example, 9033 9034@Example 9035.di x 9036\\\\ 9037.br 9038.di 9039.x 9040@endExample 9041 9042@esindex \e 9043@esindex \! 9044@esindex \? 9045@cindex @code{\e}, incompatibilities with Unix @code{troff} 9046@cindex @code{\!}, incompatibilities with Unix @code{troff} 9047@cindex @code{\?}, incompatibilities with Unix @code{troff} 9048@cindex transparent output, incompatibilities with Unix @code{troff} 9049@cindex output, transparent, incompatibilities with Unix @code{troff} 9050@noindent 9051prints @samp{\\} in GNU @code{troff}; each pair of input backslashes 9052is turned into one output backslash and the resulting output backslashes 9053are not interpreted as escape characters when they are reread. 9054@acronym{UNIX} @code{troff} would interpret them as escape characters 9055when they were reread and would end up printing one @samp{\}. The 9056correct way to obtain a printable backslash is to use the @code{\e} 9057escape sequence: This always prints a single instance of the current 9058escape character, regardless of whether or not it is used in a 9059diversion; it also works in both GNU @code{troff} and @acronym{UNIX} 9060@code{troff}. To store, for some reason, an escape sequence in a 9061diversion that will be interpreted when the diversion is reread, either 9062use the traditional @code{\!} transparent output facility, or, if this 9063is unsuitable, the new @code{\?} escape sequence. 9064 9065@c XXX .tl compatibility mode -> input stack level 9066@c XXX .if compatibility mode -> input stack level 9067 9068@xref{Diversions}, for more information. 9069 9070 9071@c ===================================================================== 9072 9073@node Summary, , Implementation Differences, gtroff Reference 9074@section Summary 9075@cindex summary 9076 9077@c XXX documentation 9078 9079 9080 9081@c ===================================================================== 9082@c ===================================================================== 9083 9084@node Preprocessors, Output Devices, gtroff Reference, Top 9085@chapter Preprocessors 9086@cindex preprocessors 9087 9088This chapter describes all preprocessors that come with @code{groff} or 9089which are freely available. 9090 9091@menu 9092* geqn:: 9093* gtbl:: 9094* gpic:: 9095* ggrn:: 9096* grap:: 9097* grefer:: 9098* gsoelim:: 9099@end menu 9100 9101 9102@c ===================================================================== 9103 9104@node geqn, gtbl, Preprocessors, Preprocessors 9105@section @code{geqn} 9106@cindex @code{eqn} 9107@cindex @code{geqn} 9108 9109@c XXX 9110 9111@menu 9112* Invoking geqn:: 9113@end menu 9114 9115@c --------------------------------------------------------------------- 9116 9117@node Invoking geqn, , geqn, geqn 9118@subsection Invoking @code{geqn} 9119@cindex invoking @code{geqn} 9120@cindex @code{geqn}, invoking 9121 9122@c XXX 9123 9124 9125@c ===================================================================== 9126 9127@node gtbl, gpic, geqn, Preprocessors 9128@section @code{gtbl} 9129@cindex @code{tbl} 9130@cindex @code{gtbl} 9131 9132@c XXX 9133 9134@menu 9135* Invoking gtbl:: 9136@end menu 9137 9138@c --------------------------------------------------------------------- 9139 9140@node Invoking gtbl, , gtbl, gtbl 9141@subsection Invoking @code{gtbl} 9142@cindex invoking @code{gtbl} 9143@cindex @code{gtbl}, invoking 9144 9145@c XXX 9146 9147 9148@c ===================================================================== 9149 9150@node gpic, ggrn, gtbl, Preprocessors 9151@section @code{gpic} 9152@cindex @code{pic} 9153@cindex @code{gpic} 9154 9155@c XXX 9156 9157@menu 9158* Invoking gpic:: 9159@end menu 9160 9161@c --------------------------------------------------------------------- 9162 9163@node Invoking gpic, , gpic, gpic 9164@subsection Invoking @code{gpic} 9165@cindex invoking @code{gpic} 9166@cindex @code{gpic}, invoking 9167 9168@c XXX 9169 9170 9171@c ===================================================================== 9172 9173@node ggrn, grap, gpic, Preprocessors 9174@section @code{ggrn} 9175@cindex @code{grn} 9176@cindex @code{ggrn} 9177 9178@c XXX 9179 9180@menu 9181* Invoking ggrn:: 9182@end menu 9183 9184@c --------------------------------------------------------------------- 9185 9186@node Invoking ggrn, , ggrn, ggrn 9187@subsection Invoking @code{ggrn} 9188@cindex invoking @code{ggrn} 9189@cindex @code{ggrn}, invoking 9190 9191@c XXX 9192 9193 9194@c ===================================================================== 9195 9196@node grap, grefer, ggrn, Preprocessors 9197@section @code{grap} 9198@cindex @code{grap} 9199 9200A free implementation of @code{grap}, written by Ted Faber, 9201is available as an extra package from the following address: 9202 9203@display 9204@url{http://www.lunabase.org/~faber/Vault/software/grap/} 9205@end display 9206 9207 9208@c ===================================================================== 9209 9210@node grefer, gsoelim, grap, Preprocessors 9211@section @code{grefer} 9212@cindex @code{refer} 9213@cindex @code{grefer} 9214 9215@c XXX 9216 9217@menu 9218* Invoking grefer:: 9219@end menu 9220 9221@c --------------------------------------------------------------------- 9222 9223@node Invoking grefer, , grefer, grefer 9224@subsection Invoking @code{grefer} 9225@cindex invoking @code{grefer} 9226@cindex @code{grefer}, invoking 9227 9228@c XXX 9229 9230 9231@c ===================================================================== 9232 9233@node gsoelim, , grefer, Preprocessors 9234@section @code{gsoelim} 9235@cindex @code{soelim} 9236@cindex @code{gsoelim} 9237 9238@c XXX 9239 9240@menu 9241* Invoking gsoelim:: 9242@end menu 9243 9244@c --------------------------------------------------------------------- 9245 9246@node Invoking gsoelim, , gsoelim, gsoelim 9247@subsection Invoking @code{gsoelim} 9248@cindex invoking @code{gsoelim} 9249@cindex @code{gsoelim}, invoking 9250 9251@c XXX 9252 9253 9254 9255@c ===================================================================== 9256@c ===================================================================== 9257 9258@node Output Devices, File formats, Preprocessors, Top 9259@chapter Output Devices 9260@cindex output devices 9261@cindex devices for output 9262 9263@c XXX 9264 9265@menu 9266* Special Characters:: 9267* grotty:: 9268* grops:: 9269* grodvi:: 9270* grolj4:: 9271* grolbp:: 9272* grohtml:: 9273* gxditview:: 9274@end menu 9275 9276 9277@c ===================================================================== 9278 9279@node Special Characters, grotty, Output Devices, Output Devices 9280@section Special Characters 9281@cindex special characters 9282@cindex characters, special 9283 9284@c XXX 9285 9286@xref{Font Files}. 9287 9288 9289@c ===================================================================== 9290 9291@node grotty, grops, Special Characters, Output Devices 9292@section @code{grotty} 9293@cindex @code{grotty} 9294 9295@c XXX 9296 9297@menu 9298* Invoking grotty:: 9299@end menu 9300 9301@c --------------------------------------------------------------------- 9302 9303@node Invoking grotty, , grotty, grotty 9304@subsection Invoking @code{grotty} 9305@cindex invoking @code{grotty} 9306@cindex @code{grotty}, invoking 9307 9308@c XXX 9309 9310 9311@c ===================================================================== 9312 9313@node grops, grodvi, grotty, Output Devices 9314@section @code{grops} 9315@cindex @code{grops} 9316 9317@c XXX 9318 9319@menu 9320* Invoking grops:: 9321* Embedding PostScript:: 9322@end menu 9323 9324@c --------------------------------------------------------------------- 9325 9326@node Invoking grops, Embedding PostScript, grops, grops 9327@subsection Invoking @code{grops} 9328@cindex invoking @code{grops} 9329@cindex @code{grops}, invoking 9330 9331@c XXX 9332 9333@c --------------------------------------------------------------------- 9334 9335@node Embedding PostScript, , Invoking grops, grops 9336@subsection Embedding @sc{PostScript} 9337@cindex embedding postscript 9338@cindex postscript, embedding 9339 9340@c XXX 9341 9342 9343@c ===================================================================== 9344 9345@node grodvi, grolj4, grops, Output Devices 9346@section @code{grodvi} 9347@cindex @code{grodvi} 9348 9349@c XXX 9350 9351@menu 9352* Invoking grodvi:: 9353@end menu 9354 9355@c --------------------------------------------------------------------- 9356 9357@node Invoking grodvi, , grodvi, grodvi 9358@subsection Invoking @code{grodvi} 9359@cindex invoking @code{grodvi} 9360@cindex @code{grodvi}, invoking 9361 9362@c XXX 9363 9364 9365@c ===================================================================== 9366 9367@node grolj4, grolbp, grodvi, Output Devices 9368@section @code{grolj4} 9369@cindex @code{grolj4} 9370 9371@c XXX 9372 9373@menu 9374* Invoking grolj4:: 9375@end menu 9376 9377@c --------------------------------------------------------------------- 9378 9379@node Invoking grolj4, , grolj4, grolj4 9380@subsection Invoking @code{grolj4} 9381@cindex invoking @code{grolj4} 9382@cindex @code{grolj4}, invoking 9383 9384@c XXX 9385 9386 9387@c ===================================================================== 9388 9389@node grolbp, grohtml, grolj4, Output Devices 9390@section @code{grolbp} 9391@cindex @code{grolbp} 9392 9393@c XXX 9394 9395@menu 9396* Invoking grolbp:: 9397@end menu 9398 9399@c --------------------------------------------------------------------- 9400 9401@node Invoking grolbp, , grolbp, grolbp 9402@subsection Invoking @code{grolbp} 9403@cindex invoking @code{grolbp} 9404@cindex @code{grolbp}, invoking 9405 9406@c XXX 9407 9408 9409@c ===================================================================== 9410 9411@node grohtml, gxditview, grolbp, Output Devices 9412@section @code{grohtml} 9413@cindex @code{grohtml} 9414 9415@c XXX 9416 9417@menu 9418* Invoking grohtml:: 9419@end menu 9420 9421@c --------------------------------------------------------------------- 9422 9423@node Invoking grohtml, , grohtml, grohtml 9424@subsection Invoking @code{grohtml} 9425@cindex invoking @code{grohtml} 9426@cindex @code{grohtml}, invoking 9427 9428@c XXX 9429 9430 9431@c ===================================================================== 9432 9433@node gxditview, , grohtml, Output Devices 9434@section @code{gxditview} 9435@cindex @code{gxditview} 9436 9437@c XXX 9438 9439@menu 9440* Invoking gxditview:: 9441@end menu 9442 9443@c --------------------------------------------------------------------- 9444 9445@node Invoking gxditview, , gxditview, gxditview 9446@subsection Invoking @code{gxditview} 9447@cindex invoking @code{gxditview} 9448@cindex @code{gxditview}, invoking 9449 9450@c XXX 9451@c X11's xditview 9452 9453 9454 9455@c ===================================================================== 9456@c ===================================================================== 9457 9458@node File formats, Installation, Output Devices, Top 9459@chapter File formats 9460@cindex file formats 9461@cindex formats, file 9462 9463@c XXX 9464 9465@menu 9466* gtroff Output:: 9467* Font Files:: 9468@end menu 9469 9470 9471@c ===================================================================== 9472 9473@node gtroff Output, Font Files, File formats, File formats 9474@section @code{gtroff} Output 9475@cindex @code{gtroff} output 9476@cindex output, @code{gtroff} 9477 9478This section describes the format output of GNU @code{troff}. The 9479output format used by GNU @code{troff} is very similar -- but 9480not identical -- to that used by 9481@acronym{UNIX} device-independent @code{troff} (@code{ditroff}). 9482 9483@menu 9484* Output Format:: 9485* Device Control:: 9486* Drawing Functions:: 9487* Line Continuation:: 9488@end menu 9489 9490@c --------------------------------------------------------------------- 9491 9492@node Output Format, Device Control, gtroff Output, gtroff Output 9493@subsection Output Format 9494@cindex output format 9495@cindex format of output 9496 9497@cindex 8-bit input 9498@cindex input, 8-bit 9499The output format is text based, as opposed to a binary format (like 9500@TeX{} DVI). The output format is @w{8-bit} clean, thus single 9501characters can have the eighth bit set, as can the names of fonts and 9502special characters. 9503 9504The output format consists of single command characters with attached 9505parameters which are separated from subsequent text by whitespace or a 9506newline. 9507 9508The names of characters and fonts can be of arbitrary length; drivers 9509should not assume that they are only two characters long (as 9510@code{ditroff} does). 9511 9512When a character is to be printed, that character is always in the 9513current font. Unlike @code{ditroff}, it is not necessary for drivers to 9514search special fonts to find a character. 9515 9516@table @code 9517@item H@var{n} 9518@c XXX 9519 9520@item V@var{n} 9521@c XXX 9522 9523@item h@var{n} 9524@c XXX 9525 9526@item v@var{n} 9527@c XXX 9528 9529@item c@var{n} 9530@c XXX 9531 9532@item C@var{n} 9533@c XXX 9534 9535@item @var{nn}@var{c} 9536@c XXX 9537 9538@item t@var{xxx} 9539@var{xxx} is any sequence of characters terminated by a space or a 9540newline; the first character should be printed at the current position, 9541the the current horizontal position should be increased by the width of 9542the first character, and so on for each character. The width of the 9543character is that given in the font file, appropriately scaled for the 9544current point size, and rounded so that it is a multiple of the 9545horizontal resolution. Special characters cannot be printed using this 9546command. 9547 9548@kindex tcommand 9549@pindex DESC@r{, and @code{tcommand}} 9550This command is only allowed if the @samp{tcommand} line is present in 9551the @file{DESC} file. 9552 9553@item u@var{n} @var{xxx} 9554This is same as the @samp{t} command except that after printing each 9555character, the current horizontal position is increased by the sum of 9556the width of that character and@w{ }@var{n}. 9557 9558This command is only allowed if the @samp{tcommand} line is present in 9559the @file{DESC} file. 9560 9561@item n@var{a}@var{b} 9562@c XXX 9563 9564@item p@var{n} 9565@c XXX 9566 9567@item s@var{n} 9568@kindex sizescale 9569@pindex DESC@r{, and @code{sizescale}} 9570The argument to the @samp{s} command is in scaled points (units of 9571points/@var{n}, where @var{n} is the argument to the @samp{sizescale} 9572command in the @file{DESC} file). 9573 9574@item f@var{n} 9575@item x @dots{} \n 9576Device control. 9577@c XXX more info 9578 9579@item D@var{c} @var{x}@dots{}\n 9580@c XXX 9581@end table 9582 9583@c --------------------------------------------------------------------- 9584 9585@node Device Control, Drawing Functions, Output Format, gtroff Output 9586@subsection Device Control 9587@cindex device control 9588@cindex control of devices 9589 9590The @samp{x} command is normally followed by a letter or word indicating 9591the function to perform, followed by white space separated arguments. 9592 9593The first argument can be abbreviated to the first letter. 9594 9595@table @code 9596@item x init 9597@c XXX 9598 9599@item x T 9600@c XXX 9601 9602@item x res @var{n} @var{h} @var{v} 9603@c XXX 9604 9605@item x H 9606@c XXX more info 9607The argument to the @w{@samp{x Height}} command is also in scaled 9608points. 9609@end table 9610 9611The first three output commands are guaranteed to be: 9612 9613@Example 9614x T device 9615x res n h v 9616x init 9617@endExample 9618 9619@noindent 9620For example, the input 9621 9622@Example 9623crunchy \fH\s+2frog\s0\fP!? 9624@endExample 9625 9626@noindent 9627produces 9628 9629@c XXX example 9630 9631@ignore 9632@Example 9633... sample output here ... 9634@endExample 9635@end ignore 9636 9637@c --------------------------------------------------------------------- 9638 9639@node Drawing Functions, Line Continuation, Device Control, gtroff Output 9640@subsection Drawing Functions 9641@cindex drawing functions 9642@cindex functions for drawing 9643 9644@pindex gpic 9645The @samp{D} drawing command has been extended. These extensions are 9646used by GNU @code{pic} only if the @option{-x} option is given. 9647 9648@xref{Drawing Requests}. 9649 9650@table @code 9651@c XXX ... 9652@item Df @var{n} 9653Set the shade of gray to be used for filling solid objects to@w{ 9654}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 9655corresponds solid white and 1000 to solid black, and values in between 9656correspond to intermediate shades of gray. This applies only to solid 9657circles, solid ellipses and solid polygons. By default, a level of@w{ 9658}1000 is used. Whatever color a solid object has, it should 9659completely obscure everything beneath it. A value greater than@w{ }1000 9660or less than@w{ }0 can also be used: this means fill with the shade of 9661gray that is currently being used for lines and text. Normally this 9662is black, but some drivers may provide a way of changing this. 9663 9664@item DC @var{d} 9665Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost 9666point at the current position. 9667 9668@item DE @var{dx} @var{dy} 9669Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a 9670vertical diameter of@w{ }@var{dy} with the leftmost point at the current 9671position. 9672 9673@item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn} 9674Draw a polygon with automatic closure. The first vertex is at the 9675current position, the second vertex at an offset (@var{dx1},@var{dy1}) 9676from the current position, the second vertex at an offset 9677(@var{dx2},@var{dy2}) from the first vertex, and so on up to the 9678@var{n}@dmn{th} vertex. At the moment, GNU @code{pic} only uses this 9679command to generate triangles and rectangles. 9680 9681@item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn} 9682Like @code{Dp} but draw a solid rather than outlined polygon. 9683 9684@item Dt @var{n} 9685@cindex line thickness 9686@cindex thickness of lines 9687Set the current line thickness to @var{n}@w{ }machine units. 9688Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness 9689proportional to the current point size; drivers should continue to do 9690this if no @code{Dt} command has been given, or if a @code{Dt} command 9691has been given with a negative value of@w{ }@var{n}. A zero value of@w{ 9692}@var{n} selects the smallest available line thickness. 9693@end table 9694 9695@esindex \D 9696A difficulty arises in how the current position should be changed after 9697the execution of these commands. This is not of great importance since 9698the code generated by GNU @code{pic} does not depend on this. Given a 9699drawing command of the form 9700 9701@Example 9702\D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}' 9703@endExample 9704 9705@esindex \w 9706@vindex st 9707@vindex sb 9708@noindent 9709where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or 9710@samp{~}, @acronym{UNIX} @code{troff} treats each x@w{ }value 9711as a horizontal quantity, and each y@w{ }value as a vertical 9712quantity; it assumes that the width of the drawn object is the sum of 9713all x@w{ }values, and that the height is the sum of all y@w{ }values. 9714(The assumption about the height can be seen by examining the @code{st} 9715and @code{sb} registers after using such a @code{D}@w{ }command in a 9716@code{\w} escape sequence.) This rule also holds for all the original 9717drawing commands with the exception of @code{De}. For the sake of 9718compatibility GNU @code{troff} also follows this rule, even though it 9719produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to 9720a lesser extent, @code{DE}@w{ }commands. Thus after executing a 9721@code{D}@w{ }command of the form 9722 9723@Example 9724D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn} 9725@endExample 9726 9727@noindent 9728the current position should be increased horizontally by the sum of all 9729x@w{ }values and vertically by the sum of all y@w{ }values. 9730 9731@c --------------------------------------------------------------------- 9732 9733@node Line Continuation, , Drawing Functions, gtroff Output 9734@subsection Line Continuation 9735@cindex line continuation in output commands 9736@cindex output commands, line continuation 9737 9738There is a continuation convention which permits the argument to the 9739@w{@samp{x X}} command to contain newlines: When outputting the argument 9740to the @w{@samp{x X}} command, GNU @code{troff} follows each newline 9741in the argument with a @samp{+} character (as usual, it terminates 9742the entire argument with a newline); thus if the line after the line 9743containing the @w{@samp{x X}} command starts with @samp{+}, then the 9744newline ending the line containing the @w{@samp{x X}} command should be 9745treated as part of the argument to the @w{@samp{x X}} command, the 9746@samp{+} should be ignored, and the part of the line following the 9747@samp{+} should be treated like the part of the line following the 9748@w{@samp{x X}} command. 9749 9750 9751@c ===================================================================== 9752 9753@node Font Files, , gtroff Output, File formats 9754@section Font Files 9755@cindex font files 9756@cindex files, font 9757 9758The @code{gtroff} font format is roughly a superset of the 9759@code{ditroff} font format. Unlike the @code{ditroff} font format, 9760there is no associated binary format; all files are text files. The 9761font files for device @var{name} are stored in a directory 9762@file{dev@var{name}}. There are two types of file: a device description 9763file called @file{DESC} and for each font@w{ }@var{f} a font file 9764called@w{ }@file{@var{f}}. 9765 9766@menu 9767* DESC File Format:: 9768* Font File Format:: 9769@end menu 9770 9771@c --------------------------------------------------------------------- 9772 9773@node DESC File Format, Font File Format, Font Files, Font Files 9774@subsection @file{DESC} File Format 9775@cindex @file{DESC} file format 9776@cindex font description file format 9777@cindex format of font description file 9778@pindex DESC@r{ file format} 9779 9780The @file{DESC} file can contain the following types of line: 9781 9782@table @code 9783@item res @var{n} 9784@kindex res 9785There are @var{n} machine units per inch. 9786 9787@item hor @var{n} 9788@kindex hor 9789The horizontal resolution is @var{n} machine units. 9790 9791@item vert @var{n} 9792@kindex vert 9793The vertical resolution is @var{n} machine units. 9794 9795@item sizescale @var{n} 9796@kindex sizescale 9797The scale factor for point sizes. By default this has a value of@w{ }1. 9798One scaled point is equal to one point/@var{n}. The arguments to the 9799@code{unitwidth} and @code{sizes} commands are given in scaled points. 9800@xref{Fractional Type Sizes}, for more information. 9801 9802@item unitwidth @var{n} 9803@kindex unitwidth 9804Quantities in the font files are given in machine units for fonts whose 9805point size is @var{n}@w{ }scaled points. 9806 9807@item tcommand 9808@kindex tcommand 9809This means that the postprocessor can handle the @samp{t} and @samp{u} 9810output commands. 9811 9812@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 9813@kindex sizes 9814This means that the device has fonts at @var{s1}, @var{s2}, @dots{} 9815@var{sn} scaled points. The list of sizes must be terminated by a@w{ 9816}0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The 9817list can extend over more than one line. 9818 9819@item styles @var{S1} @var{S2} @dots{} @var{Sm} 9820@kindex styles 9821The first @var{m}@w{ }font positions are associated with styles 9822@var{S1} @dots{} @var{Sm}. 9823 9824@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 9825@kindex fonts 9826Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 9827@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 9828styles. This command may extend over more than one line. A font name 9829of@var{ }0 means no font is mounted on the corresponding font position. 9830 9831@item family @var{fam} 9832@kindex family 9833The default font family is @var{fam}. 9834 9835@item charset 9836@kindex charset 9837This line and everything following in the file are ignored. It is 9838allowed for the sake of backwards compatibility. 9839@end table 9840 9841The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines 9842are mandatory. Other commands are ignored by @code{gtroff} but may be 9843used by postprocessors to store arbitrary information about the device 9844in the @file{DESC} file. 9845 9846@c XXX add other commands resp. xrefs to output devices 9847@c XXX add obsolete commands 9848 9849@c --------------------------------------------------------------------- 9850 9851@node Font File Format, , DESC File Format, Font Files 9852@subsection Font File Format 9853@cindex font file format 9854@cindex format of font files 9855 9856A font file has two sections. The first section is a sequence of lines 9857each containing a sequence of blank delimited words; the first word in 9858the line is a key, and subsequent words give a value for that key. 9859 9860@table @code 9861@item name @var{f} 9862@kindex name 9863The name of the font is@w{ }@var{f}. 9864 9865@item spacewidth @var{n} 9866@kindex spacewidth 9867The normal width of a space is@w{ }@var{n}. 9868 9869@item slant @var{n} 9870@kindex slant 9871The characters of the font have a slant of @var{n}@w{ }degrees. 9872(Positive means forward.) 9873 9874@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 9875@kindex ligatures 9876Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 9877possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 9878@samp{ffl}. For backwards compatibility, the list of ligatures may be 9879terminated with a@w{ }0. The list of ligatures may not extend over more 9880than one line. 9881 9882@item special 9883@kindex special 9884The font is special; this means that when a character is requested that 9885is not present in the current font, it is searched for in any 9886special fonts that are mounted. 9887@end table 9888 9889Other commands are ignored by @code{gtroff} but may be used by 9890postprocessors to store arbitrary information about the font in the font 9891file. 9892 9893@cindex comments in font files 9894@cindex font files, comments 9895@kindex # 9896The first section can contain comments which start with the @samp{#} 9897character and extend to the end of a line. 9898 9899The second section contains one or two subsections. It must contain a 9900@code{charset} subsection and it may also contain a @code{kernpairs} 9901subsection. These subsections can appear in any order. Each 9902subsection starts with a word on a line by itself. 9903 9904@kindex charset 9905The word @code{charset} starts the character set subsection. The 9906@code{charset} line is followed by a sequence of lines. Each line gives 9907information for one character. A line comprises a number of fields 9908separated by blanks or tabs. The format is 9909 9910@c XXX fix it for new HTML additions 9911 9912@Example 9913@var{name} @var{metrics} @var{type} @var{code} @var{comment} 9914@endExample 9915 9916@cindex 8-bit input 9917@cindex input, 8-bit 9918@esindex \N 9919@kindex --- 9920@noindent 9921@var{name} identifies the character: If @var{name} is a single 9922character@w{ }@var{c} then it corresponds to the @code{gtroff} input 9923character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is 9924a single character, then it corresponds to the @code{gtroff} input 9925character@w{ }\@var{c}; otherwise it corresponds to the groff input 9926character @samp{\[@var{name}]}. (If it is exactly two characters 9927@var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff} 9928supports 8-bit characters; however some utilities have difficulties with 9929eight-bit characters. For this reason, there is a convention that the 9930name @samp{char@var{n}} is equivalent to the single character whose code 9931is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the 9932character with code@w{ }163 which is the pounds sterling sign in @w{ISO 9933Latin-1} character set. The name @samp{---} is special and indicates 9934that the character is unnamed; such characters can only be used by means 9935of the @code{\N} escape sequence in @code{gtroff}. 9936 9937@c XXX input encodings vs. output encodings 9938 9939The @var{type} field gives the character type: 9940 9941@table @code 9942@item 1 9943the character has an descender, for example, `p'; 9944 9945@item 2 9946the character has an ascender, for example, `b'; 9947 9948@item 3 9949the character has both an ascender and a descender, for example, `('. 9950@end table 9951 9952The @var{code} field gives the code which the postprocessor uses to 9953print the character. The character can also be input to @code{gtroff} 9954using this code by means of the @code{\N} escape sequence. The code can 9955be any integer. If it starts with @samp{0} it is interpreted as 9956octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 9957hexadecimal. 9958 9959Anything on the line after the @var{code} field is ignored. 9960 9961The @var{metrics} field has the form: 9962 9963@Example 9964@var{width}[,@var{height}[,@var{depth}[,@var{italic_correction} 9965 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]] 9966@endExample 9967 9968@noindent 9969There must not be any spaces between these subfields (it has been split 9970here into two lines for better legibility only). Missing subfields are 9971assumed to be@w{ }0. The subfields are all decimal integers. Since 9972there is no associated binary format, these values are not required to 9973fit into a variable of type @samp{char} as they are in @code{ditroff}. 9974The @var{width} subfield gives the width of the character. The 9975@var{height} subfield gives the height of the character (upwards is 9976positive); if a character does not extend above the baseline, it should 9977be given a zero height, rather than a negative height. The @var{depth} 9978subfield gives the depth of the character, that is, the distance below 9979the lowest point below the baseline to which the character extends 9980(downwards is positive); if a character does not extend below above the 9981baseline, it should be given a zero depth, rather than a negative depth. 9982The @var{italic_correction} subfield gives the amount of space that 9983should be added after the character when it is immediately to be 9984followed by a character from a roman font. The 9985@var{left_italic_correction} subfield gives the amount of space that 9986should be added before the character when it is immediately to be 9987preceded by a character from a roman font. The 9988@var{subscript_correction} gives the amount of space that should be 9989added after a character before adding a subscript. This should be less 9990than the italic correction. 9991 9992A line in the @code{charset} section can also have the format 9993 9994@Example 9995@var{name} " 9996@endExample 9997 9998@noindent 9999This indicates that @var{name} is just another name for the character 10000mentioned in the preceding line. 10001 10002@kindex kernpairs 10003The word @code{kernpairs} starts the kernpairs section. This contains a 10004sequence of lines of the form: 10005 10006@Example 10007@var{c1} @var{c2} @var{n} 10008@endExample 10009 10010@noindent 10011This means that when character @var{c1} appears next to character 10012@var{c2} the space between them should be increased by@w{ }@var{n}. 10013Most entries in the kernpairs section have a negative value for@w{ 10014}@var{n}. 10015 10016 10017 10018@c ===================================================================== 10019@c ===================================================================== 10020 10021@node Installation, Request Index, File formats, Top 10022@chapter Installation 10023@cindex installation 10024 10025@c XXX 10026 10027 10028 10029@c ===================================================================== 10030@c ===================================================================== 10031 10032@node Request Index, Escape Index, Installation, Top 10033@chapter Request Index 10034 10035Requests appear without the leading control character (normally either 10036@samp{.} or @samp{'}). 10037 10038@printindex rq 10039 10040 10041 10042@c ===================================================================== 10043@c ===================================================================== 10044 10045@node Escape Index, Operator Index, Request Index, Top 10046@chapter Escape Index 10047 10048@printindex es 10049 10050 10051 10052@c ===================================================================== 10053@c ===================================================================== 10054 10055@node Operator Index, Register Index, Escape Index, Top 10056@chapter Operator Index 10057 10058@printindex op 10059 10060 10061 10062@c ===================================================================== 10063@c ===================================================================== 10064 10065@node Register Index, Macro Index, Operator Index, Top 10066@chapter Register Index 10067 10068@printindex vr 10069 10070 10071 10072@c ===================================================================== 10073@c ===================================================================== 10074 10075@node Macro Index, String Index, Register Index, Top 10076@chapter Macro Index 10077 10078@printindex ma 10079 10080 10081 10082@c ===================================================================== 10083@c ===================================================================== 10084 10085@node String Index, Glyph Name Index, Macro Index, Top 10086@chapter String Index 10087 10088@printindex st 10089 10090 10091 10092@c ===================================================================== 10093@c ===================================================================== 10094 10095@node Glyph Name Index, Font File Keyword Index, String Index, Top 10096@chapter Glyph Name Index 10097 10098A glyph name @code{xx} consisting of exactly two characters can be 10099accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 10100accessed as @samp{\[xxx]}. 10101 10102@printindex gl 10103 10104 10105 10106@c ===================================================================== 10107@c ===================================================================== 10108 10109@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 10110@chapter Font File Keyword Index 10111 10112@printindex ky 10113 10114 10115 10116@c ===================================================================== 10117@c ===================================================================== 10118 10119@node Program and File Index, Concept Index, Font File Keyword Index, Top 10120@chapter Program and File Index 10121 10122@printindex pg 10123 10124 10125 10126@c ===================================================================== 10127@c ===================================================================== 10128 10129@node Concept Index, , Program and File Index, Top 10130@chapter Concept Index 10131 10132@printindex cp 10133 10134 10135 10136@summarycontents 10137@contents 10138@bye 10139