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