groff.texinfo revision 79543
1219019Sgabor\input texinfo @c -*-texinfo-*- 2219019Sgabor 3219019Sgabor@c 4219019Sgabor@c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug 5219019Sgabor@c in texinfo regarding expansion of user-defined macros. 6219019Sgabor@c 7219019Sgabor 8219019Sgabor@c %**start of header (This is for running Texinfo on a region.) 9219019Sgabor@setfilename groff 10219019Sgabor@settitle The GNU Troff Manual 11219019Sgabor@setchapternewpage odd 12219019Sgabor@footnotestyle separate 13219019Sgabor@c %**end of header (This is for running Texinfo on a region.) 14219019Sgabor 15219019Sgabor 16219019Sgabor@c We use the following indices: 17219019Sgabor@c 18219019Sgabor@c cindex: concepts 19219019Sgabor@c rqindex: requests 20219019Sgabor@c esindex: escapes 21219019Sgabor@c vindex: registers 22219019Sgabor@c kindex: commands in font files 23219019Sgabor@c pindex: programs and files 24219019Sgabor@c tindex: environment variables 25219019Sgabor@c maindex: macros 26219019Sgabor@c stindex: strings 27219019Sgabor@c glindex: glyph names 28219019Sgabor@c opindex: operators 29219019Sgabor@c 30219019Sgabor@c tindex and cindex are merged. 31219019Sgabor 32219019Sgabor@defcodeindex rq 33219019Sgabor@defcodeindex es 34219019Sgabor@defcodeindex ma 35219019Sgabor@defcodeindex st 36219019Sgabor@defcodeindex gl 37219019Sgabor@defcodeindex op 38219019Sgabor@syncodeindex tp cp 39219019Sgabor 40219019Sgabor 41219019Sgabor@c to avoid uppercasing in @deffn while converting to info, we define 42219019Sgabor@c our special @Var{} 43219019Sgabor@c 44219019Sgabor@c due to a (not officially documented) `feature' in makeinfo 4.0, 45219019Sgabor@c macros are not expanded in @deffn (but the macro definition is 46219019Sgabor@c properly removed), so we have to define @Var{} directly in TeX also 47219019Sgabor 48219019Sgabor@macro Var{arg} 49219019Sgabor\arg\ 50219019Sgabor@end macro 51219019Sgabor@tex 52219019Sgabor\gdef\Var#1{\var{#1}} 53219019Sgabor@end tex 54219019Sgabor 55219019Sgabor 56219019Sgabor@c definition of requests 57219019Sgabor 58219019Sgabor@macro Defreq{name, arg} 59219019Sgabor@rqindex \name\ 60219019Sgabor@deffn Request @t{.\name\} \arg\ 61219019Sgabor@end macro 62219019Sgabor 63219019Sgabor@macro Defreqx{name, arg} 64219019Sgabor@rqindex \name\ 65219019Sgabor@deffnx Request @t{.\name\} \arg\ 66219019Sgabor@end macro 67219019Sgabor 68219019Sgabor@macro endDefreq 69219019Sgabor@end deffn 70219019Sgabor@end macro 71219019Sgabor 72219019Sgabor 73219019Sgabor@c definition of escapes 74219019Sgabor 75219019Sgabor@macro Defesc{name, delimI, arg, delimII} 76219019Sgabor@esindex \name\ 77219019Sgabor@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 78219019Sgabor@end macro 79219019Sgabor 80219019Sgabor@macro Defescx{name, delimI, arg, delimII} 81219019Sgabor@esindex \name\ 82219019Sgabor@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 83219019Sgabor@end macro 84219019Sgabor 85219019Sgabor@macro endDefesc 86219019Sgabor@end deffn 87219019Sgabor@end macro 88219019Sgabor 89219019Sgabor 90219019Sgabor@c definition of registers 91219019Sgabor 92219019Sgabor@macro Defreg{name} 93219019Sgabor@vindex \name\ 94219019Sgabor@deffn Register @t{\\n[\name\]} 95219019Sgabor@end macro 96219019Sgabor 97219019Sgabor@macro Defregx{name} 98219019Sgabor@vindex \name\ 99219019Sgabor@deffnx Register @t{\\n[\name\]} 100219019Sgabor@end macro 101219019Sgabor 102219019Sgabor@macro endDefreg 103219019Sgabor@end deffn 104219019Sgabor@end macro 105219019Sgabor 106219019Sgabor 107219019Sgabor@c definition of macros 108219019Sgabor 109219019Sgabor@macro Defmac{name, arg} 110219019Sgabor@maindex \name\ 111219019Sgabor@defmac @t{.\name\} \arg\ 112219019Sgabor@end macro 113219019Sgabor 114219019Sgabor@macro Defmacx{name, arg} 115219019Sgabor@maindex \name\ 116219019Sgabor@defmacx @t{.\name\} \arg\ 117219019Sgabor@end macro 118219019Sgabor 119219019Sgabor@macro endDefmac 120219019Sgabor@end defmac 121219019Sgabor@end macro 122219019Sgabor 123219019Sgabor 124219019Sgabor@c definition of strings 125219019Sgabor 126219019Sgabor@macro Defstr{name, arg} 127219019Sgabor@stindex \name\ 128219019Sgabor@deffn String @t{\name\} \arg\ 129219019Sgabor@end macro 130219019Sgabor 131219019Sgabor@macro Defstrx{name, arg} 132219019Sgabor@stindex \name\ 133219019Sgabor@deffnx String @t{\name\} \arg\ 134219019Sgabor@end macro 135219019Sgabor 136219019Sgabor@macro endDefstr 137219019Sgabor@end deffn 138219019Sgabor@end macro 139219019Sgabor 140219019Sgabor 141219019Sgabor@c our example macro 142219019Sgabor 143219019Sgabor@macro Example 144219019Sgabor@example 145219019Sgabor@group 146219019Sgabor@end macro 147219019Sgabor 148219019Sgabor@macro endExample 149219019Sgabor@end group 150219019Sgabor@end example 151219019Sgabor@end macro 152219019Sgabor 153219019Sgabor 154219019Sgabor@c We need special parentheses and brackets: 155219019Sgabor@c 156219019Sgabor@c . Real parentheses in @deffn produce an error while compiling with 157219019Sgabor@c TeX 158219019Sgabor@c . Real brackets use the wrong font in @deffn, overriding @t{}. 159219019Sgabor@c 160219019Sgabor@c This is true for texinfo 4.0. 161219019Sgabor 162219019Sgabor@ifnottex 163219019Sgabor@macro lparen 164219019Sgabor( 165219019Sgabor@end macro 166219019Sgabor@macro rparen 167219019Sgabor) 168219019Sgabor@end macro 169219019Sgabor@macro lbrack 170219019Sgabor[ 171219019Sgabor@end macro 172219019Sgabor@macro rbrack 173219019Sgabor] 174219019Sgabor@end macro 175219019Sgabor@end ifnottex 176219019Sgabor 177219019Sgabor@iftex 178219019Sgabor@macro lparen 179219019Sgabor@@lparen 180219019Sgabor@end macro 181219019Sgabor@macro rparen 182219019Sgabor@@rparen 183219019Sgabor@end macro 184219019Sgabor@macro lbrack 185219019Sgabor@@lbrack 186219019Sgabor@end macro 187219019Sgabor@macro rbrack 188219019Sgabor@@rbrack 189219019Sgabor@end macro 190219019Sgabor@end iftex 191219019Sgabor 192219019Sgabor 193219019Sgabor@c Note: We say `Roman numerals' but `roman font'. 194219019Sgabor 195219019Sgabor 196219019Sgabor@c XXX comment all examples 197219019Sgabor 198219019Sgabor 199219019Sgabor@dircategory Miscellaneous 200219019Sgabor@direntry 201219019Sgabor* Groff: (groff). The GNU troff document formatting system. 202219019Sgabor@end direntry 203219019Sgabor 204219019Sgabor 205219019Sgabor@smallbook 206219019Sgabor 207219019Sgabor 208219019Sgabor@iftex 209219019Sgabor@finalout 210219019Sgabor@end iftex 211219019Sgabor 212219019Sgabor 213219019Sgabor@ifinfo 214219019SgaborThis Info file documents GNU troff version 1.16. 215219019Sgabor 216219019SgaborPublished by the Free Software Foundation 217219019Sgabor59 Temple Place, Suite 330 218219019SgaborBoston, MA 02111-1307 USA 219219019Sgabor 220219019SgaborCopyright (C) 1994-2000 Free Software Foundation, Inc. 221219019Sgabor 222219019SgaborPermission is granted to make and distribute verbatim copies of this 223219019Sgabormanual provided the copyright notice and this permission notice are 224219019Sgaborpreserved on all copies. 225219019Sgabor 226219019Sgabor@ignore 227219019SgaborPermission is granted to process this file through TeX and print the 228219019Sgaborresults, provided the printed document carries copying permission notice 229219019Sgaboridentical to this one except for the removal of this paragraph (this 230219019Sgaborparagraph not being relevant to the printed manual). 231219019Sgabor 232219019Sgabor@end ignore 233219019SgaborPermission is granted to copy and distribute modified versions of this 234219019Sgabormanual under the conditions for verbatim copying, provided that the 235219019Sgaborentire resulting derived work is distributed under the terms of a 236219019Sgaborpermission notice identical to this one. 237219019Sgabor 238219019SgaborPermission is granted to copy and distribute translations of this manual 239219019Sgaborinto another language, under the above conditions for modified versions, 240219019Sgaborexcept that this permission notice may be stated in a translation 241219019Sgaborapproved by the Foundation. 242219019Sgabor 243219019SgaborPermission is granted to copy and distribute modified versions of this 244219019Sgabormanual under the conditions for verbatim copying, provided also that the 245219019Sgaborsection entitled ``GNU General Public License'' is included exactly as 246219019Sgaborin the original, and provided that the entire resulting derived work is 247219019Sgabordistributed under the terms of a permission notice identical to this 248219019Sgaborone. 249219019Sgabor 250219019SgaborPermission is granted to copy and distribute translations of this manual 251219019Sgaborinto another language, under the above conditions for modified versions, 252219019Sgaborexcept that the section entitled ``GNU General Public License'' may be 253219019Sgaborincluded in a translation approved by the Free Software Foundation 254219019Sgaborinstead of in the original English. 255219019Sgabor@end ifinfo 256219019Sgabor 257219019Sgabor 258219019Sgabor@titlepage 259219019Sgabor@title groff 260219019Sgabor@subtitle The GNU implementation of @code{troff} 261219019Sgabor@subtitle Edition 1.16 262219019Sgabor@subtitle Spring 2000 263219019Sgabor@author by Trent A.@w{ }Fisher 264219019Sgabor@author and Werner Lemberg 265219019Sgabor 266219019Sgabor@c Include the Distribution inside the titlepage environment so 267219019Sgabor@c that headings are turned off. Headings on and off do not work. 268219019Sgabor 269219019Sgabor@page 270219019Sgabor@vskip 0pt plus 1filll 271219019SgaborCopyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc. 272219019Sgabor@sp 2 273219019SgaborVersion 1.16 of @code{groff}, @* 274219019SgaborSpring 2000 275219019Sgabor@sp 2 276219019SgaborPublished by the Free Software Foundation @* 277219019Sgabor59 Temple Place, Suite 330 @* 278219019SgaborBoston, MA 02111-1307 USA 279219019Sgabor 280219019Sgabor 281219019SgaborPermission is granted to make and distribute verbatim copies of this 282219019Sgabormanual provided the copyright notice and this permission notice are 283219019Sgaborpreserved on all copies. 284219019Sgabor 285219019SgaborPermission is granted to copy and distribute modified versions of this 286219019Sgabormanual under the conditions for verbatim copying, provided also that the 287219019Sgaborsection entitled ``GNU General Public License'' is included exactly as 288219019Sgaborin the original, and provided that the entire resulting derived work is 289219019Sgabordistributed under the terms of a permission notice identical to this 290219019Sgaborone. 291219019Sgabor 292219019SgaborPermission is granted to copy and distribute translations of this manual 293219019Sgaborinto another language, under the above conditions for modified versions, 294219019Sgaborexcept that the section entitled ``GNU General Public License'' may be 295219019Sgaborincluded in a translation approved by the Free Software Foundation 296219019Sgaborinstead of in the original English. 297219019Sgabor 298219019SgaborCover art by Etienne Suvasa. 299219019Sgabor@end titlepage 300219019Sgabor@page 301219019Sgabor 302219019Sgabor 303219019Sgabor 304219019Sgabor@node Top, Copying, (dir), (dir) 305219019Sgabor 306219019Sgabor@ifinfo 307219019SgaborThis Info file documents groff version 1.16, the GNU implementation of 308219019Sgaborthe troff typesetting system. 309219019Sgabor 310219019SgaborThis is an in-progress document; contributions, comments, or 311219019Sgaborcontributions are welcome. Send them to bug-groff@@gnu.org. 312219019Sgabor@end ifinfo 313219019Sgabor 314219019Sgabor@menu 315219019Sgabor* Copying:: 316219019Sgabor* Introduction:: 317219019Sgabor* Invoking groff:: 318219019Sgabor* Tutorial for Macro Users:: 319219019Sgabor* Macro Packages:: 320219019Sgabor* gtroff Reference:: 321219019Sgabor* Preprocessors:: 322219019Sgabor* Output Devices:: 323219019Sgabor* File formats:: 324219019Sgabor* Installation:: 325219019Sgabor* Request Index:: 326219019Sgabor* Escape Index:: 327219019Sgabor* Operator Index:: 328219019Sgabor* Register Index:: 329219019Sgabor* Macro Index:: 330219019Sgabor* String Index:: 331219019Sgabor* Glyph Name Index:: 332219019Sgabor* Font File Keyword Index:: 333219019Sgabor* Program and File Index:: 334219019Sgabor* Concept Index:: 335219019Sgabor@end menu 336219019Sgabor 337219019Sgabor 338219019Sgabor 339219019Sgabor@node Copying, Introduction, Top, Top 340219019Sgabor@cindex copying 341219019Sgabor@unnumbered GNU GENERAL PUBLIC LICENSE 342219019Sgabor@center Version 2, June 1991 343219019Sgabor 344219019Sgabor@display 345219019SgaborCopyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc. 346219019Sgabor59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA 347219019Sgabor 348219019SgaborEveryone is permitted to copy and distribute verbatim copies of this 349219019Sgaborlicense document, but changing it is not allowed. 350219019Sgabor@end display 351219019Sgabor 352219019Sgabor@unnumberedsec Preamble 353219019Sgabor 354219019SgaborThe licenses for most software are designed to take away your freedom to 355219019Sgaborshare and change it. By contrast, the GNU General Public License is 356219019Sgaborintended to guarantee your freedom to share and change free software -- 357219019Sgaborto make sure the software is free for all its users. This General 358219019SgaborPublic License applies to most of the Free Software Foundation's 359219019Sgaborsoftware and to any other program whose authors commit to using it. 360219019Sgabor(Some other Free Software Foundation software is covered by the GNU 361219019SgaborLibrary General Public License instead.) You can apply it to your 362219019Sgaborprograms, too. 363219019Sgabor 364219019SgaborWhen we speak of free software, we are referring to freedom, not price. 365219019SgaborOur General Public Licenses are designed to make sure that you have the 366219019Sgaborfreedom to distribute copies of free software (and charge for this 367219019Sgaborservice if you wish), that you receive source code or can get it if you 368219019Sgaborwant it, that you can change the software or use pieces of it in new 369219019Sgaborfree programs; and that you know you can do these things. 370219019Sgabor 371219019SgaborTo protect your rights, we need to make restrictions that forbid anyone 372219019Sgaborto deny you these rights or to ask you to surrender the rights. These 373219019Sgaborrestrictions translate to certain responsibilities for you if you 374219019Sgabordistribute copies of the software, or if you modify it. 375219019Sgabor 376219019SgaborFor example, if you distribute copies of such a program, whether gratis 377219019Sgaboror for a fee, you must give the recipients all the rights that you have. 378219019SgaborYou must make sure that they, too, receive or can get the source code. 379219019SgaborAnd you must show them these terms so they know their rights. 380219019Sgabor 381219019SgaborWe protect your rights with two steps: (1)@w{ }copyright the software, 382219019Sgaborand (2)@w{ }offer you this license which gives you legal permission to 383219019Sgaborcopy, distribute and/or modify the software. 384219019Sgabor 385219019SgaborAlso, for each author's protection and ours, we want to make certain 386219019Sgaborthat everyone understands that there is no warranty for this free 387219019Sgaborsoftware. If the software is modified by someone else and passed on, we 388219019Sgaborwant its recipients to know that what they have is not the original, so 389219019Sgaborthat any problems introduced by others will not reflect on the original 390219019Sgaborauthors' reputations. 391219019Sgabor 392219019SgaborFinally, any free program is threatened constantly by software patents. 393219019SgaborWe wish to avoid the danger that redistributors of a free program will 394219019Sgaborindividually obtain patent licenses, in effect making the program 395219019Sgaborproprietary. To prevent this, we have made it clear that any patent 396219019Sgabormust be licensed for everyone's free use or not licensed at all. 397219019Sgabor 398219019SgaborThe precise terms and conditions for copying, distribution and 399219019Sgabormodification follow. 400219019Sgabor 401219019Sgabor@iftex 402219019Sgabor@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 403219019Sgabor@end iftex 404219019Sgabor@ifinfo 405219019Sgabor@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 406219019Sgabor@end ifinfo 407219019Sgabor 408219019Sgabor@enumerate 0 409219019Sgabor@item 410219019SgaborThis License applies to any program or other work which contains a 411219019Sgabornotice placed by the copyright holder saying it may be distributed under 412219019Sgaborthe terms of this General Public License. The ``Program'', below, 413219019Sgaborrefers to any such program or work, and a ``work based on the Program'' 414219019Sgabormeans either the Program or any derivative work under copyright law: 415219019Sgaborthat is to say, a work containing the Program or a portion of it, either 416219019Sgaborverbatim or with modifications and/or translated into another language. 417219019Sgabor(Hereinafter, translation is included without limitation in the term 418219019Sgabor``modification''.) Each licensee is addressed as ``you''. 419219019Sgabor 420219019SgaborActivities other than copying, distribution and modification are not 421219019Sgaborcovered by this License; they are outside its scope. The act of running 422219019Sgaborthe Program is not restricted, and the output from the Program is 423219019Sgaborcovered only if its contents constitute a work based on the Program 424219019Sgabor(independent of having been made by running the Program). Whether that 425219019Sgaboris true depends on what the Program does. 426219019Sgabor 427219019Sgabor@item 428219019SgaborYou may copy and distribute verbatim copies of the Program's source code 429219019Sgaboras you receive it, in any medium, provided that you conspicuously and 430219019Sgaborappropriately publish on each copy an appropriate copyright notice and 431219019Sgabordisclaimer of warranty; keep intact all the notices that refer to this 432219019SgaborLicense and to the absence of any warranty; and give any other 433219019Sgaborrecipients of the Program a copy of this License along with the Program. 434219019Sgabor 435219019SgaborYou may charge a fee for the physical act of transferring a copy, and 436219019Sgaboryou may at your option offer warranty protection in exchange for a fee. 437219019Sgabor 438219019Sgabor@item 439219019SgaborYou may modify your copy or copies of the Program or any portion of it, 440219019Sgaborthus forming a work based on the Program, and copy and distribute such 441219019Sgabormodifications or work under the terms of Section@w{ }1 above, provided 442219019Sgaborthat you also meet all of these conditions: 443219019Sgabor 444219019Sgabor@enumerate a 445219019Sgabor@item 446219019SgaborYou must cause the modified files to carry prominent notices stating 447219019Sgaborthat you changed the files and the date of any change. 448219019Sgabor 449219019Sgabor@item 450219019SgaborYou must cause any work that you distribute or publish, that in whole or 451219019Sgaborin part contains or is derived from the Program or any part thereof, to 452219019Sgaborbe licensed as a whole at no charge to all third parties under the terms 453219019Sgaborof this License. 454219019Sgabor 455219019Sgabor@item 456219019SgaborIf the modified program normally reads commands interactively when run, 457219019Sgaboryou must cause it, when started running for such interactive use in the 458219019Sgabormost ordinary way, to print or display an announcement including an 459219019Sgaborappropriate copyright notice and a notice that there is no warranty (or 460219019Sgaborelse, saying that you provide a warranty) and that users may 461219019Sgaborredistribute the program under these conditions, and telling the user 462219019Sgaborhow to view a copy of this License. (Exception: if the Program itself 463219019Sgaboris interactive but does not normally print such an announcement, your 464219019Sgaborwork based on the Program is not required to print an announcement.) 465219019Sgabor@end enumerate 466219019Sgabor 467219019SgaborThese requirements apply to the modified work as a whole. If 468219019Sgaboridentifiable sections of that work are not derived from the Program, and 469219019Sgaborcan be reasonably considered independent and separate works in 470219019Sgaborthemselves, then this License, and its terms, do not apply to those 471219019Sgaborsections when you distribute them as separate works. But when you 472219019Sgabordistribute the same sections as part of a whole which is a work based on 473219019Sgaborthe Program, the distribution of the whole must be on the terms of this 474219019SgaborLicense, whose permissions for other licensees extend to the entire 475219019Sgaborwhole, and thus to each and every part regardless of who wrote it. 476219019Sgabor 477219019SgaborThus, it is not the intent of this section to claim rights or contest 478219019Sgaboryour rights to work written entirely by you; rather, the intent is to 479219019Sgaborexercise the right to control the distribution of derivative or 480219019Sgaborcollective works based on the Program. 481219019Sgabor 482219019SgaborIn addition, mere aggregation of another work not based on the Program 483219019Sgaborwith the Program (or with a work based on the Program) on a volume of a 484219019Sgaborstorage or distribution medium does not bring the other work under the 485219019Sgaborscope of this License. 486219019Sgabor 487219019Sgabor@item 488219019SgaborYou may copy and distribute the Program (or a work based on it, under 489219019SgaborSection@w{ }2) in object code or executable form under the terms of 490219019SgaborSections@w{ }1 and@w{ }2 above provided that you also do one of the 491219019Sgaborfollowing: 492219019Sgabor 493219019Sgabor@enumerate a 494219019Sgabor@item 495219019SgaborAccompany it with the complete corresponding machine-readable source 496219019Sgaborcode, which must be distributed under the terms of Sections@w{ }1 and@w{ 497219019Sgabor}2 above on a medium customarily used for software interchange; or, 498219019Sgabor 499219019Sgabor@item 500219019SgaborAccompany it with a written offer, valid for at least three years, to 501219019Sgaborgive any third party, for a charge no more than your cost of physically 502219019Sgaborperforming source distribution, a complete machine-readable copy of the 503219019Sgaborcorresponding source code, to be distributed under the terms of 504219019SgaborSections@w{ }1 and@w{ }2 above on a medium customarily used for software 505219019Sgaborinterchange; or, 506219019Sgabor 507219019Sgabor@item 508219019SgaborAccompany it with the information you received as to the offer to 509219019Sgabordistribute corresponding source code. (This alternative is allowed only 510219019Sgaborfor noncommercial distribution and only if you received the program in 511219019Sgaborobject code or executable form with such an offer, in accord with 512219019SgaborSubsection@w{ }b above.) 513219019Sgabor@end enumerate 514219019Sgabor 515219019SgaborThe source code for a work means the preferred form of the work for 516219019Sgabormaking modifications to it. For an executable work, complete source 517219019Sgaborcode means all the source code for all modules it contains, plus any 518219019Sgaborassociated interface definition files, plus the scripts used to control 519219019Sgaborcompilation and installation of the executable. However, as a special 520219019Sgaborexception, the source code distributed need not include anything that is 521219019Sgabornormally distributed (in either source or binary form) with the major 522219019Sgaborcomponents (compiler, kernel, and so on) of the operating system on 523219019Sgaborwhich the executable runs, unless that component itself accompanies the 524219019Sgaborexecutable. 525219019Sgabor 526219019SgaborIf distribution of executable or object code is made by offering access 527219019Sgaborto copy from a designated place, then offering equivalent access to copy 528219019Sgaborthe source code from the same place counts as distribution of the source 529219019Sgaborcode, even though third parties are not compelled to copy the source 530219019Sgaboralong with the object code. 531219019Sgabor 532219019Sgabor@item 533219019SgaborYou may not copy, modify, sublicense, or distribute the Program except 534219019Sgaboras expressly provided under this License. Any attempt otherwise to 535219019Sgaborcopy, modify, sublicense or distribute the Program is void, and will 536219019Sgaborautomatically terminate your rights under this License. However, 537219019Sgaborparties who have received copies, or rights, from you under this License 538219019Sgaborwill not have their licenses terminated so long as such parties remain 539219019Sgaborin full compliance. 540219019Sgabor 541219019Sgabor@item 542219019SgaborYou are not required to accept this License, since you have not signed 543219019Sgaborit. However, nothing else grants you permission to modify or distribute 544219019Sgaborthe Program or its derivative works. These actions are prohibited by 545219019Sgaborlaw if you do not accept this License. Therefore, by modifying or 546219019Sgabordistributing the Program (or any work based on the Program), you 547219019Sgaborindicate your acceptance of this License to do so, and all its terms and 548219019Sgaborconditions for copying, distributing or modifying the Program or works 549219019Sgaborbased on it. 550219019Sgabor 551219019Sgabor@item 552219019SgaborEach time you redistribute the Program (or any work based on the 553219019SgaborProgram), the recipient automatically receives a license from the 554219019Sgabororiginal licensor to copy, distribute or modify the Program subject to 555219019Sgaborthese terms and conditions. You may not impose any further restrictions 556219019Sgaboron the recipients' exercise of the rights granted herein. You are not 557219019Sgaborresponsible for enforcing compliance by third parties to this License. 558219019Sgabor 559219019Sgabor@item 560219019SgaborIf, as a consequence of a court judgment or allegation of patent 561219019Sgaborinfringement or for any other reason (not limited to patent issues), 562219019Sgaborconditions are imposed on you (whether by court order, agreement or 563219019Sgaborotherwise) that contradict the conditions of this License, they do not 564219019Sgaborexcuse you from the conditions of this License. If you cannot 565219019Sgabordistribute so as to satisfy simultaneously your obligations under this 566219019SgaborLicense and any other pertinent obligations, then as a consequence you 567219019Sgabormay not distribute the Program at all. For example, if a patent license 568219019Sgaborwould not permit royalty-free redistribution of the Program by all those 569219019Sgaborwho receive copies directly or indirectly through you, then the only way 570219019Sgaboryou could satisfy both it and this License would be to refrain entirely 571219019Sgaborfrom distribution of the Program. 572219019Sgabor 573219019SgaborIf any portion of this section is held invalid or unenforceable under 574219019Sgaborany particular circumstance, the balance of the section is intended to 575219019Sgaborapply and the section as a whole is intended to apply in other 576219019Sgaborcircumstances. 577219019Sgabor 578219019SgaborIt is not the purpose of this section to induce you to infringe any 579219019Sgaborpatents or other property right claims or to contest validity of any 580219019Sgaborsuch claims; this section has the sole purpose of protecting the 581219019Sgaborintegrity of the free software distribution system, which is implemented 582219019Sgaborby public license practices. Many people have made generous 583219019Sgaborcontributions to the wide range of software distributed through that 584219019Sgaborsystem in reliance on consistent application of that system; it is up to 585219019Sgaborthe author/donor to decide if he or she is willing to distribute 586219019Sgaborsoftware through any other system and a licensee cannot impose that 587219019Sgaborchoice. 588219019Sgabor 589219019SgaborThis section is intended to make thoroughly clear what is believed to be 590219019Sgabora consequence of the rest of this License. 591219019Sgabor 592219019Sgabor@item 593219019SgaborIf the distribution and/or use of the Program is restricted in certain 594219019Sgaborcountries either by patents or by copyrighted interfaces, the original 595219019Sgaborcopyright holder who places the Program under this License may add an 596219019Sgaborexplicit geographical distribution limitation excluding those countries, 597219019Sgaborso that distribution is permitted only in or among countries not thus 598219019Sgaborexcluded. In such case, this License incorporates the limitation as if 599219019Sgaborwritten in the body of this License. 600219019Sgabor 601219019Sgabor@item 602219019SgaborThe Free Software Foundation may publish revised and/or new versions of 603219019Sgaborthe General Public License from time to time. Such new versions will be 604219019Sgaborsimilar in spirit to the present version, but may differ in detail to 605219019Sgaboraddress new problems or concerns. 606219019Sgabor 607219019SgaborEach version is given a distinguishing version number. If the Program 608219019Sgaborspecifies a version number of this License which applies to it and ``any 609219019Sgaborlater version'', you have the option of following the terms and 610219019Sgaborconditions either of that version or of any later version published by 611219019Sgaborthe Free Software Foundation. If the Program does not specify a version 612219019Sgabornumber of this License, you may choose any version ever published by the 613219019SgaborFree Software Foundation. 614219019Sgabor 615219019Sgabor@item 616219019SgaborIf you wish to incorporate parts of the Program into other free programs 617219019Sgaborwhose distribution conditions are different, write to the author to ask 618219019Sgaborfor permission. For software which is copyrighted by the Free Software 619219019SgaborFoundation, write to the Free Software Foundation; we sometimes make 620219019Sgaborexceptions for this. Our decision will be guided by the two goals of 621219019Sgaborpreserving the free status of all derivatives of our free software and 622219019Sgaborof promoting the sharing and reuse of software generally. 623219019Sgabor 624219019Sgabor@iftex 625219019Sgabor@heading NO WARRANTY 626219019Sgabor@end iftex 627219019Sgabor@ifinfo 628219019Sgabor@center NO WARRANTY 629219019Sgabor@end ifinfo 630219019Sgabor 631219019Sgabor@item 632219019SgaborBECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR 633219019SgaborTHE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN 634219019SgaborOTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 635219019SgaborPROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER 636219019SgaborEXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 637219019SgaborWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. 638219019SgaborTHE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH 639219019SgaborYOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 640219019SgaborNECESSARY SERVICING, REPAIR OR CORRECTION. 641219019Sgabor 642219019Sgabor@item 643219019SgaborIN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 644219019SgaborWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 645219019SgaborREDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 646219019SgaborDAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL 647219019SgaborDAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM 648219019Sgabor(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED 649219019SgaborINACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF 650219019SgaborTHE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR 651219019SgaborOTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 652219019Sgabor@end enumerate 653219019Sgabor 654219019Sgabor@iftex 655219019Sgabor@heading END OF TERMS AND CONDITIONS 656219019Sgabor@end iftex 657219019Sgabor@ifinfo 658219019Sgabor@center END OF TERMS AND CONDITIONS 659219019Sgabor@end ifinfo 660219019Sgabor 661219019Sgabor 662219019Sgabor@page 663219019Sgabor@unnumberedsec How to Apply These Terms to Your New Programs 664219019Sgabor 665219019SgaborIf you develop a new program, and you want it to be of the greatest 666219019Sgaborpossible use to the public, the best way to achieve this is to make it 667219019Sgaborfree software which everyone can redistribute and change under these 668219019Sgaborterms. 669219019Sgabor 670219019SgaborTo do so, attach the following notices to the program. It is safest to 671219019Sgaborattach them to the start of each source file to most effectively convey 672219019Sgaborthe exclusion of warranty; and each file should have at least the 673219019Sgabor``copyright'' line and a pointer to where the full notice is found. 674219019Sgabor 675219019Sgabor@smallexample 676219019Sgabor@var{one line to give the program's name and an idea of what it does.} 677219019SgaborCopyright (C) 19@var{yy} @var{name of author} 678219019Sgabor 679219019SgaborThis program is free software; you can redistribute it and/or modify 680219019Sgaborit under the terms of the GNU General Public License as published by 681219019Sgaborthe Free Software Foundation; either version 2 of the License, or (at 682219019Sgaboryour option) any later version. 683219019Sgabor 684219019SgaborThis program is distributed in the hope that it will be useful, but 685219019SgaborWITHOUT ANY WARRANTY; without even the implied warranty of 686219019SgaborMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU 687219019SgaborGeneral Public License for more details. 688219019Sgabor 689219019SgaborYou should have received a copy of the GNU General Public License 690219019Sgaboralong with this program; if not, write to the Free Software 691219019SgaborFoundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA. 692219019Sgabor@end smallexample 693219019Sgabor 694219019SgaborAlso add information on how to contact you by electronic and paper mail. 695219019Sgabor 696219019SgaborIf the program is interactive, make it output a short notice like this 697219019Sgaborwhen it starts in an interactive mode: 698219019Sgabor 699219019Sgabor@smallexample 700219019SgaborGnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} 701219019SgaborGnomovision comes with ABSOLUTELY NO WARRANTY; for details type 702219019Sgabor`show w'. This is free software, and you are welcome to redistribute 703219019Sgaborit under certain conditions; type `show c' for details. 704219019Sgabor@end smallexample 705219019Sgabor 706219019SgaborThe hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should 707219019Sgaborshow the appropriate parts of the General Public License. Of course, 708219019Sgaborthe commands you use may be called something other than @samp{show@w{ 709219019Sgabor}w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items 710219019Sgabor-- whatever suits your program. 711219019Sgabor 712219019SgaborYou should also get your employer (if you work as a programmer) or your 713219019Sgaborschool, if any, to sign a ``copyright disclaimer'' for the program, if 714219019Sgabornecessary. Here is a sample; alter the names: 715219019Sgabor 716219019Sgabor@smallexample 717219019Sgabor@group 718219019SgaborYoyodyne, Inc., hereby disclaims all copyright interest 719219019Sgaborin the program `Gnomovision' (which makes passes at compilers) 720219019Sgaborwritten by James Hacker. 721219019Sgabor 722219019Sgabor@var{signature of Ty Coon}, 1 April 1989 723219019SgaborTy Coon, President of Vice 724219019Sgabor@end group 725219019Sgabor@end smallexample 726219019Sgabor 727219019SgaborThis General Public License does not permit incorporating your program 728219019Sgaborinto proprietary programs. If your program is a subroutine library, you 729219019Sgabormay consider it more useful to permit linking proprietary applications 730219019Sgaborwith the library. If this is what you want to do, use the GNU Library 731219019SgaborGeneral Public License instead of this License. 732219019Sgabor 733219019Sgabor 734219019Sgabor 735219019Sgabor@c ===================================================================== 736219019Sgabor@c ===================================================================== 737219019Sgabor 738219019Sgabor@node Introduction, Invoking groff, Copying, Top 739219019Sgabor@chapter Introduction 740219019Sgabor@cindex introduction 741219019Sgabor 742219019SgaborGNU @code{troff} (or @code{groff}) is a system for typesetting 743219019Sgabordocuments. @code{troff} is very flexible and has been in existence (and 744219019Sgaboruse) for about 3@w{ }decades. It is quite widespread and firmly 745219019Sgaborentrenched in the @acronym{UNIX} community. 746219019Sgabor 747219019Sgabor@menu 748219019Sgabor* What Is groff?:: 749219019Sgabor* History:: 750219019Sgabor* groff Capabilities:: 751219019Sgabor* Macro Package Intro:: 752219019Sgabor* Preprocessor Intro:: 753219019Sgabor* Output device intro:: 754219019Sgabor* Credits:: 755219019Sgabor@end menu 756219019Sgabor 757219019Sgabor 758219019Sgabor@c ===================================================================== 759219019Sgabor 760219019Sgabor@node What Is groff?, History, Introduction, Introduction 761219019Sgabor@section What Is @code{groff}? 762219019Sgabor@cindex what is @code{groff}? 763219019Sgabor@cindex @code{groff} -- what is it? 764219019Sgabor 765219019Sgabor@code{groff} belongs to an older generation of document preparation 766219019Sgaborsystems, which operate more like compilers than the more recent 767219019Sgaborinteractive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 768219019Sgaborsystems. @code{groff} and its contemporary counterpart, @TeX{}, both 769219019Sgaborwork using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 770219019Sgabornormal text files with embedded formatting commands. These files can 771219019Sgaborthen be processed by @code{groff} to produce a typeset document on a 772219019Sgaborvariety of devices. 773219019Sgabor 774219019SgaborLikewise, @code{groff} should not be confused with a @dfn{word 775219019Sgaborprocessor}, since that term connotes an integrated system that includes 776219019Sgaboran editor and a text formatter. Also, many word processors follow the 777219019Sgabor@acronym{WYSIWYG} paradigm discussed earlier. 778219019Sgabor 779219019SgaborAlthough @acronym{WYSIWYG} systems may be easier to use, they have a 780219019Sgabornumber of disadvantages compared to @code{troff}: 781219019Sgabor 782219019Sgabor@itemize @bullet 783219019Sgabor@item 784219019SgaborThey must be used on a graphics display to work on a document. 785219019Sgabor 786219019Sgabor@item 787219019SgaborMost of the @acronym{WYSIWYG} systems are either non-free or are not 788219019Sgaborvery portable. 789219019Sgabor 790219019Sgabor@item 791219019Sgabor@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 792219019Sgabor 793219019Sgabor@item 794219019SgaborIt is difficult to have a wide range of capabilities available within 795219019Sgaborthe confines of a GUI/window system. 796219019Sgabor 797219019Sgabor@item 798219019SgaborIt is more difficult to make global changes to a document. 799219019Sgabor@end itemize 800219019Sgabor 801219019Sgabor@quotation 802219019Sgabor``GUIs normally make it simple to accomplish simple actions and 803219019Sgaborimpossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 804219019Sgabor@code{comp.unix.wizards}) 805219019Sgabor@end quotation 806219019Sgabor 807219019Sgabor 808219019Sgabor@c ===================================================================== 809219019Sgabor 810219019Sgabor@node History, groff Capabilities, What Is groff?, Introduction 811219019Sgabor@section History 812219019Sgabor@cindex history 813219019Sgabor 814219019Sgabor@cindex @code{runoff} 815219019Sgabor@cindex @code{rf} 816219019Sgabor@code{troff} can trace its origins back to a formatting program called 817219019Sgabor@code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS 818219019Sgaboroperating system in the mid-sixties. This name came from the common 819219019Sgaborphrase of the time ``I'll run off a document.'' Bob Morris ported it to 820219019Sgaborthe 635 architecture and called the program @code{roff} (an abbreviation 821219019Sgaborof @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 822219019Sgabor(before having @acronym{UNIX}), and at the same time (1969), Doug 823219019SgaborMcIllroy rewrote an extended and simplified version of @code{roff} in 824219019Sgaborthe @acronym{BCPL} programming language. 825219019Sgabor 826219019Sgabor@cindex @code{roff} 827219019SgaborThe first version of @acronym{UNIX} was developed on a @w{PDP-7} which 828219019Sgaborwas sitting around Bell Labs. In 1971 the developers wanted to get a 829219019Sgabor@w{PDP-11} for further work on the operating system. In order to 830219019Sgaborjustify the cost for this system, they proposed that they would 831219019Sgaborimplement a document formatting system for the AT&T patents division. 832219019SgaborThis first formatting program was a reimplementation of McIllroy's 833219019Sgabor@code{roff}, written by J.@w{ }F.@w{ }Ossanna. 834219019Sgabor 835219019Sgabor@cindex @code{nroff} 836219019SgaborWhen they needed a more flexible language, a new version of @code{roff} 837219019Sgaborcalled @code{nroff} (``Newer @code{roff}'') was written. It had a much 838219019Sgabormore complicated syntax, but provided the basis for all future versions. 839219019SgaborWhen they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 840219019Sgaborversion of @code{nroff} that would drive it. It was dubbed 841219019Sgabor@code{troff}, for ``typesetter @code{roff}'', although many people have 842219019Sgaborspeculated that it actually means ``Times @code{roff}'' because of the 843219019Sgaboruse of the Times font family in @code{troff} by default. As such, the 844219019Sgaborname @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 845219019Sgabor 846219019SgaborWith @code{troff} came @code{nroff} (they were actually the same program 847219019Sgaborexcept for some @samp{#ifdef}s), which was for producing output for line 848219019Sgaborprinters and character terminals. It understood everything @code{troff} 849219019Sgabordid, and ignored the commands which were not applicable (e.g.@: font 850219019Sgaborchanges). 851219019Sgabor 852219019SgaborSince there are several things which cannot be done easily in 853219019Sgabor@code{troff}, work on several preprocessors began. These programs would 854219019Sgabortransform certain parts of a document into @code{troff}, which made a 855219019Sgaborvery natural use of pipes in @acronym{UNIX}. 856219019Sgabor 857219019SgaborThe @code{eqn} preprocessor allowed mathematical formul@ae{} to be 858219019Sgaborspecified in a much simpler and more intuitive manner. @code{tbl} is a 859219019Sgaborpreprocessor for formatting tables. The @code{refer} preprocessor (and 860219019Sgaborthe similar program, @code{bib}) processes citations in a document 861219019Sgaboraccording to a bibliographic database. 862219019Sgabor 863219019SgaborUnfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 864219019Sgaborlanguage and produced output specifically for the CAT phototypesetter. 865219019SgaborHe rewrote it in C, although it was now 7000@w{ }lines of uncommented 866219019Sgaborcode and still dependent on the CAT. As the CAT became less common, and 867219019Sgaborwas no longer supported by the manufacturer, the need to make it support 868219019Sgaborother devices became a priority. However, before this could be done, 869219019SgaborOssanna was killed in an auto accident. 870219019Sgabor 871219019Sgabor@pindex ditroff 872219019Sgabor@cindex @code{ditroff} 873219019SgaborSo, Brian Kernighan took on the task of rewriting @code{troff}. The 874219019Sgabornewly rewritten version produced a device independent code which was 875219019Sgaborvery easy for postprocessors to read and translate to the appropriate 876219019Sgaborprinter codes. Also, this new version of @code{troff} (called 877219019Sgabor@code{ditroff} for ``device independent @code{troff}'') had several 878219019Sgaborextensions, which included drawing functions. 879219019Sgabor 880219019SgaborDue to the additional abilities of the new version of @code{troff}, 881219019Sgaborseveral new preprocessors appeared. The @code{pic} preprocessor 882219019Sgaborprovides a wide range of drawing functions. Likewise the @code{ideal} 883219019Sgaborpreprocessor did the same, although via a much different paradigm. The 884219019Sgabor@code{grap} preprocessor took specifications for graphs, but, unlike 885219019Sgaborother preprocessors, produced @code{pic} code. 886219019Sgabor 887219019SgaborJames Clark began work on a GNU implementation of @code{ditroff} in 888219019Sgaborearly@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released 889219019SgaborJune@w{ }1990. @code{groff} included: 890219019Sgabor 891219019Sgabor@itemize @bullet 892219019Sgabor@item 893219019SgaborA replacement for @code{ditroff} with many extensions. 894219019Sgabor 895219019Sgabor@item 896219019SgaborThe @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 897219019Sgabor 898219019Sgabor@item 899219019SgaborPostprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 900219019SgaborX@w{ }windows. GNU @code{troff} also eliminated the need for a 901219019Sgaborseparate @code{nroff} program with a postprocessor which would produce 902219019Sgabor@acronym{ASCII} output. 903219019Sgabor 904219019Sgabor@item 905219019SgaborA version of the @file{me} macros and an implementation of the 906219019Sgabor@file{man} macros. 907219019Sgabor@end itemize 908219019Sgabor 909219019SgaborAlso, a front-end was included which could construct the, sometimes 910219019Sgaborpainfully long, pipelines required for all the post- and preprocessors. 911219019Sgabor 912219019SgaborDevelopment of GNU @code{troff} progressed rapidly, and saw the 913219019Sgaboradditions of a replacement for @code{refer}, an implementation of the 914219019Sgabor@file{ms} and @file{mm} macros, and a program to deduce how to format a 915219019Sgabordocument (@code{grog}). 916219019Sgabor 917219019SgaborIt was declared a stable (i.e.@: non-beta) package with the release of 918219019Sgaborversion@w{ }1.04 around November@w{ }1991. 919219019Sgabor 920219019SgaborBeginning in@w{ }1999, @code{groff} has new maintainers (the package was 921219019Sgaboran orphan for a few years). As a result, new features and programs like 922219019Sgabor@code{grn}, a preprocessor for gremlin images, and an output device to 923219019Sgaborproduce @acronym{HTML} output have been added. 924219019Sgabor 925219019Sgabor 926219019Sgabor@c ===================================================================== 927219019Sgabor 928219019Sgabor@node groff Capabilities, Macro Package Intro, History, Introduction 929219019Sgabor@section @code{groff} Capabilities 930219019Sgabor@cindex @code{groff} capabilities 931219019Sgabor@cindex capabilities of @code{groff} 932219019Sgabor 933219019SgaborSo what exactly is @code{groff} capable of doing? @code{groff} provides 934219019Sgabora wide range of low-level text formatting operations. Using these, it 935219019Sgaboris possible to perform a wide range of formatting tasks, such as 936219019Sgaborfootnotes, table of contents, multiple columns, etc. Here's a list of 937219019Sgaborthe most important operations supported by @code{groff}: 938219019Sgabor 939219019Sgabor@itemize @bullet 940219019Sgabor@item 941219019Sgabortext filling, adjusting, and centering 942219019Sgabor 943219019Sgabor@item 944219019Sgaborhyphenation 945219019Sgabor 946219019Sgabor@item 947219019Sgaborpage control 948219019Sgabor 949219019Sgabor@item 950219019Sgaborfont and character size control 951219019Sgabor 952219019Sgabor@item 953219019Sgaborvertical spacing (i.e.@: double spacing) 954219019Sgabor 955219019Sgabor@item 956219019Sgaborline length and indenting 957219019Sgabor 958219019Sgabor@item 959219019Sgabormacros, strings, diversions, and traps 960219019Sgabor 961219019Sgabor@item 962219019Sgabornumber registers 963219019Sgabor 964219019Sgabor@item 965219019Sgabortabs, leaders, and fields 966219019Sgabor 967219019Sgabor@item 968219019Sgaborinput and output conventions and character translation 969219019Sgabor 970219019Sgabor@item 971219019Sgaboroverstrike, bracket, line drawing, and zero-width functions 972219019Sgabor 973219019Sgabor@item 974219019Sgaborlocal horizontal and vertical motions and the width function 975219019Sgabor 976219019Sgabor@item 977219019Sgaborthree-part titles 978219019Sgabor 979219019Sgabor@item 980219019Sgaboroutput line numbering 981219019Sgabor 982219019Sgabor@item 983219019Sgaborconditional acceptance of input 984219019Sgabor 985219019Sgabor@item 986219019Sgaborenvironment switching 987219019Sgabor 988219019Sgabor@item 989219019Sgaborinsertions from the standard input 990219019Sgabor 991219019Sgabor@item 992219019Sgaborinput/output file switching 993219019Sgabor 994219019Sgabor@item 995219019Sgaboroutput and error messages 996219019Sgabor@end itemize 997219019Sgabor 998219019Sgabor 999219019Sgabor@c ===================================================================== 1000219019Sgabor 1001219019Sgabor@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 1002219019Sgabor@section Macro Packages 1003219019Sgabor@cindex macro packages 1004219019Sgabor 1005219019SgaborSince @code{groff} provides such low-level facilities, it can be quite 1006219019Sgabordifficult to use by itself. However, @code{groff} provides a 1007219019Sgabor@dfn{macro} facility to specify how certain routine operations (e.g.@w{ 1008219019Sgabor}starting paragraphs, printing headers and footers, etc.)@: should be 1009219019Sgabordone. These macros can be collected together into a @dfn{macro 1010219019Sgaborpackage}. There are a number of macro packages available; the most 1011219019Sgaborcommon (and the ones described in this manual) are @file{man}, 1012219019Sgabor@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 1013219019Sgabor 1014219019Sgabor 1015219019Sgabor@c ===================================================================== 1016219019Sgabor 1017219019Sgabor@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 1018219019Sgabor@section Preprocessors 1019219019Sgabor@cindex preprocessors 1020219019Sgabor 1021219019SgaborAlthough @code{groff} provides most functions needed to format a 1022219019Sgabordocument, some operations would be unwieldy (e.g.@: to draw pictures). 1023219019SgaborTherefore, programs called preprocessors were written which understand 1024219019Sgabortheir own language and produce the necessary @code{groff} operations. 1025219019SgaborThese preprocessors are able to differentiate their own input from the 1026219019Sgaborrest of the document via markers. 1027219019Sgabor 1028219019SgaborTo use a preprocessor, @acronym{UNIX} pipes are used to feed the output 1029219019Sgaborfrom the preprocessor into @code{groff}. Any number of preprocessors 1030219019Sgabormay be used on a given document; in this case, the preprocessors are 1031219019Sgaborlinked together into one pipeline. However, in @code{groff}, the user 1032219019Sgabordoes not need to construct the pipe, but only tell @code{groff} what 1033219019Sgaborpreprocessors to use. 1034219019Sgabor 1035219019Sgabor@code{groff} currently has preprocessors for producing tables 1036219019Sgabor(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 1037219019Sgabor(@code{pic} and @code{grn}), and for processing bibliographies 1038219019Sgabor(@code{refer}). An associated program which is useful when dealing with 1039219019Sgaborpreprocessors is @code{soelim}. 1040219019Sgabor 1041219019SgaborA free implementation of @code{grap}, a preprocessor for drawing graphs, 1042219019Sgaborcan be obtained as an extra package; @code{groff} can use @code{grap} 1043219019Sgaboralso. 1044219019Sgabor 1045219019SgaborThere are other preprocessors in existence, but, unfortunately, no free 1046219019Sgaborimplementations are available. Among them are preprocessors for drawing 1047219019Sgabormathematical pictures (@code{ideal}) and chemical structures 1048219019Sgabor(@code{chem}). 1049219019Sgabor 1050219019Sgabor 1051219019Sgabor@c ===================================================================== 1052219019Sgabor 1053219019Sgabor@node Output device intro, Credits, Preprocessor Intro, Introduction 1054219019Sgabor@section Output Devices 1055219019Sgabor@cindex postprocessors 1056219019Sgabor@cindex output devices 1057219019Sgabor@cindex devices for output 1058219019Sgabor 1059219019Sgabor@code{groff} actually produces device independent code which may be 1060219019Sgaborfed into a postprocessor to produce output for a particular device. 1061219019SgaborCurrently, @code{groff} has postprocessors for @sc{PostScript} 1062219019Sgabordevices, character terminals, X@w{ }Windows (for previewing), @TeX{} 1063219019SgaborDVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use 1064219019Sgabor@acronym{CAPSL}), and @acronym{HTML}. 1065219019Sgabor 1066219019Sgabor 1067219019Sgabor@c ===================================================================== 1068219019Sgabor 1069219019Sgabor@node Credits, , Output device intro, Introduction 1070219019Sgabor@section Credits 1071219019Sgabor@cindex credits 1072219019Sgabor 1073219019SgaborLarge portions of this manual were taken from existing documents, most 1074219019Sgabornotably, the manual pages for the @code{groff} package by James Clark, 1075219019Sgaborand Eric Allman's papers on the @file{me} macro package. 1076219019Sgabor 1077219019SgaborThe section on the @file{man} macro package is partly based on Susan@w{ 1078219019Sgabor}G.@: Kleinmann's @file{groff_man} manual page written for the Debian 1079219019SgaborGNU/Linux system. 1080219019Sgabor 1081219019Sgabor 1082219019Sgabor 1083219019Sgabor 1084219019Sgabor@c ===================================================================== 1085219019Sgabor@c ===================================================================== 1086219019Sgabor 1087219019Sgabor@node Invoking groff, Tutorial for Macro Users, Introduction, Top 1088219019Sgabor@chapter Invoking @code{groff} 1089219019Sgabor@cindex invoking @code{groff} 1090219019Sgabor@cindex @code{groff} invocation 1091219019Sgabor 1092219019SgaborThis section focuses on how to invoke the @code{groff} front end. This 1093219019Sgaborfront end takes care of the details of constructing the pipeline among 1094219019Sgaborthe preprocessors, @code{gtroff} and the postprocessor. 1095219019Sgabor 1096219019SgaborIt has become a tradition that GNU programs get the prefix @samp{g} to 1097219019Sgabordistinguish it from its original counterparts provided by the host (see 1098219019Sgabor@ref{Environment}, for more details). Thus, for example, @code{geqn} is 1099219019SgaborGNU @code{eqn}. On operating systems like Linux or the Hurd, which 1100219019Sgabordon't contain proprietary software, and on MS-DOS/MS-Windows, where 1101219019Sgabor@code{troff} and associated programs are not available at all, this 1102219019Sgaborprefix is omitted since GNU @code{troff} is the only used incarnation of 1103219019Sgabor@code{troff}. Exception: @code{groff} is never replaced by @code{roff}. 1104219019Sgabor 1105219019Sgabor@menu 1106219019Sgabor* Groff Options:: 1107219019Sgabor* Environment:: 1108219019Sgabor* Invocation Examples:: 1109219019Sgabor@end menu 1110219019Sgabor 1111219019Sgabor 1112219019Sgabor@c ===================================================================== 1113219019Sgabor 1114219019Sgabor@node Groff Options, Environment, Invoking groff, Invoking groff 1115219019Sgabor@section Options 1116219019Sgabor@cindex options 1117219019Sgabor 1118219019Sgabor@pindex groff 1119219019Sgabor@pindex gtroff 1120219019Sgabor@pindex gpic 1121219019Sgabor@pindex geqn 1122219019Sgabor@pindex ggrn 1123219019Sgabor@pindex grap 1124219019Sgabor@pindex gtbl 1125219019Sgabor@pindex grefer 1126219019Sgabor@pindex gsoelim 1127219019Sgabor@code{groff} normally runs the @code{gtroff} program and a postprocessor 1128219019Sgaborappropriate for the selected device. The default device is @samp{ps} 1129219019Sgabor(but it can be changed when @code{groff} is configured and built). It 1130219019Sgaborcan optionally preprocess with any of @code{gpic}, @code{geqn}, 1131219019Sgabor@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 1132219019Sgabor 1133219019SgaborThis section only documents options to the @code{groff} front end. Many 1134219019Sgaborof the arguments to @code{groff} are passed on to @code{gtroff}, 1135219019Sgabortherefore those are also included. Arguments to pre- or postprocessors 1136219019Sgaborcan be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 1137219019Sgaborgtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 1138219019Sgaborgsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 1139219019Sgaborgrohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 1140219019Sgaborgrolbp}, and @ref{Invoking gxditview}. 1141219019Sgabor 1142219019SgaborThe command line format for @code{groff} is: 1143219019Sgabor 1144219019Sgabor@Example 1145219019Sgaborgroff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 1146219019Sgabor [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 1147219019Sgabor [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 1148219019Sgabor [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 1149219019Sgabor [ @var{files}@dots{} ] 1150219019Sgabor@endExample 1151219019Sgabor 1152219019SgaborThe command line format for @code{gtroff} is as follows. 1153219019Sgabor 1154219019Sgabor@Example 1155219019Sgaborgtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 1156219019Sgabor [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 1157219019Sgabor [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 1158219019Sgabor [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 1159219019Sgabor@endExample 1160219019Sgabor 1161219019Sgabor@noindent 1162219019SgaborObviously, many of the options to @code{groff} are actually passed on to 1163219019Sgabor@code{gtroff}. 1164219019Sgabor 1165219019SgaborOptions without an argument can be grouped behind a single @option{-}. 1166219019SgaborA filename of @file{-} denotes the standard input. It is possible to 1167219019Sgaborhave whitespace between an option and its parameter. 1168219019Sgabor 1169219019SgaborThe @code{grog} command can be used to guess the correct @code{groff} 1170219019Sgaborcommand to format a file. 1171219019Sgabor 1172219019SgaborHere's the description of the command-line options: 1173219019Sgabor 1174219019Sgabor@cindex command-line options 1175219019Sgabor@table @samp 1176219019Sgabor@item -h 1177219019SgaborPrint a help message. 1178219019Sgabor 1179219019Sgabor@item -e 1180219019SgaborPreprocess with @code{geqn}. 1181219019Sgabor 1182219019Sgabor@item -t 1183219019SgaborPreprocess with @code{gtbl}. 1184219019Sgabor 1185219019Sgabor@item -g 1186219019SgaborPreprocess with @code{ggrn}. 1187219019Sgabor 1188219019Sgabor@item -G 1189219019SgaborPreprocess with @code{grap}. 1190219019Sgabor 1191219019Sgabor@item -p 1192219019SgaborPreprocess with @code{gpic}. 1193219019Sgabor 1194219019Sgabor@item -s 1195219019SgaborPreprocess with @code{gsoelim}. 1196219019Sgabor 1197219019Sgabor@item -R 1198219019SgaborPreprocess with @code{grefer}. No mechanism is provided for passing 1199219019Sgaborarguments to @code{grefer} because most @code{grefer} options have 1200219019Sgaborequivalent commands which can be included in the file. @xref{grefer}, 1201219019Sgaborfor more details. 1202219019Sgabor 1203219019Sgabor@pindex troffrc 1204219019Sgabor@pindex troffrc-end 1205219019SgaborNote that @code{gtroff} also accepts a @option{-R} option, which is not 1206219019Sgaboraccessible via @code{groff}. This option prevents the loading of the 1207219019Sgabor@file{troffrc} and @file{troffrc-end} files. 1208219019Sgabor 1209219019Sgabor@item -v 1210219019SgaborMake programs run by @code{groff} print out their version number. 1211219019Sgabor 1212219019Sgabor@item -V 1213219019SgaborPrint the pipeline on @code{stdout} instead of executing it. 1214219019Sgabor 1215219019Sgabor@item -z 1216219019SgaborSuppress output from @code{gtroff}. Only error messages are printed. 1217219019Sgabor 1218219019Sgabor@item -Z 1219219019SgaborDo not postprocess the output of @code{gtroff}. Normally @code{groff} 1220219019Sgaborautomatically runs the appropriate postprocessor. 1221219019Sgabor 1222219019Sgabor@item -P@var{arg} 1223219019SgaborPass @var{arg} to the postprocessor. Each argument should be passed 1224219019Sgaborwith a separate @option{-P} option. Note that @code{groff} does not 1225219019Sgaborprepend @samp{-} to @var{arg} before passing it to the postprocessor. 1226219019Sgabor 1227219019Sgabor@item -l 1228219019SgaborSend the output to a spooler for printing. The command used for this is 1229219019Sgaborspecified by the @code{print} command in the device description file 1230219019Sgabor(see @ref{Font Files}, for more info). If not present, @option{-l} is 1231219019Sgaborignored. 1232219019Sgabor 1233219019Sgabor@item -L@var{arg} 1234219019SgaborPass @var{arg} to the spooler. Each argument should be passed with a 1235219019Sgaborseparate @option{-L} option. Note that @code{groff} does not prepend a 1236219019Sgabor@samp{-} to @var{arg} before passing it to the postprocessor. If the 1237219019Sgabor@code{print} keyword in the device description file is missing, 1238219019Sgabor@option{-L} is ignored. 1239219019Sgabor 1240219019Sgabor@item -T@var{dev} 1241219019SgaborPrepare output for device @var{dev}. The default device is @samp{ps}, 1242219019Sgaborunless changed when @code{groff} was configured and built. The 1243219019Sgaborfollowing are the output devices currently available: 1244219019Sgabor 1245219019Sgabor@table @code 1246219019Sgabor@item ps 1247219019SgaborFor @sc{PostScript} printers and previewers. 1248219019Sgabor 1249219019Sgabor@item dvi 1250219019SgaborFor @TeX{} DVI format. 1251219019Sgabor 1252219019Sgabor@item X75 1253219019SgaborFor a 75@dmn{dpi} X11 previewer. 1254219019Sgabor 1255219019Sgabor@item X100 1256219019SgaborFor a 100@dmn{dpi} X11 previewer. 1257219019Sgabor 1258219019Sgabor@item ascii 1259219019SgaborFor typewriter-like devices. 1260219019Sgabor 1261219019Sgabor@item latin1 1262219019SgaborFor typewriter-like devices that support the @w{Latin-1} (@w{ISO 1263219019Sgabor8859-1}) character set. 1264219019Sgabor 1265219019Sgabor@item utf8 1266219019SgaborFor typewriter-like devices which use the Unicode (@w{ISO 10646}) 1267219019Sgaborcharacter set with @w{UTF-8} encoding. 1268219019Sgabor 1269219019Sgabor@item cp1047 1270219019Sgabor@cindex @acronym{EBCDIC} encoding 1271219019Sgabor@cindex cp1047 1272219019Sgabor@cindex IBM cp1047 1273219019SgaborFor typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 1274219019Sgaborcp1047. 1275219019Sgabor 1276219019Sgabor@item lj4 1277219019SgaborFor an HP LaserJet4-compatible (or other PCL5-compatible) printer. 1278219019Sgabor 1279219019Sgabor@item lbp 1280219019SgaborFor Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 1281219019Sgaborprinters). 1282219019Sgabor 1283219019Sgabor@pindex pre-grohtml 1284219019Sgabor@pindex post-grohtml 1285219019Sgabor@cindex @code{grohtml} 1286219019Sgabor@item html 1287219019SgaborTo produce @acronym{HTML} output. Note that the @acronym{HTML} driver 1288219019Sgaborconsists of two parts, a preprocessor (@code{pre-grohtml}) and a 1289219019Sgaborpostprocessor (@code{post-grohtml}). 1290219019Sgabor@end table 1291219019Sgabor 1292219019Sgabor@vindex .T 1293219019Sgabor@stindex .T 1294219019SgaborThe predefined @code{gtroff} string register @code{.T} contains the 1295219019Sgaborcurrent output device; the read-only number register @code{.T} is set 1296219019Sgaborto@w{ }1 if this option is used (which is always true if @code{groff} is 1297219019Sgaborused to call @code{gtroff}). @xref{Built-in Registers}. 1298219019Sgabor 1299219019SgaborThe postprocessor to be used for a device is specified by the 1300219019Sgabor@code{postpro} command in the device description file. (@xref{Font 1301219019SgaborFiles}, for more info.) This can be overridden with the @option{-X} 1302219019Sgaboroption. 1303219019Sgabor 1304219019Sgabor@item -X 1305219019SgaborPreview with @code{gxditview} instead of using the usual postprocessor. 1306219019SgaborThis is unlikely to produce good results except with @option{-Tps}. 1307219019Sgabor 1308219019SgaborNote that this is not the same as using @option{-TX75} or 1309219019Sgabor@option{-TX100} to view a document with @code{gxditview}: The former 1310219019Sgaboruses the metrics of the specified device, whereas the latter uses 1311219019SgaborX-specific fonts and metrics. 1312219019Sgabor 1313219019Sgabor@item -N 1314219019SgaborDon't allow newlines with @code{eqn} delimiters. This is the same as 1315219019Sgaborthe @option{-N} option in @code{geqn}. 1316219019Sgabor 1317219019Sgabor@item -S 1318219019SgaborSafer mode. Pass the @option{-S} option to @code{gpic} and disable the 1319219019Sgabor@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 1320219019Sgaborrequests. For security reasons, this is enabled by default. 1321219019Sgabor 1322219019Sgabor@item -U 1323219019SgaborUnsafe mode. Reverts to the old unsafe behaviour. 1324219019Sgabor 1325219019Sgabor@item -a 1326219019Sgabor@vindex .A 1327219019SgaborGenerate an @acronym{ASCII} approximation of the typeset output. The 1328219019Sgaborread-only register @code{.A} is then set to@w{ }1. @xref{Built-in 1329219019SgaborRegisters}. A typical example is 1330219019Sgabor 1331219019Sgabor@Example 1332219019Sgaborgroff -a -man -Tdvi troff.man | less 1333219019Sgabor@endExample 1334219019Sgabor 1335219019Sgabor@noindent 1336219019Sgaborwhich shows how lines are broken for the DVI device. Note that this 1337219019Sgaboroption is rather useless today since graphic output devices are 1338219019Sgaboravailable virtually everywhere. 1339219019Sgabor 1340219019Sgabor@item -b 1341219019SgaborPrint a backtrace with each warning or error message. This backtrace 1342219019Sgaborshould help track down the cause of the error. The line numbers given 1343219019Sgaborin the backtrace may not always be correct: @code{gtroff} can get 1344219019Sgaborconfused by @code{as} or @code{am} requests while counting line numbers. 1345219019Sgabor 1346219019Sgabor@item -i 1347219019SgaborRead the standard input after all the named input files have been 1348219019Sgaborprocessed. 1349219019Sgabor 1350219019Sgabor@item -w@var{name} 1351219019SgaborEnable warning @var{name}. Available warnings are described in 1352219019Sgabor@ref{Debugging}. Multiple @option{-w} options are allowed. 1353219019Sgabor 1354219019Sgabor@item -W@var{name} 1355219019SgaborInhibit warning @var{name}. Multiple @option{-W} options are allowed. 1356219019Sgabor 1357219019Sgabor@item -E 1358219019SgaborInhibit all error messages. 1359219019Sgabor 1360219019Sgabor@item -C 1361219019SgaborEnable compatibility mode. @xref{Implementation Differences}, for the 1362219019Sgaborlist of incompatibilities between @code{groff} and traditional Unix 1363219019Sgabor@code{troff}. 1364219019Sgabor 1365219019Sgabor@item -d@var{cs} 1366219019Sgabor@itemx -d@var{name}=s 1367219019SgaborDefine @var{c} or @var{name} to be a string @var{s}. @var{c} must be a 1368219019Sgaborone-letter name; @var{name} can be of arbitrary length. All string 1369219019Sgaborassignments happen before loading any macro file (including the start-up 1370219019Sgaborfile). 1371219019Sgabor 1372219019Sgabor@item -f@var{fam} 1373219019SgaborUse @var{fam} as the default font family. @xref{Font Families}. 1374219019Sgabor 1375219019Sgabor@item -m@var{name} 1376219019SgaborRead in the file @file{@var{name}.tmac}. Normally @code{groff} searches 1377219019Sgaborfor this in its macro directories. If it isn't found, it tries 1378219019Sgabor@file{tmac.@var{name}} (and searches in the same directories). 1379219019Sgabor 1380219019Sgabor@c XXX document local and system macro dirs 1381219019Sgabor 1382219019Sgabor@item -n@var{num} 1383219019SgaborNumber the first page @var{num}. 1384219019Sgabor 1385219019Sgabor@item -o@var{list} 1386219019Sgabor@vindex .P 1387219019SgaborOutput only pages in @var{list}, which is a comma-separated list of page 1388219019Sgaborranges; @samp{@var{n}} means print page @var{n}, @samp{@var{m}-@var{n}} 1389219019Sgabormeans print every page between @var{m} and @var{n}, @samp{-@var{n}} 1390219019Sgabormeans print every page up to @var{n}, @samp{@var{n}-} means print every 1391219019Sgaborpage beginning with @var{n}. @code{gtroff} exits after printing the 1392219019Sgaborlast page in the list. All the ranges are inclusive on both ends. 1393219019Sgabor 1394219019SgaborWithin @code{gtroff}, this information can be extracted with the 1395219019Sgabor@samp{.P} register. @xref{Built-in Registers}. 1396219019Sgabor 1397219019SgaborIf your document restarts page numbering at the beginning of each 1398219019Sgaborchapter, then @code{gtroff} prints the specified page range for each 1399219019Sgaborchapter. 1400219019Sgabor 1401219019Sgabor@item -r@var{cn} 1402219019Sgabor@itemx -r@var{name}=@var{n} 1403219019SgaborSet number register @var{c} or @var{name} to the value @var{n}. @var{c} 1404219019Sgabormust be a one-letter name; @var{name} can be of arbitrary length. 1405219019Sgabor@var{n} can be any @code{gtroff} numeric expression. All register 1406219019Sgaborassignments happen before loading any macro file (including the start-up 1407219019Sgaborfile). 1408219019Sgabor 1409219019Sgabor@item -F@var{dir} 1410219019SgaborSearch @file{@var{dir}} for subdirectories @file{dev@var{name}} 1411219019Sgabor(@var{name} is the name of the device), for the @file{DESC} file, and 1412219019Sgaborfor font files before looking in the standard directories. 1413219019Sgabor 1414219019Sgabor@item -M@var{dir} 1415219019SgaborSearch directory @file{@var{dir}} for macro files before the standard 1416219019Sgabordirectories. 1417219019Sgabor 1418219019Sgabor@item -I@var{dir} 1419219019SgaborThis option is as described in @ref{gsoelim}. It implies the 1420219019Sgabor@option{-s} option. 1421219019Sgabor@end table 1422219019Sgabor 1423219019Sgabor 1424219019Sgabor@c ===================================================================== 1425219019Sgabor 1426219019Sgabor@node Environment, Invocation Examples, Groff Options, Invoking groff 1427219019Sgabor@section Environment 1428219019Sgabor@cindex environment variables 1429219019Sgabor@cindex variables in environment 1430219019Sgabor 1431219019SgaborThere are also several environment variables (of the operating system, 1432219019Sgabornot within @code{gtroff}) which can modify the behavior of @code{groff}. 1433219019Sgabor 1434219019Sgabor@table @code 1435219019Sgabor@item GROFF_COMMAND_PREFIX 1436219019Sgabor@tindex GROFF_COMMAND_PREFIX, environment variable 1437219019SgaborIf this is set to @var{X}, then @code{groff} runs @code{@var{X}troff} 1438219019Sgaborinstead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 1439219019Sgabor@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 1440219019Sgaborapply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 1441219019Sgabor@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 1442219019Sgabor 1443219019Sgabor@c XXX document default values 1444219019Sgabor 1445219019Sgabor@item GROFF_TMAC_PATH 1446219019Sgabor@tindex GROFF_TMAC_PATH, environment variable 1447219019SgaborA colon-separated list of directories in which to search for macro files 1448219019Sgabor(before the default directories are tried). 1449219019Sgabor 1450219019Sgabor@c XXX document local and system macro dirs 1451219019Sgabor 1452219019Sgabor@item GROFF_TYPESETTER 1453219019Sgabor@tindex GROFF_TYPESETTER, environment variable 1454219019SgaborThe default output device. 1455219019Sgabor 1456219019Sgabor@item GROFF_FONT_PATH 1457219019Sgabor@tindex GROFF_FONT_PATH, environment variable 1458219019SgaborA colon-separated list of directories in which to search for the 1459219019Sgabor@code{dev}@var{name} directory (before the default directories are 1460219019Sgabortried). 1461219019Sgabor 1462219019Sgabor@item GROFF_BIN_PATH 1463219019Sgabor@tindex GROFF_BIN_PATH, environment variable 1464219019SgaborThis search path, followed by @code{PATH}, is used for commands executed 1465219019Sgaborby @code{groff}. 1466219019Sgabor 1467219019Sgabor@item GROFF_TMPDIR 1468219019Sgabor@tindex GROFF_TMPDIR, environment variable 1469219019Sgabor@tindex TMPDIR, environment variable 1470219019SgaborThe directory in which @code{groff} creates temporary files. If this is 1471219019Sgabornot set and @env{TMPDIR} is set, temporary files are created in that 1472219019Sgabordirectory. Otherwise temporary files are created in a system-dependent 1473219019Sgabordefault directory (on Unix and GNU/Linux systems, this is usually 1474219019Sgabor@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 1475219019Sgabor@code{post-grohtml} can create temporary files in this directory. 1476219019Sgabor@end table 1477219019Sgabor 1478219019SgaborNote that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 1479219019Sgaborrather than colons, to separate the directories in the lists described 1480219019Sgaborabove. 1481219019Sgabor 1482219019Sgabor 1483219019Sgabor@c ===================================================================== 1484219019Sgabor 1485219019Sgabor@node Invocation Examples, , Environment, Invoking groff 1486219019Sgabor@section Invocation Examples 1487219019Sgabor@cindex invocation examples 1488219019Sgabor@cindex examples of invocation 1489219019Sgabor 1490219019SgaborThis section lists several common uses of @code{groff} and the 1491219019Sgaborcorresponding command lines. 1492219019Sgabor 1493219019Sgabor@Example 1494219019Sgaborgroff file 1495219019Sgabor@endExample 1496219019Sgabor 1497219019Sgabor@noindent 1498219019SgaborThis command processes @file{file} without a macro package or a 1499219019Sgaborpreprocessor. The output device is the default, @samp{ps}, and the 1500219019Sgaboroutput is sent to @code{stdout}. 1501219019Sgabor 1502219019Sgabor@Example 1503219019Sgaborgroff -t -mandoc -Tascii file | less 1504219019Sgabor@endExample 1505219019Sgabor 1506219019Sgabor@noindent 1507219019SgaborThis is basically what a call to the @code{man} program does. 1508219019Sgabor@code{gtroff} processes the manual page @file{file} with the 1509219019Sgabor@file{mandoc} macro file (which in turn either calls the @file{man} or 1510219019Sgaborthe @file{mdoc} macro package), using the @code{tbl} preprocessor and 1511219019Sgaborthe @acronym{ASCII} output device. Finally, the @code{less} pager 1512219019Sgabordisplays the result. 1513219019Sgabor 1514219019Sgabor@Example 1515219019Sgaborgroff -X -m me file 1516219019Sgabor@endExample 1517219019Sgabor 1518219019Sgabor@noindent 1519219019SgaborPreview @file{file} with @code{gxditview}, using the @file{me} macro 1520219019Sgaborpackage. Since no @option{-T} option is specified, use the default 1521219019Sgabordevice (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 1522219019Sgabor@w{@samp{-me}}; the latter is an anachronism from the early days of 1523219019Sgabor@acronym{UNIX}.@footnote{The same is true for the other main macro 1524219019Sgaborpackages that come with @code{groff}: @file{man}, @file{mdoc}, 1525219019Sgabor@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 1526219019Sgaborfor example, to load @file{trace.tmac}, either @samp{-mtrace} or 1527219019Sgabor@w{@samp{-m trace}} must be used.} 1528219019Sgabor 1529219019Sgabor@Example 1530219019Sgaborgroff -man -rD1 -z file 1531219019Sgabor@endExample 1532219019Sgabor 1533219019Sgabor@noindent 1534219019SgaborCheck @file{file} with the @file{man} macro package, forcing 1535219019Sgabordouble-sided printing -- don't produce any output. 1536219019Sgabor 1537219019Sgabor@menu 1538219019Sgabor* grog:: 1539219019Sgabor@end menu 1540219019Sgabor 1541219019Sgabor@c --------------------------------------------------------------------- 1542219019Sgabor 1543219019Sgabor@node grog, , Invocation Examples, Invocation Examples 1544219019Sgabor@subsection @code{grog} 1545219019Sgabor 1546219019Sgabor@pindex grog 1547219019Sgabor@code{grog} reads files, guesses which of the @code{groff} preprocessors 1548219019Sgaborand/or macro packages are required for formatting them, and prints the 1549219019Sgabor@code{groff} command including those options on the standard output. It 1550219019Sgaborgenerates one or more of the options @option{-e}, @option{-man}, 1551219019Sgabor@option{-me}, @option{-mm}, @option{-ms}, @option{-mdoc}, 1552219019Sgabor@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 1553219019Sgabor@option{-s}, and @option{-t}. 1554219019Sgabor 1555219019SgaborA special file name @file{-} refers to the standard input. Specifying 1556219019Sgaborno files also means to read the standard input. Any specified options 1557219019Sgaborare included in the printed command. No space is allowed between 1558219019Sgaboroptions and their arguments. The only options recognized are 1559219019Sgabor@option{-C} (which is also passed on) to enable compatibility mode, and 1560219019Sgabor@option{-v} (if it is the only parameter) to print the version number. 1561219019Sgabor 1562219019SgaborFor example, 1563219019Sgabor 1564219019Sgabor@Example 1565219019Sgaborgrog -Tdvi paper.ms 1566219019Sgabor@endExample 1567219019Sgabor 1568219019Sgabor@noindent 1569219019Sgaborguesses the appropriate command to print @file{paper.ms} and then prints 1570219019Sgaborit to the command line after adding the @option{-Tdvi} option. For 1571219019Sgabordirect execution, enclose the call to @code{grog} in backquotes at the 1572219019Sgabor@acronym{UNIX} shell prompt: 1573219019Sgabor 1574219019Sgabor@Example 1575219019Sgabor`grog -Tdvi paper.ms` > paper.dvi 1576219019Sgabor@endExample 1577219019Sgabor 1578219019Sgabor@noindent 1579219019SgaborAs seen in the example, it is still necessary to redirect the output to 1580219019Sgaborsomething meaningful (i.e.@: either a file or a pager program like 1581219019Sgabor@code{less}). 1582219019Sgabor 1583219019Sgabor 1584219019Sgabor 1585219019Sgabor@c ===================================================================== 1586219019Sgabor@c ===================================================================== 1587219019Sgabor 1588219019Sgabor@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 1589219019Sgabor@chapter Tutorial for Macro Users 1590219019Sgabor@cindex tutorial for macro users 1591219019Sgabor@cindex macros, tutorial for users 1592219019Sgabor@cindex user's tutorial for macros 1593219019Sgabor@cindex user's macro tutorial 1594219019Sgabor 1595219019SgaborMost users tend to use a macro package to format their papers. This 1596219019Sgabormeans that the whole breadth of @code{groff} is not necessary for most 1597219019Sgaborpeople. This chapter covers the material needed to efficiently use a 1598219019Sgabormacro package. 1599219019Sgabor 1600219019Sgabor@menu 1601219019Sgabor* Basics:: 1602219019Sgabor* Common Features:: 1603219019Sgabor@end menu 1604219019Sgabor 1605219019Sgabor 1606219019Sgabor@c ===================================================================== 1607219019Sgabor 1608219019Sgabor@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1609219019Sgabor@section Basics 1610219019Sgabor@cindex basics of macros 1611219019Sgabor@cindex macro basics 1612219019Sgabor 1613219019SgaborThis section covers some of the basic concepts necessary to understand 1614219019Sgaborhow to use a macro package.@footnote{This section is derived from 1615219019Sgabor@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.} 1616219019SgaborReferences are made throughout to more detailed information, if desired. 1617219019Sgabor 1618219019Sgabor@code{gtroff} reads an input file prepared by the user and outputs a 1619219019Sgaborformatted document suitable for publication or framing. The input 1620219019Sgaborconsists of text, or words to be printed, and embedded commands 1621219019Sgabor(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 1622219019Sgaborformat the output. For more detail on this, see @ref{Embedded 1623219019SgaborCommands}. 1624219019Sgabor 1625219019SgaborThe word @dfn{argument} is used in this chapter to mean a word or number 1626219019Sgaborwhich appears on the same line as a request, and which modifies the 1627219019Sgabormeaning of that request. For example, the request 1628219019Sgabor 1629219019Sgabor@Example 1630219019Sgabor.sp 1631219019Sgabor@endExample 1632219019Sgabor 1633219019Sgabor@noindent 1634219019Sgaborspaces one line, but 1635219019Sgabor 1636219019Sgabor@Example 1637219019Sgabor.sp 4 1638219019Sgabor@endExample 1639219019Sgabor 1640219019Sgabor@noindent 1641219019Sgaborspaces four lines. The number@w{ }4 is an argument to the @code{sp} 1642219019Sgaborrequest which says to space four lines instead of one. Arguments are 1643219019Sgaborseparated from the request and from each other by spaces (@emph{no} 1644219019Sgabortabs). More details on this can be found in @ref{Request Arguments}. 1645219019Sgabor 1646219019SgaborThe primary function of @code{gtroff} is to collect words from input 1647219019Sgaborlines, fill output lines with those words, justify the right-hand margin 1648219019Sgaborby inserting extra spaces in the line, and output the result. For 1649219019Sgaborexample, the input: 1650219019Sgabor 1651219019Sgabor@Example 1652219019SgaborNow is the time 1653219019Sgaborfor all good men 1654219019Sgaborto come to the aid 1655219019Sgaborof their party. 1656219019SgaborFour score and seven 1657219019Sgaboryears ago,... 1658219019Sgabor@endExample 1659219019Sgabor 1660219019Sgabor@noindent 1661219019Sgaboris read, packed onto output lines, and justified to produce: 1662219019Sgabor 1663219019Sgabor@quotation 1664219019SgaborNow is the time for all good men to come to the aid of their party. 1665219019SgaborFour score and seven years ago,... 1666219019Sgabor@end quotation 1667219019Sgabor 1668219019Sgabor@cindex break 1669219019Sgabor@cindex line break 1670219019SgaborSometimes a new output line should be started even though the current 1671219019Sgaborline is not yet full; for example, at the end of a paragraph. To do 1672219019Sgaborthis it is possible to cause a @dfn{break}, which starts a new output 1673219019Sgaborline. Some requests cause a break automatically, as normally do blank 1674219019Sgaborinput lines and input lines beginning with a space. 1675219019Sgabor 1676219019SgaborNot all input lines are text to be formatted. Some input lines are 1677219019Sgaborrequests which describe how to format the text. Requests always have a 1678219019Sgaborperiod (@samp{.}) or an apostrophe (@samp{'}) as the first character of 1679219019Sgaborthe input line. 1680219019Sgabor 1681219019SgaborThe text formatter also does more complex things, such as automatically 1682219019Sgabornumbering pages, skipping over page boundaries, putting footnotes in the 1683219019Sgaborcorrect place, and so forth. 1684219019Sgabor 1685219019SgaborHere are a few hints for preparing text for input to @code{gtroff}. 1686219019Sgabor 1687219019Sgabor@itemize @bullet 1688219019Sgabor@item 1689219019SgaborFirst, keep the input lines short. Short input lines are easier to 1690219019Sgaboredit, and @code{gtroff} packs words onto longer lines anyhow. 1691219019Sgabor 1692219019Sgabor@item 1693219019SgaborIn keeping with this, it is helpful to begin a new line after every 1694219019Sgaborcomma or phrase, since common corrections are to add or delete sentences 1695219019Sgaboror phrases. 1696219019Sgabor 1697219019Sgabor@item 1698219019SgaborEnd each sentence with two spaces -- or better, start each sentence on a 1699219019Sgabornew line. @code{gtroff} recognizes characters that usually end a 1700219019Sgaborsentence, and inserts sentence space accordingly. 1701219019Sgabor 1702219019Sgabor@item 1703219019SgaborDo not hyphenate words at the end of lines -- @code{gtroff} is smart 1704219019Sgaborenough to hyphenate words as needed, but is not smart enough to take 1705219019Sgaborhyphens out and join a word back together. Also, words such as 1706219019Sgabor``mother-in-law'' should not be broken over a line, since then a space 1707219019Sgaborcan occur where not wanted, such as ``@w{mother- in}-law''. 1708219019Sgabor@end itemize 1709219019Sgabor 1710219019Sgabor@rqindex ls 1711219019Sgabor@cindex double spacing 1712219019Sgabor@cindex spacing 1713219019Sgabor@code{gtroff} double spaces output text automatically if you use the 1714219019Sgaborrequest @w{@samp{.ls 2}}. Reactivate single spaced mode by typing 1715219019Sgabor@w{@samp{.ls 1}}. 1716219019Sgabor 1717219019SgaborA number of requests allow to change the way the output looks, 1718219019Sgaborsometimes called the @dfn{layout} of the output page. Most of these 1719219019Sgaborrequests adjust the placing of @dfn{white space} (blank lines or 1720219019Sgaborspaces). 1721219019Sgabor 1722219019Sgabor@cindex new page 1723219019SgaborThe @samp{.bp} request starts a new page, causing a line break. 1724219019Sgabor 1725219019Sgabor@cindex blank line 1726219019Sgabor@cindex empty line 1727219019Sgabor@cindex line, empty 1728219019SgaborThe request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank 1729219019Sgaborspace. @var{N}@w{ }can be omitted (meaning skip a single line) or can 1730219019Sgaborbe of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for 1731219019Sgabor@var{N}@w{ }centimeters). For example, the input: 1732219019Sgabor 1733219019Sgabor@Example 1734219019Sgabor.sp 1.5i 1735219019SgaborMy thoughts on the subject 1736219019Sgabor.sp 1737219019Sgabor@endExample 1738219019Sgabor 1739219019Sgabor@noindent 1740219019Sgaborleaves one and a half inches of space, followed by the line ``My 1741219019Sgaborthoughts on the subject'', followed by a single blank line (more 1742219019Sgabormeasurement units are available, see @ref{Measurements}). 1743219019Sgabor 1744219019Sgabor@rqindex ce 1745219019Sgabor@cindex centering lines 1746219019Sgabor@cindex lines, centering 1747219019SgaborText lines can be centered by using the @code{ce} request. The line 1748219019Sgaborafter @code{ce} is centered (horizontally) on the page. To center more 1749219019Sgaborthan one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1750219019Sgaborof lines to center), followed by the @var{N}@w{ }lines. To center many 1751219019Sgaborlines without counting them, type: 1752219019Sgabor 1753219019Sgabor@Example 1754219019Sgabor.ce 1000 1755219019Sgaborlines to center 1756219019Sgabor.ce 0 1757219019Sgabor@endExample 1758219019Sgabor 1759219019Sgabor@noindent 1760219019SgaborThe @w{@samp{.ce 0}} request tells @code{groff} to center zero more 1761219019Sgaborlines, in other words, stop centering. 1762219019Sgabor 1763219019Sgabor@rqindex br 1764219019Sgabor@cindex line break 1765219019Sgabor@cindex break 1766219019SgaborAll of these requests cause a break; that is, they always start a new 1767219019Sgaborline. To start a new line without performing any other action, use 1768219019Sgabor@code{br}. 1769219019Sgabor 1770219019Sgabor 1771219019Sgabor@c ===================================================================== 1772219019Sgabor 1773219019Sgabor@node Common Features, , Basics, Tutorial for Macro Users 1774219019Sgabor@section Common Features 1775219019Sgabor@cindex common features 1776219019Sgabor@cindex features, common 1777219019Sgabor 1778219019Sgabor@code{gtroff} provides very low-level operations for formatting a 1779219019Sgabordocument. There are many common routine operations which are done in 1780219019Sgaborall documents. These common operations are written into @dfn{macros} 1781219019Sgaborand collected into a @dfn{macro package}. 1782219019Sgabor 1783219019SgaborAll macro packages provide certain common capabilities which fall into 1784219019Sgaborthe following categories. 1785219019Sgabor 1786219019Sgabor@menu 1787219019Sgabor* Paragraphs:: 1788219019Sgabor* Sections and Chapters:: 1789219019Sgabor* Headers and Footers:: 1790219019Sgabor* Page Layout Adjustment:: 1791219019Sgabor* Displays:: 1792219019Sgabor* Footnotes and Annotations:: 1793219019Sgabor* Table of Contents:: 1794219019Sgabor* Indices:: 1795219019Sgabor* Paper Formats:: 1796219019Sgabor* Multiple Columns:: 1797219019Sgabor* Font and Size Changes:: 1798219019Sgabor* Predefined Strings:: 1799219019Sgabor* Preprocessor Support:: 1800219019Sgabor* Configuration and Customization:: 1801219019Sgabor@end menu 1802219019Sgabor 1803219019Sgabor@c --------------------------------------------------------------------- 1804219019Sgabor 1805219019Sgabor@node Paragraphs, Sections and Chapters, Common Features, Common Features 1806219019Sgabor@subsection Paragraphs 1807219019Sgabor@cindex paragraphs 1808219019Sgabor 1809219019SgaborOne of the most common and most used capability is starting a 1810219019Sgaborparagraph. There are a number of different types of paragraphs, any 1811219019Sgaborof which can be initiated with macros supplied by the macro package. 1812219019SgaborNormally, paragraphs start with a blank line and the first line 1813219019Sgaborindented, like the text in this manual. There are also block style 1814219019Sgaborparagraphs, which omit the indentation: 1815219019Sgabor 1816219019Sgabor@Example 1817219019SgaborSome men look at constitutions with sanctimonious 1818219019Sgaborreverence, and deem them like the ark of the covenant, too 1819219019Sgaborsacred to be touched. 1820219019Sgabor@endExample 1821219019Sgabor 1822219019Sgabor@noindent 1823219019SgaborAnd there are also indented paragraphs which begin with a tag or label 1824219019Sgaborat the margin and the remaining text indented. 1825219019Sgabor 1826219019Sgabor@example 1827219019Sgabor@group 1828219019Sgaborone This is the first paragraph. Notice how the first 1829219019Sgabor line of the resulting paragraph lines up with the 1830219019Sgabor other lines in the paragraph. 1831219019Sgabor@end group 1832219019Sgabor@group 1833219019Sgaborlonglabel 1834219019Sgabor This paragraph had a long label. The first 1835219019Sgabor character of text on the first line does not line up 1836219019Sgabor with the text on second and subsequent lines, 1837219019Sgabor although they line up with each other. 1838219019Sgabor@end group 1839219019Sgabor@end example 1840219019Sgabor 1841219019SgaborA variation of this is a bulleted list. 1842219019Sgabor 1843219019Sgabor@c XXX description 1844219019Sgabor 1845219019Sgabor@c --------------------------------------------------------------------- 1846219019Sgabor 1847219019Sgabor@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 1848219019Sgabor@subsection Sections and Chapters 1849219019Sgabor 1850219019SgaborMost macro packages supply some form of section headers. The simplest 1851219019Sgaborkind is simply the heading on a line by itself in bold type. Others 1852219019Sgaborsupply automatically numbered section heading or different heading 1853219019Sgaborstyles at different levels. Some, more sophisticated, macro packages 1854219019Sgaborsupply macros for starting chapters and appendices. 1855219019Sgabor 1856219019Sgabor@c --------------------------------------------------------------------- 1857219019Sgabor 1858219019Sgabor@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 1859219019Sgabor@subsection Headers and Footers 1860219019Sgabor 1861219019SgaborEvery macro package gives some way to manipulate the headers and footers 1862219019Sgabor(or @dfn{titles}) on each page. Some packages allow for different ones 1863219019Sgaboron the even and odd pages (for material printed in a book form). 1864219019Sgabor 1865219019SgaborThe titles are called three-part titles, that is, there is a 1866219019Sgaborleft-justified part, a centered part, and a right-justified part. An 1867219019Sgaborautomatically generated page number may be put in any of these fields 1868219019Sgaborwith the @samp{%} character (see @ref{Page Layout}, for more details). 1869219019Sgabor 1870219019Sgabor@c --------------------------------------------------------------------- 1871219019Sgabor 1872219019Sgabor@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 1873219019Sgabor@subsection Page Layout 1874219019Sgabor 1875219019SgaborMost macro packages let the user specify top and bottom margins and 1876219019Sgaborother details about the appearance of the printed pages. 1877219019Sgabor 1878219019Sgabor@c --------------------------------------------------------------------- 1879219019Sgabor 1880219019Sgabor@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 1881219019Sgabor@subsection Displays 1882219019Sgabor@cindex displays 1883219019Sgabor 1884219019SgaborDisplays are sections of text to be set off from the body of the paper. 1885219019SgaborMajor quotes, tables, and figures are types of displays, as are all the 1886219019Sgaborexamples used in this document. 1887219019Sgabor 1888219019Sgabor@cindex quotes, major 1889219019Sgabor@cindex major quotes 1890219019Sgabor@dfn{Major quotes} are quotes which are several lines long, and hence 1891219019Sgaborare set in from the rest of the text without quote marks around them. 1892219019Sgabor 1893219019Sgabor@cindex list 1894219019SgaborA @dfn{list} is an indented, single spaced, unfilled display. Lists 1895219019Sgaborshould be used when the material to be printed should not be filled and 1896219019Sgaborjustified like normal text, such as columns of figures or the examples 1897219019Sgaborused in this paper. 1898219019Sgabor 1899219019Sgabor@cindex keep 1900219019SgaborA @dfn{keep} is a display of lines which are kept on a single page if 1901219019Sgaborpossible. An example for a keep might be a diagram. Keeps differ from 1902219019Sgaborlists in that lists may be broken over a page boundary whereas keeps are 1903219019Sgabornot. 1904219019Sgabor 1905219019Sgabor@cindex keep, floating 1906219019Sgabor@cindex floating keep 1907219019SgaborFloating keeps move relative to the text. Hence, they are good for 1908219019Sgaborthings which are referred to by name, such as ``See figure@w{ }3''. A 1909219019Sgaborfloating keep appears at the bottom of the current page if it fits; 1910219019Sgaborotherwise, it appears at the top of the next page. Meanwhile, the 1911219019Sgaborsurrounding text `flows' around the keep, thus leaving no blank areas. 1912219019Sgabor 1913219019Sgabor@c --------------------------------------------------------------------- 1914219019Sgabor 1915219019Sgabor@node Footnotes and Annotations, Table of Contents, Displays, Common Features 1916219019Sgabor@subsection Footnotes and Annotations 1917219019Sgabor@cindex footnotes 1918219019Sgabor@cindex annotations 1919219019Sgabor 1920219019SgaborThere are a number of requests to save text for later printing. 1921219019Sgabor 1922219019Sgabor@dfn{Footnotes} are printed at the bottom of the current page. 1923219019Sgabor 1924219019Sgabor@cindex delayed text 1925219019Sgabor@dfn{Delayed text} is very similar to a footnote except that it is 1926219019Sgaborprinted when called for explicitly. This allows a list of references to 1927219019Sgaborappear (for example) at the end of each chapter, as is the convention in 1928219019Sgaborsome disciplines. 1929219019Sgabor 1930219019SgaborMost macro packages which supply this functionality also supply a means 1931219019Sgaborof automatically numbering either type of annotation. 1932219019Sgabor 1933219019Sgabor@c --------------------------------------------------------------------- 1934219019Sgabor 1935219019Sgabor@node Table of Contents, Indices, Footnotes and Annotations, Common Features 1936219019Sgabor@subsection Table of Contents 1937219019Sgabor@cindex table of contents 1938219019Sgabor@cindex contents, table of 1939219019Sgabor 1940219019Sgabor@dfn{Tables of contents} are a type of delayed text having a tag 1941219019Sgabor(usually the page number) attached to each entry after a row of dots. 1942219019SgaborThe table accumulates throughout the paper until printed, usually after 1943219019Sgaborthe paper has ended. Many macro packages provide the ability to have 1944219019Sgaborseveral tables of contents (e.g.@: a standard table of contents, a list 1945219019Sgaborof tables, etc). 1946219019Sgabor 1947219019Sgabor@c --------------------------------------------------------------------- 1948219019Sgabor 1949219019Sgabor@node Indices, Paper Formats, Table of Contents, Common Features 1950219019Sgabor@subsection Indices 1951219019Sgabor@cindex index, in macro package 1952219019Sgabor 1953219019SgaborWhile some macro packages use the term @dfn{index}, none actually 1954219019Sgaborprovide that functionality. The facilities they call indices are 1955219019Sgaboractually more appropriate for tables of contents. 1956219019Sgabor 1957219019Sgabor@c --------------------------------------------------------------------- 1958219019Sgabor 1959219019Sgabor@node Paper Formats, Multiple Columns, Indices, Common Features 1960219019Sgabor@subsection Paper Formats 1961219019Sgabor@cindex paper formats 1962219019Sgabor 1963219019SgaborSome macro packages provide stock formats for various kinds of 1964219019Sgabordocuments. Many of them provide a common format for the title and 1965219019Sgaboropening pages of a technical paper. The @file{mm} macros in particular 1966219019Sgaborprovide formats for letters and memoranda. 1967219019Sgabor 1968219019Sgabor@c --------------------------------------------------------------------- 1969219019Sgabor 1970219019Sgabor@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 1971219019Sgabor@subsection Multiple Columns 1972219019Sgabor 1973219019SgaborSome macro packages (but not @file{man}) provide the ability to have two 1974219019Sgaboror more columns on a page. 1975219019Sgabor 1976219019Sgabor@c --------------------------------------------------------------------- 1977219019Sgabor 1978219019Sgabor@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 1979219019Sgabor@subsection Font and Size Changes 1980219019Sgabor 1981219019SgaborThe built-in font and size functions are not always intuitive, so all 1982219019Sgabormacro packages provide macros to make these operations simpler. 1983219019Sgabor 1984219019Sgabor@c --------------------------------------------------------------------- 1985219019Sgabor 1986219019Sgabor@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 1987219019Sgabor@subsection Predefined Strings 1988219019Sgabor 1989219019SgaborMost macro packages provide various predefined strings for a variety of 1990219019Sgaboruses; examples are sub- and superscripts, printable dates, quotes and 1991219019Sgaborvarious special characters. 1992219019Sgabor 1993219019Sgabor@c --------------------------------------------------------------------- 1994219019Sgabor 1995219019Sgabor@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 1996219019Sgabor@subsection Preprocessor Support 1997219019Sgabor 1998219019SgaborAll macro packages provide support for the various preprocessors and may 1999219019Sgaborextend their functionality. 2000219019Sgabor 2001219019SgaborFor example, all macro packages mark tables (which are processed with 2002219019Sgabor@code{gtbl}) by placing them between @code{.TS} and @code{.TE} macros. 2003219019SgaborThe @file{ms} macro package has an option, @code{.TS@w{}H}, that prints 2004219019Sgabora caption at the top of a new page (when the table is too long to fit on 2005219019Sgabora single page). 2006219019Sgabor 2007219019Sgabor@c --------------------------------------------------------------------- 2008219019Sgabor 2009219019Sgabor@node Configuration and Customization, , Preprocessor Support, Common Features 2010219019Sgabor@subsection Configuration and Customization 2011219019Sgabor 2012219019SgaborSome macro packages provide means of customizing many of the details of 2013219019Sgaborhow the package behaves. This ranges from setting the default type size 2014219019Sgaborto changing the appearance of section headers. 2015219019Sgabor 2016219019Sgabor 2017219019Sgabor 2018219019Sgabor@c ===================================================================== 2019219019Sgabor@c ===================================================================== 2020219019Sgabor 2021219019Sgabor@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 2022219019Sgabor@chapter Macro Packages 2023219019Sgabor@cindex macro packages 2024219019Sgabor@cindex packages, macros 2025219019Sgabor 2026219019SgaborThis chapter documents the main macro packages that come with 2027219019Sgabor@code{groff}. 2028219019Sgabor 2029219019Sgabor@menu 2030219019Sgabor* man:: 2031219019Sgabor* mdoc:: 2032219019Sgabor* ms:: 2033219019Sgabor* me:: 2034219019Sgabor* mm:: 2035219019Sgabor@end menu 2036219019Sgabor 2037219019Sgabor 2038219019Sgabor@c ===================================================================== 2039219019Sgabor 2040219019Sgabor@node man, mdoc, Macro Packages, Macro Packages 2041219019Sgabor@section @file{man} 2042219019Sgabor@cindex @file{man} 2043219019Sgabor@cindex manual pages 2044219019Sgabor@pindex an.tmac 2045219019Sgabor@pindex man.tmac 2046219019Sgabor@pindex man-old.tmac 2047219019Sgabor 2048219019SgaborThis is the most popular and probably the most important macro package 2049219019Sgaborof @code{groff}. It is easy to use, and a vast majority of manual pages 2050219019Sgaborare based on it. 2051219019Sgabor 2052219019Sgabor@menu 2053219019Sgabor* Man options:: 2054219019Sgabor* Man usage:: 2055219019Sgabor* Man font macros:: 2056219019Sgabor* Miscellaneous man macros:: 2057219019Sgabor* Predefined man strings:: 2058219019Sgabor* Preprocessors in man pages:: 2059219019Sgabor@end menu 2060219019Sgabor 2061219019Sgabor@c --------------------------------------------------------------------- 2062219019Sgabor 2063219019Sgabor@node Man options, Man usage, man, man 2064219019Sgabor@subsection Options 2065219019Sgabor 2066219019SgaborThe command line format for using the @file{man} macros with 2067219019Sgabor@code{groff} is: 2068219019Sgabor 2069219019Sgabor@Example 2070219019Sgaborgroff -m man [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ] 2071219019Sgabor [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ] 2072219019Sgabor@endExample 2073219019Sgabor 2074219019Sgabor@noindent 2075219019SgaborIt is possible to use @samp{-man} instead of @w{@samp{-m man}}. 2076219019Sgabor 2077219019Sgabor@table @code 2078219019Sgabor@item -rcR=1 2079219019SgaborThis option (the default if a tty output device is used) creates a 2080219019Sgaborsingle, very long page instead of multiple pages. Use @code{-rcR=0} 2081219019Sgaborto disable it. 2082219019Sgabor 2083219019Sgabor@item -rC1 2084219019SgaborIf more than one manual page is given on the command line, number the 2085219019Sgaborpages continuously, rather than starting each at@w{ }1. 2086219019Sgabor 2087219019Sgabor@item -rD1 2088219019SgaborDouble-sided printing. Footers for even and odd pages are formatted 2089219019Sgabordifferently. 2090219019Sgabor 2091219019Sgabor@item -rP@var{nnn} 2092219019SgaborPage numbering starts with @var{nnn} rather than with@w{ }1. 2093219019Sgabor 2094219019Sgabor@item -rS@var{xx} 2095219019SgaborUse @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base 2096219019Sgabordocument font size instead of the default value of@w{ }10@dmn{pt}. 2097219019Sgabor 2098219019Sgabor@item -rX@var{nnn} 2099219019SgaborAfter page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 2100219019Sgabor@var{nnn}c, etc. For example, the option @option{-rX2} produces the 2101219019Sgaborfollowing page numbers: 1, 2, 2a, 2b, 2c, etc. 2102219019Sgabor@end table 2103219019Sgabor 2104219019Sgabor@c --------------------------------------------------------------------- 2105219019Sgabor 2106219019Sgabor@node Man usage, Man font macros, Man options, man 2107219019Sgabor@subsection Usage 2108219019Sgabor@cindex @code{man} macros 2109219019Sgabor@cindex macros for manual pages 2110219019Sgabor 2111219019Sgabor@pindex man.local 2112219019SgaborThis section describes the available macros for manual pages. For 2113219019Sgaborfurther customization, put additional macros and requests into the file 2114219019Sgabor@file{man.local} which is loaded immediately after the @file{man} 2115219019Sgaborpackage. 2116219019Sgabor 2117219019Sgabor@Defmac {TH, title section [@Var{extra1}] [@Var{extra2}] [@Var{extra3}]} 2118219019SgaborSet the title of the man page to @var{title} and the section to 2119219019Sgabor@var{section}, which must have a value between 1 and@w{ }8. The value 2120219019Sgaborof @var{section} may also have a string appended, e.g.@: @samp{.pm}, 2121219019Sgaborto indicate a specific subsection of the man pages. 2122219019Sgabor 2123219019SgaborBoth @var{title} and @var{section} are positioned at the left and right 2124219019Sgaborin the header line (with @var{section} in parentheses immediately 2125219019Sgaborappended to @var{title}. @var{extra1} is positioned in the middle of 2126219019Sgaborthe footer line. @var{extra2} is positioned at the left in the footer 2127219019Sgaborline (or at the left on even pages and at the right on odd pages if 2128219019Sgabordouble-sided printing is active). @var{extra3} is centered in the 2129219019Sgaborheader line. 2130219019Sgabor 2131219019SgaborFor @acronym{HTML} output, headers and footers are completely suppressed. 2132219019Sgabor 2133219019SgaborAdditionally, this macro starts a new page; the new line number is@w{ }1 2134219019Sgaboragain (except if the @option{-rC1} option is given on the command line) 2135219019Sgabor-- this feature is intended only for formatting multiple man pages; a 2136219019Sgaborsingle man page should contain exactly one @code{TH} macro at the 2137219019Sgaborbeginning of the file. 2138219019Sgabor@endDefmac 2139219019Sgabor 2140219019Sgabor@Defmac {SH, [@Var{heading}]} 2141219019SgaborSet up an unnumbered section heading sticking out to the left. Prints 2142219019Sgaborout all the text following @code{SH} up to the end of the line (or the 2143219019Sgabortext in the next line if there is no argument to @code{SH}) in bold 2144219019Sgaborface, one size larger than the base document size. Additionally, the 2145219019Sgaborleft margin for the following text is reset to its default value. 2146219019Sgabor@endDefmac 2147219019Sgabor 2148219019Sgabor@Defmac {SS, [@Var{heading}]} 2149219019SgaborSet up an unnumbered (sub)section heading. Prints out all the text 2150219019Sgaborfollowing @code{SS} up to the end of the line (or the text in the next 2151219019Sgaborline if there is no argument to @code{SS}) in bold face, at the same 2152219019Sgaborsize as the base document size. Additionally, the left margin for the 2153219019Sgaborfollowing text is reset to its default value. 2154219019Sgabor@endDefmac 2155219019Sgabor 2156219019Sgabor@Defmac {TP, [@Var{nnn}]} 2157219019SgaborSet up an indented paragraph with label. The indentation is set to 2158219019Sgabor@var{nnn} if that argument is supplied (the default unit is @samp{n} 2159219019Sgaborif omitted), otherwise it is set to the default indentation value. 2160219019Sgabor 2161219019SgaborThe first line of text following this macro is interpreted as a string 2162219019Sgaborto be printed flush-left, as it is appropriate for a label. It is not 2163219019Sgaborinterpreted as part of a paragraph, so there is no attempt to fill the 2164219019Sgaborfirst line with text from the following input lines. Nevertheless, if 2165219019Sgaborthe label is not as wide as the indentation, then the paragraph starts 2166219019Sgaborat the same line (but indented), continuing on the following lines. 2167219019SgaborIf the label is wider than the indentation, then the descriptive part 2168219019Sgaborof the paragraph begins on the line following the label, entirely 2169219019Sgaborindented. Note that neither font shape nor font size of the label is 2170219019Sgaborset to a default value; on the other hand, the rest of the text has 2171219019Sgabordefault font settings. 2172219019Sgabor@endDefmac 2173219019Sgabor 2174219019Sgabor@Defmac {LP} 2175219019Sgabor@Defmacx {PP} 2176219019Sgabor@Defmacx {P} 2177219019SgaborThese macros are mutual aliases. Any of them causes a line break at 2178219019Sgaborthe current position, followed by a vertical space downwards by the 2179219019Sgaboramount specified by the @code{PD} macro. The font size and shape are 2180219019Sgaborreset to the default value (10@dmn{pt} roman). Finally, the current 2181219019Sgaborleft margin is restored. 2182219019Sgabor@endDefmac 2183219019Sgabor 2184219019Sgabor@Defmac {IP, [@Var{designator}] [@Var{nnn}]} 2185219019SgaborSet up an indented paragraph, using @var{designator} as a tag to mark 2186219019Sgaborits beginning. The indentation is set to @var{nnn} if that argument 2187219019Sgaboris supplied (default unit is @samp{n}), otherwise the default 2188219019Sgaborindentation value is used. Font size and face of the paragraph (but 2189219019Sgabornot the designator) are reset to their default values. To start an 2190219019Sgaborindented paragraph with a particular indentation but without a 2191219019Sgabordesignator, use @samp{""} (two double quotes) as the first argument of 2192219019Sgabor@code{IP}. 2193219019Sgabor 2194219019SgaborFor example, to start a paragraph with bullets as the designator and 2195219019Sgabor4@dmn{en} indentation, write 2196219019Sgabor 2197219019Sgabor@Example 2198219019Sgabor.IP \(bu 4 2199219019Sgabor@endExample 2200219019Sgabor@endDefmac 2201219019Sgabor 2202219019Sgabor@cindex hanging indentation, in manual pages 2203219019Sgabor@Defmac {HP, [@Var{nnn}]} 2204219019SgaborSet up a paragraph with hanging left indentation. The indentation is 2205219019Sgaborset to @var{nnn} if that argument is supplied (default unit is 2206219019Sgabor@samp{n}), otherwise the default indentation value is used. Font size 2207219019Sgaborand face are reset to their default values. 2208219019Sgabor@endDefmac 2209219019Sgabor 2210219019Sgabor@cindex left margin, how to move, in manual pages 2211219019Sgabor@Defmac {RS, [@Var{nnn}]} 2212219019SgaborMove the left margin to the right by the value @var{nnn} if specified 2213219019Sgabor(default unit is @samp{n}); otherwise the default indentation value is 2214219019Sgaborused. Calls to the @code{RS} macro can be nested. 2215219019Sgabor@endDefmac 2216219019Sgabor 2217219019Sgabor@Defmac {RE, [@Var{nnn}]} 2218219019SgaborMove the left margin back to level @var{nnn}; if no argument is given, 2219219019Sgaborit moves one level back. The first level (i.e., no call to @code{RS} 2220219019Sgaboryet) has number@w{ }1, and each call to @code{RS} increases the level 2221219019Sgaborby@w{ }1. 2222219019Sgabor@endDefmac 2223219019Sgabor 2224219019Sgabor@maindex SH 2225219019Sgabor@maindex SS 2226219019Sgabor@maindex TP 2227219019Sgabor@maindex LP 2228219019Sgabor@maindex PP 2229219019Sgabor@maindex P 2230219019Sgabor@maindex IP 2231219019Sgabor@maindex HP 2232219019SgaborTo summarize, the following macros cause a line break with the insertion 2233219019Sgaborof vertical space (which amount can be changed with the @code{PD} 2234219019Sgabormacro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 2235219019Sgabor@code{P}), @code{IP}, and @code{HP}. 2236219019Sgabor 2237219019Sgabor@maindex RS 2238219019Sgabor@maindex RE 2239219019SgaborThe macros @code{RS} and @code{RE} also cause a break but do not insert 2240219019Sgaborvertical space. 2241219019Sgabor 2242219019Sgabor@c --------------------------------------------------------------------- 2243219019Sgabor 2244219019Sgabor@node Man font macros, Miscellaneous man macros, Man usage, man 2245219019Sgabor@subsection Macros to set fonts 2246219019Sgabor@cindex fonts in manual pages 2247219019Sgabor@cindex @code{man}, how to set fonts 2248219019Sgabor 2249219019SgaborThe standard font is roman; the default text size is 10@w{ }point. 2250219019Sgabor 2251219019Sgabor@Defmac {SM, [@Var{text}]} 2252219019SgaborSet the text on the same line or the text on the next line in a font 2253219019Sgaborthat is one point size smaller than the default font. 2254219019Sgabor@endDefmac 2255219019Sgabor 2256219019Sgabor@cindex boldface, in manual pages 2257219019Sgabor@Defmac {SB, [@Var{text}]} 2258219019SgaborSet the text on the same line or the text on the next line in boldface 2259219019Sgaborfont, one point size smaller than the default font. 2260219019Sgabor@endDefmac 2261219019Sgabor 2262219019Sgabor@Defmac {BI, text} 2263219019SgaborSet its arguments alternately in bold face and italic. Thus, 2264219019Sgabor 2265219019Sgabor@Example 2266219019Sgabor.BI this "word and" that 2267219019Sgabor@endExample 2268219019Sgabor 2269219019Sgabor@noindent 2270219019Sgaborwould set ``this'' and ``that'' in bold face, and ``word and'' in 2271219019Sgaboritalics. 2272219019Sgabor@endDefmac 2273219019Sgabor 2274219019Sgabor@Defmac {IB, text} 2275219019SgaborSet its arguments alternately in italic and bold face. 2276219019Sgabor@endDefmac 2277219019Sgabor 2278219019Sgabor@Defmac {RI, text} 2279219019SgaborSet its arguments alternately in roman and italic. 2280219019Sgabor@endDefmac 2281219019Sgabor 2282219019Sgabor@Defmac {IR, text} 2283219019SgaborSet its arguments alternately in italic and roman. 2284219019Sgabor@endDefmac 2285219019Sgabor 2286219019Sgabor@Defmac {BR, text} 2287219019SgaborSet its arguments alternately in bold face and roman. 2288219019Sgabor@endDefmac 2289219019Sgabor 2290219019Sgabor@Defmac {RB, text} 2291219019SgaborSet its arguments alternately in roman and bold face. 2292219019Sgabor@endDefmac 2293219019Sgabor 2294219019Sgabor@Defmac {R, [@Var{text}]} 2295219019SgaborSet @var{text} in roman font. If no text is present on the line where 2296219019Sgaborthe macro is called, then the text of the next line appears in roman. 2297219019SgaborThis is the default font to which text is returned at the end of 2298219019Sgaborprocessing of the other macros. 2299219019Sgabor@endDefmac 2300219019Sgabor 2301219019Sgabor@Defmac {B, [@Var{text}]} 2302219019SgaborSet @var{text} in bold face. If no text is present on the line where 2303219019Sgaborthe macro is called, then the text of the next line appears in bold 2304219019Sgaborface. 2305219019Sgabor@endDefmac 2306219019Sgabor 2307219019Sgabor@cindex italic, in manual pages 2308219019Sgabor@Defmac {I, [@Var{text}]} 2309219019SgaborSet @var{text} in italic. If no text is present on the line where the 2310219019Sgabormacro is called, then the text of the next line appears in italic. 2311219019Sgabor@endDefmac 2312219019Sgabor 2313219019Sgabor@c --------------------------------------------------------------------- 2314219019Sgabor 2315219019Sgabor@node Miscellaneous man macros, Predefined man strings, Man font macros, man 2316219019Sgabor@subsection Miscellaneous macros 2317219019Sgabor 2318219019Sgabor@pindex grohtml 2319219019Sgabor@cindex @file{man}, default indentation 2320219019Sgabor@cindex default indentation, @file{man} 2321219019SgaborThe default indentation is 7.2@dmn{n} for all output devices except for 2322219019Sgabor@code{grohtml} which ignores indentation. 2323219019Sgabor 2324219019Sgabor@maindex TH 2325219019Sgabor@cindex tab stops, in manual pages 2326219019Sgabor@Defmac {DT} 2327219019SgaborSet tabs every 0.5@w{ }inches. Since this macro is always called 2328219019Sgaborduring a @code{TH} request, it makes sense to call it only if the tab 2329219019Sgaborpositions have been changed. 2330219019Sgabor@endDefmac 2331219019Sgabor 2332219019Sgabor@cindex empty space before a paragraph, in manual pages 2333219019Sgabor@Defmac {PD, [@Var{nnn}]} 2334219019SgaborAdjust the empty space before a new paragraph (or section). The 2335219019Sgaboroptional argument gives the amount of space (default unit is 2336219019Sgabor@samp{v}); without parameter, the value is reset to its default value 2337219019Sgabor(1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise). 2338219019Sgabor@endDefmac 2339219019Sgabor 2340219019Sgabor@maindex SH 2341219019Sgabor@maindex SS 2342219019Sgabor@maindex TP 2343219019Sgabor@maindex LP 2344219019Sgabor@maindex PP 2345219019Sgabor@maindex P 2346219019Sgabor@maindex IP 2347219019Sgabor@maindex HP 2348219019SgaborThis affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 2349219019Sgaborwell as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2350219019Sgabor 2351219019Sgabor@c --------------------------------------------------------------------- 2352219019Sgabor 2353219019Sgabor@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 2354219019Sgabor@subsection Predefined strings 2355219019Sgabor 2356219019SgaborThe following strings are defined: 2357219019Sgabor 2358219019Sgabor@Defstr {*S} 2359219019SgaborSwitch back to the default font size. 2360219019Sgabor@endDefstr 2361219019Sgabor 2362219019Sgabor@Defstr {*R} 2363219019SgaborThe `registered' sign. 2364219019Sgabor@endDefstr 2365219019Sgabor 2366219019Sgabor@Defstr {Tm} 2367219019SgaborThe `trademark' sign. 2368219019Sgabor@endDefstr 2369219019Sgabor 2370219019Sgabor@glindex lq 2371219019Sgabor@glindex rq 2372219019Sgabor@Defstr {lq} 2373219019Sgabor@Defstrx {rq} 2374219019SgaborLeft and right quote. This is equal to @code{\(lq} and @code{\(rq}, 2375219019Sgaborrespectively. 2376219019Sgabor@endDefstr 2377219019Sgabor 2378219019Sgabor@c --------------------------------------------------------------------- 2379219019Sgabor 2380219019Sgabor@node Preprocessors in man pages, , Predefined man strings, man 2381219019Sgabor@subsection Preprocessors in @file{man} pages 2382219019Sgabor 2383219019Sgabor@cindex preprocessor, calling convention 2384219019Sgabor@cindex calling convention of preprocessors 2385219019SgaborIf a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 2386219019Sgaborbecome common usage to make the first line of the man page look like 2387219019Sgaborthis: 2388219019Sgabor 2389219019Sgabor@Example 2390219019Sgabor.\" @var{word} 2391219019Sgabor@endExample 2392219019Sgabor 2393219019Sgabor@pindex geqn@r{, invocation in manual pages} 2394219019Sgabor@pindex grefer@r{, invocation in manual pages} 2395219019Sgabor@pindex gtbl@r{, invocation in manual pages} 2396219019Sgabor@pindex man@r{, invocation of preprocessors} 2397219019Sgabor@noindent 2398219019SgaborNote the single space character after the double quote. @var{word} 2399219019Sgaborconsists of letters for the needed preprocessors: @samp{e} for 2400219019Sgabor@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 2401219019SgaborModern implementations of the @code{man} program read this first line 2402219019Sgaborand automatically call the right preprocessor(s). 2403219019Sgabor 2404219019Sgabor 2405219019Sgabor@c ===================================================================== 2406219019Sgabor 2407219019Sgabor@node mdoc, ms, man, Macro Packages 2408219019Sgabor@section @file{mdoc} 2409219019Sgabor@cindex @file{mdoc} 2410219019Sgabor 2411219019Sgabor@c XXX documentation 2412219019Sgabor 2413219019Sgabor 2414219019Sgabor@c ===================================================================== 2415219019Sgabor 2416219019Sgabor@node ms, me, mdoc, Macro Packages 2417219019Sgabor@section @file{ms} 2418219019Sgabor@cindex @file{ms} 2419219019Sgabor 2420219019Sgabor@c XXX documentation 2421219019Sgabor 2422219019Sgabor 2423219019Sgabor@c ===================================================================== 2424219019Sgabor 2425219019Sgabor@node me, mm, ms, Macro Packages 2426219019Sgabor@section @file{me} 2427219019Sgabor@cindex @file{me} 2428219019Sgabor 2429219019Sgabor@c XXX documentation 2430219019Sgabor 2431219019Sgabor 2432219019Sgabor@c ===================================================================== 2433219019Sgabor 2434219019Sgabor@node mm, , me, Macro Packages 2435219019Sgabor@section @file{mm} 2436219019Sgabor@cindex @file{mm} 2437219019Sgabor 2438219019Sgabor@c XXX documentation 2439219019Sgabor 2440219019Sgabor 2441219019Sgabor 2442219019Sgabor@c ===================================================================== 2443219019Sgabor@c ===================================================================== 2444219019Sgabor 2445219019Sgabor@node gtroff Reference, Preprocessors, Macro Packages, Top 2446219019Sgabor@chapter @code{gtroff} Reference 2447219019Sgabor@cindex reference, @code{gtroff} 2448219019Sgabor@cindex @code{gtroff} reference 2449219019Sgabor 2450219019SgaborThis chapter covers @strong{all} of the facilities of @code{gtroff}. 2451219019SgaborUsers of macro packages may skip it if not interested in details. 2452219019Sgabor 2453219019Sgabor 2454219019Sgabor@menu 2455219019Sgabor* Text:: 2456219019Sgabor* Input Conventions:: 2457219019Sgabor* Measurements:: 2458219019Sgabor* Expressions:: 2459219019Sgabor* Identifiers:: 2460219019Sgabor* Embedded Commands:: 2461219019Sgabor* Registers:: 2462219019Sgabor* Manipulating Filling and Adjusting:: 2463219019Sgabor* Manipulating Hyphenation:: 2464219019Sgabor* Manipulating Spacing:: 2465219019Sgabor* Tabs and Fields:: 2466219019Sgabor* Character Translations:: 2467219019Sgabor* Troff and Nroff Mode:: 2468219019Sgabor* Line Layout:: 2469219019Sgabor* Page Layout:: 2470219019Sgabor* Page Control:: 2471219019Sgabor* Fonts:: 2472219019Sgabor* Sizes:: 2473219019Sgabor* Strings:: 2474219019Sgabor* Conditionals and Loops:: 2475219019Sgabor* Writing Macros:: 2476219019Sgabor* Page Motions:: 2477219019Sgabor* Drawing Requests:: 2478219019Sgabor* Traps:: 2479219019Sgabor* Diversions:: 2480219019Sgabor* Environments:: 2481219019Sgabor* Suppressing output:: 2482219019Sgabor* I/O:: 2483219019Sgabor* Postprocessor Access:: 2484219019Sgabor* Miscellaneous:: 2485219019Sgabor* Gtroff Internals:: 2486219019Sgabor* Debugging:: 2487219019Sgabor* Implementation Differences:: 2488219019Sgabor* Summary:: 2489219019Sgabor@end menu 2490219019Sgabor 2491219019Sgabor 2492219019Sgabor@c ===================================================================== 2493219019Sgabor 2494219019Sgabor@node Text, Input Conventions, gtroff Reference, gtroff Reference 2495219019Sgabor@section Text 2496219019Sgabor@cindex text, @code{gtroff} processing 2497219019Sgabor 2498219019Sgabor@code{gtroff} input files contain text with control commands 2499219019Sgaborinterspersed throughout. But, even without control codes, @code{gtroff} 2500219019Sgaborstill does several things with the input text: 2501219019Sgabor 2502219019Sgabor@itemize @bullet 2503219019Sgabor@item 2504219019Sgaborfilling and adjusting 2505219019Sgabor 2506219019Sgabor@item 2507219019Sgaboradding additional space after sentences 2508219019Sgabor 2509219019Sgabor@item 2510219019Sgaborhyphenating 2511219019Sgabor 2512219019Sgabor@item 2513219019Sgaborinserting implicit line breaks 2514219019Sgabor@end itemize 2515219019Sgabor 2516219019Sgabor@menu 2517219019Sgabor* Filling and Adjusting:: 2518219019Sgabor* Hyphenation:: 2519219019Sgabor* Sentences:: 2520219019Sgabor* Tab Stops:: 2521219019Sgabor* Implicit Line Breaks:: 2522219019Sgabor@end menu 2523219019Sgabor 2524219019Sgabor@c --------------------------------------------------------------------- 2525219019Sgabor 2526219019Sgabor@node Filling and Adjusting, Hyphenation, Text, Text 2527219019Sgabor@subsection Filling and Adjusting 2528219019Sgabor@cindex filling 2529219019Sgabor@cindex adjusting 2530219019Sgabor 2531219019SgaborWhen @code{gtroff} reads text, it collects words from the input and fits 2532219019Sgaboras many of them together on one output line as it can. This is known as 2533219019Sgabor@dfn{filling}. 2534219019Sgabor 2535219019Sgabor@cindex leading spaces 2536219019Sgabor@cindex spaces, leading and trailing 2537219019Sgabor@cindex extra spaces 2538219019Sgabor@cindex trailing spaces 2539219019SgaborOnce @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 2540219019Sgaborit. This means it widens the spacing between words until the text 2541219019Sgaborreaches the right margin (in the default adjustment mode). Extra spaces 2542219019Sgaborbetween words are preserved, but spaces at the end of lines are ignored. 2543219019SgaborSpaces at the front of a line cause a @dfn{break} (breaks are 2544219019Sgaborexplained in @ref{Implicit Line Breaks}) 2545219019Sgabor 2546219019Sgabor@xref{Manipulating Filling and Adjusting}. 2547219019Sgabor 2548219019Sgabor@c --------------------------------------------------------------------- 2549219019Sgabor 2550219019Sgabor@node Hyphenation, Sentences, Filling and Adjusting, Text 2551219019Sgabor@subsection Hyphenation 2552219019Sgabor@cindex hyphenation 2553219019Sgabor 2554219019SgaborSince the odds are not great for finding a set of words, for every 2555219019Sgaboroutput line, which fit nicely on a line without inserting excessive 2556219019Sgaboramounts of space between words, @code{gtroff} hyphenates words so 2557219019Sgaborthat it can justify lines without inserting too much space between 2558219019Sgaborwords. It uses an internal hyphenation algorithm (a simplified version 2559219019Sgaborof the algorithm used within @TeX{}) to indicate which words can be 2560219019Sgaborhyphenated and how to do so. When a word is hyphenated, the first part 2561219019Sgaborof the word is added to the current filled line being output (with 2562219019Sgaboran attached hyphen), and the other portion is added to the next 2563219019Sgaborline to be filled. 2564219019Sgabor 2565219019Sgabor@xref{Manipulating Hyphenation}. 2566219019Sgabor 2567219019Sgabor@c --------------------------------------------------------------------- 2568219019Sgabor 2569219019Sgabor@node Sentences, Tab Stops, Hyphenation, Text 2570219019Sgabor@subsection Sentences 2571219019Sgabor@cindex sentences 2572219019Sgabor 2573219019SgaborAlthough it is often debated, some typesetting rules say there should be 2574219019Sgabordifferent amounts of space after various punctuation marks. For 2575219019Sgaborexample, the @cite{Chicago typsetting manual} says that a period at the 2576219019Sgaborend of a sentence should have twice as much space following it as would 2577219019Sgabora comma or a period as part of an abbreviation. 2578219019Sgabor 2579219019Sgabor@c XXX exact citation of Chicago manual 2580219019Sgabor 2581219019Sgabor@cindex sentence space 2582219019Sgabor@cindex space between sentences 2583219019Sgabor@cindex french-spacing 2584219019Sgabor@code{gtroff} does this by flagging certain characters (normally 2585219019Sgabor@samp{!}, @samp{?}, and @samp{.}) as @dfn{end of sentence} characters. 2586219019SgaborWhen @code{gtroff} encounters one of these characters at the end of a 2587219019Sgaborline, it appends a normal space followed by a @dfn{sentence space} in 2588219019Sgaborthe formatted output. (This justifies one of the conventions mentioned 2589219019Sgaborin @ref{Input Conventions}.) 2590219019Sgabor 2591219019Sgabor@cindex transparent characters 2592219019Sgabor@cindex character, transparent 2593219019Sgabor@glindex dg 2594219019Sgabor@glindex rq 2595219019Sgabor@cindex " 2596219019Sgabor@cindex ' 2597219019Sgabor@cindex ) 2598219019Sgabor@cindex ] 2599219019Sgabor@cindex * 2600219019SgaborIn addition, the following characters or glyphs are treated 2601219019Sgabortransparently while handling end of sentence characters: @samp{"}, 2602219019Sgabor@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}. 2603219019Sgabor 2604219019SgaborSee the @code{cflags} request in @ref{Using Symbols}, for more details. 2605219019Sgabor 2606219019Sgabor@esindex \& 2607219019SgaborTo prevent the insertion of extra space after an end of sentence 2608219019Sgaborcharacter (at the end of a line), append @code{\&}. 2609219019Sgabor 2610219019Sgabor@c --------------------------------------------------------------------- 2611219019Sgabor 2612219019Sgabor@node Tab Stops, Implicit Line Breaks, Sentences, Text 2613219019Sgabor@subsection Tab Stops 2614219019Sgabor@cindex tab stops 2615219019Sgabor@cindex stops, tabulator 2616219019Sgabor@cindex tab character 2617219019Sgabor@cindex character, tabulator 2618219019Sgabor 2619219019Sgabor@cindex @acronym{EBCDIC} encoding 2620219019Sgabor@code{gtroff} translates @dfn{tabulator characters}, also called 2621219019Sgabor@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 2622219019Sgabor@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 2623219019Sgabortabulator stop. These tab stops are initially located every half inch 2624219019Sgaboracross the page. Using this, simple tables can be made easily. 2625219019SgaborHowever, it can often be deceptive as the appearance (and width) of the 2626219019Sgabortext on a terminal and the results from @code{gtroff} can vary greatly. 2627219019Sgabor 2628219019SgaborAlso, a possible sticking point is that lines beginning with tab 2629219019Sgaborcharacters are still filled, again producing unexpected results. 2630219019SgaborFor example, the following input 2631219019Sgabor 2632219019Sgabor@multitable {12345678} {12345678} {12345678} {12345678} 2633219019Sgabor@item 2634219019Sgabor@tab 1 @tab 2 @tab 3 2635219019Sgabor@item 2636219019Sgabor@tab @tab 4 @tab 5 2637219019Sgabor@end multitable 2638219019Sgabor 2639219019Sgabor@noindent 2640219019Sgaborproduces 2641219019Sgabor 2642219019Sgabor@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 2643219019Sgabor@item 2644219019Sgabor@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 2645219019Sgabor@end multitable 2646219019Sgabor 2647219019Sgabor@xref{Tabs and Fields}. 2648219019Sgabor 2649219019Sgabor@c --------------------------------------------------------------------- 2650219019Sgabor 2651219019Sgabor@node Implicit Line Breaks, , Tab Stops, Text 2652219019Sgabor@subsection Implicit Line Breaks 2653219019Sgabor@cindex implicit line breaks 2654219019Sgabor@cindex implicit breaks of lines 2655219019Sgabor@cindex line, implicit breaks 2656219019Sgabor@cindex break, implicit 2657219019Sgabor@cindex line break 2658219019Sgabor 2659219019SgaborAn important concept in @code{gtroff} is the @dfn{break}. When a break 2660219019Sgaboroccurs, @code{gtroff} outputs the partially filled line 2661219019Sgabor(unjustified), and resumes collecting and filling text on the next output 2662219019Sgaborline. 2663219019Sgabor 2664219019Sgabor@cindex blank line 2665219019Sgabor@cindex empty line 2666219019Sgabor@cindex line, blank 2667219019Sgabor@cindex blank line macro 2668219019Sgabor@rqindex blm 2669219019SgaborThere are several ways to cause a break in @code{gtroff}. A blank 2670219019Sgaborline not only causes a break, but it also outputs a one line vertical 2671219019Sgaborspace (effectively a blank line). Note that this behaviour can be 2672219019Sgabormodified with the blank line macro request @code{blm}. 2673219019Sgabor 2674219019Sgabor@c XXX xref for blm 2675219019Sgabor 2676219019Sgabor@cindex fill mode 2677219019Sgabor@cindex mode, fill 2678219019SgaborA line that begins with a space causes a break and the space is 2679219019Sgaboroutput at the beginning of the next line. Note that this space isn't 2680219019Sgaboradjusted, even in fill mode. 2681219019Sgabor 2682219019SgaborThe end of file also causes a break -- otherwise the last line of 2683219019Sgaborthe document may vanish! 2684219019Sgabor 2685219019SgaborCertain requests also cause breaks, implicitly or explicitly. This is 2686219019Sgabordiscussed in @ref{Manipulating Filling and Adjusting}. 2687219019Sgabor 2688219019Sgabor 2689219019Sgabor@c ===================================================================== 2690219019Sgabor 2691219019Sgabor@node Input Conventions, Measurements, Text, gtroff Reference 2692219019Sgabor@section Input Conventions 2693219019Sgabor@cindex input conventions 2694219019Sgabor@cindex conventions for input 2695219019Sgabor 2696219019SgaborSince @code{gtroff} does filling automatically, it is traditional in 2697219019Sgabor@code{groff} not to try and type things in as nicely formatted 2698219019Sgaborparagraphs. These are some conventions commonly used when typing 2699219019Sgabor@code{gtroff} text: 2700219019Sgabor 2701219019Sgabor@itemize @bullet 2702219019Sgabor@item 2703219019SgaborBreak lines after punctuation, particularly at the end of a sentence 2704219019Sgaborand in other logical places. Keep separate phrases on lines by 2705219019Sgaborthemselves, as entire phrases are often added or deleted when editing. 2706219019Sgabor 2707219019Sgabor@item 2708219019SgaborTry to keep lines less than 40-60@w{ }characters, to allow space for 2709219019Sgaborinserting more text. 2710219019Sgabor 2711219019Sgabor@item 2712219019SgaborDo not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 2713219019Sgabordon't try using spaces to get proper indentation). 2714219019Sgabor@end itemize 2715219019Sgabor 2716219019Sgabor 2717219019Sgabor@c ===================================================================== 2718219019Sgabor 2719219019Sgabor@node Measurements, Expressions, Input Conventions, gtroff Reference 2720219019Sgabor@section Measurements 2721219019Sgabor@cindex measurements 2722219019Sgabor 2723219019Sgabor@cindex units of measurement 2724219019Sgabor@cindex basic units 2725219019Sgabor@cindex machine units 2726219019Sgabor@cindex measurement units 2727219019Sgabor@cindex @code{u} unit 2728219019Sgabor@cindex unit, @code{u} 2729219019Sgabor@code{gtroff} (like many other programs) requires numeric parameters to 2730219019Sgaborspecify various measurements. Most numeric parameters@footnote{those 2731219019Sgaborthat specify vertical or horizontal motion or a type size} may have a 2732219019Sgabor@dfn{measurement unit} attached. These units are specified as a single 2733219019Sgaborcharacter which immediately follows the number or expression. Each of 2734219019Sgaborthese units are understood, by @code{gtroff}, to be a multiple of its 2735219019Sgabor@dfn{basic unit}. So, whenever a different measurement unit is 2736219019Sgaborspecified @code{gtroff} converts this into its @dfn{basic units}. This 2737219019Sgaborbasic unit, represented by a @samp{u}, is a device dependent measurement 2738219019Sgaborwhich is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 2739219019Sgaborinch. The values may be given as fractional numbers; however, 2740219019Sgaborfractional basic units are always rounded to integers. 2741219019Sgabor 2742219019SgaborSome of the measurement units are completely independent of any of the 2743219019Sgaborcurrent settings (e.g.@: type size) of @code{gtroff}. 2744219019Sgabor 2745219019Sgabor@table @code 2746219019Sgabor@item i 2747219019Sgabor@cindex inch 2748219019Sgabor@cindex @code{i} unit 2749219019Sgabor@cindex unit, @code{i} 2750219019SgaborInches. An antiquated measurement unit still in use in certain 2751219019Sgaborbackwards countries with incredibly low-cost computer equipment. One 2752219019Sgaborinch is equal to@w{ }2.54@dmn{cm}. 2753219019Sgabor 2754219019Sgabor@item c 2755219019Sgabor@cindex centimeter 2756219019Sgabor@cindex @code{c} unit 2757219019Sgabor@cindex unit, @code{c} 2758219019SgaborCentimeters. One centimeter is equal to@w{ }0.3937@dmn{in}. 2759219019Sgabor 2760219019Sgabor@item p 2761219019Sgabor@cindex points 2762219019Sgabor@cindex @code{p} unit 2763219019Sgabor@cindex unit, @code{p} 2764219019SgaborPoints. This is a typesetter's measurement used for measure type size. 2765219019SgaborIt is 72@w{ }points to an inch. 2766219019Sgabor 2767219019Sgabor@item P 2768219019Sgabor@cindex pica 2769219019Sgabor@cindex @code{P} unit 2770219019Sgabor@cindex unit, @code{P} 2771219019SgaborPica. Another typesetting measurement. 6@w{ }Picas to an inch (and 2772219019Sgabor12@w{ }points to a pica). 2773219019Sgabor 2774219019Sgabor@item s 2775219019Sgabor@itemx z 2776219019Sgabor@cindex @code{s} unit 2777219019Sgabor@cindex unit, @code{s} 2778219019Sgabor@cindex @code{z} unit 2779219019Sgabor@cindex unit, @code{z} 2780219019Sgabor@xref{Fractional Type Sizes}, for a discussion of these units. 2781219019Sgabor@end table 2782219019Sgabor 2783219019SgaborThe other measurements understood by @code{gtroff} depend on 2784219019Sgaborsettings currently in effect in @code{gtroff}. These are very useful 2785219019Sgaborfor specifying measurements which should look proper with any size of 2786219019Sgabortext. 2787219019Sgabor 2788219019Sgabor@table @code 2789219019Sgabor@item m 2790219019Sgabor@cindex em unit 2791219019Sgabor@cindex @code{m} unit 2792219019Sgabor@cindex unit, @code{m} 2793219019SgaborEms. This unit is equal to the current font size in points. So called 2794219019Sgaborbecause it is @emph{approximately} the width of the letter@w{ }@samp{m} 2795219019Sgaborin the current font. 2796219019Sgabor 2797219019Sgabor@item n 2798219019Sgabor@cindex en unit 2799219019Sgabor@cindex @code{n} unit 2800219019Sgabor@cindex unit, @code{n} 2801219019SgaborEns. This is half of an em. 2802219019Sgabor 2803219019Sgabor@item v 2804219019Sgabor@cindex vertical space 2805219019Sgabor@cindex space, vertical 2806219019Sgabor@cindex @code{v} unit 2807219019Sgabor@cindex unit, @code{v} 2808219019SgaborVertical space. This is equivalent to the current line spacing. 2809219019Sgabor@xref{Sizes}, for more information about this. 2810219019Sgabor 2811219019Sgabor@item M 2812219019Sgabor@cindex @code{M} unit 2813219019Sgabor@cindex unit, @code{M} 2814219019Sgabor100ths of an em. 2815219019Sgabor@end table 2816219019Sgabor 2817219019Sgabor@menu 2818219019Sgabor* Default Units:: 2819219019Sgabor@end menu 2820219019Sgabor 2821219019Sgabor@c --------------------------------------------------------------------- 2822219019Sgabor 2823219019Sgabor@node Default Units, , Measurements, Measurements 2824219019Sgabor@subsection Default Units 2825219019Sgabor@cindex default units 2826219019Sgabor@cindex units, default 2827219019Sgabor 2828219019SgaborMany requests take a default unit. While this can be helpful at times, 2829219019Sgaborit can cause strange errors in some expressions. For example, the line 2830219019Sgaborlength request expects em units. Here are several attempts to get a 2831219019Sgaborline length of 3.5@w{ }inches and their results: 2832219019Sgabor 2833219019Sgabor@Example 2834219019Sgabor3.5i @result{} 3.5i 2835219019Sgabor7/2 @result{} 0i 2836219019Sgabor7/2i @result{} 0i 2837219019Sgabor7i/2 @result{} 0.1i 2838219019Sgabor7i/2u @result{} 3.5i 2839219019Sgabor@endExample 2840219019Sgabor 2841219019Sgabor@noindent 2842219019SgaborEverything is converted to basic units first. In the above example it 2843219019Sgaboris assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{ 2844219019Sgabor}10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2 2845219019Sgaboris first handled as 7@dmn{i}/2@dmn{m}, then converted to 2846219019Sgabor1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 2847219019Sgabor0.1@dmn{i}. 2848219019Sgabor 2849219019Sgabor@cindex measurements, specifying safely 2850219019SgaborThus, the safest way to specify measurements is to always 2851219019Sgaborattach a scaling indicator. If you want to multiply or divide by a 2852219019Sgaborcertain scalar value, use @samp{u} as the unit for that value. 2853219019Sgabor 2854219019Sgabor 2855219019Sgabor@c ===================================================================== 2856219019Sgabor 2857219019Sgabor@node Expressions, Identifiers, Measurements, gtroff Reference 2858219019Sgabor@section Expressions 2859219019Sgabor@cindex expressions 2860219019Sgabor 2861219019Sgabor@code{gtroff} has most arithmetic operators common to other languages: 2862219019Sgabor 2863219019Sgabor@c XXX more details; examples 2864219019Sgabor 2865219019Sgabor@itemize @bullet 2866219019Sgabor@item 2867219019Sgabor@cindex arithmetic operators 2868219019Sgabor@cindex operators, arithmetic 2869219019Sgabor@opindex + 2870219019Sgabor@opindex - 2871219019Sgabor@opindex / 2872219019Sgabor@opindex * 2873219019Sgabor@opindex % 2874219019SgaborArithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 2875219019Sgabor(division), @samp{*} (multiplication), @samp{%} (modulo). 2876219019Sgabor 2877219019Sgabor@code{gtroff} only provides integer arithmetic. The internal type used 2878219019Sgaborfor computing results is @samp{int}, which is usually a 32@dmn{bit} 2879219019Sgaborsigned integer. 2880219019Sgabor 2881219019Sgabor@item 2882219019Sgabor@cindex comparison operators 2883219019Sgabor@cindex operators, comparison 2884219019Sgabor@opindex < 2885219019Sgabor@opindex > 2886219019Sgabor@opindex >= 2887219019Sgabor@opindex <= 2888219019Sgabor@opindex = 2889219019Sgabor@opindex == 2890219019SgaborComparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 2891219019Sgabor(less than or equal), @samp{>=} (greater than or equal), @samp{=} 2892219019Sgabor(equal), @samp{==} (the same as @samp{=}). 2893219019Sgabor 2894219019Sgabor@item 2895219019Sgabor@cindex logical operators 2896219019Sgabor@cindex operators, logical 2897219019Sgabor@opindex & 2898219019Sgabor@opindex : 2899219019SgaborLogical: @samp{&} (logical and), @samp{:} (logical or). 2900219019Sgabor 2901219019Sgabor@item 2902219019Sgabor@cindex unary operators 2903219019Sgabor@cindex operators, unary 2904219019Sgabor@opindex - 2905219019Sgabor@opindex + 2906219019Sgabor@opindex ! 2907219019Sgabor@rqindex if 2908219019Sgabor@rqindex while 2909219019Sgabor@cindex @code{if}, and the @samp{!} operator 2910219019Sgabor@cindex @code{while}, and the @samp{!} operator 2911219019SgaborUnary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 2912219019Sgabor(just for completeness; does nothing in expressions), @samp{!} (logical 2913219019Sgabornot; this works only within @code{if} and @code{while} requests). See 2914219019Sgaborbelow for the use of unary operators in motion requests. 2915219019Sgabor 2916219019Sgabor@item 2917219019Sgabor@cindex extremum operators 2918219019Sgabor@cindex operators, extremum 2919219019Sgabor@opindex >? 2920219019Sgabor@opindex <? 2921219019SgaborExtrema: @samp{>?} (maximum), @samp{<?} (minimum). For example, 2922219019Sgabor@samp{5>?3} yields@w{ }@samp{5}. 2923219019Sgabor 2924219019Sgabor@c XXX add examples 2925219019Sgabor 2926219019Sgabor@item 2927219019Sgabor@cindex scaling operator 2928219019Sgabor@cindex operator, scaling 2929219019SgaborScaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as 2930219019Sgaborthe default scaling indicator. If @var{c} is missing, ignore scaling 2931219019Sgaborindicators in the evaluation of @var{e}. 2932219019Sgabor@end itemize 2933219019Sgabor 2934219019Sgabor@cindex parentheses 2935219019Sgabor@cindex order of evaluation in expressions 2936219019Sgabor@cindex expression, order of evaluation 2937219019Sgabor@opindex ( 2938219019Sgabor@opindex ) 2939219019SgaborParentheses may be used as in any other language. However, in 2940219019Sgabor@code{gtroff} they are necessary to ensure order of evaluation. 2941219019Sgabor@code{gtroff} has no operator precedence; expressions are evaluated left 2942219019Sgaborto right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 2943219019Sgaborparenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 2944219019Sgaborexpected. 2945219019Sgabor 2946219019Sgabor@opindex +@r{, and page motion} 2947219019Sgabor@opindex -@r{, and page motion} 2948219019Sgabor@opindex |@r{, and page motion} 2949219019Sgabor@cindex motion operators 2950219019Sgabor@cindex operators, motion 2951219019SgaborFor many requests which cause a motion on the page, the unary operators 2952219019Sgaborwork differently. The @samp{+} and @samp{-} operators then indicate a 2953219019Sgabormotion relative to the current position (down or up, respectively), and 2954219019Sgaborthe @samp{|} operator indicates an absolute position on the page or 2955219019Sgaborinput line. 2956219019Sgabor@c XXX xref 2957219019Sgabor@samp{+} and @samp{-} are also treated differently by the following 2958219019Sgaborrequests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 2959219019Sgabor@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 2960219019Sgabor@code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus 2961219019Sgaborsigns indicate increments and decrements. 2962219019Sgabor 2963219019Sgabor@c XXX add more xref 2964219019Sgabor@xref{Setting Registers}. 2965219019Sgabor 2966219019Sgabor@cindex space characters in expressions 2967219019Sgabor@cindex expressions and space characters 2968219019SgaborDue to the way arguments are parsed, spaces are not allowed in 2969219019Sgaborexpressions, unless the entire expression is surrounded by parentheses. 2970219019Sgabor 2971219019Sgabor@xref{Request Arguments}, and @ref{Conditionals and Loops}. 2972219019Sgabor 2973219019Sgabor 2974219019Sgabor@c ===================================================================== 2975219019Sgabor 2976219019Sgabor@node Identifiers, Embedded Commands, Expressions, gtroff Reference 2977219019Sgabor@section Identifiers 2978219019Sgabor@cindex identifiers 2979219019Sgabor 2980219019SgaborLike any other language, @code{gtroff} has rules for properly formed 2981219019Sgabor@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 2982219019Sgaboralmost any printable character, with the exception of the following 2983219019Sgaborcharacters: 2984219019Sgabor 2985219019Sgabor@itemize @bullet 2986219019Sgabor@item 2987219019Sgabor@cindex whitespace characters 2988219019Sgabor@cindex newline character 2989219019Sgabor@cindex character, whitespace 2990219019SgaborWhitespace characters (spaces, tabs, and newlines). 2991219019Sgabor 2992219019Sgabor@item 2993219019Sgabor@cindex character, backspace 2994219019Sgabor@cindex backspace character 2995219019Sgabor@cindex @acronym{EBCDIC} encoding of backspace 2996219019SgaborBackspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{ 2997219019Sgabor}@code{0x16}) and character code @code{0x01}. 2998219019Sgabor 2999219019Sgabor@item 3000219019Sgabor@cindex invalid input characters 3001219019Sgabor@cindex input characters, invalid 3002219019Sgabor@cindex characters, invalid input 3003219019Sgabor@cindex unicode 3004219019SgaborThe following input characters are invalid and are ignored if 3005219019Sgabor@code{groff} runs on a machine based on @acronym{ASCII}, causing a 3006219019Sgaborwarning message of type @samp{input} (see @ref{Debugging}, for more 3007219019Sgabordetails): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 3008219019Sgabor@code{0x80}-@code{0x9F}. 3009219019Sgabor 3010219019SgaborAnd here are the invalid input characters if @code{groff} runs on an 3011219019Sgabor@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 3012219019Sgabor@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 3013219019Sgabor@code{0x30}-@code{0x3F}. 3014219019Sgabor 3015219019SgaborCurrently, some of these reserved codepoints are used internally, thus 3016219019Sgabormaking it non-trivial to extend @code{gtroff} to cover Unicode or other 3017219019Sgaborcharacter sets and encodings which use characters of these ranges. 3018219019Sgabor 3019219019SgaborNote that invalid characters are removed before parsing; an 3020219019Sgaboridentifier @code{foo}, followed by an invalid character, followed by 3021219019Sgabor@code{bar} is treated as @code{foobar}. 3022219019Sgabor@end itemize 3023219019Sgabor 3024219019SgaborFor example, any of the following is valid. 3025219019Sgabor 3026219019Sgabor@Example 3027219019Sgaborbr 3028219019SgaborPP 3029219019Sgabor(l 3030219019Sgaborend-list 3031219019Sgabor@@_ 3032219019Sgabor@endExample 3033219019Sgabor 3034219019Sgabor@rqindex ] 3035219019Sgabor@noindent 3036219019SgaborNote that identifiers longer than two characters with a closing bracket 3037219019Sgabor(@samp{]}) in its name can't be accessed with escape sequences which 3038219019Sgaborexpect an identifier as a parameter. For example, @samp{\[foo]]} 3039219019Sgaboraccesses the glyph @samp{foo}, followed by @samp{]}, whereas 3040219019Sgabor@samp{\C'foo]'} really asks for glyph @samp{foo]}. 3041219019Sgabor 3042219019Sgabor@c XXX xref 3043219019Sgabor 3044219019Sgabor@Defesc {\\A, ', ident, '} 3045219019SgaborTest whether an identifier @var{ident} is valid in @code{gtroff}. It 3046219019Sgaborexpands to the character@w{ }1 or@w{ }0 according to whether its 3047219019Sgaborargument (usually delimited by quotes) is or is not acceptable as the 3048219019Sgaborname of a string, macro, diversion, number register, environment, or 3049219019Sgaborfont. It returns@w{ }0 if no argument is given. This is useful for 3050219019Sgaborlooking up user input in some sort of associative table. 3051219019Sgabor 3052219019Sgabor@Example 3053219019Sgabor\A'end-list' 3054219019Sgabor @result{} 1 3055219019Sgabor@endExample 3056219019Sgabor@endDefesc 3057219019Sgabor 3058219019Sgabor@xref{Escapes}, for details on parameter delimiting characters. 3059219019Sgabor 3060219019Sgabor@c XXX add xrefs above 3061219019Sgabor 3062219019SgaborIdentifiers in @code{gtroff} can be any length, but, in some contexts, 3063219019Sgabor@code{gtroff} needs to be told where identifiers end and text begins 3064219019Sgabor(and in different ways depending on their length): 3065219019Sgabor 3066219019Sgabor@rqindex ( 3067219019Sgabor@rqindex [ 3068219019Sgabor@rqindex ] 3069219019Sgabor@itemize @bullet 3070219019Sgabor@item 3071219019SgaborSingle character. 3072219019Sgabor 3073219019Sgabor@item 3074219019SgaborTwo characters. Must be prefixed with @samp{(} in some situations. 3075219019Sgabor 3076219019Sgabor@item 3077219019SgaborArbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 3078219019Sgaborand@w{ }@samp{]} in some situations. Any length identifier can be put 3079219019Sgaborin brackets. 3080219019Sgabor@end itemize 3081219019Sgabor 3082219019Sgabor@cindex undefined identifiers 3083219019Sgabor@cindex indentifiers, undefined 3084219019SgaborUnlike many other programming languages, undefined identifiers are 3085219019Sgaborsilently ignored or expanded to nothing. 3086219019SgaborWhen @code{gtroff} finds an undefined identifier, it emits a 3087219019Sgaborwarning then: 3088219019Sgabor 3089219019Sgabor@itemize @bullet 3090219019Sgabor@item 3091219019SgaborIf the identifier is a string, macro, or diversion, 3092219019Sgabor@code{gtroff} defines it as empty. 3093219019Sgabor 3094219019Sgabor@item 3095219019SgaborIf the identifier is a number register, @code{gtroff} 3096219019Sgabordefines it with a value of@w{ }0. 3097219019Sgabor@end itemize 3098219019Sgabor 3099219019Sgabor@xref{Warnings}. 3100219019Sgabor 3101219019Sgabor@c XXX info about common identifier pool for strings and macros. 3102219019Sgabor 3103219019Sgabor@xref{Interpolating Registers}, and @ref{Strings}. 3104219019Sgabor 3105219019Sgabor 3106219019Sgabor@c ===================================================================== 3107219019Sgabor 3108219019Sgabor@node Embedded Commands, Registers, Identifiers, gtroff Reference 3109219019Sgabor@section Embedded Commands 3110219019Sgabor@cindex embedded commands 3111219019Sgabor@cindex commands, embedded 3112219019Sgabor 3113219019SgaborMost documents need more functionality beyond filling, adjusting and 3114219019Sgaborimplicit line breaking. In order to gain further functionality, 3115219019Sgabor@code{gtroff} allows commands to be embedded into the text, in two ways. 3116219019Sgabor 3117219019SgaborThe first is a @dfn{request} which takes up an entire line, and does 3118219019Sgaborsome large-scale operation (e.g.@: break lines, start new pages). 3119219019Sgabor 3120219019SgaborThe other is an @dfn{escape} which can be embedded anywhere in the text, 3121219019Sgaboror even as an argument to a request. 3122219019Sgabor@c XXX (Not always?) 3123219019SgaborEscapes generally do more minor operations like sub- and superscripts, 3124219019Sgaborprint a symbol, etc. 3125219019Sgabor 3126219019Sgabor@menu 3127219019Sgabor* Requests:: 3128219019Sgabor* Macros:: 3129219019Sgabor* Escapes:: 3130219019Sgabor@end menu 3131219019Sgabor 3132219019Sgabor@c --------------------------------------------------------------------- 3133219019Sgabor 3134219019Sgabor@node Requests, Macros, Embedded Commands, Embedded Commands 3135219019Sgabor@subsection Requests 3136219019Sgabor@cindex requests 3137219019Sgabor 3138219019Sgabor@cindex control character 3139219019Sgabor@cindex character, control 3140219019Sgabor@cindex no-break control character 3141219019Sgabor@cindex character, no-break control 3142219019Sgabor@cindex control character, no-break 3143219019Sgabor@rqindex ' 3144219019Sgabor@rqindex . 3145219019SgaborA request line begins with a control character, which is either a single 3146219019Sgaborquote (@samp{'}, the @dfn{no-break control character}) or a period 3147219019Sgabor(@samp{.}, the normal @dfn{control character}). These can be changed; 3148219019Sgaborsee @ref{Character Translations}, for details. After this there may be 3149219019Sgaboroptional tabs or spaces followed by an identifier which is the name of 3150219019Sgaborthe request. This may be followed by any number of space-separated 3151219019Sgaborarguments (@emph{no} tabs here). 3152219019Sgabor 3153219019Sgabor@cindex structuring source code of documents or macro packages 3154219019Sgabor@cindex documents, structuring the source code 3155219019Sgabor@cindex macro packages, strucuring the source code 3156219019SgaborSince a control character followed by whitespace only is ignored, it 3157219019Sgaboris common practice to use this feature for structuring the source code 3158219019Sgaborof documents or macro packages. 3159219019Sgabor 3160219019Sgabor@Example 3161219019Sgabor.de foo 3162219019Sgabor. tm This is foo. 3163219019Sgabor.. 3164219019Sgabor. 3165219019Sgabor. 3166219019Sgabor.de bar 3167219019Sgabor. tm This is bar. 3168219019Sgabor.. 3169219019Sgabor@endExample 3170219019Sgabor 3171219019Sgabor@cindex blank line 3172219019Sgabor@cindex blank line macro 3173219019Sgabor@rqindex blm 3174219019SgaborAnother possibility is to use the blank line macro request @code{blm} 3175219019Sgaborby assigning an empty macro to it. 3176219019Sgabor 3177219019Sgabor@Example 3178219019Sgabor.de do-nothing 3179219019Sgabor.. 3180219019Sgabor.blm do-nothing \" activate blank line macro 3181219019Sgabor 3182219019Sgabor.de foo 3183219019Sgabor. tm This is foo. 3184219019Sgabor.. 3185219019Sgabor 3186219019Sgabor 3187219019Sgabor.de bar 3188219019Sgabor. tm This is bar. 3189219019Sgabor.. 3190219019Sgabor 3191219019Sgabor.blm \" deactivate blank line macro 3192219019Sgabor@endExample 3193219019Sgabor 3194219019Sgabor@c XXX xref to blm 3195219019Sgabor 3196219019Sgabor@cindex zero width space character 3197219019Sgabor@cindex character, zero width space 3198219019Sgabor@cindex space character, zero width 3199219019Sgabor@esindex \& 3200219019Sgabor@cindex @code{\&}, escaping control characters 3201219019SgaborTo begin a line with a control character without it being interpreted, 3202219019Sgaborprecede it with @code{\&}. This represents a zero width space, which 3203219019Sgabormeans it does not affect the output. 3204219019Sgabor 3205219019SgaborIn most cases the period is used as a control character. Several 3206219019Sgaborrequests cause a break implicitly; using the single quote control 3207219019Sgaborcharacter prevents this. 3208219019Sgabor 3209219019Sgabor@menu 3210219019Sgabor* Request Arguments:: 3211219019Sgabor@end menu 3212219019Sgabor 3213219019Sgabor@node Request Arguments, , Requests, Requests 3214219019Sgabor@subsubsection Request Arguments 3215219019Sgabor@cindex request arguments 3216219019Sgabor@cindex arguments to requests 3217219019Sgabor 3218219019SgaborArguments to requests (and macros) are processed much like the shell: 3219219019SgaborThe line is split into arguments according to spaces. An argument 3220219019Sgaborwhich is intended to contain spaces can either be enclosed in double 3221219019Sgaborquotes, or have the spaces @dfn{escaped} with backslashes. 3222219019Sgabor 3223219019SgaborHere are a few examples: 3224219019Sgabor 3225219019Sgabor@Example 3226219019Sgabor.uh The Mouse Problem 3227219019Sgabor.uh "The Mouse Problem" 3228219019Sgabor.uh The\ Mouse\ Problem 3229219019Sgabor@endExample 3230219019Sgabor 3231219019Sgabor@esindex \~ 3232219019Sgabor@esindex \@key{SP} 3233219019Sgabor@noindent 3234219019SgaborThe first line is the @code{uh} macro being called with 3 arguments, 3235219019Sgabor@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 3236219019Sgaborsame effect of calling the @code{uh} macro with one argument, @samp{The 3237219019SgaborMouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 3238219019Sgaboris ``classical'' in the sense that it can be found in most @code{troff} 3239219019Sgabordocuments. Nevertheless, it is not optimal in all situations, since 3240219019Sgabor@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 3241219019Sgaborcan't stretch. @code{gtroff} provides a different command @code{\~} to 3242219019Sgaborinsert a stretchable, non-breaking space.} 3243219019Sgabor 3244219019Sgabor@cindex @code{"}, as a macro argument 3245219019Sgabor@cindex double quote, as a macro argument 3246219019SgaborA double quote which isn't preceded by a space doesn't start a macro 3247219019Sgaborargument. If not closing a string, it is printed literally. 3248219019Sgabor 3249219019SgaborFor example, 3250219019Sgabor 3251219019Sgabor@Example 3252219019Sgabor.xxx a" "b c" "de"fg" 3253219019Sgabor@endExample 3254219019Sgabor 3255219019Sgabor@noindent 3256219019Sgaborhas the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 3257219019Sgabor 3258219019Sgabor@rqindex ds 3259219019SgaborDuoble quotes in the @code{ds} request are handled differently. 3260219019Sgabor@xref{Strings}, for more details. 3261219019Sgabor 3262219019Sgabor@c --------------------------------------------------------------------- 3263219019Sgabor 3264219019Sgabor@node Macros, Escapes, Requests, Embedded Commands 3265219019Sgabor@subsection Macros 3266219019Sgabor@cindex macros 3267219019Sgabor 3268219019Sgabor@code{gtroff} has a @dfn{macro} facility for defining a series of lines 3269219019Sgaborwhich can be invoked by name. They are called in the same manner as 3270219019Sgaborrequests -- arguments also may be passed in the same manner. 3271219019Sgabor 3272219019Sgabor@xref{Writing Macros}, and @ref{Request Arguments}. 3273219019Sgabor 3274219019Sgabor@c --------------------------------------------------------------------- 3275219019Sgabor 3276219019Sgabor@node Escapes, , Macros, Embedded Commands 3277219019Sgabor@subsection Escapes 3278219019Sgabor@cindex escapes 3279219019Sgabor 3280219019SgaborEscapes may occur anywhere in the input to @code{gtroff}. They usually 3281219019Sgaborbegin with a backslash and are followed by a single character which 3282219019Sgaborindicates the function to be performed. The escape character can be 3283219019Sgaborchanged; see @ref{Character Translations}. 3284219019Sgabor 3285219019Sgabor@rqindex ( 3286219019Sgabor@rqindex [ 3287219019Sgabor@rqindex ] 3288219019SgaborEscape sequences which require an identifier as a parameter accept three 3289219019Sgaborpossible syntax forms. 3290219019Sgabor 3291219019Sgabor@itemize @bullet 3292219019Sgabor@item 3293219019SgaborThe next single character is the identifier. 3294219019Sgabor 3295219019Sgabor@item 3296219019SgaborIf this single character is an opening parenthesis, take the following 3297219019Sgabortwo characters as the identifier. Note that there is no closing 3298219019Sgaborparenthesis after the identifier. 3299219019Sgabor 3300219019Sgabor@item 3301219019SgaborIf this single character is an opening bracket, take all characters 3302219019Sgaboruntil a closing bracket as the identifier. 3303219019Sgabor@end itemize 3304219019Sgabor 3305219019Sgabor@noindent 3306219019SgaborExamples: 3307219019Sgabor 3308219019Sgabor@Example 3309219019Sgabor\fB 3310219019Sgabor\n(XX 3311219019Sgabor\*[TeX] 3312219019Sgabor@endExample 3313219019Sgabor 3314219019Sgabor@rqindex ' 3315219019Sgabor@cindex argument delimiting characters 3316219019Sgabor@cindex characters, argument delimiting 3317219019Sgabor@cindex delimiting characters for arguments 3318219019SgaborOther escapes may require several arguments and/or some special format. 3319219019SgaborIn such cases the argument is traditionally enclosed in single quotes 3320219019Sgabor(and quotes are always used in this manual for the definitions of escape 3321219019Sgaborsequences). The enclosed text is then processed according to what that 3322219019Sgaborescape expects. Example: 3323219019Sgabor 3324219019Sgabor@Example 3325219019Sgabor\l'1.5i\(bu' 3326219019Sgabor@endExample 3327219019Sgabor 3328219019Sgabor@esindex \o 3329219019Sgabor@esindex \b 3330219019Sgabor@esindex \X 3331219019SgaborNote that the quote character can be replaced with any other character 3332219019Sgaborwhich does not occur in the argument (even a newline or a space 3333219019Sgaborcharacter) in the following escapes: @code{\o}, @code{\b}, and 3334219019Sgabor@code{\X}. This makes e.g. 3335219019Sgabor 3336219019Sgabor@Example 3337219019SgaborA caf 3338219019Sgabor\o 3339219019Sgabore\' 3340219019Sgabor 3341219019Sgabor 3342219019Sgaborin Paris 3343219019Sgabor @result{} A caf@'e in Paris 3344219019Sgabor@endExample 3345219019Sgabor 3346219019Sgabor@noindent 3347219019Sgaborpossible, but it is better not to use this feature to avoid confusion. 3348219019Sgabor 3349219019Sgabor@esindex \% 3350219019Sgabor@esindex \@key{SP} 3351219019Sgabor@esindex \| 3352219019Sgabor@esindex \^ 3353219019Sgabor@esindex \@{ 3354219019Sgabor@esindex \@} 3355219019Sgabor@esindex \' 3356219019Sgabor@esindex \` 3357219019Sgabor@esindex \- 3358219019Sgabor@esindex \_ 3359219019Sgabor@esindex \! 3360219019Sgabor@esindex \? 3361219019Sgabor@esindex \@@ 3362219019Sgabor@esindex \) 3363219019Sgabor@esindex \/ 3364219019Sgabor@esindex \, 3365219019Sgabor@esindex \& 3366219019Sgabor@esindex \~ 3367219019Sgabor@esindex \0 3368219019Sgabor@esindex \a 3369219019Sgabor@esindex \c 3370219019Sgabor@esindex \d 3371219019Sgabor@esindex \e 3372219019Sgabor@esindex \E 3373219019Sgabor@esindex \p 3374219019Sgabor@esindex \r 3375219019Sgabor@esindex \t 3376219019Sgabor@esindex \u 3377219019SgaborThe following escapes sequences (which are handled similarly to 3378219019Sgaborcharacters since they don't take a parameter) are also allowed as 3379219019Sgabordelimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 3380219019Sgabor@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 3381219019Sgabor@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 3382219019Sgabor@code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e}, 3383219019Sgabor@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't 3384219019Sgaboruse these if possible. 3385219019Sgabor 3386219019Sgabor@esindex \A 3387219019Sgabor@esindex \Z 3388219019Sgabor@esindex \C 3389219019Sgabor@esindex \w 3390219019SgaborNo newline characters as delimiters are allowed in the following 3391219019Sgaborescapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}. 3392219019Sgabor 3393219019Sgabor@esindex \D 3394219019Sgabor@esindex \h 3395219019Sgabor@esindex \H 3396219019Sgabor@esindex \l 3397219019Sgabor@esindex \L 3398219019Sgabor@esindex \N 3399219019Sgabor@esindex \R 3400219019Sgabor@esindex \s 3401219019Sgabor@esindex \S 3402219019Sgabor@esindex \v 3403219019Sgabor@esindex \x 3404219019SgaborFinally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 3405219019Sgabor@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and 3406219019Sgabor@code{\x} can't use the following characters as delimiters: 3407219019Sgabor 3408219019Sgabor@itemize @bullet 3409219019Sgabor@item 3410219019Sgabor@cindex numbers 3411219019Sgabor@cindex digits 3412219019SgaborThe digits @code{0}-@code{9}. 3413219019Sgabor 3414219019Sgabor@item 3415219019Sgabor@cindex operators 3416219019Sgabor@opindex + 3417219019Sgabor@opindex - 3418219019Sgabor@opindex / 3419219019Sgabor@opindex * 3420219019Sgabor@opindex % 3421219019Sgabor@opindex < 3422219019Sgabor@opindex > 3423219019Sgabor@opindex = 3424219019Sgabor@opindex & 3425219019Sgabor@opindex : 3426219019Sgabor@opindex ( 3427219019Sgabor@opindex ) 3428219019Sgabor@opindex . 3429219019SgaborThe (single-character) operators @samp{+-/*%<>=&:().}. 3430219019Sgabor 3431219019Sgabor@item 3432219019Sgabor@cindex space character 3433219019Sgabor@cindex character, space 3434219019Sgabor@cindex tab character 3435219019Sgabor@cindex character, tab 3436219019Sgabor@cindex newline character 3437219019Sgabor@cindex character, newline 3438219019SgaborThe space, tab, and newline characters. 3439219019Sgabor 3440219019Sgabor@item 3441219019Sgabor@esindex \% 3442219019Sgabor@esindex \@{ 3443219019Sgabor@esindex \@} 3444219019Sgabor@esindex \' 3445219019Sgabor@esindex \` 3446219019Sgabor@esindex \- 3447219019Sgabor@esindex \_ 3448219019Sgabor@esindex \! 3449219019Sgabor@esindex \@@ 3450219019Sgabor@esindex \/ 3451219019Sgabor@esindex \c 3452219019Sgabor@esindex \e 3453219019Sgabor@esindex \p 3454219019SgaborAll escape sequences except @code{\%}, @code{\@{}, @code{\@}}, 3455219019Sgabor@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 3456219019Sgabor@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 3457219019Sgabor@end itemize 3458219019Sgabor 3459219019Sgabor@esindex \\ 3460219019Sgabor@esindex \e 3461219019Sgabor@esindex \E 3462219019SgaborTo have a backslash (actually, the current escape character) appear in the 3463219019Sgaboroutput several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 3464219019SgaborThese are very similar, and only differ with respect to being used in 3465219019Sgabormacros or diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for 3466219019Sgabormore information. 3467219019Sgabor 3468219019Sgabor@c XXX explanation of \E 3469219019Sgabor 3470219019Sgabor@xref{Identifiers}, and @ref{Character Translations}. 3471219019Sgabor 3472219019Sgabor@menu 3473219019Sgabor* Comments:: 3474219019Sgabor@end menu 3475219019Sgabor 3476219019Sgabor@node Comments, , Escapes, Escapes 3477219019Sgabor@subsubsection Comments 3478219019Sgabor@cindex comments 3479219019Sgabor 3480219019SgaborProbably one of the most@footnote{Unfortunately, this is a lie. But 3481219019Sgaborhopefully future @code{gtroff} hackers will believe it @code{:-)}} 3482219019Sgaborcommon forms of escapes is the comment. 3483219019Sgabor 3484219019Sgabor@Defesc {\\", , , } 3485219019SgaborStart a comment. Everything to the end of the input line is ignored. 3486219019Sgabor 3487219019SgaborThis may sound simple, but it can be tricky to keep the comments from 3488219019Sgaborinterfering with the appearance of the final output. 3489219019Sgabor 3490219019Sgabor@rqindex ds 3491219019Sgabor@rqindex as 3492219019SgaborIf the escape is to the right of some text or a request, that portion 3493219019Sgaborof the line is ignored, but the space leading up to it is noticed by 3494219019Sgabor@code{gtroff}. This only affects the @code{.ds} and @code{.as} 3495219019Sgaborrequest. 3496219019Sgabor 3497219019Sgabor@cindex tabs before comments 3498219019Sgabor@cindex comments, lining up with tabs 3499219019SgaborOne possibly irritating idiosyncracy is that tabs must not be used to 3500219019Sgaborline up comments. Tabs are not treated as white space between the 3501219019Sgaborrequest and macro arguments. 3502219019Sgabor 3503219019Sgabor@cindex undefined request 3504219019Sgabor@cindex request, undefined 3505219019SgaborA comment on a line by itself is treated as a blank line, because 3506219019Sgaborafter eliminating the comment, that is all that remains: 3507219019Sgabor 3508219019Sgabor@Example 3509219019SgaborTest 3510219019Sgabor\" comment 3511219019SgaborTest 3512219019Sgabor@endExample 3513219019Sgabor 3514219019Sgabor@noindent 3515219019Sgaborproduces 3516219019Sgabor 3517219019Sgabor@Example 3518219019SgaborTest 3519219019Sgabor 3520219019SgaborTest 3521219019Sgabor@endExample 3522219019Sgabor 3523219019SgaborTo avoid this, it is common to start the line with @code{.\"} which 3524219019Sgaborcauses the line to be treated as an undefined request and thus ignored 3525219019Sgaborcompletely. 3526219019Sgabor 3527219019Sgabor@rqindex ' 3528219019SgaborAnother commenting scheme seen sometimes is three consecutive single 3529219019Sgaborquotes (@code{'''}) at the beginning of a line. This works, but 3530219019Sgabor@code{gtroff} gives a warning about an undefined macro (namely 3531219019Sgabor@code{''}), which is harmless, but irritating. 3532219019Sgabor@endDefesc 3533219019Sgabor 3534219019Sgabor@Defesc {\\#, , , } 3535219019SgaborTo avoid all this, @code{gtroff} has a new comment mechanism using the 3536219019Sgabor@code{\#} escape. This escape works the same as @code{\"} except that 3537219019Sgaborthe newline is also ignored: 3538219019Sgabor 3539219019Sgabor@Example 3540219019SgaborTest 3541219019Sgabor\# comment 3542219019SgaborTest 3543219019Sgabor@endExample 3544219019Sgabor 3545219019Sgabor@noindent 3546219019Sgaborproduces 3547219019Sgabor 3548219019Sgabor@Example 3549219019SgaborTest Test 3550219019Sgabor@endExample 3551219019Sgabor 3552219019Sgabor@noindent 3553219019Sgaboras expected. 3554219019Sgabor@endDefesc 3555219019Sgabor 3556219019Sgabor@Defreq {ig, yy} 3557219019SgaborIgnore all input until @code{gtroff} encounters the macro named 3558219019Sgabor@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not 3559219019Sgaborspecified). This is useful for commenting out large blocks of text: 3560219019Sgabor 3561219019Sgabor@Example 3562219019Sgabortext text text... 3563219019Sgabor.ig 3564219019SgaborThis is part of a large block 3565219019Sgaborof text that has been 3566219019Sgabortemporarily(?) commented out. 3567219019Sgabor 3568219019SgaborWe can restore it simply by removing 3569219019Sgaborthe .ig request and the ".." at the 3570219019Sgaborend of the block. 3571219019Sgabor.. 3572219019SgaborMore text text text... 3573219019Sgabor@endExample 3574219019Sgabor 3575219019Sgabor@noindent 3576219019Sgaborproduces 3577219019Sgabor 3578219019Sgabor@Example 3579219019Sgabortext text text@dots{} More text text text@dots{} 3580219019Sgabor@endExample 3581219019Sgabor 3582219019Sgabor@noindent 3583219019SgaborNote that the commented-out block of text does not 3584219019Sgaborcause a break. 3585219019Sgabor 3586219019SgaborThe input is read in copy-mode; auto-incremented registers @emph{are} 3587219019Sgaboraffected (@pxref{Auto-increment}). 3588219019Sgabor@endDefreq 3589219019Sgabor 3590219019Sgabor 3591219019Sgabor@c ===================================================================== 3592219019Sgabor 3593219019Sgabor@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 3594219019Sgabor@section Registers 3595219019Sgabor@cindex registers 3596219019Sgabor 3597219019SgaborNumeric variables in @code{gtroff} are called @dfn{registers}. There 3598219019Sgaborare a number of built-in registers, supplying anything from the date to 3599219019Sgabordetails of formatting parameters. 3600219019Sgabor 3601219019Sgabor@xref{Identifiers}, for details on register identifiers. 3602219019Sgabor 3603219019Sgabor@menu 3604219019Sgabor* Setting Registers:: 3605219019Sgabor* Interpolating Registers:: 3606219019Sgabor* Auto-increment:: 3607219019Sgabor* Assigning Formats:: 3608219019Sgabor* Built-in Registers:: 3609219019Sgabor@end menu 3610219019Sgabor 3611219019Sgabor@c --------------------------------------------------------------------- 3612219019Sgabor 3613219019Sgabor@node Setting Registers, Interpolating Registers, Registers, Registers 3614219019Sgabor@subsection Setting Registers 3615219019Sgabor@cindex setting registers 3616219019Sgabor@cindex registers, setting 3617219019Sgabor 3618219019SgaborDefine or set registers using the @code{nr} request or the 3619219019Sgabor@code{\R} escape. 3620219019Sgabor 3621219019Sgabor@Defreq {nr, ident value} 3622219019Sgabor@Defescx {\\R, ', ident value, '} 3623219019SgaborSet number register @var{ident} to @var{value}. If @var{ident} 3624219019Sgabordoesn't exist, @code{gtroff} creates it. 3625219019Sgabor 3626219019SgaborThe argument to @code{\R} usually has to be enclosed in quotes. 3627219019Sgabor@xref{Escapes}, for details on parameter delimiting characters. 3628219019Sgabor@endDefreq 3629219019Sgabor 3630219019SgaborFor example, the following two lines are equivalent: 3631219019Sgabor 3632219019Sgabor@Example 3633219019Sgabor.nr a 1 3634219019Sgabor\R'a 1' 3635219019Sgabor@endExample 3636219019Sgabor 3637219019SgaborBoth @code{nr} and @code{\R} have two additional special forms to 3638219019Sgaborincrement or decrement a register. 3639219019Sgabor 3640219019Sgabor@Defreq {nr, ident @t{+}@Var{value}} 3641219019Sgabor@Defreqx {nr, ident @t{-}@Var{value}} 3642219019Sgabor@Defescx {\\R, ', ident @t{+}@Var{value}, '} 3643219019Sgabor@Defescx {\\R, ', ident @t{-}@Var{value}, '} 3644219019SgaborIncrement (decrement) register @var{ident} by @var{value}. 3645219019Sgabor 3646219019Sgabor@Example 3647219019Sgabor.nr a 1 3648219019Sgabor.nr a +1 3649219019Sgabor\na 3650219019Sgabor @result{} 2 3651219019Sgabor@endExample 3652219019Sgabor 3653219019Sgabor@cindex negating register values 3654219019SgaborTo assign the negated value of a register to another register, some care 3655219019Sgabormust be taken to get the desired result: 3656219019Sgabor 3657219019Sgabor@Example 3658219019Sgabor.nr a 7 3659219019Sgabor.nr b 3 3660219019Sgabor.nr a -\nb 3661219019Sgabor\na 3662219019Sgabor @result{} 4 3663219019Sgabor.nr a (-\nb) 3664219019Sgabor\na 3665219019Sgabor @result{} -3 3666219019Sgabor@endExample 3667219019Sgabor 3668219019Sgabor@noindent 3669219019SgaborThe surrounding parentheses prevent the interpretation of the minus sign 3670219019Sgaboras a decrementing operator. An alternative is to start the assignment 3671219019Sgaborwith a @samp{0}: 3672219019Sgabor 3673219019Sgabor@Example 3674219019Sgabor.nr a 7 3675219019Sgabor.nr b -3 3676219019Sgabor.nr a \nb 3677219019Sgabor\na 3678219019Sgabor @result{} 4 3679219019Sgabor.nr a 0\nb 3680219019Sgabor\na 3681219019Sgabor @result{} -3 3682219019Sgabor@endExample 3683219019Sgabor@endDefreq 3684219019Sgabor 3685219019Sgabor@Defreq {rr, ident} 3686219019SgaborRemove number register @var{ident}. If @var{ident} doesn't exist, the 3687219019Sgaborrequest is ignored. 3688219019Sgabor@endDefreq 3689219019Sgabor 3690219019Sgabor@Defreq {rnn, ident1 ident2} 3691219019SgaborRename number register @var{ident1} to @var{ident2}. If either 3692219019Sgabor@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 3693219019Sgabor@endDefreq 3694219019Sgabor 3695219019Sgabor@Defreq {aln, ident1 ident2} 3696219019SgaborCreate an alias @var{ident1} for a number register @var{ident2}. The 3697219019Sgabornew name and the old name are exactly equivalent. If @var{ident1} is 3698219019Sgaborundefined, a warning of type @samp{reg} is generated, and the request 3699219019Sgaboris ignored. @xref{Debugging}, for information about warnings. 3700219019Sgabor@endDefreq 3701219019Sgabor 3702219019Sgabor@c --------------------------------------------------------------------- 3703219019Sgabor 3704219019Sgabor@node Interpolating Registers, Auto-increment, Setting Registers, Registers 3705219019Sgabor@subsection Interpolating Registers 3706219019Sgabor@cindex interpolating registers 3707219019Sgabor@cindex registers, interpolating 3708219019Sgabor 3709219019SgaborNumeric registers can be accessed via the @code{\n} escape. 3710219019Sgabor 3711219019Sgabor@cindex nested assignments 3712219019Sgabor@cindex assignments, nested 3713219019Sgabor@cindex indirect assignments 3714219019Sgabor@cindex assignments, indirect 3715219019Sgabor@Defesc {\\n, , i, } 3716219019Sgabor@Defescx {\\n, @lparen{}, id, } 3717219019Sgabor@Defescx {\\n, @lbrack{}, ident, @rbrack} 3718219019SgaborInterpolate number register with name @var{ident} (one-character name 3719219019Sgabor@var{i}, two-character name @var{id}). This means that the value of 3720219019Sgaborthe register is expanded in-place while @code{gtroff} is parsing the 3721219019Sgaborinput line. Nested assignments (also called indirect assignments) are 3722219019Sgaborpossible. 3723219019Sgabor 3724219019Sgabor@Example 3725219019Sgabor.nr a 5 3726219019Sgabor.nr as \na+\na 3727219019Sgabor\n(as 3728219019Sgabor @result{} 10 3729219019Sgabor@endExample 3730219019Sgabor 3731219019Sgabor@Example 3732219019Sgabor.nr a1 5 3733219019Sgabor.nr ab 6 3734219019Sgabor.ds str b 3735219019Sgabor.ds num 1 3736219019Sgabor\n[a\n[num]] 3737219019Sgabor @result{} 5 3738219019Sgabor\n[a\*[str]] 3739219019Sgabor @result{} 6 3740219019Sgabor@endExample 3741219019Sgabor@endDefesc 3742219019Sgabor 3743219019Sgabor@c --------------------------------------------------------------------- 3744219019Sgabor 3745219019Sgabor@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 3746219019Sgabor@subsection Auto-increment 3747219019Sgabor@cindex auto-increment 3748219019Sgabor@cindex increment, automatic 3749219019Sgabor 3750219019SgaborNumber registers can also be auto-incremented and auto-decremented. 3751219019SgaborThe increment or decrement value can be specified with a third 3752219019Sgaborargument to the @code{nr} request or @code{\R} escape. 3753219019Sgabor 3754219019Sgabor@esindex \R 3755219019Sgabor@Defreq {nr, ident value incr} 3756219019SgaborSet number register @var{ident} to @var{value}; the increment for 3757219019Sgaborauto-incrementing is set to @var{incr}. Note that the @code{\R} 3758219019Sgaborescape doesn't support this notation. 3759219019Sgabor@endDefreq 3760219019Sgabor 3761219019SgaborTo activate auto-incrementing, the escape @code{\n} has a special 3762219019Sgaborsyntax form. 3763219019Sgabor 3764219019Sgabor@Defesc {\\n, +, i, } 3765219019Sgabor@Defescx {\\n, -, i, } 3766219019Sgabor@Defescx {\\n, @lparen{}+, id, } 3767219019Sgabor@Defescx {\\n, @lparen{}-, id, } 3768219019Sgabor@Defescx {\\n, +@lparen{}, id, } 3769219019Sgabor@Defescx {\\n, -@lparen{}, id, } 3770219019Sgabor@Defescx {\\n, @lbrack{}+, ident, @rbrack{}} 3771219019Sgabor@Defescx {\\n, @lbrack{}-, ident, @rbrack{}} 3772219019Sgabor@Defescx {\\n, +@lbrack{}, ident, @rbrack{}} 3773219019Sgabor@Defescx {\\n, -@lbrack{}, ident, @rbrack{}} 3774219019SgaborBefore interpolating, increment or decrement @var{ident} 3775219019Sgabor(one-character name @var{i}, two-character name @var{id}) by the 3776219019Sgaborauto-increment value as specified with the @code{nr} request (or the 3777219019Sgabor@code{\R} escape). If no auto-increment value has been specified, 3778219019Sgaborthese syntax forms are identical to @code{\n}. 3779219019Sgabor@endDefesc 3780219019Sgabor 3781219019SgaborFor example, 3782219019Sgabor 3783219019Sgabor@Example 3784219019Sgabor.nr a 0 1 3785219019Sgabor.nr xx 0 5 3786219019Sgabor.nr foo 0 -2 3787219019Sgabor\n+a, \n+a, \n+a, \n+a, \n+a 3788219019Sgabor.br 3789219019Sgabor\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 3790219019Sgabor.br 3791219019Sgabor\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 3792219019Sgabor@endExample 3793219019Sgabor 3794219019Sgabor@noindent 3795219019Sgaborproduces 3796219019Sgabor 3797219019Sgabor@Example 3798219019Sgabor1, 2, 3, 4, 5 3799219019Sgabor-5, -10, -15, -20, -25 3800219019Sgabor-2, -4, -6, -8, -10 3801219019Sgabor@endExample 3802219019Sgabor 3803219019Sgabor@cindex increment value without changing the register 3804219019SgaborTo change the increment value without changing the value of a register 3805219019Sgabor(@var{a} in the example), the following can be used: 3806219019Sgabor 3807219019Sgabor@Example 3808219019Sgabor.nr a \na 10 3809219019Sgabor@endExample 3810219019Sgabor 3811219019Sgabor@c --------------------------------------------------------------------- 3812219019Sgabor 3813219019Sgabor@node Assigning Formats, Built-in Registers, Auto-increment, Registers 3814219019Sgabor@subsection Assigning Formats 3815219019Sgabor@cindex assigning formats 3816219019Sgabor@cindex formats, assigning 3817219019Sgabor 3818219019SgaborWhen a register is used in the text of an input file (as opposed to 3819219019Sgaborpart of an expression), it is textually replaced (or interpolated) 3820219019Sgaborwith a representation of that number. This output format can be 3821219019Sgaborchanged to a variety of formats (numbers, Roman numerals, etc.). This 3822219019Sgaboris done using the @code{af} request. 3823219019Sgabor 3824219019Sgabor@Defreq {af, ident format} 3825219019SgaborChange the output format of a number register. The first argument 3826219019Sgabor@var{ident} is the name of the number register to be changed, and the 3827219019Sgaborsecond argument @var{format} is the output format. The following 3828219019Sgaboroutput formats are available: 3829219019Sgabor 3830219019Sgabor@table @code 3831219019Sgabor@item 1 3832219019SgaborDecimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{ 3833219019Sgabor}@enddots{} 3834219019Sgabor 3835219019Sgabor@item 0@dots{}0 3836219019SgaborDecimal numbers with as many digits as specified. So, @samp{00} would 3837219019Sgaborresult in printing numbers as 01, 02, 03,@w{ }@enddots{} 3838219019Sgabor 3839219019SgaborIn fact, any digit instead of zero will do; @code{gtroff} only counts 3840219019Sgaborhow many digits are specified. As a consequence, @code{af}'s default 3841219019Sgaborformat @samp{1} could be specified as @samp{0} also (and exactly this is 3842219019Sgaborreturned by the @code{\g} escape, see below). 3843219019Sgabor 3844219019Sgabor@item I 3845219019Sgabor@cindex Roman numerals 3846219019Sgabor@cindex numerals, Roman 3847219019SgaborUpper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{} 3848219019Sgabor 3849219019Sgabor@item i 3850219019SgaborLower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{} 3851219019Sgabor 3852219019Sgabor@item A 3853219019SgaborUpper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{} 3854219019Sgabor 3855219019Sgabor@item a 3856219019SgaborLower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{} 3857219019Sgabor@end table 3858219019Sgabor 3859219019SgaborOmitting the number register format causes a warning of type 3860219019Sgabor@samp{missing}. @xref{Debugging}, for more details. Specifying a 3861219019Sgabornonexistent format causes an error. 3862219019Sgabor 3863219019SgaborThe following example produces @samp{10, X, j, 010}: 3864219019Sgabor 3865219019Sgabor@Example 3866219019Sgabor.nr a 10 3867219019Sgabor.af a 1 \" the default format 3868219019Sgabor\na, 3869219019Sgabor.af a I 3870219019Sgabor\na, 3871219019Sgabor.af a a 3872219019Sgabor\na, 3873219019Sgabor.af a 001 3874219019Sgabor\na 3875219019Sgabor@endExample 3876219019Sgabor 3877219019Sgabor@cindex Roman numerals, maximum and minimum 3878219019Sgabor@cindex maximum values of Roman numerals 3879219019Sgabor@cindex minimum values of Roman numerals 3880219019SgaborThe largest number representable for the @samp{i} and @samp{I} formats 3881219019Sgaboris 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 3882219019Sgaborand @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 3883219019Sgabor@code{gtroff}. Currently, the correct glyphs of Roman numeral five 3884219019Sgaborthousand and Roman numeral ten thousand (Unicode code points 3885219019Sgabor@code{U+2182} and @code{U+2181}, respectively) are not available. 3886219019Sgabor 3887219019SgaborIf @var{ident} doesn't exist, it is created. 3888219019Sgabor 3889219019Sgabor@cindex read-only register, changing format 3890219019Sgabor@cindex changing format, read-only register 3891219019SgaborChanging the output format of a read-only register causes an error. It 3892219019Sgaboris necessary to first copy the register's value to a writeable register, 3893219019Sgaborthen apply the @code{af} request to this other register. 3894219019Sgabor@endDefreq 3895219019Sgabor 3896219019Sgabor@cindex format of register 3897219019Sgabor@cindex register, format 3898219019Sgabor@Defesc {\\g, , i, } 3899219019Sgabor@Defescx {\\g, @lparen{}, id, } 3900219019Sgabor@Defescx {\\g, @lbrack{}, ident, @rbrack{}} 3901219019SgaborReturn the current format of the specified register @var{ident} 3902219019Sgabor(one-character name @var{i}, two-character name @var{id}). For 3903219019Sgaborexample, @samp{\ga} after the previous example would produce the 3904219019Sgaborstring @samp{000}. If the register hasn't been defined yet, nothing 3905219019Sgaboris returned. 3906219019Sgabor@endDefesc 3907219019Sgabor 3908219019Sgabor@c --------------------------------------------------------------------- 3909219019Sgabor 3910219019Sgabor@node Built-in Registers, , Assigning Formats, Registers 3911219019Sgabor@subsection Built-in Registers 3912219019Sgabor@cindex built-in registers 3913219019Sgabor@cindex registers, built-in 3914219019Sgabor 3915219019SgaborThe following lists some built-in registers which are not described 3916219019Sgaborelsewhere in this manual. Any register which begins with a @samp{.} is 3917219019Sgaborread-only. A complete listing of all built-in registers can be found in 3918219019Sgabor@ref{Register Index}. 3919219019Sgabor 3920219019Sgabor@table @code 3921219019Sgabor@item .H 3922219019Sgabor@cindex horizontal resolution register 3923219019Sgabor@cindex resolution, horizontal, register 3924219019Sgabor@vindex .H 3925219019SgaborHorizontal resolution in basic units. 3926219019Sgabor 3927219019Sgabor@item .V 3928219019Sgabor@cindex vertical resolution register 3929219019Sgabor@cindex resolution, vertical, register 3930219019Sgabor@vindex .V 3931219019SgaborVertical resolution in basic units. 3932219019Sgabor 3933219019Sgabor@item dw 3934219019Sgabor@cindex day of the week register 3935219019Sgabor@cindex date, day of the week register 3936219019Sgabor@vindex dw 3937219019SgaborDay of the week (1-7). 3938219019Sgabor 3939219019Sgabor@item dy 3940219019Sgabor@cindex day of the month register 3941219019Sgabor@cindex date, day of the month register 3942219019Sgabor@vindex dy 3943219019SgaborDay of the month (1-31). 3944219019Sgabor 3945219019Sgabor@item mo 3946219019Sgabor@cindex month of the year register 3947219019Sgabor@cindex date, month of the year register 3948219019Sgabor@vindex mo 3949219019SgaborCurrent month (1-12). 3950219019Sgabor 3951219019Sgabor@item year 3952219019Sgabor@cindex date, year register 3953219019Sgabor@cindex year, current, register 3954219019Sgabor@vindex year 3955219019SgaborThe current year. 3956219019Sgabor 3957219019Sgabor@item yr 3958219019Sgabor@vindex yr 3959219019SgaborThe current year minus@w{ }1900. Unfortunately, the documentation of 3960219019Sgabor@acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It 3961219019Sgaborincorrectly claimed that @code{yr} contains the last two digits of the 3962219019Sgaboryear. That claim has never been true of either traditional @code{troff} 3963219019Sgaboror GNU @code{troff}. Old @code{troff} input that looks like this: 3964219019Sgabor 3965219019Sgabor@Example 3966219019Sgabor'\" The following line stopped working after 1999 3967219019SgaborThis document was formatted in 19\n(yr. 3968219019Sgabor@endExample 3969219019Sgabor 3970219019Sgabor@noindent 3971219019Sgaborcan be corrected as follows: 3972219019Sgabor 3973219019Sgabor@Example 3974219019SgaborThis document was formatted in \n[year]. 3975219019Sgabor@endExample 3976219019Sgabor 3977219019Sgabor@noindent 3978219019Sgaboror, to be portable to older @code{troff} versions, as follows: 3979219019Sgabor 3980219019Sgabor@Example 3981219019Sgabor.nr y4 1900+\n(yr 3982219019SgaborThis document was formatted in \n(y4. 3983219019Sgabor@endExample 3984219019Sgabor 3985219019Sgabor@item .c 3986219019Sgabor@vindex .c 3987219019Sgabor@itemx c. 3988219019Sgabor@vindex c. 3989219019Sgabor@cindex input line number register 3990219019Sgabor@cindex line number, input, register 3991219019SgaborThe current @emph{input} line number. Register @samp{.c} is read-only, 3992219019Sgaborwhereas @samp{c.} (a @code{gtroff} extension) is writable also, 3993219019Sgaboraffecting both @samp{.c} and @samp{c.}. 3994219019Sgabor 3995219019Sgabor@item ln 3996219019Sgabor@vindex ln 3997219019Sgabor@rqindex nm 3998219019Sgabor@cindex output line number register 3999219019Sgabor@cindex line number, output, register 4000219019SgaborThe current @emph{output} line number after a call to the @code{nm} 4001219019Sgaborrequest to activate line numbering. 4002219019Sgabor 4003219019Sgabor@xref{Miscellaneous}, for more information about line numbering. 4004219019Sgabor 4005219019Sgabor@item .x 4006219019Sgabor@vindex .x 4007219019Sgabor@cindex major version number register 4008219019Sgabor@cindex version number, major, register 4009219019SgaborThe major version number. For example, if the version number is@w{ 4010219019Sgabor}1.03 then @code{.x} contains@w{ }@samp{1}. 4011219019Sgabor 4012219019Sgabor@item .y 4013219019Sgabor@vindex .y 4014219019Sgabor@cindex minor version number register 4015219019Sgabor@cindex version number, minor, register 4016219019SgaborThe minor version number. For example, if the version number is@w{ 4017219019Sgabor}1.03 then @code{.y} contains@w{ }@samp{03}. 4018219019Sgabor 4019219019Sgabor@item .Y 4020219019Sgabor@vindex .Y 4021219019Sgabor@cindex revision number register 4022219019SgaborThe revision number of @code{groff}. 4023219019Sgabor 4024219019Sgabor@item .g 4025219019Sgabor@vindex .g 4026219019Sgabor@cindex @code{gtroff} identification register 4027219019Sgabor@cindex GNU-specific register 4028219019SgaborAlways@w{ }1. Macros should use this to determine whether they are 4029219019Sgaborrunning under GNU @code{troff}. 4030219019Sgabor 4031219019Sgabor@item .A 4032219019Sgabor@vindex .A 4033219019Sgabor@cindex @acronym{ASCII} approximation output register 4034219019SgaborIf the command line option @option{-a} is used to produce an 4035219019Sgabor@acronym{ASCII} approximation of the output, this is set to@w{ }1, zero 4036219019Sgaborotherwise. @xref{Groff Options}. 4037219019Sgabor 4038219019Sgabor@item .P 4039219019Sgabor@vindex .P 4040219019SgaborThis register is set to@w{ }1 (and to@w{ }0 otherwise) if the current 4041219019Sgaborpage is actually being printed, i.e., if the @option{-o} option is being 4042219019Sgaborused to only print selected pages. @xref{Groff Options}, for more 4043219019Sgaborinformation. 4044219019Sgabor 4045219019Sgabor@item .T 4046219019Sgabor@vindex .T 4047219019SgaborIf @code{gtroff} is called with the @option{-T} command line option, the 4048219019Sgabornumber register @code{.T} is set to@w{ }1, and zero otherwise. 4049219019Sgabor@xref{Groff Options}. 4050219019Sgabor 4051219019Sgabor@stindex .T 4052219019Sgabor@cindex output device register 4053219019SgaborAdditionally, @code{gtroff} predefines a single read-write string 4054219019Sgaborregister @code{.T} which contains the current output device (for 4055219019Sgaborexample, @samp{latin1} or @samp{ps}). 4056219019Sgabor@end table 4057219019Sgabor 4058219019Sgabor 4059219019Sgabor@c ===================================================================== 4060219019Sgabor 4061219019Sgabor@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 4062219019Sgabor@section Manipulating Filling and Adjusting 4063219019Sgabor@cindex manipulating filling and adjusting 4064219019Sgabor@cindex filling and adjusting, manipulating 4065219019Sgabor@cindex adjusting and filling, manipulating 4066219019Sgabor@cindex justifying text 4067219019Sgabor@cindex text, justifying 4068219019Sgabor 4069219019Sgabor@cindex break 4070219019Sgabor@cindex line break 4071219019Sgabor@rqindex bp 4072219019Sgabor@rqindex ce 4073219019Sgabor@rqindex cf 4074219019Sgabor@rqindex fi 4075219019Sgabor@rqindex fl 4076219019Sgabor@rqindex in 4077219019Sgabor@rqindex nf 4078219019Sgabor@rqindex rj 4079219019Sgabor@rqindex sp 4080219019Sgabor@rqindex ti 4081219019Sgabor@rqindex trf 4082219019SgaborVarious ways of causing @dfn{breaks} were given in @ref{Implicit Line 4083219019SgaborBreaks}. The @code{br} request likewise causes a break. Several 4084219019Sgaborother requests also cause breaks, but implicitly. These are 4085219019Sgabor@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 4086219019Sgabor@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 4087219019Sgabor 4088219019Sgabor@Defreq {br, } 4089219019SgaborBreak the current line, i.e., the input collected so far is emitted 4090219019Sgaborwithout adjustment. 4091219019Sgabor 4092219019SgaborIf the no-break control character is used, @code{gtroff} suppresses 4093219019Sgaborthe break: 4094219019Sgabor 4095219019Sgabor@Example 4096219019Sgabora 4097219019Sgabor'br 4098219019Sgaborb 4099219019Sgabor @result{} a b 4100219019Sgabor@endExample 4101219019Sgabor@endDefreq 4102219019Sgabor 4103219019SgaborInitially, @code{gtroff} fills and adjusts text to both margins. 4104219019SgaborFilling can be disabled via the @code{nf} request and re-enabled with 4105219019Sgaborthe @code{fi} request. 4106219019Sgabor 4107219019Sgabor@cindex fill mode 4108219019Sgabor@cindex mode, fill 4109219019Sgabor@Defreq {fi, } 4110219019Sgabor@Defregx {.u} 4111219019SgaborActivate fill mode (which is the default). This request implicitly 4112219019Sgaborenables adjusting; it also inserts a break in the text currently being 4113219019Sgaborfilled. The read-only number register @code{.u} is set to@w{ }1. 4114219019Sgabor 4115219019SgaborThe fill mode status is associated with the current environment 4116219019Sgabor(@pxref{Environments}). 4117219019Sgabor@endDefreq 4118219019Sgabor 4119219019Sgabor@cindex no-fill mode 4120219019Sgabor@cindex mode, no-fill 4121219019Sgabor@Defreq {nf, } 4122219019SgaborActivate no-fill mode. Input lines are output as-is, retaining line 4123219019Sgaborbreaks and ignoring the current line length. This command implicitly 4124219019Sgabordisables adjusting; it also causes a break. The number register 4125219019Sgabor@code{.u} is set to@w{ }0. 4126219019Sgabor 4127219019SgaborThe fill mode status is associated with the current environment 4128219019Sgabor(@pxref{Environments}). 4129219019Sgabor@endDefreq 4130219019Sgabor 4131219019Sgabor@Defreq {ad, [@Var{mode}]} 4132219019Sgabor@Defregx {.j} 4133219019SgaborSet adjusting mode. 4134219019Sgabor 4135219019SgaborActivation and deactivation of adjusting is done implicitly with 4136219019Sgaborcalls to the @code{fi} or @code{nf} requests. 4137219019Sgabor 4138219019Sgabor@var{mode} can have one of the following values: 4139219019Sgabor 4140219019Sgabor@table @code 4141219019Sgabor@item l 4142219019Sgabor@cindex ragged-right 4143219019SgaborAdjust text to the left margin. This produces what is traditionally 4144219019Sgaborcalled ragged-right text. 4145219019Sgabor 4146219019Sgabor@item r 4147219019Sgabor@cindex ragged-left 4148219019SgaborAdjust text to the right margin, producing ragged-left text. 4149219019Sgabor 4150219019Sgabor@item c 4151219019Sgabor@cindex centered text 4152219019Sgabor@rqindex ce 4153219019SgaborCenter filled text. This is different to the @code{ce} request which 4154219019Sgaboronly centers text without filling. 4155219019Sgabor 4156219019Sgabor@item b 4157219019Sgabor@itemx n 4158219019SgaborJustify to both margins. This is the default used by @code{gtroff}. 4159219019Sgabor@end table 4160219019Sgabor 4161219019SgaborWith no argument, @code{gtroff} adjusts lines in the same way it did 4162219019Sgaborbefore adjusting was deactivated (with a call to @code{na}, for 4163219019Sgaborexample). 4164219019Sgabor 4165219019Sgabor@Example 4166219019Sgabortext 4167219019Sgabor.ad r 4168219019Sgabortext 4169219019Sgabor.ad c 4170219019Sgabortext 4171219019Sgabor.na 4172219019Sgabortext 4173219019Sgabor.ad \" back to centering 4174219019Sgabortext 4175219019Sgabor@endExample 4176219019Sgabor 4177219019Sgabor@cindex current adjustment mode register 4178219019SgaborThe current adjustment mode is available in the read-only number 4179219019Sgaborregister @code{.j}; it can be stored and subsequently used to set 4180219019Sgaboradjustment. 4181219019Sgabor 4182219019SgaborThe adjustment mode status is associated with the current environment 4183219019Sgabor(@pxref{Environments}). 4184219019Sgabor@endDefreq 4185219019Sgabor 4186219019Sgabor@Defreq {na, } 4187219019SgaborDisable adjusting. This request won't change the current adjustment 4188219019Sgabormode: A subsequent call to @code{ad} uses the previous adjustment 4189219019Sgaborsetting. 4190219019Sgabor 4191219019SgaborThe adjustment mode status is associated with the current environment 4192219019Sgabor(@pxref{Environments}). 4193219019Sgabor@endDefreq 4194219019Sgabor 4195219019Sgabor@Defesc {\\p, , , } 4196219019SgaborAdjust the current line and cause a break. 4197219019Sgabor 4198219019SgaborIn most cases this produces very ugly results, since @code{gtroff} 4199219019Sgabordoesn't have a sophisticated paragraph building algorithm (as @TeX{} 4200219019Sgaborhave, for example); instead, @code{gtroff} fills and adjusts a paragraph 4201219019Sgaborline by line: 4202219019Sgabor 4203219019Sgabor@Example 4204219019Sgabor This is an uninteresting sentence. 4205219019Sgabor This is an uninteresting sentence.\p 4206219019Sgabor This is an uninteresting sentence. 4207219019Sgabor@endExample 4208219019Sgabor 4209219019Sgabor@noindent 4210219019Sgaboris formatted as 4211219019Sgabor 4212219019Sgabor@Example 4213219019Sgabor This is an uninteresting sentence. This is an 4214219019Sgabor uninteresting sentence. 4215219019Sgabor This is an uninteresting sentence. 4216219019Sgabor@endExample 4217219019Sgabor@endDefesc 4218219019Sgabor 4219219019Sgabor@cindex word space size 4220219019Sgabor@cindex size of word space 4221219019Sgabor@cindex space between words 4222219019Sgabor@cindex sentence space size 4223219019Sgabor@cindex size of sentence space 4224219019Sgabor@cindex space between sentences 4225219019Sgabor@Defreq {ss, word_space_size [@Var{sentence_space_size}]} 4226219019Sgabor@Defregx {.ss} 4227219019Sgabor@Defregx {.sss} 4228219019SgaborChange the minimum size of a space between filled words. It takes its 4229219019Sgaborunits as one twelfth of the space width parameter for the current 4230219019Sgaborfont. Initially both the @var{word_space_size} and 4231219019Sgabor@var{sentence_space_size} are@w{ }12. 4232219019Sgabor 4233219019Sgabor@cindex fill mode 4234219019Sgabor@cindex mode, fill 4235219019SgaborIf two arguments are given to the @code{ss} request, the second 4236219019Sgaborargument sets the sentence space size. If the second argument is not 4237219019Sgaborgiven, sentence space size is set to @var{word_space_size}. The 4238219019Sgaborsentence space size is used in two circumstances: If the end of a 4239219019Sgaborsentence occurs at the end of a line in fill mode, then both an 4240219019Sgaborinter-word space and a sentence space are added; if two spaces follow 4241219019Sgaborthe end of a sentence in the middle of a line, then the second space 4242219019Sgaboris a sentence space. If a second argument is never given to the 4243219019Sgabor@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 4244219019Sgaborsame as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 4245219019Sgaborin @acronym{UNIX} @code{troff}, a sentence should always be followed 4246219019Sgaborby either a newline or two spaces. 4247219019Sgabor 4248219019SgaborThe read-only number registers @code{.ss} and @code{.sss} hold the 4249219019Sgaborvalues of the parameters set by the first and second arguments of the 4250219019Sgabor@code{ss} request. 4251219019Sgabor 4252219019SgaborThe word space and sentence space values are associated with the current 4253219019Sgaborenvironment (@pxref{Environments}). 4254219019Sgabor 4255219019SgaborContrary to traditional Unix @code{troff}, this request is @emph{not} 4256219019Sgaborignored if a tty output device is used; the given values are then 4257219019Sgaborrounded down to a multiple of@w{ }12. 4258219019Sgabor 4259219019Sgabor@c XXX xref implementation differences 4260219019Sgabor 4261219019SgaborThe request is ignored if there is no parameter. 4262219019Sgabor@endDefreq 4263219019Sgabor 4264219019Sgabor@cindex centering lines 4265219019Sgabor@cindex lines, centering 4266219019Sgabor@Defreq {ce, [@Var{nnn}]} 4267219019Sgabor@Defregx {.ce} 4268219019SgaborCenter text. While the @w{@samp{.ad c}} request also centers text, 4269219019Sgaborit fills the text as well. @code{ce} does not fill the 4270219019Sgabortext it affects. This request causes a break. 4271219019Sgabor 4272219019SgaborThe following example demonstrates the differences. 4273219019SgaborHere the input: 4274219019Sgabor 4275219019Sgabor@Example 4276219019Sgabor.ll 4i 4277219019Sgabor.ce 1000 4278219019SgaborThis is a small text fragment which shows the differences 4279219019Sgaborbetween the `.ce' and the `.ad c' request. 4280219019Sgabor.ce 0 4281219019Sgabor 4282219019Sgabor.ad c 4283219019SgaborThis is a small text fragment which shows the differences 4284219019Sgaborbetween the `.ce' and the `.ad c' request. 4285219019Sgabor@endExample 4286219019Sgabor 4287219019Sgabor@noindent 4288219019SgaborAnd here the result: 4289219019Sgabor 4290219019Sgabor@Example 4291219019Sgabor This is a small text fragment which 4292219019Sgabor shows the differences 4293219019Sgaborbetween the `.ce' and the `.ad c' request. 4294219019Sgabor 4295219019Sgabor This is a small text fragment which 4296219019Sgaborshows the differences between the `.ce' 4297219019Sgabor and the `.ad c' request. 4298219019Sgabor@endExample 4299219019Sgabor 4300219019SgaborWith no arguments, @code{ce} centers the next line of text. @var{nnn} 4301219019Sgaborspecifies the number of lines to be centered. If the argument is zero 4302219019Sgaboror negative, centering is disabled. 4303219019Sgabor 4304219019Sgabor@rqindex ll 4305219019Sgabor@rqindex in 4306219019Sgabor@rqindex ti 4307219019SgaborThe basic length for centering text is the line length (as set with the 4308219019Sgabor@code{ll} request) minus the indentation (as set with the @code{in} 4309219019Sgaborrequest). Temporary indentation is ignored. 4310219019Sgabor 4311219019SgaborAs can be seen in the previous example, it is a common idiom to turn 4312219019Sgaboron centering for a large number of lines, and to turn off centering 4313219019Sgaborafter text to be centered. This is useful for any request which takes 4314219019Sgabora number of lines as an argument. 4315219019Sgabor 4316219019SgaborThe @code{.ce} read-only number register contains the number of lines 4317219019Sgaborremaining to be centered, as set by the @code{ce} request. 4318219019Sgabor@endDefreq 4319219019Sgabor 4320219019Sgabor@cindex justifying text 4321219019Sgabor@cindex text, justifying 4322219019Sgabor@cindex right-justifying 4323219019Sgabor@Defreq {rj, [@Var{nnn}]} 4324219019Sgabor@Defregx {.rj} 4325219019SgaborJustify unfilled text to the right margin. Arguments are identical to 4326219019Sgaborthe @code{ce} request. The @code{.rj} read-only number register is 4327219019Sgaborthe number of lines to be right-justified as set by the @code{rj} 4328219019Sgaborrequest. This request causes a break. 4329219019Sgabor@endDefreq 4330219019Sgabor 4331219019Sgabor 4332219019Sgabor@c ===================================================================== 4333219019Sgabor 4334219019Sgabor@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 4335219019Sgabor@section Manipulating Hyphenation 4336219019Sgabor@cindex manipulating hyphenation 4337219019Sgabor@cindex hyphenation, manipulating 4338219019Sgabor 4339219019SgaborAs discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words. 4340219019SgaborThere are a number of ways to influence hyphenation. 4341219019Sgabor 4342219019Sgabor@Defreq {hy, [@Var{mode}]} 4343219019Sgabor@Defregx {.hy} 4344219019SgaborEnable hyphenation. The request has an optional numeric argument, 4345219019Sgabor@var{mode}, to restrict hyphenation if necessary: 4346219019Sgabor 4347219019Sgabor@table @code 4348219019Sgabor@item 1 4349219019SgaborThe default argument if @var{mode} is omitted. Hyphenate without 4350219019Sgaborrestrictions. This is also the start-up value of @code{gtroff}. 4351219019Sgabor 4352219019Sgabor@item 2 4353219019SgaborDo not hyphenate the last word on a page or column. 4354219019Sgabor 4355219019Sgabor@item 4 4356219019SgaborDo not hyphenate the last two characters of a word. 4357219019Sgabor 4358219019Sgabor@item 8 4359219019SgaborDo not hyphenate the first two characters of a word. 4360219019Sgabor@end table 4361219019Sgabor 4362219019SgaborValues in the previous table are additive. For example, the value@w{ 4363219019Sgabor}12 causes @code{gtroff} to neither hyphenate the last two nor the first 4364219019Sgabortwo characters of a word. 4365219019Sgabor 4366219019Sgabor@cindex hyphenation restrictions register 4367219019SgaborThe current hyphenation restrictions can be found in the read-only 4368219019Sgabornumber register @samp{.hy}. 4369219019Sgabor 4370219019SgaborThe hyphenation mode is associated with the current environment 4371219019Sgabor(@pxref{Environments}). 4372219019Sgabor@endDefreq 4373219019Sgabor 4374219019Sgabor@Defreq {nh, } 4375219019SgaborDisable hyphenation (i.e., set the hyphenation mode to zero). Note 4376219019Sgaborthat the hyphenation mode of the last call to @code{hy} is not 4377219019Sgaborremembered. 4378219019Sgabor 4379219019SgaborThe hyphenation mode is associated with the current environment 4380219019Sgabor(@pxref{Environments}). 4381219019Sgabor@endDefreq 4382219019Sgabor 4383219019Sgabor@esindex \% 4384219019Sgabor@cindex explicit hyphens 4385219019Sgabor@cindex hyphen, explicit 4386219019Sgabor@cindex consecutive hyphenated lines 4387219019Sgabor@cindex lines, consecutive hyphenated 4388219019Sgabor@cindex hyphenated lines, consecutive 4389219019Sgabor@Defreq {hlm, [@Var{nnn}]} 4390219019Sgabor@Defregx {.hlm} 4391219019Sgabor@Defregx {.hlc} 4392219019SgaborSet the maximum number of consecutive hyphenated lines to @var{nnn}. 4393219019SgaborIf this number is negative, there is no maximum. The default value 4394219019Sgaboris@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated 4395219019Sgaborwith the current environment (@pxref{Environments}). Only lines 4396219019Sgaboroutput from a given environment count towards the maximum associated 4397219019Sgaborwith that environment. Hyphens resulting from @code{\%} are counted; 4398219019Sgaborexplicit hyphens are not. 4399219019Sgabor 4400219019SgaborThe current setting of @code{hlm} is available in the @code{.hlm} 4401219019Sgaborread-only number register. Also the number of immediately preceding 4402219019Sgaborconsecutive hyphenated lines are available in the read-only number 4403219019Sgaborregister @samp{.hlc}. 4404219019Sgabor@endDefreq 4405219019Sgabor 4406219019Sgabor@Defreq {hw, word1 word2 @dots{}} 4407219019SgaborDefine how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 4408219019Sgaborwords must be given with hyphens at the hyphenation points. For 4409219019Sgaborexample: 4410219019Sgabor 4411219019Sgabor@Example 4412219019Sgabor.hw in-sa-lub-rious 4413219019Sgabor@endExample 4414219019Sgabor 4415219019Sgabor@noindent 4416219019SgaborBesides the space character, any character whose hyphenation code value 4417219019Sgaboris zero can be used to separate the arguments of @code{hw} (see the 4418219019Sgabordocumentation for the @code{hcode} request below for more information). 4419219019SgaborIn addition, this request can be used more than once. 4420219019Sgabor 4421219019SgaborHyphenation exceptions specified with the @code{hw} request are 4422219019Sgaborassociated with the current hyphenation language; it causes an error 4423219019Sgaborif there is no current hyphenation language. 4424219019Sgabor 4425219019SgaborThis request is ignored if there is no parameter. 4426219019Sgabor 4427219019SgaborIn old versions of @code{troff} there was a limited amount of space to 4428219019Sgaborstore such information; fortunately, with @code{gtroff}, this is no 4429219019Sgaborlonger a restriction. 4430219019Sgabor@endDefreq 4431219019Sgabor 4432219019Sgabor@cindex hyphenation character 4433219019Sgabor@cindex character, hyphenation 4434219019Sgabor@cindex disabling hyphenation 4435219019Sgabor@cindex hyphenation, disabling 4436219019Sgabor@Defesc {\\%, , , } 4437219019SgaborTo tell @code{gtroff} how to hyphenate words on the fly, use the 4438219019Sgabor@code{\%} escape, also known as the @dfn{hyphenation character}. 4439219019SgaborPreceding a word with this character prevents it from being 4440219019Sgaborhyphenated; putting it inside a word indicates to @code{gtroff} that 4441219019Sgaborthe word may be hyphenated at that point. Note that this mechanism 4442219019Sgaboronly affects that one occurrence of the word; to change the 4443219019Sgaborhyphenation of a word for the entire document, use the @code{hw} 4444219019Sgaborrequest. 4445219019Sgabor@endDefesc 4446219019Sgabor 4447219019Sgabor@Defreq {hc, [@Var{char}]} 4448219019SgaborChange the hyphenation character to @var{char}. This character then 4449219019Sgaborworks the same as the @code{\%} escape, and thus, no longer appears in 4450219019Sgaborthe output. Without an argument, @code{hc} resets the hyphenation 4451219019Sgaborcharacter to be @code{\%} (the default) only. 4452219019Sgabor 4453219019SgaborThe hyphenation character is associated with the current environment 4454219019Sgabor(@pxref{Environments}). 4455219019Sgabor@endDefreq 4456219019Sgabor 4457219019Sgabor@cindex hyphenation patterns 4458219019Sgabor@cindex patterns for hyphenation 4459219019Sgabor@Defreq {hpf, pattern_file} 4460219019SgaborRead in a file of hyphenation patterns. This file is searched for in 4461219019Sgaborthe same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 4462219019Sgaborsearched for if the @option{-m@var{name}} option is specified. 4463219019Sgabor 4464219019SgaborIt should have the same format as the argument to the @code{\patterns} 4465219019Sgaborprimitive in @TeX{} (without using @TeX{}'s macro expansion); the 4466219019Sgaborletters appearing in this file are interpreted as hyphenation codes. A 4467219019Sgabor@samp{%} character in the patterns file introduces a comment that 4468219019Sgaborcontinues to the end of the line. 4469219019Sgabor 4470219019SgaborIf no @code{hpf} request is specified (either in the document or in a 4471219019Sgabormacro package), @code{gtroff} won't hyphenate at all. 4472219019Sgabor 4473219019Sgabor@rqindex hla 4474219019Sgabor@pindex troffrc 4475219019Sgabor@pindex troffrc-end 4476219019Sgabor@pindex hyphen.us 4477219019SgaborThe set of hyphenation patterns is associated with the current language 4478219019Sgaborset by the @code{hla} request. The @code{hpf} request is usually 4479219019Sgaborinvoked by the @file{troffrc} or @file{troffrc-end} file; by default, 4480219019Sgabor@file{troffrc} loads hyphenation patterns for American English (in file 4481219019Sgabor@file{hyphen.us}). 4482219019Sgabor 4483219019SgaborInvoking @code{hpf} causes an error if there is no current hyphenation 4484219019Sgaborlanguage. 4485219019Sgabor@endDefreq 4486219019Sgabor 4487219019Sgabor@cindex hyphenation code 4488219019Sgabor@cindex code, hyphenation 4489219019Sgabor@Defreq {hcode, c1 code1 c2 code2 @dots{}} 4490219019SgaborSet the hyphenation code of character @var{c1} to @var{code1}, that of 4491219019Sgabor@var{c2} to @var{code2}, etc. A hyphenation code must be a single 4492219019Sgaborinput character (not a special character) other than a digit or a 4493219019Sgaborspace. Initially each lower-case letter (@samp{a}-@samp{z}) has its 4494219019Sgaborhyphenation set to itself, and each upper-case letter 4495219019Sgabor(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case 4496219019Sgaborversion of itself. 4497219019Sgabor 4498219019SgaborThis request is ignored if it has no parameter. 4499219019Sgabor@endDefreq 4500219019Sgabor 4501219019Sgabor@cindex hyphenation margin 4502219019Sgabor@cindex margin for hyphenation 4503219019Sgabor@rqindex ad 4504219019Sgabor@Defreq {hym, [@Var{length}]} 4505219019Sgabor@Defregx {.hym} 4506219019SgaborSet the (right) hyphenation margin to @var{length}. If the current 4507219019Sgaboradjustment mode is not @samp{b} or@w{ }@samp{n}, the line is not 4508219019Sgaborhyphenated if it is shorter than @var{length}. Without an argument, 4509219019Sgaborthe hyphenation margin is reset to its default value, which is@w{ }0. 4510219019SgaborThe default scaling indicator for this request is@w{ }@code{m}. The 4511219019Sgaborhyphenation margin is associated with the current environment 4512219019Sgabor(@pxref{Environments}). 4513219019Sgabor 4514219019SgaborA negative argument resets the hyphenation margin to zero, emitting 4515219019Sgabora warning of type @samp{range}. 4516219019Sgabor 4517219019Sgabor@cindex current hyphenation margin register 4518219019SgaborThe current hyphenation margin is available in the @code{.hym} read-only 4519219019Sgabornumber register. 4520219019Sgabor@endDefreq 4521219019Sgabor 4522219019Sgabor@cindex hyphenation space 4523219019Sgabor@rqindex ad 4524219019Sgabor@Defreq {hys, [@Var{hyphenation_space}]} 4525219019Sgabor@Defregx {.hys} 4526219019SgaborSet the hyphenation space to @var{hyphenation_space}. If the current 4527219019Sgaboradjustment mode is @samp{b} or@w{ }@samp{n}, don't hyphenate the line 4528219019Sgaborif it can be justified by adding no more than @var{hyphenation_space} 4529219019Sgaborextra space to each word space. Without argument, the hyphenation 4530219019Sgaborspace is set to its default value, which is@w{ }0. The default 4531219019Sgaborscaling indicator for this request is@w{ }@code{m}. The hyphenation 4532219019Sgaborspace is associated with the current environment 4533219019Sgabor(@pxref{Environments}). 4534219019Sgabor 4535219019SgaborA negative argument resets the hyphenation space to zero, emitting a 4536219019Sgaborwarning of type @samp{range}. 4537219019Sgabor 4538219019Sgabor@cindex current hyphenation space register 4539219019SgaborThe current hyphenation space is available in the @code{.hys} read-only 4540219019Sgabornumber register. 4541219019Sgabor@endDefreq 4542219019Sgabor 4543219019Sgabor@cindex soft hyphen character 4544219019Sgabor@cindex character, soft hyphen 4545219019Sgabor@glindex hy 4546219019Sgabor@rqindex char 4547219019Sgabor@rqindex tr 4548219019Sgabor@Defreq {shc, [@Var{char}]} 4549219019SgaborSet the soft hyphen character to @var{char}. If the argument is 4550219019Sgaboromitted, the soft hyphen character is set to the default character 4551219019Sgabor@code{\(hy} (this is the start-up value of @code{gtroff} also). The 4552219019Sgaborsoft hyphen character is the character that is inserted when a word is 4553219019Sgaborhyphenated at a line break. If the soft hyphen character does not 4554219019Sgaborexist in the font of the character immediately preceding a potential 4555219019Sgaborbreak point, then the line is not broken at that point. Neither 4556219019Sgabordefinitions (specified with the @code{char} request) nor translations 4557219019Sgabor(specified with the @code{tr} request) are considered when finding the 4558219019Sgaborsoft hyphen character. 4559219019Sgabor@endDefreq 4560219019Sgabor 4561219019Sgabor@rqindex hpf 4562219019Sgabor@rqindex hw 4563219019Sgabor@pindex troffrc 4564219019Sgabor@pindex troffrc-end 4565219019Sgabor@Defreq {hla, language} 4566219019Sgabor@Defregx {.hla} 4567219019SgaborSet the current hyphenation language to the string @var{language}. 4568219019SgaborHyphenation exceptions specified with the @code{hw} request and 4569219019Sgaborhyphenation patterns specified with the @code{hpf} request are both 4570219019Sgaborassociated with the current hyphenation language. The @code{hla} 4571219019Sgaborrequest is usually invoked by the @file{troffrc} or the 4572219019Sgabor@file{troffrc-end} files; @file{troffrc} sets the default language to 4573219019Sgabor@samp{us}. 4574219019Sgabor 4575219019Sgabor@cindex current hyphenation language register 4576219019SgaborThe current hyphenation language is available as a string in the 4577219019Sgaborread-only number register @samp{.hla}. 4578219019Sgabor 4579219019Sgabor@Example 4580219019Sgabor.ds curr_language \n[.hla] 4581219019Sgabor\*[curr_language] 4582219019Sgabor @result{} us 4583219019Sgabor@endExample 4584219019Sgabor@endDefreq 4585219019Sgabor 4586219019Sgabor 4587219019Sgabor@c ===================================================================== 4588219019Sgabor 4589219019Sgabor@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 4590219019Sgabor@section Manipulating Spacing 4591219019Sgabor@cindex manipulating spacing 4592219019Sgabor@cindex spacing, manipulating 4593219019Sgabor 4594219019Sgabor@Defreq {sp, [@Var{distance}]} 4595219019SgaborSpace downwards @var{distance}. With no argument it advances 1@w{ 4596219019Sgabor}line. A negative argument causes @code{gtroff} to move up the page 4597219019Sgaborthe specified distance. If the argument is preceded by a @samp{|} 4598219019Sgaborthen @code{gtroff} moves that distance from the top of the page. This 4599219019Sgaborrequest causes a line break. The default scaling indicator is@w{ 4600219019Sgabor}@code{v}. 4601219019Sgabor@endDefreq 4602219019Sgabor 4603219019Sgabor@cindex double-spacing 4604219019Sgabor@Defreq {ls, [@Var{nnn}]} 4605219019Sgabor@Defregx {.L} 4606219019SgaborOutput @w{@var{nnn}@minus{}1} blank lines after each line of text. 4607219019SgaborWith no argument, @code{gtroff} uses the previous value before the 4608219019Sgaborlast @code{ls} call. 4609219019Sgabor 4610219019Sgabor@Example 4611219019Sgabor.ls 2 \" This causes double-spaced output 4612219019Sgabor.ls 3 \" This causes triple-spaced output 4613219019Sgabor.ls \" Again double spaced 4614219019Sgabor@endExample 4615219019Sgabor 4616219019SgaborThe line spacing is associated with the current environment 4617219019Sgabor(@pxref{Environments}). 4618219019Sgabor 4619219019Sgabor@cindex current line spacing register 4620219019SgaborThe read-only number register @code{.L} contains the current line 4621219019Sgaborspacing setting. 4622219019Sgabor@endDefreq 4623219019Sgabor 4624219019Sgabor@c XXX document \n[nl] 4625219019Sgabor@c XXX document \n[nl] == -1 if vertical position is zero 4626219019Sgabor 4627219019Sgabor@Defesc {\\x, ', spacing, '} 4628219019Sgabor@Defregx {.a} 4629219019SgaborSometimes, extra vertical spacing is only needed occasionally, e.g.@: 4630219019Sgaborto allow space for a tall construct (like an equation). The @code{\x} 4631219019Sgaborescape does this. The escape is given a numerical argument, usually 4632219019Sgaborenclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 4633219019Sgaboris@w{ }@code{v}. If this number is positive extra vertical space is 4634219019Sgaborinserted below the current line. A negative number adds space above. 4635219019SgaborIf this escape is used multiple times on the same line, the maximum of 4636219019Sgaborthe values is used. 4637219019Sgabor 4638219019Sgabor@xref{Escapes}, for details on parameter delimiting characters. 4639219019Sgabor 4640219019Sgabor@cindex extra vertical line space register 4641219019SgaborThe @code{.a} read-only number register contains the most recent 4642219019Sgabor(nonnegative) extra vertical line space. 4643219019Sgabor 4644219019Sgabor@c XXX 4645219019Sgabor@ignore 4646219019Sgabor@Example 4647219019Sgabor... example of inline equation ... 4648219019Sgabor@endExample 4649219019Sgabor@end ignore 4650219019Sgabor@endDefesc 4651219019Sgabor 4652219019Sgabor@rqindex sp 4653219019Sgabor@cindex no-space mode 4654219019Sgabor@cindex mode, no-space 4655219019Sgabor@cindex blank lines, disabling 4656219019Sgabor@cindex lines, blank, disabling 4657219019Sgabor@Defreq {ns, } 4658219019Sgabor@Defregx {.ns} 4659219019SgaborEnable @dfn{no-space mode}. In this mode, spacing (either via 4660219019Sgabor@code{sp} or via blank lines) is disabled. The @code{bp} request to 4661219019Sgaboradvance to the next page is also disabled, except if it is accompanied 4662219019Sgaborby a page number (see @ref{Page Control}, for more information). This 4663219019Sgabormode ends when actual text is output or the @code{rs} request is 4664219019Sgaborencountered. The read-only number register @code{.ns} is set to@w{ }1. 4665219019Sgabor 4666219019SgaborThis request is useful for macros which want to avoid that subsequent 4667219019Sgabormacros inadvertently insert some vertical space before the text starts 4668219019Sgabor(for example, to set up the first paragraph after a section header). 4669219019Sgabor 4670219019Sgabor@c XXX xref 4671219019Sgabor@endDefreq 4672219019Sgabor 4673219019Sgabor@Defreq {rs, } 4674219019SgaborDisable no-space mode. 4675219019Sgabor 4676219019Sgabor@c XXX xref 4677219019Sgabor@endDefreq 4678219019Sgabor 4679219019Sgabor 4680219019Sgabor@c ===================================================================== 4681219019Sgabor 4682219019Sgabor@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 4683219019Sgabor@section Tabs and Fields 4684219019Sgabor@cindex tabs and fields 4685219019Sgabor@cindex fields and tabs 4686219019Sgabor 4687219019Sgabor@cindex @acronym{EBCDIC} encoding of a tab 4688219019SgaborA tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{ 4689219019Sgabor}5) causes a horizontal movement to the next tab stop (much 4690219019Sgaborlike it did on a typewriter). 4691219019Sgabor 4692219019Sgabor@Defesc {\\t, , , } 4693219019SgaborThis escape is a non-interpreted tab character. In copy mode 4694219019Sgabor(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 4695219019Sgabor@endDefesc 4696219019Sgabor 4697219019Sgabor@Defreq {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 4698219019Sgabor@Defregx {.tabs} 4699219019SgaborChange tab stop positions. This request takes a series of tab 4700219019Sgaborspecifiers as arguments (optionally divided into two groups with the 4701219019Sgaborletter @samp{T}) which indicate where each tab stop is to be 4702219019Sgabor(overriding any previous settings). 4703219019Sgabor 4704219019SgaborTab stops can be specified absolutely, i.e., as the distance from the 4705219019Sgaborleft margin. For example, the following sets 6@w{ }tab stops every 4706219019Sgaborone inch. 4707219019Sgabor 4708219019Sgabor@Example 4709219019Sgabor.ta 1i 2i 3i 4i 5i 6i 4710219019Sgabor@endExample 4711219019Sgabor 4712219019SgaborTab stops can also be specified using a leading @samp{+} 4713219019Sgaborwhich means that the specified tab stop is set relative to 4714219019Sgaborthe previous tab stop. For example, the following is equivalent to the 4715219019Sgaborprevious example. 4716219019Sgabor 4717219019Sgabor@Example 4718219019Sgabor.ta 1i +1i +1i +1i +1i +1i 4719219019Sgabor@endExample 4720219019Sgabor 4721219019Sgabor@code{gtroff} supports an extended syntax to specify repeat values after 4722219019Sgaborthe @samp{T} mark (these values are always taken as relative) -- this is 4723219019Sgaborthe usual way to specify tabs set at equal intervals. The following is, 4724219019Sgaboryet again, the same as the previous examples. It does even more since 4725219019Sgaborit defines an infinite number of tab stops separated by one inch. 4726219019Sgabor 4727219019Sgabor@Example 4728219019Sgabor.ta T 1i 4729219019Sgabor@endExample 4730219019Sgabor 4731219019SgaborNow we are ready to interpret the full syntax given at the beginning: 4732219019SgaborSet tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 4733219019Sgabortabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 4734219019Sgaborand then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 4735219019Sgabor@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 4736219019Sgabor 4737219019SgaborExample: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 4738219019Sgabor20c 23c 28c 30c @dots{}}. 4739219019Sgabor 4740219019SgaborThe material in each tab column (i.e., the column between two tab stops) 4741219019Sgabormay be justified to the right or left or centered in the column. This 4742219019Sgaboris specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 4743219019Sgaborspecifier. The default justification is @samp{L}. Example: 4744219019Sgabor 4745219019Sgabor@Example 4746219019Sgabor.ta 1i 2iC 2iR 4747219019Sgabor@endExample 4748219019Sgabor 4749219019SgaborSome notes: 4750219019Sgabor 4751219019Sgabor@itemize @bullet 4752219019Sgabor@item 4753219019SgaborThe default unit of the @code{ta} request is @samp{m}. 4754219019Sgabor 4755219019Sgabor@item 4756219019SgaborA tab stop is converted into a non-breakable horizontal movement which 4757219019Sgaborcan be neither stretched nor squeezed. For example, 4758219019Sgabor 4759219019Sgabor@Example 4760219019Sgabor.ds foo a\tb\tc 4761219019Sgabor.ta T 5i 4762219019Sgabor\*[foo] 4763219019Sgabor@endExample 4764219019Sgabor 4765219019Sgabor@noindent 4766219019Sgaborcreates a single line which is a bit longer than 10@w{ }inches (a string 4767219019Sgaboris used to show exactly where the tab characters are). Now consider the 4768219019Sgaborfollowing: 4769219019Sgabor 4770219019Sgabor@Example 4771219019Sgabor.ds bar a\tb b\tc 4772219019Sgabor.ta T 5i 4773219019Sgabor\*[bar] 4774219019Sgabor@endExample 4775219019Sgabor 4776219019Sgabor@noindent 4777219019Sgabor@code{gtroff} first converts the tab stops of the line into unbreakable 4778219019Sgaborhorizontal movements, then splits the line after the second @samp{b} 4779219019Sgabor(assuming a sufficiently short line length). Usually, this isn't what 4780219019Sgaborthe user wants. 4781219019Sgabor 4782219019Sgabor@item 4783219019SgaborSuperfluous tabs (i.e., tab characters which do not correspond to a tab 4784219019Sgaborstop) are ignored except the first one which delimits the characters 4785219019Sgaborbelonging to the last tab stop for right-justifying or centering. 4786219019SgaborConsider the following example 4787219019Sgabor 4788219019Sgabor@Example 4789219019Sgabor.ds Z foo\tbar\tfoo 4790219019Sgabor.ds ZZ foo\tbar\tfoobar 4791219019Sgabor.ds ZZZ foo\tbar\tfoo\tbar 4792219019Sgabor.ta 2i 4iR 4793219019Sgabor\*[Z] 4794219019Sgabor.br 4795219019Sgabor\*[ZZ] 4796219019Sgabor.br 4797219019Sgabor\*[ZZZ] 4798219019Sgabor.br 4799219019Sgabor@endExample 4800219019Sgabor 4801219019Sgabor@noindent 4802219019Sgaborwhich produces the following output: 4803219019Sgabor 4804219019Sgabor@Example 4805219019Sgaborfoo bar foo 4806219019Sgaborfoo bar foobar 4807219019Sgaborfoo bar foobar 4808219019Sgabor@endExample 4809219019Sgabor 4810219019Sgabor@noindent 4811219019SgaborThe first line right-justifies the second `foo' relative to the tab 4812219019Sgaborstop. The second line right-justifies `foobar'. The third line finally 4813219019Sgaborright-justifies only `foo' because of the additional tab character which 4814219019Sgabormarks the end of the string belonging to the last defined tab stop. 4815219019Sgabor 4816219019Sgabor@item 4817219019SgaborTab stops are associated with the current environment 4818219019Sgabor(@pxref{Environments}). 4819219019Sgabor 4820219019Sgabor@item 4821219019SgaborCalling @code{ta} without an argument removes all tab stops. 4822219019Sgabor 4823219019Sgabor@item 4824219019Sgabor@cindex tab stops, for tty output devices 4825219019SgaborThe start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. This value 4826219019Sgaboris used even for tty output devices (contrary to @acronym{UNIX} 4827219019Sgabor@code{nroff} which has tab stops preset every 0.8@dmn{i}). 4828219019Sgabor 4829219019Sgabor@c XXX xref implementation differences 4830219019Sgabor@end itemize 4831219019Sgabor 4832219019Sgabor@cindex current tab settings register 4833219019SgaborThe read-only number register @code{.tabs} contains a string 4834219019Sgaborrepresentation of the current tab settings suitable for use as an 4835219019Sgaborargument to the @code{ta} request. 4836219019Sgabor 4837219019Sgabor@Example 4838219019Sgabor.ds tab-string \n[.tabs] 4839219019Sgabor\*[tab-string] 4840219019Sgabor @result{} T120u 4841219019Sgabor@endExample 4842219019Sgabor@endDefreq 4843219019Sgabor 4844219019Sgabor@cindex tab repetition character 4845219019Sgabor@cindex character, tab repetition 4846219019Sgabor@Defreq {tc, [@Var{fill-char}]} 4847219019SgaborNormally @code{gtroff} fills the space to the next tab stop with 4848219019Sgaborwhitespace. This can be changed with the @code{tc} request. With no 4849219019Sgaborargument @code{gtroff} reverts to using whitespace, which is the 4850219019Sgabordefault. The value of this @dfn{tab repetition} character is 4851219019Sgaborassociated with the current environment (@pxref{Environments}). 4852219019Sgabor@endDefreq 4853219019Sgabor 4854219019Sgabor@menu 4855219019Sgabor* Leaders:: 4856219019Sgabor* Fields:: 4857219019Sgabor@end menu 4858219019Sgabor 4859219019Sgabor@c --------------------------------------------------------------------- 4860219019Sgabor 4861219019Sgabor@node Leaders, Fields, Tabs and Fields, Tabs and Fields 4862219019Sgabor@subsection Leaders 4863219019Sgabor@cindex leaders 4864219019Sgabor 4865219019SgaborSometimes it may may be desirable to use the @code{tc} request to fill a 4866219019Sgaborparticular tab stop with a given character (for example dots in a table 4867219019Sgaborof contents), but also normal tab stops on the rest of the line. For 4868219019Sgaborthis @code{gtroff} provides an alternate tab mechanism, called 4869219019Sgabor@dfn{leaders} which does just that. 4870219019Sgabor 4871219019Sgabor@cindex leader character 4872219019SgaborA leader character (character code@w{ }1) behaves similarly to a tab 4873219019Sgaborcharacter: It moves to the next tab stop. The only difference is that 4874219019Sgaborfor this movement, the fill character defaults to a period character and 4875219019Sgabornot to space. 4876219019Sgabor 4877219019Sgabor@Defesc {\\a, , , } 4878219019SgaborThis escape is a non-interpreted leader character. In copy mode 4879219019Sgabor(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 4880219019Sgaborcharacter. 4881219019Sgabor@endDefesc 4882219019Sgabor 4883219019Sgabor@cindex leader repetition character 4884219019Sgabor@cindex character, leader repetition 4885219019Sgabor@Defreq {lc, [@Var{fill-char}]} 4886219019SgaborDeclare the leader character. Without an argument, leaders act the 4887219019Sgaborsame as tabs (i.e., using whitespace for filling). @code{gtroff}'s 4888219019Sgaborstart-up value is @samp{.}. The value of this @dfn{leader repetition} 4889219019Sgaborcharacter is associated with the current environment 4890219019Sgabor(@pxref{Environments}). 4891219019Sgabor@endDefreq 4892219019Sgabor 4893219019Sgabor@cindex table of contents 4894219019Sgabor@cindex contents, table of 4895219019SgaborFor a table of contents, to name an example, tab stops may be defined so 4896219019Sgaborthat the section number is one tab stop, the title is the second with 4897219019Sgaborthe remaining space being filled with a line of dots, and then the page 4898219019Sgabornumber slightly separated from the dots. 4899219019Sgabor 4900219019Sgabor@Example 4901219019Sgabor.ds entry 1.1\tFoo\a\t12 4902219019Sgabor.lc . 4903219019Sgabor.ta 1i 5i +.25i 4904219019Sgabor\*[entry] 4905219019Sgabor@endExample 4906219019Sgabor 4907219019Sgabor@noindent 4908219019SgaborThis produces 4909219019Sgabor 4910219019Sgabor@Example 4911219019Sgabor1.1 Foo.......................................... 12 4912219019Sgabor@endExample 4913219019Sgabor 4914219019Sgabor@c --------------------------------------------------------------------- 4915219019Sgabor 4916219019Sgabor@node Fields, , Leaders, Tabs and Fields 4917219019Sgabor@subsection Fields 4918219019Sgabor@cindex fields 4919219019Sgabor 4920219019Sgabor@cindex field delimiting character 4921219019Sgabor@cindex delimiting character for fields 4922219019Sgabor@cindex character, field delimiting 4923219019Sgabor@cindex field padding character 4924219019Sgabor@cindex padding character for fields 4925219019Sgabor@cindex character, field padding 4926219019Sgabor@dfn{Fields} are a more general way of laying out tabular data. A field 4927219019Sgaboris defined as the data between a pair of @dfn{delimiting characters}. 4928219019SgaborIt contains substrings which are separated by @dfn{padding characters}. 4929219019SgaborThe width of a field is the distance on the @emph{input} line from the 4930219019Sgaborposition where the field starts to the next tab stop. A padding 4931219019Sgaborcharacter inserts stretchable space similar to @TeX{}'s @code{\hss} 4932219019Sgaborcommand (thus it can even be negative) to make the sum of all substring 4933219019Sgaborlengths plus the stretchable space equal to the field width. If more 4934219019Sgaborthan one padding character is inserted, the available space is evenly 4935219019Sgabordistributed among them. 4936219019Sgabor 4937219019Sgabor@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 4938219019SgaborDefine a delimiting and a padding character for fields. If the latter 4939219019Sgaboris missing, the padding character defaults to a space character. If 4940219019Sgaborthere is no argument at all, the field mechanism is disabled (which is 4941219019Sgaborthe default). Note that contrary to e.g.@: the tab repetition 4942219019Sgaborcharacter, delimiting and padding characters are not associated to the 4943219019Sgaborcurrent environment (@pxref{Environments}). 4944219019Sgabor 4945219019SgaborExample: 4946219019Sgabor 4947219019Sgabor@Example 4948219019Sgabor.fc # ^ 4949219019Sgabor.ta T 3i 4950219019Sgabor#foo^bar^smurf# 4951219019Sgabor.br 4952219019Sgabor#foo^^bar^smurf# 4953219019Sgabor@endExample 4954219019Sgabor 4955219019Sgabor@noindent 4956219019Sgaborand here the result: 4957219019Sgabor 4958219019Sgabor@Example 4959219019Sgaborfoo bar smurf 4960219019Sgaborfoo bar smurf 4961219019Sgabor@endExample 4962219019Sgabor@endDefreq 4963219019Sgabor 4964219019Sgabor 4965219019Sgabor@c ===================================================================== 4966219019Sgabor 4967219019Sgabor@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 4968219019Sgabor@section Character Translations 4969219019Sgabor@cindex character translations 4970219019Sgabor@cindex translations of characters 4971219019Sgabor 4972219019Sgabor@rqindex . 4973219019Sgabor@rqindex ' 4974219019Sgabor@cindex control character 4975219019Sgabor@cindex character, control 4976219019Sgabor@cindex no-break control character 4977219019Sgabor@cindex character, no-break control 4978219019Sgabor@cindex control character, no-break 4979219019SgaborThe control character (@samp{.}) and the no-break control character 4980219019Sgabor(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 4981219019Sgaborrespectively. 4982219019Sgabor 4983219019Sgabor@Defreq {cc, [@Var{c}]} 4984219019SgaborSet the control character to @var{c}. With no argument the default 4985219019Sgaborcontrol character @samp{.} is restored. The value of the control 4986219019Sgaborcharacter is associated with the current environment 4987219019Sgabor(@pxref{Environments}). 4988219019Sgabor@endDefreq 4989219019Sgabor 4990219019Sgabor@Defreq {c2, [@Var{c}]} 4991219019SgaborSet the no-break control character to @var{c}. With no argument the 4992219019Sgabordefault control character @samp{'} is restored. The value of the 4993219019Sgaborno-break control character is associated with the current environment 4994219019Sgabor(@pxref{Environments}). 4995219019Sgabor@endDefreq 4996219019Sgabor 4997219019Sgabor@esindex \\ 4998219019Sgabor@Defreq {eo, } 4999219019SgaborDisable the escape mechanism completely. After executing this 5000219019Sgaborrequest, the backslash character @samp{\} no longer starts an escape 5001219019Sgaborsequence. 5002219019Sgabor 5003219019SgaborThis request can be very helpful in writing macros since it is not 5004219019Sgabornecessary then to double the escape character. Here an example: 5005219019Sgabor 5006219019Sgabor@Example 5007219019Sgabor.\" This is a simplified version of the 5008219019Sgabor.\" .BR request from the man macro package 5009219019Sgabor.eo 5010219019Sgabor.de BR 5011219019Sgabor. ds result \& 5012219019Sgabor. while (\n[.$] >= 2) \@{\ 5013219019Sgabor. as result \fB\$1\fR\$2 5014219019Sgabor. shift 2 5015219019Sgabor. \@} 5016219019Sgabor. if \n[.$] .as result \fB\$1 5017219019Sgabor\*[result] 5018219019Sgabor. ft R 5019219019Sgabor.. 5020219019Sgabor.ec 5021219019Sgabor@endExample 5022219019Sgabor@endDefreq 5023219019Sgabor 5024219019Sgabor@cindex escape character 5025219019Sgabor@cindex character, escape 5026219019Sgabor@Defreq {ec, [@Var{c}]} 5027219019SgaborSet the escape character to @var{c}. With no argument the default 5028219019Sgaborescape character @samp{\} is restored. It can be also used to 5029219019Sgaborre-enable the escape mechanism after an @code{eo} request. 5030219019Sgabor 5031219019SgaborNote that changing the escape character globally will likely break 5032219019Sgabormacro packages since @code{gtroff} has no mechanism (like @TeX{}) to 5033219019Sgabor`intern' macros, i.e., to convert a macro definition into an internal 5034219019Sgaborform which is independent of its representation. If a macro is 5035219019Sgaborcalled, it is executed literally. 5036219019Sgabor@endDefreq 5037219019Sgabor 5038219019Sgabor@Defesc {\\e, , , } 5039219019SgaborThis escape sequence prints the current escape character (which is the 5040219019Sgaborbackslash character @samp{\} by default). 5041219019Sgabor@endDefesc 5042219019Sgabor 5043219019SgaborA @dfn{translation} is a mapping of an input character to an output 5044219019Sgaborcharacter. The default mappings are given in the font definition files 5045219019Sgaborfor the specific output device (@pxref{Font Files}); all mappings (both 5046219019Sgaborwith @code{tr} and in the font definition files) occur at output time, 5047219019Sgabori.e., the input character gets assigned the metric information of the 5048219019Sgabormapped output character. 5049219019Sgabor 5050219019Sgabor@Defreq {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 5051219019SgaborTranslate character @var{a} to @var{b}, character @var{c} to @var{d}, 5052219019Sgaboretc. If there is an odd number of arguments, the last one is 5053219019Sgabortranslated to the space character. 5054219019Sgabor 5055219019SgaborSome notes: 5056219019Sgabor 5057219019Sgabor@itemize @bullet 5058219019Sgabor@item 5059219019Sgabor@esindex \( 5060219019Sgabor@esindex \[ 5061219019Sgabor@esindex \' 5062219019Sgabor@esindex \` 5063219019Sgabor@esindex \- 5064219019Sgabor@esindex \_ 5065219019Sgabor@esindex \C 5066219019Sgabor@esindex \N 5067219019Sgabor@rqindex char 5068219019Sgabor@cindex special character 5069219019Sgabor@cindex character, special 5070219019Sgabor@cindex numbered character 5071219019Sgabor@cindex character, numbered 5072219019SgaborSpecial characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 5073219019Sgabor@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 5074219019Sgaborcharacters defined with the @code{char} request, and numbered characters 5075219019Sgabor(@code{\N'@var{xxx}'}) can be translated also. 5076219019Sgabor 5077219019Sgabor@item 5078219019Sgabor@esindex \e 5079219019SgaborThe @code{\e} escape can be translated also. 5080219019Sgabor 5081219019Sgabor@item 5082219019Sgabor@esindex \% 5083219019Sgabor@esindex \~ 5084219019SgaborCharacters can be mapped onto the @code{\%} and @code{\~} escapes (but 5085219019Sgabor@code{\%} and @code{\~} can't be mapped onto another character). 5086219019Sgabor 5087219019Sgabor@item 5088219019Sgabor@cindex backspace character 5089219019Sgabor@cindex character, backspace 5090219019Sgabor@cindex leader character 5091219019Sgabor@cindex character, leader 5092219019Sgabor@cindex newline character 5093219019Sgabor@cindex character, newline 5094219019Sgabor@cindex tab character 5095219019Sgabor@cindex character, tab 5096219019Sgabor@esindex \a 5097219019Sgabor@esindex \t 5098219019SgaborThe following characters can't be translated: space (with one exception, 5099219019Sgaborsee below), backspace, newline, leader (and @code{\a}), tab (and 5100219019Sgabor@code{\t}). 5101219019Sgabor 5102219019Sgabor@item 5103219019Sgabor@rqindex shc 5104219019SgaborTranslations are not considered for finding the soft hyphen character 5105219019Sgaborset with the @code{shc} request. 5106219019Sgabor 5107219019Sgabor@item 5108219019Sgabor@esindex \& 5109219019SgaborThe character pair @samp{@var{c}\&} (this is an arbitrary character@w{ 5110219019Sgabor}@var{c} followed by the zero width space character) maps this 5111219019Sgaborcharacter to nothing. 5112219019Sgabor 5113219019Sgabor@Example 5114219019Sgabor.tr a\& 5115219019Sgaborfoo bar 5116219019Sgabor @result{} foo br 5117219019Sgabor@endExample 5118219019Sgabor 5119219019Sgabor@noindent 5120219019SgaborIt is even possible to map the space character to nothing: 5121219019Sgabor 5122219019Sgabor@Example 5123219019Sgabor.tr aa \& 5124219019Sgaborfoo bar 5125219019Sgabor @result{} foobar 5126219019Sgabor@endExample 5127219019Sgabor 5128219019Sgabor@noindent 5129219019SgaborAs shown in the example, the space character can't be the first 5130219019Sgaborcharacter pair as an argument of @code{tr}. Additionally, it is not 5131219019Sgaborpossible to map the space character to any other character; requests 5132219019Sgaborlike @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 5133219019Sgabor 5134219019SgaborIf justification is active, lines are justified in spite of the 5135219019Sgabor`empty' space character (but there is no minimal distance, i.e.@: the 5136219019Sgaborspace character, between words). 5137219019Sgabor 5138219019Sgabor@item 5139219019SgaborAfter an output character has been constructed (this happens at the 5140219019Sgabormoment immediately before the character is appended to an output 5141219019Sgaborcharacter list, either by direct output, in a macro, diversion, or 5142219019Sgaborstring), it is no longer affected by @code{tr}. 5143219019Sgabor 5144219019Sgabor@c XXX xref 5145219019Sgabor 5146219019Sgabor@item 5147219019SgaborWithout an argument, the @code{tr} request is ignored. 5148219019Sgabor@end itemize 5149219019Sgabor@endDefreq 5150219019Sgabor 5151219019Sgabor@esindex \! 5152219019Sgabor@cindex @code{\!}, and @code{trnt} 5153219019Sgabor@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 5154219019Sgabor@code{trnt} is the same as the @code{tr} request except that the 5155219019Sgabortranslations do not apply to text that is transparently throughput 5156219019Sgaborinto a diversion with @code{\!}. @xref{Diversions}, for more 5157219019Sgaborinformation. 5158219019Sgabor 5159219019SgaborFor example, 5160219019Sgabor 5161219019Sgabor@Example 5162219019Sgabor.tr ab 5163219019Sgabor.di x 5164219019Sgabor\!.tm a 5165219019Sgabor.di 5166219019Sgabor.x 5167219019Sgabor@endExample 5168219019Sgabor 5169219019Sgabor@noindent 5170219019Sgaborprints @samp{b} to the standard error stream; if @code{trnt} is used 5171219019Sgaborinstead of @code{tr} it prints @samp{a}. 5172219019Sgabor@endDefreq 5173219019Sgabor 5174219019Sgabor 5175219019Sgabor@c ===================================================================== 5176219019Sgabor 5177219019Sgabor@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 5178219019Sgabor@section Troff and Nroff Mode 5179219019Sgabor@cindex troff mode 5180219019Sgabor@cindex mode, troff 5181219019Sgabor@cindex nroff mode 5182219019Sgabor@cindex mode, nroff 5183219019Sgabor 5184219019SgaborOriginally, @code{nroff} and @code{troff} were two separate programs, 5185219019Sgaborthe former for tty output, the latter for everything else. With GNU 5186219019Sgabor@code{troff}, both programs are merged into one executable, sending 5187219019Sgaborits output to a device driver (@code{grotty} for tty devices, 5188219019Sgabor@code{grops} for @sc{PostScript}, etc.) which interprets the 5189219019Sgaborintermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 5190219019Sgaborit makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 5191219019Sgaborsince the differences are hardcoded. For GNU @code{troff}, this 5192219019Sgabordistinction is not appropriate because @code{gtroff} simply takes the 5193219019Sgaborinformation given in the font files for a particular device without 5194219019Sgaborhandling requests specially if a tty output device is used. 5195219019Sgabor 5196219019SgaborUsually, a macro package can be used with all output devices. 5197219019SgaborNevertheless, it is sometimes necessary to make a distinction between 5198219019Sgabortty and non-tty devices: @code{gtroff} provides two built-in 5199219019Sgaborconditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 5200219019Sgabor@code{while} requests to decide whether @code{gtroff} shall behave 5201219019Sgaborlike @code{nroff} or like @code{troff}. 5202219019Sgabor 5203219019Sgabor@pindex troffrc 5204219019Sgabor@pindex troffrc-end 5205219019Sgabor@Defreq {troff, } 5206219019SgaborMake the @samp{t} built-in condition true (and the @samp{n} built-in 5207219019Sgaborcondition false) for @code{if}, @code{ie}, and @code{while} 5208219019Sgaborconditional requests. This is the default if @code{gtroff} 5209219019Sgabor(@emph{not} @code{groff}) is started with the @option{-R} switch to 5210219019Sgaboravoid loading of the start-up files @file{troffrc} and 5211219019Sgabor@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 5212219019Sgabormode if the output device is not a tty (e.g.@: `ps'). 5213219019Sgabor@endDefreq 5214219019Sgabor 5215219019Sgabor@pindex tty.tmac 5216219019Sgabor@Defreq {nroff, } 5217219019SgaborMake the @samp{n} built-in condition true (and the @samp{t} built-in 5218219019Sgaborcondition false) for @code{if}, @code{ie}, and @code{while} 5219219019Sgaborconditional requests. This is the default if @code{gtroff} uses a tty 5220219019Sgaboroutput device; the code for switching to nroff mode is in the file 5221219019Sgabor@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 5222219019Sgabor@endDefreq 5223219019Sgabor 5224219019Sgabor@xref{Conditionals and Loops}, for more details on built-in 5225219019Sgaborconditions. 5226219019Sgabor 5227219019Sgabor@c XXX move the following to grotty section 5228219019Sgabor 5229219019Sgabor@pindex less 5230219019Sgabor@cindex Teletype 5231219019Sgabor@cindex ISO 6249 SGR 5232219019Sgabor@cindex terminal control sequences 5233219019Sgabor@cindex control sequences, for terminals 5234219019SgaborFor tty output devices, underlining is done by emitting sequences of 5235219019Sgabor@samp{_} and @samp{\b} (the backspace character) before the actual 5236219019Sgaborcharacter. Literally, this is printing an underline character, then 5237219019Sgabormoving back one character position, and printing the actual character 5238219019Sgaborat the same position as the underline character (similar to a 5239219019Sgabortypewriter). Usually, a modern terminal can't interpret this (and the 5240219019Sgabororiginal Teletype machines for which this sequence was appropriate are 5241219019Sgaborno longer in use). You need a pager program like @code{less} which 5242219019Sgabortranslates this into ISO 6429 SGR sequences to control terminals. 5243219019Sgabor 5244219019Sgabor@c ===================================================================== 5245219019Sgabor 5246219019Sgabor@node Line Layout, Page Layout, Troff and Nroff Mode, gtroff Reference 5247219019Sgabor@section Line Layout 5248219019Sgabor@cindex line layout 5249219019Sgabor@cindex layout, line 5250219019Sgabor 5251219019Sgabor@cindex dimensions, line 5252219019Sgabor@cindex line dimensions 5253219019SgaborThe following drawing shows the dimensions which @code{gtroff} uses for 5254219019Sgaborplacing a line of output onto the page. They are labeled with the 5255219019Sgaborrequest which manipulates each dimension. 5256219019Sgabor 5257219019Sgabor@Example 5258219019Sgabor -->| in |<-- 5259219019Sgabor |<-----------ll------------>| 5260219019Sgabor +----+----+----------------------+----+ 5261219019Sgabor | : : : | 5262219019Sgabor +----+----+----------------------+----+ 5263219019Sgabor -->| po |<-- 5264219019Sgabor |<--------paper width---------------->| 5265219019Sgabor@endExample 5266219019Sgabor 5267219019Sgabor@noindent 5268219019SgaborThese dimensions are: 5269219019Sgabor 5270219019Sgabor@ftable @code 5271219019Sgabor@item po 5272219019Sgabor@cindex left margin 5273219019Sgabor@cindex margin, left 5274219019Sgabor@cindex page offset 5275219019Sgabor@cindex offset, page 5276219019Sgabor@dfn{Page offset} -- this is the leftmost position of text on the final 5277219019Sgaboroutput, defining the @dfn{left margin}. 5278219019Sgabor 5279219019Sgabor@item in 5280219019Sgabor@cindex indentation 5281219019Sgabor@cindex line indentation 5282219019Sgabor@dfn{Indentation} -- this is the distance from the left margin where 5283219019Sgabortext is printed. 5284219019Sgabor 5285219019Sgabor@item ll 5286219019Sgabor@cindex line length 5287219019Sgabor@cindex length of line 5288219019Sgabor@dfn{Line length} -- this is the distance from the left margin to right 5289219019Sgabormargin. 5290219019Sgabor@end ftable 5291219019Sgabor 5292219019Sgabor@c XXX improve example 5293219019Sgabor 5294219019Sgabor@Example 5295219019Sgabor.in +.5i 5296219019Sgabor.ll -.5i 5297219019SgaborA bunch of really boring text which should 5298219019Sgaborbe indented from both margins. 5299219019SgaborReplace me with a better (and more) example! 5300219019Sgabor.in -.5i 5301219019Sgabor.ll +.5i 5302219019Sgabor@endExample 5303219019Sgabor 5304219019Sgabor@pindex troffrc 5305219019Sgabor@Defreq {po, [@Var{offset}]} 5306219019Sgabor@Defreqx {po, @t{+}@Var{offset}} 5307219019Sgabor@Defreqx {po, @t{-}@Var{offset}} 5308219019Sgabor@Defregx {.o} 5309219019SgaborSet horizontal page offset to @var{offset} (or increment or decrement 5310219019Sgaborthe current value by @var{offset}). Note that this request does not 5311219019Sgaborcause a break, so changing the page offset in the middle of text being 5312219019Sgaborfilled may not yield the expected result. The initial value is 5313219019Sgabor1@dmn{i}. For tty output devices, it is set to 0 in the startup file 5314219019Sgabor@file{troffrc}; the default scaling indicator is@w{ }@code{m} (and 5315219019Sgabornot@w{ }@code{v} as incorrectly documented in the original 5316219019Sgabor@acronym{UNIX} troff manual). 5317219019Sgabor 5318219019SgaborThe current page offset can be found in the read-only number register 5319219019Sgabor@samp{.o}. 5320219019Sgabor 5321219019SgaborIf @code{po} is called without an argument, the page offset is reset to 5322219019Sgaborthe previous value before the last call to @code{po}. 5323219019Sgabor 5324219019Sgabor@Example 5325219019Sgabor.po 3i 5326219019Sgabor\n[.o] 5327219019Sgabor @result{} 720 5328219019Sgabor.po -1i 5329219019Sgabor\n[.o] 5330219019Sgabor @result{} 480 5331219019Sgabor.po 5332219019Sgabor\n[.o] 5333219019Sgabor @result{} 720 5334219019Sgabor@endExample 5335219019Sgabor@endDefreq 5336219019Sgabor 5337219019Sgabor@Defreq {in, [@Var{indent}]} 5338219019Sgabor@Defreqx {in, @t{+}@Var{indent}} 5339219019Sgabor@Defreqx {in, @t{-}@Var{indent}} 5340219019Sgabor@Defregx {.i} 5341219019SgaborSet indentation to @var{indent} (or increment or decrement the 5342219019Sgaborcurrent value by @var{indent}). This request causes a break. 5343219019SgaborInitially, there is no indentation. 5344219019Sgabor 5345219019SgaborIf @code{in} is called without an argument, the indentation is reset to 5346219019Sgaborthe previous value before the last call to @code{in}. The default 5347219019Sgaborscaling indicator is@w{ }@code{m}. 5348219019Sgabor 5349219019SgaborThe indentation is associated with the current environment. 5350219019Sgabor 5351219019SgaborIf a negative indentation value is specified (which is not allowed), 5352219019Sgabor@code{gtroff} emits a warning of type @samp{range} and sets the 5353219019Sgaborindentation to zero. 5354219019Sgabor 5355219019SgaborThe effect of @code{in} is delayed until a partially collected line (if 5356219019Sgaborit exists) is output. A temporary indent value is reset to zero also. 5357219019Sgabor 5358219019SgaborThe current indentation (as set by @code{in}) can be found in the 5359219019Sgaborread-only number register @samp{.i}. 5360219019Sgabor@endDefreq 5361219019Sgabor 5362219019Sgabor@Defreq {ti, offset} 5363219019Sgabor@Defreqx {ti, @t{+}@Var{offset}} 5364219019Sgabor@Defreqx {ti, @t{-}@Var{offset}} 5365219019Sgabor@Defregx {.in} 5366219019SgaborTemporarily indent the next output line by @var{offset}. If an 5367219019Sgaborincrement or decrement value is specified, adjust the temporary 5368219019Sgaborindentation relative to the value set by the @code{in} request. 5369219019Sgabor 5370219019SgaborThis request causes a break; its value is associated with the current 5371219019Sgaborenvironment. The default scaling indicator is@w{ }@code{m}. A call 5372219019Sgaborof @code{ti} without an argument is ignored. 5373219019Sgabor 5374219019SgaborIf the total indentation value is negative (which is not allowed), 5375219019Sgabor@code{gtroff} emits a warning of type @samp{range} and sets the 5376219019Sgabortemporary indentation to zero. `Total indentation' is either 5377219019Sgabor@var{offset} if specified as an absolute value, or the temporary plus 5378219019Sgabornormal indentation, if @var{offset} is given as a relative value. 5379219019Sgabor 5380219019SgaborThe effect of @code{ti} is delayed until a partially collected line (if 5381219019Sgaborit exists) is output. 5382219019Sgabor 5383219019SgaborThe read-only number register @code{.in} is the indentation that applies 5384219019Sgaborto the current output line. 5385219019Sgabor 5386219019SgaborThe difference between @code{.i} and @code{.in} is that the latter takes 5387219019Sgaborinto account whether a partially collected line still uses the old 5388219019Sgaborindentation value or a temporary indentation value is active. 5389219019Sgabor@endDefreq 5390219019Sgabor 5391219019Sgabor@Defreq {ll, [@Var{length}]} 5392219019Sgabor@Defreqx {ll, @t{+}@Var{length}} 5393219019Sgabor@Defreqx {ll, @t{-}@Var{length}} 5394219019Sgabor@Defregx {.l} 5395219019Sgabor@Defregx {.ll} 5396219019SgaborSet the line length to @var{length} (or increment or decrement the 5397219019Sgaborcurrent value by @var{length}). Initially, the line length is set to 5398219019Sgabor6.5@dmn{i}. The effect of @code{ll} is delayed until a partially 5399219019Sgaborcollected line (if it exists) is output. The default scaling 5400219019Sgaborindicator is@w{ }@code{m}. 5401219019Sgabor 5402219019SgaborIf @code{ll} is called without an argument, the line length is reset to 5403219019Sgaborthe previous value before the last call to @code{ll}. If a negative 5404219019Sgaborline length is specified (which is not allowed), @code{gtroff} emits a 5405219019Sgaborwarning of type @samp{range} and sets the line length to zero. 5406219019Sgabor 5407219019SgaborThe line length is associated with the current environment. 5408219019Sgabor 5409219019Sgabor@cindex current line length register 5410219019SgaborThe current line length (as set by @code{ll}) can be found in the 5411219019Sgaborread-only number register @samp{.l}. The read-only number register 5412219019Sgabor@code{.ll} is the line length that applies to the current output line. 5413219019Sgabor 5414219019SgaborSimilar to @code{.i} and @code{.in}, the difference between @code{.l} 5415219019Sgaborand @code{.ll} is that the latter takes into account whether a partially 5416219019Sgaborcollected line still uses the old line length value. 5417219019Sgabor@endDefreq 5418219019Sgabor 5419219019Sgabor 5420219019Sgabor@c ===================================================================== 5421219019Sgabor 5422219019Sgabor@node Page Layout, Page Control, Line Layout, gtroff Reference 5423219019Sgabor@section Page Layout 5424219019Sgabor@cindex page layout 5425219019Sgabor@cindex layout, page 5426219019Sgabor 5427219019Sgabor@code{gtroff} provides some very primitive operations for controlling 5428219019Sgaborpage layout. 5429219019Sgabor 5430219019Sgabor@cindex page length 5431219019Sgabor@cindex length of page 5432219019Sgabor@Defreq {pl, [@Var{length}]} 5433219019Sgabor@Defreqx {pl, @t{+}@Var{length}} 5434219019Sgabor@Defreqx {pl, @t{-}@Var{length}} 5435219019Sgabor@Defregx {.p} 5436219019SgaborSet the @dfn{page length} to @var{length} (or increment or decrement 5437219019Sgaborthe current value by @var{length}). This is the length of the 5438219019Sgaborphysical output page. The default scaling indicator is@w{ }@code{v}. 5439219019Sgabor 5440219019Sgabor@cindex current page length register 5441219019SgaborThe current setting can be found in the read-only number register 5442219019Sgabor@samp{.p}. 5443219019Sgabor 5444219019Sgabor@cindex top margin 5445219019Sgabor@cindex margin, top 5446219019Sgabor@cindex bottom margin 5447219019Sgabor@cindex margin, bottom 5448219019SgaborNote that this only specifies the size of the page, not the top and 5449219019Sgaborbottom margins. Those are not set by @code{gtroff} directly. 5450219019Sgabor@xref{Traps}, for further information on how to do this. 5451219019Sgabor 5452219019SgaborNegative @code{pl} values are possible also, but not very useful: No 5453219019Sgabortrap is sprung, and each line is output on a single page (thus 5454219019Sgaborsuppressing all vertical spacing). 5455219019Sgabor 5456219019SgaborIf no argument or an invalid argument is given, @code{pl} sets the page 5457219019Sgaborlength to 11@dmn{i}. 5458219019Sgabor@endDefreq 5459219019Sgabor 5460219019Sgabor@cindex headers 5461219019Sgabor@cindex footers 5462219019Sgabor@cindex titles 5463219019Sgabor@code{gtroff} provides several operations which help in setting up top 5464219019Sgaborand bottom titles (or headers and footers). 5465219019Sgabor 5466219019Sgabor@cindex title line 5467219019Sgabor@cindex three-part title 5468219019Sgabor@cindex page number character 5469219019Sgabor@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 5470219019SgaborPrint a @dfn{title line}. It consists of three parts: a left 5471219019Sgaborjustified portion, a centered portion, and a right justified portion. 5472219019SgaborThe argument separator @samp{'} can be replaced with any character not 5473219019Sgaboroccurring in the title line. The @samp{%} character is replaced with 5474219019Sgaborthe current page number. This character can be changed with the 5475219019Sgabor@code{pc} request (see below). 5476219019Sgabor 5477219019SgaborWithout argument, @code{tl} is ignored. 5478219019Sgabor 5479219019SgaborSome notes: 5480219019Sgabor 5481219019Sgabor@itemize @bullet 5482219019Sgabor@item 5483219019SgaborA title line is not restricted to the top or bottom of a page. 5484219019Sgabor 5485219019Sgabor@item 5486219019Sgabor@code{tl} prints the title line immediately, ignoring a partially filled 5487219019Sgaborline (which stays untouched). 5488219019Sgabor 5489219019Sgabor@item 5490219019SgaborIt is not an error to omit closing delimiters. For example, 5491219019Sgabor@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 5492219019Sgabortitle line with the left justified word @samp{foo}; the centered and 5493219019Sgaborright justfied parts are empty. 5494219019Sgabor 5495219019Sgabor@item 5496219019SgaborAny modifications to the current environment within @code{tl} (e.g.@: 5497219019Sgaborchanging the font or font size) are undone after processing @code{tl}. 5498219019Sgabor 5499219019Sgabor@item 5500219019Sgabor@code{tl} accepts the same parameter delimiting characters as the 5501219019Sgabor@code{\A} escape; see @ref{Escapes}. 5502219019Sgabor@end itemize 5503219019Sgabor@endDefreq 5504219019Sgabor 5505219019Sgabor@cindex length of title line 5506219019Sgabor@cindex title line, length 5507219019Sgabor@cindex current title line length register 5508219019Sgabor@Defreq {lt, [@Var{length}]} 5509219019Sgabor@Defreqx {lt, @t{+}@Var{length}} 5510219019Sgabor@Defreqx {lt, @t{-}@Var{length}} 5511219019Sgabor@Defregx {.lt} 5512219019SgaborThe title line is printed using its own line length, which is 5513219019Sgaborspecified (or incremented or decremented) with the @code{lt} request. 5514219019SgaborInitially, the title line length is set to 6.5@dmn{i}. If a negative 5515219019Sgaborline length is specified (which is not allowed), @code{gtroff} emits a 5516219019Sgaborwarning of type @samp{range} and sets the title line length to zero. 5517219019SgaborThe default scaling indicator is@w{ }@code{m}. If @code{lt} is called 5518219019Sgaborwithout an argument, the title length is reset to the previous value 5519219019Sgaborbefore the last call to @code{lt}. 5520219019Sgabor 5521219019SgaborThe current setting of this is available in the @code{.lt} read-only 5522219019Sgabornumber register; it is associated with the current environment 5523219019Sgabor(@pxref{Environments}). 5524219019Sgabor 5525219019Sgabor@endDefreq 5526219019Sgabor 5527219019Sgabor@cindex page number 5528219019Sgabor@cindex number, page 5529219019Sgabor@Defreq {pn, page} 5530219019Sgabor@Defreqx {pn, @t{+}@Var{page}} 5531219019Sgabor@Defreqx {pn, @t{-}@Var{page}} 5532219019Sgabor@Defregx {.pn} 5533219019SgaborChange (increase or decrease) the page number of the @emph{next} page. 5534219019SgaborThe only argument is the page number; the request is ignored without a 5535219019Sgaborparameter. 5536219019Sgabor 5537219019SgaborThe read-only number register @code{.pn} contains the number of the next 5538219019Sgaborpage: either the value set by a @code{pn} request, or the number of the 5539219019Sgaborcurrent page plus@w{ }1. 5540219019Sgabor@endDefreq 5541219019Sgabor 5542219019Sgabor@cindex current page number register 5543219019Sgabor@Defreg {%} 5544219019SgaborA read-write register holding the current page number. 5545219019Sgabor@endDefreg 5546219019Sgabor 5547219019Sgabor@cindex changing the page number character 5548219019Sgabor@cindex page number character, changing 5549219019Sgabor@vindex % 5550219019Sgabor@Defreq {pc, [@Var{char}]} 5551219019SgaborChange the page number character (used by the @code{tl} request) to a 5552219019Sgabordifferent character. With no argument, this mechanism is disabled. 5553219019SgaborNote that this doesn't affect the number register @code{%}. 5554219019Sgabor@endDefreq 5555219019Sgabor 5556219019Sgabor@xref{Traps}. 5557219019Sgabor 5558219019Sgabor 5559219019Sgabor@c ===================================================================== 5560219019Sgabor 5561219019Sgabor@node Page Control, Fonts, Page Layout, gtroff Reference 5562219019Sgabor@section Page Control 5563219019Sgabor@cindex page control 5564219019Sgabor@cindex control, page 5565219019Sgabor 5566219019Sgabor@rqindex pn 5567219019Sgabor@cindex new page 5568219019Sgabor@Defreq {bp, [@Var{page}]} 5569219019Sgabor@Defreqx {bp, @t{+}@Var{page}} 5570219019Sgabor@Defreqx {bp, @t{-}@Var{page}} 5571219019SgaborStop processing the current page and move to the next page. This 5572219019Sgaborrequest causes a break. It can also take an argument to set 5573219019Sgabor(increase, decrease) the page number of the next page. The only 5574219019Sgabordifference between @code{bp} and @code{pn} is that @code{pn} does not 5575219019Sgaborcause a break or actually eject a page. 5576219019Sgabor 5577219019Sgabor@Example 5578219019Sgabor.de newpage \" define macro 5579219019Sgabor'bp \" begin page 5580219019Sgabor'sp .5i \" vertical space 5581219019Sgabor.tl 'left top'center top'right top' \" title 5582219019Sgabor'sp .3i \" vertical space 5583219019Sgabor.. \" end macro 5584219019Sgabor@endExample 5585219019Sgabor 5586219019Sgabor@cindex top-level diversion 5587219019Sgabor@cindex diversion, top-level 5588219019Sgabor@code{bp} has no effect if not called within the top-level diversion 5589219019Sgabor(@pxref{Diversions}). 5590219019Sgabor@endDefreq 5591219019Sgabor 5592219019Sgabor@cindex orphan line 5593219019Sgabor@Defreq {ne, [@Var{space}]} 5594219019SgaborIt is often necessary to force a certain amount of space before a new 5595219019Sgaborpage occurs. This is most useful to make sure that there is not a 5596219019Sgaborsingle @dfn{orphan} line left at the bottom of a page. The @code{ne} 5597219019Sgaborrequest ensures that there is a certain distance, specified by the 5598219019Sgaborfirst argument, before the next page is triggered (see @ref{Traps}, 5599219019Sgaborfor further information). The default unit for @code{ne} is @samp{v}; 5600219019Sgaborthe default value of @var{space} is@w{ }1@dmn{v} if no argument is 5601219019Sgaborgiven. 5602219019Sgabor 5603219019SgaborFor example, to make sure that no fewer than 2@w{ }lines get orphaned, 5604219019Sgabordo the following before each paragraph: 5605219019Sgabor 5606219019Sgabor@Example 5607219019Sgabor.ne 2 5608219019Sgabortext text text 5609219019Sgabor@endExample 5610219019Sgabor@endDefreq 5611219019Sgabor 5612219019Sgabor@rqindex os 5613219019Sgabor@rqindex ne 5614219019Sgabor@Defreq {sv, [@Var{space}]} 5615219019Sgabor@code{sv} is similar to the @code{ne} request; it reserves the 5616219019Sgaborspecified amount of vertical space. If the desired amount of space 5617219019Sgaborexists before the next trap (bottom page boundary), the space is 5618219019Sgaboroutput immediately (ignoring a partial filled line which stays 5619219019Sgaboruntouched). If there is not enough space, it is stored for later 5620219019Sgaboroutput via the @code{os} request. The default value is@w{ }1@dmn{v} 5621219019Sgaborif no argument is given; the default unit is @samp{v}. 5622219019Sgabor@endDefreq 5623219019Sgabor 5624219019Sgabor 5625219019Sgabor@c ===================================================================== 5626219019Sgabor 5627219019Sgabor@node Fonts, Sizes, Page Control, gtroff Reference 5628219019Sgabor@section Fonts 5629219019Sgabor@cindex fonts 5630219019Sgabor 5631219019Sgabor@code{gtroff} can switch fonts at any point in the text. 5632219019Sgabor 5633219019SgaborThe basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 5634219019SgaborThese are Times Roman, Italic, Bold, and Bold Italic. For non-tty 5635219019Sgabordevices, there is also at least one symbol font which contains various 5636219019Sgaborspecial symbols (Greek, mathematics). 5637219019Sgabor 5638219019Sgabor@menu 5639219019Sgabor* Changing Fonts:: 5640219019Sgabor* Font Families:: 5641219019Sgabor* Font Positions:: 5642219019Sgabor* Using Symbols:: 5643219019Sgabor* Special Fonts:: 5644219019Sgabor* Artificial Fonts:: 5645219019Sgabor* Ligatures and Kerning:: 5646219019Sgabor@end menu 5647219019Sgabor 5648219019Sgabor@c --------------------------------------------------------------------- 5649219019Sgabor 5650219019Sgabor@node Changing Fonts, Font Families, Fonts, Fonts 5651219019Sgabor@subsection Changing Fonts 5652219019Sgabor@cindex changing fonts 5653219019Sgabor@cindex fonts, changing 5654219019Sgabor 5655219019Sgabor@rqindex sty 5656219019Sgabor@rqindex fam 5657219019Sgabor@kindex styles 5658219019Sgabor@kindex family 5659219019Sgabor@pindex DESC 5660219019Sgabor@Defreq {ft, [@Var{font}]} 5661219019Sgabor@Defescx {\\f, , f, } 5662219019Sgabor@Defescx {\\f, @lparen{}, fn, } 5663219019Sgabor@Defescx {\\f, @lbrack{}, font, @rbrack} 5664219019SgaborThe @code{ft} request and the @code{\f} escape change the current font 5665219019Sgaborto @var{font} (one-character name @var{f}, two-character name 5666219019Sgabor@var{fn}). 5667219019Sgabor 5668219019SgaborIf @var{font} is a style name (as set with the @code{sty} request or 5669219019Sgaborwith the @code{styles} command in the @file{DESC} file), use it within 5670219019Sgaborthe current font family (as set with the @code{fam} request or with 5671219019Sgaborthe @code{family} command in the @file{DESC} file). 5672219019Sgabor 5673219019Sgabor@cindex previous font 5674219019Sgabor@cindex font, previous 5675219019SgaborWith no argument or using @samp{P} as an argument, @code{.ft} switches 5676219019Sgaborto the previous font. Use @code{\fP} or @code{\f[P]} to do this with 5677219019Sgaborthe escape. 5678219019Sgabor 5679219019SgaborFonts are generally specified as upper-case strings, which are usually 5680219019Sgabor1@w{ }to 4 characters representing an abbreviation or acronym of the 5681219019Sgaborfont name. This is no limitation, just a convention. 5682219019Sgabor 5683219019SgaborThe example below produces two identical lines. 5684219019Sgabor 5685219019Sgabor@Example 5686219019Sgaboreggs, bacon, 5687219019Sgabor.ft B 5688219019Sgaborspam 5689219019Sgabor.ft 5690219019Sgaborand sausage. 5691219019Sgabor 5692219019Sgaboreggs, bacon, \fBspam\fP and sausage. 5693219019Sgabor@endExample 5694219019Sgabor 5695219019Sgabor@xref{Font Positions}, for an alternative syntax. 5696219019Sgabor@endDefreq 5697219019Sgabor 5698219019Sgabor@rqindex ft 5699219019Sgabor@rqindex ul 5700219019Sgabor@rqindex bd 5701219019Sgabor@esindex \f 5702219019Sgabor@rqindex cs 5703219019Sgabor@rqindex tkf 5704219019Sgabor@rqindex special 5705219019Sgabor@rqindex fspecial 5706219019Sgabor@rqindex fp 5707219019Sgabor@rqindex code 5708219019Sgabor@Defreq {ftr, f [@Var{g}]} 5709219019SgaborTranslate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named 5710219019Sgabor@var{f} is referred to in a @code{\f} escape sequence, or in the 5711219019Sgabor@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 5712219019Sgabor@code{special}, @code{fspecial}, @code{fp}, or @code{code} requests, 5713219019Sgaborfont@w{ }@var{g} is used. If @var{g} is missing or equal to @var{f} 5714219019Sgaborthe translation is undone. 5715219019Sgabor@endDefreq 5716219019Sgabor 5717219019Sgabor@c --------------------------------------------------------------------- 5718219019Sgabor 5719219019Sgabor@node Font Families, Font Positions, Changing Fonts, Fonts 5720219019Sgabor@subsection Font Families 5721219019Sgabor@cindex font families 5722219019Sgabor@cindex families, font 5723219019Sgabor@cindex font styles 5724219019Sgabor@cindex styles, font 5725219019Sgabor 5726219019SgaborDue to the variety of fonts available, @code{gtroff} has added the 5727219019Sgaborconcept of @dfn{font families} and @dfn{font styles}. The fonts are 5728219019Sgaborspecified as the concatenation of the font family and style. Specifying 5729219019Sgabora font without the family part causes @code{gtroff} to use that style of 5730219019Sgaborthe current family. 5731219019Sgabor 5732219019Sgabor@cindex postscript fonts 5733219019Sgabor@cindex fonts, postscript 5734219019SgaborCurrently, only @sc{PostScript} fonts are set up to this mechanism. 5735219019SgaborBy default, @code{gtroff} uses the Times family with the four styles 5736219019Sgabor@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 5737219019Sgabor 5738219019SgaborThis way, it is possible to use the basic four fonts and to select a 5739219019Sgabordifferent font family on the command line (@pxref{Groff Options}). 5740219019Sgabor 5741219019Sgabor@Defreq {fam, [@Var{family}]} 5742219019Sgabor@Defregx {.fam} 5743219019SgaborSwitch font family to @var{family}. If no argument is given, switch 5744219019Sgaborback to the previous font family. The current font family is available 5745219019Sgaborin the read-only number register @samp{.fam} (this is a string-valued 5746219019Sgaborregister); it is associated with the current environment. 5747219019Sgabor 5748219019Sgabor@Example 5749219019Sgaborspam, 5750219019Sgabor.fam H \" helvetica family 5751219019Sgaborspam, \" used font is family H + style R = HR 5752219019Sgabor.ft B \" family H + style B = font HB 5753219019Sgaborspam, 5754219019Sgabor.fam T \" times family 5755219019Sgaborspam, \" used font is family T + style B = TB 5756219019Sgabor.ft AR \" font AR (not a style) 5757219019Sgaborbaked beans, 5758219019Sgabor.ft R \" family T + style R = font TR 5759219019Sgaborand spam. 5760219019Sgabor@endExample 5761219019Sgabor@endDefreq 5762219019Sgabor 5763219019Sgabor@rqindex cs 5764219019Sgabor@rqindex bd 5765219019Sgabor@rqindex tkf 5766219019Sgabor@rqindex uf 5767219019Sgabor@rqindex fspecial 5768219019Sgabor@Defreq {sty, n style} 5769219019SgaborAssociate @var{style} with font position@w{ }@var{n}. A font position 5770219019Sgaborcan be associated either with a font or with a style. The current 5771219019Sgaborfont is the index of a font position and so is also either a font or a 5772219019Sgaborstyle. When it is a style, the font that is actually used is the font 5773219019Sgaborthe name of which is the concatenation of the name of the current 5774219019Sgaborfamily and the name of the current style. For example, if the current 5775219019Sgaborfont is@w{ }1 and font position@w{ }1 is associated with style@w{ 5776219019Sgabor}@samp{R} and the current font family is@w{ }@samp{T}, then font 5777219019Sgabor@samp{TR} will be used. If the current font is not a style, then the 5778219019Sgaborcurrent family is ignored. When the requests @code{cs}, @code{bd}, 5779219019Sgabor@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, then 5780219019Sgaborthey will instead be applied to the member of the current family 5781219019Sgaborcorresponding to that style. 5782219019Sgabor 5783219019Sgabor@var{n} must be a non-negative integer value. 5784219019Sgabor 5785219019Sgabor@pindex DESC 5786219019Sgabor@kindex styles 5787219019SgaborThe default family can be set with the @option{-f} option 5788219019Sgabor(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 5789219019Sgaborfile controls which font positions (if any) are initially associated 5790219019Sgaborwith styles rather than fonts. For example, the default setting for 5791219019Sgabor@sc{PostScript} fonts 5792219019Sgabor 5793219019Sgabor@Example 5794219019Sgaborstyles R I B BI 5795219019Sgabor@endExample 5796219019Sgabor 5797219019Sgabor@noindent 5798219019Sgaboris equivalent to 5799219019Sgabor 5800219019Sgabor@Example 5801219019Sgabor.sty 1 R 5802219019Sgabor.sty 2 I 5803219019Sgabor.sty 3 B 5804219019Sgabor.sty 4 BI 5805219019Sgabor@endExample 5806219019Sgabor 5807219019Sgabor@code{.fam} always checks whether the current font position is valid; 5808219019Sgaborthis can give surprising results if the current font position is 5809219019Sgaborassociated with a style. 5810219019Sgabor 5811219019SgaborIn the following example, we want to access the @sc{PostScript} font 5812219019Sgabor@code{FooBar} from the font family @code{Foo}: 5813219019Sgabor 5814219019Sgabor@Example 5815219019Sgabor.sty \n[.fp] Bar 5816219019Sgabor.fam Foo 5817219019Sgabor @result{} warning: can't find font `FooR' 5818219019Sgabor@endExample 5819219019Sgabor 5820219019Sgabor@noindent 5821219019SgaborThe default font position at start-up is@w{ }1; for the 5822219019Sgabor@sc{PostScript} device, this is associated with style @samp{R}, so 5823219019Sgabor@code{gtroff} tries to open @code{FooR}. 5824219019Sgabor 5825219019SgaborA solution to this problem is to use a dummy font like the following: 5826219019Sgabor 5827219019Sgabor@Example 5828219019Sgabor.fp 0 dummy TR \" set up dummy font at position 0 5829219019Sgabor.sty \n[.fp] Bar \" register style `Bar' 5830219019Sgabor.ft 0 \" switch to font at position 0 5831219019Sgabor.fam Foo \" activate family `Foo' 5832219019Sgabor.ft Bar \" switch to font `FooBar' 5833219019Sgabor@endExample 5834219019Sgabor 5835219019Sgabor@xref{Font Positions}. 5836219019Sgabor@endDefreq 5837219019Sgabor 5838219019Sgabor@c --------------------------------------------------------------------- 5839219019Sgabor 5840219019Sgabor@node Font Positions, Using Symbols, Font Families, Fonts 5841219019Sgabor@subsection Font Positions 5842219019Sgabor@cindex font positions 5843219019Sgabor@cindex positions, font 5844219019Sgabor 5845219019SgaborFor the sake of old phototypesetters and compatibility with old versions 5846219019Sgaborof @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 5847219019Sgaboron which various fonts are mounted. 5848219019Sgabor 5849219019Sgabor@Defreq {fp, pos font [@Var{external-name}]} 5850219019Sgabor@Defregx {.f} 5851219019Sgabor@Defregx {.fp} 5852219019SgaborMount font @var{font} at position @var{pos} (which must be a 5853219019Sgabornon-negative integer). This numeric position can then be referred to 5854219019Sgaborwith font changing commands. When @code{gtroff} starts it is using 5855219019Sgaborfont position@w{ }1 (which must exist; position@w{ }0 is unused 5856219019Sgaborusually at start-up). 5857219019Sgabor 5858219019Sgabor@cindex current font position register 5859219019SgaborThe current font in use, as a font position, is available in the 5860219019Sgaborread-only number register @samp{.f}. This can be useful to remember the 5861219019Sgaborcurrent font for later recall. It is associated with the current 5862219019Sgaborenvironment (@pxref{Environments}). 5863219019Sgabor 5864219019Sgabor@Example 5865219019Sgabor.nr save-font \n[.f] 5866219019Sgabor.ft B 5867219019Sgabor... text text text ... 5868219019Sgabor.ft \n[save-font] 5869219019Sgabor@endExample 5870219019Sgabor 5871219019Sgabor@cindex next free font position register 5872219019SgaborThe number of the next free font position is available in the read-only 5873219019Sgabornumber register @samp{.fp}. This is useful when mounting a new font, 5874219019Sgaborlike so: 5875219019Sgabor 5876219019Sgabor@Example 5877219019Sgabor.fp \n[.fp] NEATOFONT 5878219019Sgabor@endExample 5879219019Sgabor 5880219019Sgabor@pindex DESC@r{, and font mounting} 5881219019SgaborFonts not listed in the @file{DESC} file are automatically mounted on 5882219019Sgaborthe next available font position when they are referenced. If a font 5883219019Sgaboris to be mounted explicitly with the @code{fp} request on an unused 5884219019Sgaborfont position, it should be mounted on the first unused font position, 5885219019Sgaborwhich can be found in the @code{.fp} register. Although @code{gtroff} 5886219019Sgabordoes not enforce this strictly, it is not allowed to mount a font at a 5887219019Sgaborposition whose number is much greater (approx.@: 1000 positions) than 5888219019Sgaborthat of any currently used position. 5889219019Sgabor 5890219019SgaborThe @code{fp} request has an optional third argument. This argument 5891219019Sgaborgives the external name of the font, which is used for finding the font 5892219019Sgabordescription file. The second argument gives the internal name of the 5893219019Sgaborfont which is used to refer to the font in @code{gtroff} after it has 5894219019Sgaborbeen mounted. If there is no third argument then the internal name is 5895219019Sgaborused as the external name. This feature makes it possible to use 5896219019Sgaborfonts with long names in compatibility mode. 5897219019Sgabor@endDefreq 5898219019Sgabor 5899219019SgaborBoth the @code{ft} request and the @code{\f} escape have alternative 5900219019Sgaborsyntax forms to access font positions. 5901219019Sgabor 5902219019Sgabor@rqindex sty 5903219019Sgabor@rqindex fam 5904219019Sgabor@kindex styles 5905219019Sgabor@kindex family 5906219019Sgabor@pindex DESC 5907219019Sgabor@Defreq {ft, nnn} 5908219019Sgabor@Defescx {\\f, , n, } 5909219019Sgabor@Defescx {\\f, @lparen{}, nn, } 5910219019Sgabor@Defescx {\\f, @lbrack{}, nnn, @rbrack} 5911219019SgaborChange the current font position to @var{nnn} (one-digit position 5912219019Sgabor@var{n}, two-digit position @var{nn}), which must be a non-negative 5913219019Sgaborinteger. 5914219019Sgabor 5915219019SgaborIf @var{nnn} is associated with a style (as set with the @code{sty} 5916219019Sgaborrequest or with the @code{styles} command in the @file{DESC} file), use 5917219019Sgaborit within the current font family (as set with the @code{fam} request or 5918219019Sgaborwith the @code{family} command in the @file{DESC} file). 5919219019Sgabor 5920219019Sgabor@Example 5921219019Sgaborthis is font 1 5922219019Sgabor.ft 2 5923219019Sgaborthis is font 2 5924219019Sgabor.ft \" switch back to font 1 5925219019Sgabor.ft 3 5926219019Sgaborthis is font 3 5927219019Sgabor.ft 5928219019Sgaborthis is font 1 again 5929219019Sgabor@endExample 5930219019Sgabor 5931219019Sgabor@xref{Changing Fonts}, for the standard syntax form. 5932219019Sgabor@endDefreq 5933219019Sgabor 5934219019Sgabor@c --------------------------------------------------------------------- 5935219019Sgabor 5936219019Sgabor@node Using Symbols, Special Fonts, Font Positions, Fonts 5937219019Sgabor@subsection Using Symbols 5938219019Sgabor@cindex using symbols 5939219019Sgabor@cindex symbols, using 5940219019Sgabor 5941219019Sgabor@cindex glyph 5942219019Sgabor@cindex character 5943219019Sgabor@cindex ligature 5944219019SgaborA @dfn{glyph} is a graphical representation of a @dfn{character}. 5945219019SgaborWhile a character is an abstract entity containing semantic 5946219019Sgaborinformation, a glyph is something which can be actually seen on screen 5947219019Sgaboror paper. It is possible that a character has multiple glyph 5948219019Sgaborrepresentation forms (for example, the character `A' can be either 5949219019Sgaborwritten in a roman or an italic font, yielding two different glyphs); 5950219019Sgaborsometimes more than one character maps to a single glyph (this is a 5951219019Sgabor@dfn{ligature} -- the most common is `fi'). 5952219019Sgabor 5953219019Sgabor@c XXX 5954219019Sgabor 5955219019SgaborPlease note that currently the distinction between glyphs and 5956219019Sgaborcharacters in this reference is not clearly carried out. This will be 5957219019Sgaborimproved eventually in the next revision. 5958219019Sgabor 5959219019Sgabor@cindex symbol 5960219019Sgabor@cindex special fonts 5961219019Sgabor@kindex fonts 5962219019Sgabor@pindex DESC 5963219019Sgabor@rqindex fspecial 5964219019SgaborA @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 5965219019Sgaborglyph names of a particular font are defined in its font file. If the 5966219019Sgaboruser requests a glyph not available in this font, @code{gtroff} looks 5967219019Sgaborup an ordered list of @dfn{special fonts}. By default, the 5968219019Sgabor@sc{PostScript} output device supports the two special fonts @samp{SS} 5969219019Sgabor(slanted symbols) and @samp{S} (symbols) (the former is looked up 5970219019Sgaborbefore the latter). Other output devices use different names for 5971219019Sgaborspecial fonts. Fonts mounted with the @code{fonts} keyword in the 5972219019Sgabor@file{DESC} file are globally available. To install additional 5973219019Sgaborspecial fonts locally (i.e.@: for a particular font), use the 5974219019Sgabor@code{fspecial} request. 5975219019Sgabor 5976219019Sgabor@xref{Font Files}, and @ref{Special Fonts}, for more details. 5977219019Sgabor 5978219019Sgabor@Defesc {\\, @lparen{}, nm, } 5979219019Sgabor@Defescx {\\, @lbrack{}, name, @rbrack} 5980219019SgaborInsert a symbol @var{name} (two-character name @var{nm}). There is no 5981219019Sgaborspecial syntax for one-character names -- the natural form 5982219019Sgabor@samp{\@var{n}} would collide with escapes. 5983219019Sgabor 5984219019SgaborIf @var{name} is undefined, a warning of type @samp{char} is generated, 5985219019Sgaborand the escape is ignored. @xref{Debugging}, for information about 5986219019Sgaborwarnings. 5987219019Sgabor 5988219019SgaborThe list of available symbols is device dependent; see @ref{Glyph Name 5989219019SgaborIndex} for some of them discussed in this reference. 5990219019Sgabor 5991219019Sgabor@c XXX list of common symbols 5992219019Sgabor@endDefesc 5993219019Sgabor 5994219019Sgabor@Defesc {\\C, ', xxx, '} 5995219019SgaborTypeset the character named @var{xxx}. Normally it is more convenient 5996219019Sgaborto use @code{\[@var{xxx}]}, but @code{\C} has the advantage that it is 5997219019Sgaborcompatible with newer versions of @code{ditroff} and is available in 5998219019Sgaborcompatibility mode. 5999219019Sgabor@endDefesc 6000219019Sgabor 6001219019Sgabor@rqindex char 6002219019Sgabor@cindex unicode 6003219019Sgabor@Defesc {\\N, ', n, '} 6004219019SgaborTypeset the character with code@w{ }@var{n} in the current font (this 6005219019Sgaboris @strong{not} the input character code). @var{n} can be any 6006219019Sgaborinteger. Most devices only have characters with codes between 0 6007219019Sgaborand@w{ }255; the Unicode output device uses codes in the range 6008219019Sgabor0--65535. If the current font does not contain a character with that 6009219019Sgaborcode, special fonts are @emph{not} searched. The @code{\N} escape 6010219019Sgaborsequence can be conveniently used in conjunction with the @code{char} 6011219019Sgaborrequest: 6012219019Sgabor 6013219019Sgabor@Example 6014219019Sgabor.char \[phone] \f[ZD]\N'37' 6015219019Sgabor@endExample 6016219019Sgabor 6017219019Sgabor@noindent 6018219019Sgabor@pindex DESC 6019219019Sgabor@cindex unnamed characters 6020219019Sgabor@cindex characters, unnamed 6021219019SgaborThe code of each character is given in the fourth column in the font 6022219019Sgabordescription file after the @code{charset} command. It is possible to 6023219019Sgaborinclude unnamed characters in the font description file by using a 6024219019Sgaborname of @samp{---}; the @code{\N} escape sequence is the only way to 6025219019Sgaboruse these. 6026219019Sgabor@endDefesc 6027219019Sgabor 6028219019Sgabor@c XXX should be `glyph', not `character' 6029219019Sgabor 6030219019Sgabor@cindex character properties 6031219019Sgabor@cindex properties of characters 6032219019Sgabor@Defreq {cflags, n c1 c2 @dots{}} 6033219019SgaborEach character has certain properties associated with it. These 6034219019Sgaborproperties can be modified with the @code{cflags} request. The first 6035219019Sgaborargument is the the sum of the desired flags and the remaining 6036219019Sgaborarguments are the characters to have those properties. It is possible 6037219019Sgaborto omit the spaces between the characters. 6038219019Sgabor 6039219019Sgabor@table @code 6040219019Sgabor@item 1 6041219019Sgabor@cindex end of sentence characters 6042219019Sgabor@cindex characters, end of sentence 6043219019Sgaborthe character ends sentences (initially characters @samp{.?!} have this 6044219019Sgaborproperty) 6045219019Sgabor 6046219019Sgabor@item 2 6047219019Sgabor@cindex hyphenating characters 6048219019Sgabor@cindex characters, hyphenation 6049219019Sgaborlines can be broken before the character (initially no characters have 6050219019Sgaborthis property) 6051219019Sgabor 6052219019Sgabor@item 4 6053219019Sgabor@glindex hy 6054219019Sgabor@glindex em 6055219019Sgaborlines can be broken after the character (initially the characters 6056219019Sgabor@samp{-\(hy\(em} have this property) 6057219019Sgabor 6058219019Sgabor@item 8 6059219019Sgabor@cindex overlapping characters 6060219019Sgabor@cindex characters, overlapping 6061219019Sgabor@glindex ul 6062219019Sgabor@glindex rn 6063219019Sgabor@glindex ru 6064219019Sgaborthe character overlaps horizontally (initially the characters 6065219019Sgabor@samp{\(ul\(rn\(ru} have this property) 6066219019Sgabor 6067219019Sgabor@item 16 6068219019Sgabor@glindex br 6069219019Sgaborthe character overlaps vertically (initially character @samp{\(br} has 6070219019Sgaborthis property) 6071219019Sgabor 6072219019Sgabor@item 32 6073219019Sgabor@cindex transparent characters 6074219019Sgabor@cindex character, transparent 6075219019Sgabor@cindex ' 6076219019Sgabor@cindex " 6077219019Sgabor@cindex ] 6078219019Sgabor@cindex ) 6079219019Sgabor@cindex * 6080219019Sgabor@glindex dg 6081219019Sgabor@glindex rq 6082219019Sgaboran end of sentence character followed by any number of characters with 6083219019Sgaborthis property is treated as the end of a sentence if followed by a 6084219019Sgabornewline or two spaces; in other words the character is 6085219019Sgabor@dfn{transparent} for the purposes of end of sentence recognition -- 6086219019Sgaborthis is the same as having a zero space factor in @TeX{} (initially 6087219019Sgaborcharacters @samp{"')]*\(dg\(rq} have this property). 6088219019Sgabor@end table 6089219019Sgabor@endDefreq 6090219019Sgabor 6091219019Sgabor@cindex defining characters 6092219019Sgabor@cindex characters, defining 6093219019Sgabor@cindex creating new characters 6094219019Sgabor@cindex escape character 6095219019Sgabor@cindex character, escape 6096219019Sgabor@rqindex tr 6097219019Sgabor@rqindex cp 6098219019Sgabor@rqindex rc 6099219019Sgabor@rqindex lc 6100219019Sgabor@esindex \l 6101219019Sgabor@esindex \L 6102219019Sgabor@esindex \& 6103219019Sgabor@esindex \e 6104219019Sgabor@rqindex hcode 6105219019Sgabor@Defreq {char, c [@Var{string}]} 6106219019SgaborDefine a new character@w{ }@var{c} to be @var{string} (which can be 6107219019Sgaborempty). Every time character@w{ }@var{c} needs to be printed, 6108219019Sgabor@var{string} is processed in a temporary environment and the result is 6109219019Sgaborwrapped up into a single object. Compatibility mode is turned off and 6110219019Sgaborthe escape character is set to @samp{\} while @var{string} is being 6111219019Sgaborprocessed. Any emboldening, constant spacing or track kerning is 6112219019Sgaborapplied to this object rather than to individual characters in 6113219019Sgabor@var{string}. A character defined by this request can be used just 6114219019Sgaborlike a normal character provided by the output device. In particular, 6115219019Sgaborother characters can be translated to it with the @code{tr} request; 6116219019Sgaborit can be made the leader character by the @code{lc} request; repeated 6117219019Sgaborpatterns can be drawn with the character using the @code{\l} and 6118219019Sgabor@code{\L} escape sequences; words containing the character can be 6119219019Sgaborhyphenated correctly, if the @code{hcode} request is used to give the 6120219019Sgaborcharacter a hyphenation code. There is a special anti-recursion 6121219019Sgaborfeature: Use of character within the character's definition is handled 6122219019Sgaborlike normal characters not defined with @code{char}. 6123219019Sgabor@endDefreq 6124219019Sgabor 6125219019Sgabor@cindex removing character definition 6126219019Sgabor@cindex character, removing definition 6127219019Sgabor@Defreq {rchar, c1 c2 @dots{}} 6128219019SgaborRemove the definitions of characters @var{c1}, @var{c2},@w{ 6129219019Sgabor}@enddots{} This undoes the effect of a @code{char} request. 6130219019Sgabor 6131219019SgaborIt is possible to omit the whitespace between arguments. 6132219019Sgabor@endDefreq 6133219019Sgabor 6134219019Sgabor@xref{Special Characters}. 6135219019Sgabor 6136219019Sgabor@c --------------------------------------------------------------------- 6137219019Sgabor 6138219019Sgabor@node Special Fonts, Artificial Fonts, Using Symbols, Fonts 6139219019Sgabor@subsection Special Fonts 6140219019Sgabor@cindex special fonts 6141219019Sgabor@cindex fonts, special 6142219019Sgabor 6143219019Sgabor@c XXX 6144219019Sgabor 6145219019SgaborTo be written. 6146219019Sgabor 6147219019Sgabor@c --------------------------------------------------------------------- 6148219019Sgabor 6149219019Sgabor@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts 6150219019Sgabor@subsection Artificial Fonts 6151219019Sgabor@cindex artificial fonts 6152219019Sgabor@cindex fonts, artificial 6153219019Sgabor 6154219019SgaborThere are a number of requests for artificially creating fonts. These 6155219019Sgaborare largely vestiges of the days when output devices did not have a 6156219019Sgaborwide variety of fonts, and when @code{nroff} and @code{troff} were 6157219019Sgaborseparate programs. These are no longer necessary in GNU 6158219019Sgabor@code{troff}. Nevertheless, they are supported. 6159219019Sgabor 6160219019Sgabor@cindex underlining 6161219019Sgabor@Defreq {ul, [@Var{lines}]} 6162219019SgaborThe @code{ul} request normally underlines subsequent lines if a tty 6163219019Sgaboroutput device is used. Otherwise, the lines are printed in italics 6164219019Sgabor(only the term `underlined' is used in the following). The single 6165219019Sgaborargument is the number of input lines to be underlined; with no 6166219019Sgaborargument, the next line is underlined. If @var{lines} is zero or 6167219019Sgabornegative, stop the effects of @code{ul} (if it was active). Requests 6168219019Sgaborand empty lines do not count for computing the number of underlined 6169219019Sgaborinput lines, even if they produce some output like @code{tl}. Lines 6170219019Sgaborinserted by macros (e.g.@: invoked by a trap) do count. 6171219019Sgabor 6172219019SgaborAt the beginning of @code{ul}, the current font is stored and the 6173219019Sgaborunderline font is activated. Within the span of a @code{ul} request, 6174219019Sgaborit is possible to change fonts, but after the last line affected by 6175219019Sgabor@code{ul} the saved font is restored. 6176219019Sgabor 6177219019Sgabor@cindex underline font 6178219019Sgabor@cindex font, for underlining 6179219019Sgabor@rqindex uf 6180219019SgaborThis command is associated with the current environment. The 6181219019Sgaborunderline font can be changed with the @code{uf} request. 6182219019Sgabor 6183219019Sgabor@c XXX @xref should be changed to grotty 6184219019Sgabor 6185219019Sgabor@xref{Troff and Nroff Mode}, for a discussion how underlining is 6186219019Sgaborimplemented in for tty output devices, and which problems can arise. 6187219019Sgabor 6188219019SgaborThe @code{ul} request does not underline spaces. 6189219019Sgabor@endDefreq 6190219019Sgabor 6191219019Sgabor@cindex continuous underlining 6192219019Sgabor@cindex underlining, continuous 6193219019Sgabor@Defreq {cu, [@Var{lines}]} 6194219019SgaborThe @code{cu} request is similar to @code{ul} but underlines spaces as 6195219019Sgaborwell (if a tty output device is used). 6196219019Sgabor@endDefreq 6197219019Sgabor 6198219019Sgabor@cindex underline font 6199219019Sgabor@cindex font for underlining 6200219019Sgabor@rqindex ul 6201219019Sgabor@rqindex cu 6202219019Sgabor@Defreq {uf, font} 6203219019SgaborSet the underline font (globally) used by @code{ul} and @code{cu}. By 6204219019Sgabordefault, this is the font at position@w{ }2. @var{font} can be either 6205219019Sgabora non-negative font position or the name of a font. 6206219019Sgabor@endDefreq 6207219019Sgabor 6208219019Sgabor@cindex imitating bold face 6209219019Sgabor@cindex bold face, imitating 6210219019Sgabor@Defreq {bd, font [@Var{offset}]} 6211219019Sgabor@Defreqx {bd, font1 font2 [@Var{offset}]} 6212219019Sgabor@Defregx {.b} 6213219019SgaborArtificially create a bold font by printing each character twice, 6214219019Sgaborslightly offset. 6215219019Sgabor 6216219019SgaborTwo syntax forms are available. 6217219019Sgabor 6218219019Sgabor@itemize @bullet 6219219019Sgabor@item 6220219019SgaborImitate a bold font unconditionally. The first argument specifies the 6221219019Sgaborfont to embolden, and the second is the number of basic units, minus 6222219019Sgaborone, by which the two characters is offset. If the second argument is 6223219019Sgabormissing, emboldening is turned off. 6224219019Sgabor 6225219019Sgabor@var{font} can be either a non-negative font position or the name of a 6226219019Sgaborfont. 6227219019Sgabor 6228219019Sgabor@var{offset} is available in the @code{.b} read-only register if a 6229219019Sgaborspecial font is active; in the @code{bd} request, its default unit is 6230219019Sgabor@samp{u}. 6231219019Sgabor 6232219019Sgabor@rqindex fspecial 6233219019Sgabor@kindex special 6234219019Sgabor@cindex embolding of special fonts 6235219019Sgabor@cindex special fonts, emboldening 6236219019Sgabor@item 6237219019SgaborImitate a bold form conditionally. Embolden @var{font1} by 6238219019Sgabor@var{offset} only if font @var{font2} is the current font. This 6239219019Sgaborcommand can be issued repeatedly to set up different emboldening 6240219019Sgaborvalues for different current fonts. If the second argument is 6241219019Sgabormissing, emboldening is turned off for this particular current font. 6242219019Sgabor 6243219019SgaborThis affects special fonts only (either set up with the @code{special} 6244219019Sgaborcommand in font files or with the @code{fspecial} request). 6245219019Sgabor@end itemize 6246219019Sgabor@endDefreq 6247219019Sgabor 6248219019Sgabor@cindex constant character space mode 6249219019Sgabor@cindex mode for constant character space 6250219019Sgabor@cindex character, constant space 6251219019Sgabor@rqindex ps 6252219019Sgabor@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 6253219019SgaborSwitch to and from constant character space mode. If activated, the 6254219019Sgaborwidth of every character is @math{@var{width}/36} ems. The em size is 6255219019Sgaborgiven absolutely by @var{em-size}; if this argument is missing, the em 6256219019Sgaborvalue is taken from the current font size (as set with the @code{ps} 6257219019Sgaborrequest) when the font is effectively in use. Without second and 6258219019Sgaborthird argument, constant character space mode is deactivated. 6259219019Sgabor 6260219019SgaborDefault unit for @var{em-size} is @samp{z}; @var{width} is an integer. 6261219019Sgabor@endDefreq 6262219019Sgabor 6263219019Sgabor@c --------------------------------------------------------------------- 6264219019Sgabor 6265219019Sgabor@node Ligatures and Kerning, , Artificial Fonts, Fonts 6266219019Sgabor@subsection Ligatures and Kerning 6267219019Sgabor@cindex ligatures and kerning 6268219019Sgabor@cindex kerning and ligatures 6269219019Sgabor 6270219019SgaborLigatures are groups of characters that are run together. For 6271219019Sgaborexample, the letters `f' and `i' can form a ligature `fi' as in the 6272219019Sgaborword `file'. This produces a cleaner look (albeit subtle) to the 6273219019Sgaborprinted output. Usually, ligatures are not available in fonts for tty 6274219019Sgaboroutput devices. 6275219019Sgabor 6276219019SgaborMost @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 6277219019Sgabortypesetter that was the target of AT&T @code{troff} also supported 6278219019Sgabor`ff', `ffi', and `ffl' ligatures. Advanced typesetters or `expert' 6279219019Sgaborfonts may include ligatures for `ft' and `ct', although GNU 6280219019Sgabor@code{troff} does not support these (yet). 6281219019Sgabor 6282219019Sgabor@cindex ligatures enabled register 6283219019Sgabor@Defreq {lg, [@Var{flag}]} 6284219019Sgabor@Defregx {.lg} 6285219019SgaborThe ligature mechanism can be switched on or off with the @code{lg} 6286219019Sgaborrequest; if the parameter is non-zero or missing, ligatures are 6287219019Sgaborenabled, otherwise disabled. Default is on. The current ligature 6288219019Sgabormode can be found in the read-only number register @code{.lg} (set to 6289219019Sgabor1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise). 6290219019Sgabor 6291219019SgaborSetting the ligature mode to@w{ }2 enables the two-character ligatures 6292219019Sgabor(fi, fl, and ff) and disables the three-character ligatures (ffi and 6293219019Sgaborffl). 6294219019Sgabor@endDefreq 6295219019Sgabor 6296219019Sgabor@dfn{Pairwise kerning} is another subtle typesetting mechanism that 6297219019Sgabormodifies the distance between a character pair to improve readability. 6298219019SgaborIn most cases (but not always) the distance is decreased. 6299219019Sgabor@ifnotinfo 6300219019SgaborFor example, compare the combination of the letters `V' and `A'. With 6301219019Sgaborkerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 6302219019Sgabor@end ifnotinfo 6303219019SgaborTypewriter-like fonts and fonts for terminals where all characters 6304219019Sgaborhave the same width don't use kerning. 6305219019Sgabor 6306219019Sgabor@cindex kerning enabled register 6307219019Sgabor@Defreq {kern, [@Var{flag}]} 6308219019Sgabor@Defregx {.kern} 6309219019SgaborKerning can be activated with the @code{kern} request. If the 6310219019Sgaborparameter is non-zero or missing, enable pairwise kerning, otherwise 6311219019Sgabordisable it. The read-only number register @code{.kern} is set to@w{ 6312219019Sgabor}1 if pairwise kerning is enabled, 0@w{ }otherwise. 6313219019Sgabor 6314219019Sgabor@cindex zero width space character 6315219019Sgabor@cindex character, zero width space 6316219019Sgabor@cindex space character, zero width 6317219019SgaborIf the font description file contains pairwise kerning information, 6318219019Sgaborcharacters from that font are kerned. Kerning between two characters 6319219019Sgaborcan be inhibited by placing @code{\&} between them: @samp{V\&A}. 6320219019Sgabor 6321219019Sgabor@xref{Font File Format}. 6322219019Sgabor@endDefreq 6323219019Sgabor 6324219019Sgabor@cindex track kerning 6325219019Sgabor@cindex kerning, track 6326219019Sgabor@dfn{Track kerning} expands or reduces the space between characters. 6327219019SgaborThis can be handy, for example, if you need to squeeze a long word 6328219019Sgaboronto a single line or spread some text to fill a narrow column. It 6329219019Sgabormust be used with great care since it is usually considered bad 6330219019Sgabortypography if the reader notices the effect. 6331219019Sgabor 6332219019Sgabor@Defreq {tkf, f s1 n1 s2 n2} 6333219019SgaborEnable track kerning for font@w{ }@var{f}. If the current font is@w{ 6334219019Sgabor}@var{f} the width of every character is increased by an amount 6335219019Sgaborbetween @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 6336219019Sgaborthe current point size is less than or equal to @var{s1} the width is 6337219019Sgaborincreased by @var{n1}; if it is greater than or equal to @var{s2} the 6338219019Sgaborwidth is increased by @var{n2}; if the point size is greater than or 6339219019Sgaborequal to @var{s1} and less than or equal to @var{s2} the increase in 6340219019Sgaborwidth is a linear function of the point size. 6341219019Sgabor 6342219019SgaborThe default unit is @samp{z} for @var{s1} and @var{s2}, @samp{p} for 6343219019Sgabor@var{n1} and @var{n2}. 6344219019Sgabor@endDefreq 6345219019Sgabor 6346219019SgaborSometimes, when typesetting letters of different fonts, more or less 6347219019Sgaborspace at such boundaries are needed. There are two escapes to help 6348219019Sgaborwith this. 6349219019Sgabor 6350219019Sgabor@cindex italic correction 6351219019Sgabor@cindex correction, italic 6352219019Sgabor@cindex correction between italic and roman character 6353219019Sgabor@cindex roman character, correction after italic character 6354219019Sgabor@cindex italic character, correction before roman character 6355219019Sgabor@Defesc {\\/, , , } 6356219019SgaborIncrease the width of the preceding character so that the spacing 6357219019Sgaborbetween that character and the following character is correct if the 6358219019Sgaborfollowing character is a roman character. For example, if an 6359219019Sgaboritalic@w{ }@code{f} is immediately followed by a roman right 6360219019Sgaborparenthesis, then in many fonts the top right portion of the @code{f} 6361219019Sgaboroverlaps the top left of the right parenthesis. Use this escape 6362219019Sgaborsequence whenever an italic character is immediately followed by a 6363219019Sgaborroman character without any intervening space. This small amount of 6364219019Sgaborspace is also called @dfn{italic correction}. 6365219019Sgabor 6366219019Sgabor@iftex 6367219019Sgabor@example 6368219019Sgabor@group 6369219019Sgabor\f[I]f\f[R]) 6370219019Sgabor @result{} {@it f}@r{)} 6371219019Sgabor\f[I]f\/\f[R]) 6372219019Sgabor @result{} @i{f}@r{)} 6373219019Sgabor@end group 6374219019Sgabor@end example 6375219019Sgabor@end iftex 6376219019Sgabor@endDefesc 6377219019Sgabor 6378219019Sgabor@cindex left italic correction 6379219019Sgabor@cindex correction, left italic 6380219019Sgabor@cindex roman character, correction before italic character 6381219019Sgabor@cindex italic character, correction after roman character 6382219019Sgabor@Defesc {\\\,, , , } 6383219019SgaborModify the spacing of the following character so that the spacing 6384219019Sgaborbetween that character and the preceding character is correct if the 6385219019Sgaborpreceding character is a roman character. Use this escape sequence 6386219019Sgaborwhenever a roman character is immediately followed by an italic 6387219019Sgaborcharacter without any intervening space. In analogy to above, this 6388219019Sgaborspace could be called @dfn{left italic correction}, but this term 6389219019Sgaborisn't used widely. 6390219019Sgabor 6391219019Sgabor@iftex 6392219019Sgabor@example 6393219019Sgabor@group 6394219019Sgaborq\f[I]f 6395219019Sgabor @result{} @r{q}@i{f} 6396219019Sgaborq\,\f[I]f 6397219019Sgabor @result{} @r{q}@math{@ptexcomma}@i{f} 6398219019Sgabor@end group 6399219019Sgabor@end example 6400219019Sgabor@end iftex 6401219019Sgabor@endDefesc 6402219019Sgabor 6403219019Sgabor@Defesc {\\&, , , } 6404219019SgaborInsert a zero-width character, which is invisible. Its intended use 6405219019Sgaboris to stop interaction of a character with its surrounding. 6406219019Sgabor 6407219019Sgabor@itemize @bullet 6408219019Sgabor@item 6409219019SgaborIt prevents the insertion of extra space after an end of sentence 6410219019Sgaborcharacter. 6411219019Sgabor 6412219019Sgabor@Example 6413219019SgaborTest. 6414219019SgaborTest. 6415219019Sgabor @result{} Test. Test. 6416219019SgaborTest.\& 6417219019SgaborTest. 6418219019Sgabor @result{} Test. Test. 6419219019Sgabor@endExample 6420219019Sgabor 6421219019Sgabor@item 6422219019SgaborIt prevents interpretation of a control character at the beginning of 6423219019Sgaboran input line. 6424219019Sgabor 6425219019Sgabor@Example 6426219019Sgabor.Test 6427219019Sgabor @result{} warning: `Test' not defined 6428219019Sgabor\&.Test 6429219019Sgabor @result{} .Test 6430219019Sgabor@endExample 6431219019Sgabor 6432219019Sgabor@item 6433219019SgaborIt prevents kerning between two characters. 6434219019Sgabor 6435219019Sgabor@ifnotinfo 6436219019Sgabor@example 6437219019Sgabor@group 6438219019SgaborVA 6439219019Sgabor @result{} @r{VA} 6440219019SgaborV\&A 6441219019Sgabor @result{} @r{V@w{}A} 6442219019Sgabor@end group 6443219019Sgabor@end example 6444219019Sgabor@end ifnotinfo 6445219019Sgabor 6446219019Sgabor@item 6447219019SgaborIt is needed to map an arbitrary character to nothing in the @code{tr} 6448219019Sgaborrequest (@pxref{Character Translations}). 6449219019Sgabor@end itemize 6450219019Sgabor@endDefesc 6451219019Sgabor 6452219019Sgabor 6453219019Sgabor@c ===================================================================== 6454219019Sgabor 6455219019Sgabor@node Sizes, Strings, Fonts, gtroff Reference 6456219019Sgabor@section Sizes 6457219019Sgabor@cindex sizes 6458219019Sgabor 6459219019Sgabor@cindex baseline 6460219019Sgabor@cindex type size 6461219019Sgabor@cindex size of type 6462219019Sgabor@cindex vertical spacing 6463219019Sgabor@cindex spacing, vertical 6464219019Sgabor@code{gtroff} uses two dimensions with each line of text, type size 6465219019Sgaborand vertical spacing. The @dfn{type size} is approximately the height 6466219019Sgaborof the tallest character.@footnote{This is usually the parenthesis. 6467219019SgaborNote that in most cases the real dimensions of the glyphs in a font 6468219019Sgaborare @emph{not} related to its type size! For example, the standard 6469219019Sgabor@sc{PostScript} font families `Times Roman', `Helvetica', and 6470219019Sgabor`Courier' can't be used together at 10@dmn{pt}; to get acceptable 6471219019Sgaboroutput, the size of `Helvetica' has to be reduced by one point, and 6472219019Sgaborthe size of `Courier' must be increased by one point.} @dfn{Vertical 6473219019Sgaborspacing} is the amount of space @code{gtroff} allows for a line of 6474219019Sgabortext; normally, this is about 20%@w{ }larger than the current type 6475219019Sgaborsize. Ratios smaller than this can result in hard-to-read text; 6476219019Sgaborlarger than this, it spreads the text out more vertically (useful for 6477219019Sgaborterm papers). By default, @code{gtroff} uses 10@w{ }point type on 6478219019Sgabor12@w{ }point spacing. 6479219019Sgabor 6480219019Sgabor@cindex leading 6481219019SgaborThe difference between type size and vertical spacing is known, by 6482219019Sgabortypesetters, as @dfn{leading}. 6483219019Sgabor 6484219019Sgabor@menu 6485219019Sgabor* Changing Type Sizes:: 6486219019Sgabor* Fractional Type Sizes:: 6487219019Sgabor@end menu 6488219019Sgabor 6489219019Sgabor@c --------------------------------------------------------------------- 6490219019Sgabor 6491219019Sgabor@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 6492219019Sgabor@subsection Changing Type Sizes 6493219019Sgabor@cindex changing type sizes 6494219019Sgabor@cindex type sizes, changing 6495219019Sgabor 6496219019Sgabor@Defreq {ps, [@Var{size}]} 6497219019Sgabor@Defreqx {ps, @t{+}@Var{size}} 6498219019Sgabor@Defreqx {ps, @t{-}@Var{size}} 6499219019Sgabor@Defescx {\\s, , size, } 6500219019Sgabor@Defregx {.s} 6501219019SgaborUse the @code{ps} request or the @code{\s} escape to change (increase, 6502219019Sgabordecrease) the type size (in points). Specify @var{size} as either an 6503219019Sgaborabsolute point size, or as a relative change from the current size. 6504219019SgaborThe size@w{ }0, or no argument, goes back to the previous size. 6505219019Sgabor 6506219019SgaborDefault unit of @code{size} is @samp{z}. If @code{size} is zero or 6507219019Sgabornegative, it is set to 1@dmn{u}. 6508219019Sgabor 6509219019SgaborThe read-only number register @code{.s} returns the point size in 6510219019Sgaborpoints as a decimal fraction. This is a string. To get the point 6511219019Sgaborsize in scaled points, use the @code{.ps} register instead. 6512219019Sgabor 6513219019Sgabor@code{.s} is associated with the current environment 6514219019Sgabor(@pxref{Environments}). 6515219019Sgabor 6516219019Sgabor@Example 6517219019Sgaborsnap, snap, 6518219019Sgabor.ps +2 6519219019Sgaborgrin, grin, 6520219019Sgabor.ps +2 6521219019Sgaborwink, wink, \s+2nudge, nudge,\s+8 say no more! 6522219019Sgabor.ps 10 6523219019Sgabor@endExample 6524219019Sgabor 6525219019SgaborThe @code{\s} escape may be called in a variety of ways. Much like 6526219019Sgaborother escapes there must be a way to determine where the argument ends 6527219019Sgaborand the text begins. Any of the following forms are valid: 6528219019Sgabor 6529219019Sgabor@table @code 6530219019Sgabor@item \s@var{n} 6531219019SgaborSet the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 6532219019Sgabor0 or in the range 4 to@w{ }39. 6533219019Sgabor 6534219019Sgabor@item \s+@var{n} 6535219019Sgabor@itemx \s-@var{n} 6536219019SgaborIncrease or decrease the point size by @var{n}@w{ }points. @var{n}@w{ 6537219019Sgabor}must be exactly one digit. 6538219019Sgabor 6539219019Sgabor@item \s(@var{nn} 6540219019SgaborSet the point size to @var{nn}@w{ }points. @var{nn} must be exactly 6541219019Sgabortwo digits. 6542219019Sgabor 6543219019Sgabor@item \s+(@var{nn} 6544219019Sgabor@itemx \s-(@var{nn} 6545219019Sgabor@itemx \s(+@var{nn} 6546219019Sgabor@itemx \s(-@var{nn} 6547219019SgaborIncrease or decrease the point size by @var{nn}@w{ }points. @var{nn} 6548219019Sgabormust be exactly two digits. 6549219019Sgabor@end table 6550219019Sgabor 6551219019Sgabor@xref{Fractional Type Sizes}, for yet another syntactical form of 6552219019Sgaborusing the @code{\s} escape. 6553219019Sgabor 6554219019SgaborSome devices may only have certain permissible sizes, in which case 6555219019Sgabor@code{gtroff} rounds to the nearest permissible size. 6556219019Sgabor@endDefreq 6557219019Sgabor 6558219019Sgabor@cindex current type size register 6559219019Sgabor@cindex current vertical spacing register 6560219019Sgabor@Defreq {vs, [@Var{space}]} 6561219019Sgabor@Defreqx {vs, @t{+}@Var{space}} 6562219019Sgabor@Defreqx {vs, @t{-}@Var{space}} 6563219019Sgabor@Defregx {.v} 6564219019SgaborChange (increase, decrease) the vertical spacing by @var{space}. The 6565219019Sgabordefault unit is @samp{p}. 6566219019Sgabor 6567219019SgaborIf @code{vs} is called without an argument, the vertical spacing is 6568219019Sgaborreset to the previous value before the last call to @code{vs}. 6569219019Sgabor 6570219019Sgabor@vindex .V 6571219019Sgabor@code{gtroff} creates a warning of type @samp{range} if @var{space} is 6572219019Sgaborzero or negative; the vertical spacing is then set to the vertical 6573219019Sgaborresolution (as given in the @code{.V} register). 6574219019Sgabor 6575219019SgaborThe read-only number register @code{.v} contains the current vertical 6576219019Sgaborspacing; it is associated with the current environment 6577219019Sgabor(@pxref{Environments}). 6578219019Sgabor@endDefreq 6579219019Sgabor 6580219019Sgabor@c XXX example 6581219019Sgabor 6582219019Sgabor@ignore 6583219019Sgabor@Example 6584219019Sgabor... .sz macro example?? ... 6585219019Sgabor@endExample 6586219019Sgabor@end ignore 6587219019Sgabor 6588219019Sgabor@c --------------------------------------------------------------------- 6589219019Sgabor 6590219019Sgabor@node Fractional Type Sizes, , Changing Type Sizes, Sizes 6591219019Sgabor@subsection Fractional Type Sizes 6592219019Sgabor@cindex fractional type sizes 6593219019Sgabor@cindex type sizes, fractional 6594219019Sgabor 6595219019Sgabor@cindex @code{s} unit 6596219019Sgabor@cindex unit, @code{s} 6597219019Sgabor@cindex @code{z} unit 6598219019Sgabor@cindex unit, @code{z} 6599219019Sgabor@rqindex ps 6600219019Sgabor@rqindex cs 6601219019Sgabor@rqindex tkf 6602219019Sgabor@esindex \H 6603219019Sgabor@esindex \s 6604219019SgaborA @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 6605219019Sgaborwhere @var{sizescale} is specified in the @file{DESC} file (1@w{ }by 6606219019Sgabordefault). There is a new scale indicator @samp{z} which has the 6607219019Sgaboreffect of multiplying by @var{sizescale}. Requests and escape 6608219019Sgaborsequences in @code{gtroff} interpret arguments that represent a point 6609219019Sgaborsize as being in units of scaled points, but they evaluate each such 6610219019Sgaborargument using a default scale indicator of @samp{z}. Arguments 6611219019Sgabortreated in this way are the argument to the @code{ps} request, the 6612219019Sgaborthird argument to the @code{cs} request, the second and fourth 6613219019Sgaborarguments to the @code{tkf} request, the argument to the @code{\H} 6614219019Sgaborescape sequence, and those variants of the @code{\s} escape sequence 6615219019Sgaborthat take a numeric expression as their argument (see below). 6616219019Sgabor 6617219019SgaborFor example, suppose @var{sizescale} is@w{ }1000; then a scaled point 6618219019Sgaboris equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 6619219019Sgaborequivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 6620219019Sgabor10250@w{ }scaled points, which is equal to 10.25@w{ }points. 6621219019Sgabor 6622219019Sgabor@code{gtroff} disallows the use of the @samp{z} scale indicator in 6623219019Sgaborinstances where it would make no sense, such as a numeric 6624219019Sgaborexpression whose default scale indicator was neither @samp{u} nor 6625219019Sgabor@samp{z}. Similarly it would make 6626219019Sgaborno sense to use a scaling indicator other than @samp{z} or @samp{u} in a 6627219019Sgabornumeric expression whose default scale indicator was @samp{z}, and so 6628219019Sgabor@code{gtroff} disallows this as well. 6629219019Sgabor 6630219019SgaborThere is also new scale indicator @samp{s} which multiplies by the 6631219019Sgabornumber of units in a scaled point. So, for example, @samp{\n[.ps]s} is 6632219019Sgaborequal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 6633219019Sgaborscale indicators. 6634219019Sgabor 6635219019Sgabor@vindex .s 6636219019Sgabor@Defreg {.ps} 6637219019SgaborA read-only number register returning the point size in scaled points. 6638219019Sgabor 6639219019Sgabor@code{.ps} is associated with the current environment 6640219019Sgabor(@pxref{Environments}). 6641219019Sgabor@endDefreg 6642219019Sgabor 6643219019Sgabor@cindex last-requested point size register 6644219019Sgabor@cindex point size, last-requested 6645219019Sgabor@vindex .ps 6646219019Sgabor@vindex .s 6647219019Sgabor@Defreg {.psr} 6648219019Sgabor@Defregx {.sr} 6649219019SgaborThe last-requested point size in scaled points is contained in the 6650219019Sgabor@code{.psr} read-only number register. The last requested point size 6651219019Sgaborin points as a decimal fraction can be found in @code{.sr}. This is a 6652219019Sgaborstring-valued read-only number register. 6653219019Sgabor 6654219019SgaborNote that the requested point sizes are device-independent, whereas 6655219019Sgaborthe values returned by the @code{.ps} and @code{.s} registers are not. 6656219019SgaborFor example, if a point size of 11@dmn{pt} is requested for a DVI 6657219019Sgabordevice, 10.95@dmn{pt} are actually used (as specified in the 6658219019Sgabor@file{DESC} file). 6659219019Sgabor 6660219019SgaborBoth registers are associated with the current environment 6661219019Sgabor(@pxref{Environments}). 6662219019Sgabor@endDefreg 6663219019Sgabor 6664219019SgaborThe @code{\s} escape has the following syntax for working with 6665219019Sgaborfractional type sizes: 6666219019Sgabor 6667219019Sgabor@table @code 6668219019Sgabor@item \s[@var{n}] 6669219019Sgabor@itemx \s'@var{n}' 6670219019SgaborSet the point size to @var{n} scaled points; @var{n}@w{ }is a numeric 6671219019Sgaborexpression with a default scale indicator of @samp{z}. 6672219019Sgabor 6673219019Sgabor@item \s[+@var{n}] 6674219019Sgabor@itemx \s[-@var{n}] 6675219019Sgabor@itemx \s+[@var{n}] 6676219019Sgabor@itemx \s-[@var{n}] 6677219019Sgabor@itemx \s'+@var{n}' 6678219019Sgabor@itemx \s'-@var{n}' 6679219019Sgabor@itemx \s+'@var{n}' 6680219019Sgabor@itemx \s-'@var{n}' 6681219019SgaborIncrease or or decrease the point size by @var{n} scaled points; 6682219019Sgabor@var{n} is a numeric expression with a default scale indicator of 6683219019Sgabor@samp{z}. 6684219019Sgabor@end table 6685219019Sgabor 6686219019Sgabor@xref{Font Files}. 6687219019Sgabor 6688219019Sgabor 6689219019Sgabor@c ===================================================================== 6690219019Sgabor 6691219019Sgabor@node Strings, Conditionals and Loops, Sizes, gtroff Reference 6692219019Sgabor@section Strings 6693219019Sgabor@cindex strings 6694219019Sgabor 6695219019Sgabor@code{gtroff} has string variables, which are entirely for user 6696219019Sgaborconvenience (i.e.@: there are no built-in strings exept @code{.T}, but 6697219019Sgaboreven this is a read-write string variable). 6698219019Sgabor 6699219019Sgabor@cindex string interpolation 6700219019Sgabor@cindex string expansion 6701219019Sgabor@cindex interpolation of strings 6702219019Sgabor@cindex expansion of strings 6703219019Sgabor@Defreq {ds, name [@Var{string}]} 6704219019Sgabor@Defescx {\\*, , n, } 6705219019Sgabor@Defescx {\\*, @lparen{}, nm, } 6706219019Sgabor@Defescx {\\*, @lbrack{}, name, @rbrack{}} 6707219019SgaborDefine and access a string variable @var{name} (one-character name 6708219019Sgabor@var{n}, two-character name @var{nm}). If @var{name} already exists, 6709219019Sgabor@code{ds} overwrites the previous definition. 6710219019Sgabor 6711219019SgaborExample: 6712219019Sgabor 6713219019Sgabor@Example 6714219019Sgabor.ds UX \s-1UNIX\s0\u\s-3tm\s0\d 6715219019Sgabor. 6716219019SgaborThe \*(UX Operating System 6717219019Sgabor@endExample 6718219019Sgabor 6719219019SgaborThe @code{\*} escape @dfn{interpolates} (expands in-place) a 6720219019Sgaborpreviously-defined string variable. To be more precise, the stored 6721219019Sgaborstring is pushed onto the input stack which is then parsed by 6722219019Sgabor@code{gtroff}. Similar to number registers, it is possible to nest 6723219019Sgaborstrings, i.e. a string variables can be called within string 6724219019Sgaborvariables. 6725219019Sgabor 6726219019SgaborIf the string named by the @code{\*} does not exist, it is defined as 6727219019Sgaborempty, and a warning of type @samp{mac} is emitted (see 6728219019Sgabor@ref{Debugging}, for more details). 6729219019Sgabor 6730219019Sgabor@cindex comments, with @code{ds} 6731219019Sgabor@strong{Caution:} Unlike other requests, the second argument to the 6732219019Sgabor@code{ds} request takes up the entire line including trailing spaces. 6733219019SgaborThis means that comments on a line with such a request can introduce 6734219019Sgaborunwanted space into a string. 6735219019Sgabor 6736219019Sgabor@Example 6737219019Sgabor.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 6738219019Sgabor@endExample 6739219019Sgabor 6740219019Sgabor@noindent 6741219019SgaborInstead the comment should be put on another line or have the comment 6742219019Sgaborescape adjacent with the end of the string. 6743219019Sgabor 6744219019Sgabor@Example 6745219019Sgabor.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 6746219019Sgabor@endExample 6747219019Sgabor 6748219019Sgabor@cindex trailing quotes 6749219019Sgabor@cindex quotes, trailing 6750219019Sgabor@cindex leading spaces with @code{ds} 6751219019Sgabor@cindex spaces with @code{ds} 6752219019SgaborTo produce leading space the string can be started with a double 6753219019Sgaborquote. No trailing quote is needed; in fact, any trailing quote is 6754219019Sgaborincluded in your string. 6755219019Sgabor 6756219019Sgabor@Example 6757219019Sgabor.ds sign " Yours in a white wine sauce, 6758219019Sgabor@endExample 6759219019Sgabor 6760219019Sgabor@esindex \@key{RET} 6761219019Sgabor@cindex multi-line strings 6762219019Sgabor@cindex strings, multi-line 6763219019Sgabor@cindex newline character in strings, escaping 6764219019Sgabor@cindex escaping newline characters in strings 6765219019SgaborStrings are not limited to a single line of text. A string can span 6766219019Sgaborseveral lines by escaping the newlines with a backslash. The 6767219019Sgaborresulting string is stored @emph{without} the newlines. 6768219019Sgabor 6769219019Sgabor@Example 6770219019Sgabor.ds foo lots and lots \ 6771219019Sgaborof text are on these \ 6772219019Sgabornext several lines 6773219019Sgabor@endExample 6774219019Sgabor 6775219019SgaborIt is not possible to have real newlines in a string. 6776219019Sgabor 6777219019Sgabor@cindex name space of macros and strings 6778219019Sgabor@cindex macros, shared name space with strings 6779219019Sgabor@cindex strings, shared name space with macros 6780219019SgaborStrings, macros, and diversions (and boxes) share the same name space. 6781219019SgaborInternally, even the same mechanism is used to store them. This has 6782219019Sgaborsome interesting consequences. For example, it is possible to call a 6783219019Sgabormacro with string syntax and vice versa. 6784219019Sgabor 6785219019Sgabor@Example 6786219019Sgabor.de xxx 6787219019Sgabora funny test. 6788219019Sgabor.. 6789219019SgaborThis is \*[xxx] 6790219019Sgabor @result{} This is a funny test. 6791219019Sgabor 6792219019Sgabor.ds yyy a funny test 6793219019SgaborThis is 6794219019Sgabor.yyy 6795219019Sgabor @result{} This is a funny test. 6796219019Sgabor@endExample 6797219019Sgabor 6798219019SgaborDiversions and boxes can be also called with string syntax. It is not 6799219019Sgaborpossible to pass arguments to a macro if called with @code{\*}. 6800219019Sgabor 6801219019SgaborAnother consequence is that you can copy one-line diversions or boxes 6802219019Sgaborto a string. 6803219019Sgabor 6804219019Sgabor@Example 6805219019Sgabor.di xxx 6806219019Sgabora \fItest\fR 6807219019Sgabor.br 6808219019Sgabor.di 6809219019Sgabor.ds yyy This is \*[xxx]\c 6810219019Sgabor\*[yyy]. 6811219019Sgabor @result{} @r{This is a }@i{test}. 6812219019Sgabor@endExample 6813219019Sgabor 6814219019Sgabor@noindent 6815219019SgaborAs the previous example shows, it is possible to store formatted 6816219019Sgaboroutput in strings. The @code{\c} escape prevents the insertion of an 6817219019Sgaboradditional blank line in the output. 6818219019Sgabor 6819219019SgaborCopying diversions longer than a single output line produces 6820219019Sgaborunexpected results. 6821219019Sgabor 6822219019Sgabor@Example 6823219019Sgabor.di xxx 6824219019Sgabora funny 6825219019Sgabor.br 6826219019Sgabortest 6827219019Sgabor.br 6828219019Sgabor.di 6829219019Sgabor.ds yyy This is \*[xxx]\c 6830219019Sgabor\*[yyy]. 6831219019Sgabor @result{} test This is a funny. 6832219019Sgabor@endExample 6833219019Sgabor 6834219019SgaborUsually, it is not predictable whether a diversion contains one or 6835219019Sgabormore output lines, so this mechanism should be avoided. With 6836219019Sgabor@acronym{UNIX} @code{troff}, this was the only solution to strip off a 6837219019Sgaborfinal newline from a diversion. Another disadvantage is that the 6838219019Sgaborspaces in the copied string are already formatted, making them 6839219019Sgaborunstretchable. This can cause ugly results. 6840219019Sgabor 6841219019Sgabor@rqindex chop 6842219019Sgabor@rqindex unformat 6843219019SgaborA clean solution to this problem is available in GNU @code{troff}, 6844219019Sgaborusing the requests @code{chop} to remove the final newline of a 6845219019Sgabordiversion, and @code{unformat} to make the horizontal spaces 6846219019Sgaborstretchable again. 6847219019Sgabor 6848219019Sgabor@Example 6849219019Sgabor.box xxx 6850219019Sgabora funny 6851219019Sgabor.br 6852219019Sgabortest 6853219019Sgabor.br 6854219019Sgabor.box 6855219019Sgabor.chop xxx 6856219019Sgabor.unformat xxx 6857219019SgaborThis is \*[xxx]. 6858219019Sgabor @result{} This is a funny test. 6859219019Sgabor@endExample 6860219019Sgabor 6861219019Sgabor@xref{Gtroff Internals}, for more information. 6862219019Sgabor@endDefreq 6863219019Sgabor 6864219019Sgabor@cindex appending to strings 6865219019Sgabor@cindex strings, appending 6866219019Sgabor@Defreq {as, name [@Var{string}]} 6867219019SgaborThe @code{as} request is similar to @code{ds} but appends @var{string} 6868219019Sgaborto the string stored as @var{name} instead of redefining it. If 6869219019Sgabor@var{name} doesn't exist yet, it is created. 6870219019Sgabor 6871219019Sgabor@Example 6872219019Sgabor.as sign " with shallots, onions and garlic, 6873219019Sgabor@endExample 6874219019Sgabor@endDefreq 6875219019Sgabor 6876219019SgaborRudimentary string manipulation routines are given with the next two 6877219019Sgaborrequests. 6878219019Sgabor 6879219019Sgabor@cindex substring 6880219019Sgabor@Defreq {substring, str n1 [@Var{n2}]} 6881219019SgaborReplace the string in register@w{ }@var{str} with the substring 6882219019Sgabordefined by the indices @var{n1} and@w{ }@var{n2}. The first character 6883219019Sgaborin the string has index one. If @var{n2} is omitted, it is taken to 6884219019Sgaborbe equal to the string's length. If the index value @var{n1} or 6885219019Sgabor@var{n2} is negative or zero, it is counted from the end of the 6886219019Sgaborstring, going backwards: The last character has index@w{ }0, the 6887219019Sgaborcharacter before the last character has index@w{ }@minus{}1, etc. 6888219019Sgabor 6889219019Sgabor@Example 6890219019Sgabor.ds xxx abcdefgh 6891219019Sgabor.substring xxx 2 -3 6892219019Sgabor\*[xxx] 6893219019Sgabor @result{} bcde 6894219019Sgabor@endExample 6895219019Sgabor@endDefreq 6896219019Sgabor 6897219019Sgabor@cindex length of a string 6898219019Sgabor@cindex string, length of 6899219019Sgabor@Defreq {length, reg str} 6900219019SgaborCompute the length of @var{str} and returns it in the number 6901219019Sgaborregister@w{ }@var{reg}. If @var{reg} doesn't exist, it is created. 6902219019Sgabor 6903219019Sgabor@Example 6904219019Sgabor.ds xxx abcdefgh 6905219019Sgabor.length yyy xxx 6906219019Sgabor\n[yyy] 6907219019Sgabor @result{} 8 6908219019Sgabor@endExample 6909219019Sgabor@endDefreq 6910219019Sgabor 6911219019Sgabor@cindex rename request 6912219019Sgabor@cindex rename macro 6913219019Sgabor@cindex rename string 6914219019Sgabor@Defreq {rn, xx yy} 6915219019SgaborRename the request, macro, or string @var{xx} to @var{yy}. 6916219019Sgabor@endDefreq 6917219019Sgabor 6918219019Sgabor@cindex remove request 6919219019Sgabor@cindex remove macro 6920219019Sgabor@cindex remove string 6921219019Sgabor@Defreq {rm, xx} 6922219019SgaborRemove the request, macro, or string @var{xx}. @code{gtroff} treats 6923219019Sgaborsubsequent invocations as if the object had never been defined. 6924219019Sgabor@endDefreq 6925219019Sgabor 6926219019Sgabor@cindex alias 6927219019Sgabor@Defreq {als, new old} 6928219019SgaborCreate an alias named @var{new} for the request, string, macro, or 6929219019Sgabordiversion object named @var{old}. The new name and the old name are 6930219019Sgaborexactly equivalent (it is similar to a hard rather than a soft 6931219019Sgaborlink). If @var{old} is undefined, @code{gtroff} generates a warning of 6932219019Sgabortype @samp{mac} and ignores the request. 6933219019Sgabor@endDefreq 6934219019Sgabor 6935219019Sgabor@Defreq {chop, xx} 6936219019SgaborRemove (chop) the last character from the macro, string, or diversion 6937219019Sgabornamed @var{xx}. This is useful for removing the newline from the end 6938219019Sgaborof diversions that are to be interpolated as strings. This command 6939219019Sgaborcan be used repeatedly; see @ref{Gtroff Internals}, for details on 6940219019Sgabornodes inserted by @code{gtroff} automatically. 6941219019Sgabor@endDefreq 6942219019Sgabor 6943219019Sgabor@xref{Identifiers}, and @ref{Comments}. 6944219019Sgabor 6945219019Sgabor 6946219019Sgabor@c ===================================================================== 6947219019Sgabor 6948219019Sgabor@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 6949219019Sgabor@section Conditionals and Loops 6950219019Sgabor@cindex conditionals and loops 6951219019Sgabor@cindex loops and conditionals 6952219019Sgabor 6953219019Sgabor@menu 6954219019Sgabor* Operators in Conditionals:: 6955219019Sgabor* if-else:: 6956219019Sgabor* while:: 6957219019Sgabor@end menu 6958219019Sgabor 6959219019Sgabor@c --------------------------------------------------------------------- 6960219019Sgabor 6961219019Sgabor@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 6962219019Sgabor@subsection Operators in Conditionals 6963219019Sgabor 6964219019Sgabor@rqindex if 6965219019Sgabor@rqindex while 6966219019Sgabor@cindex @code{if}, operators to use with it 6967219019Sgabor@cindex @code{while}, operators to use with it 6968219019SgaborIn @code{if} and @code{while} requests, there are several more 6969219019Sgaboroperators available: 6970219019Sgabor 6971219019Sgabor@table @code 6972219019Sgabor@item e 6973219019Sgabor@itemx o 6974219019SgaborTrue if the current page is even or odd numbered (respectively). 6975219019Sgabor 6976219019Sgabor@item n 6977219019Sgabor@rqindex nroff 6978219019SgaborTrue if the document is being processed in nroff mode (i.e., the 6979219019Sgabor@code{.nroff} command has been issued). 6980219019Sgabor 6981219019Sgabor@item t 6982219019Sgabor@rqindex troff 6983219019SgaborTrue if the document is being processed in troff mode (i.e., the 6984219019Sgabor@code{.troff} command has been issued). 6985219019Sgabor 6986219019Sgabor@item v 6987219019SgaborAlways false. 6988219019Sgabor 6989219019Sgabor@item '@var{xxx}'@var{yyy}' 6990219019SgaborTrue if the string @var{xxx} is equal to the string @var{yyy}. Other 6991219019Sgaborcharacters can be used in place of the single quotes; the same set of 6992219019Sgabordelimiters as for the @code{\D} escape is used (@pxref{Escapes}). 6993219019Sgabor@code{gtroff} formats the strings before being compared: 6994219019Sgabor 6995219019Sgabor@Example 6996219019Sgabor.ie "|"\fR|\fP" \ 6997219019Sgabortrue 6998219019Sgabor.el \ 6999219019Sgaborfalse 7000219019Sgabor @result{} true 7001219019Sgabor@endExample 7002219019Sgabor 7003219019Sgabor@noindent 7004219019SgaborThe resulting motions, character sizes, and fonts have to 7005219019Sgabormatch,@footnote{The created output nodes must be identical. 7006219019Sgabor@xref{Gtroff Internals}.} and not the individual motion, size, and 7007219019Sgaborfont requests. In the previous example, @samp{|} and @samp{\fR|\fP} 7008219019Sgaborboth result in a roman @samp{|} character with the same point size and 7009219019Sgaborat the same location on the page, so the strings are equal. If 7010219019Sgabor@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result 7011219019Sgaborwould be ``false'' because (the first) @samp{|} produces an italic 7012219019Sgabor@samp{|} rather than a roman one. 7013219019Sgabor 7014219019Sgabor@item r @var{xxx} 7015219019SgaborTrue if there is a number register named @var{xxx}. 7016219019Sgabor 7017219019Sgabor@item d @var{xxx} 7018219019SgaborTrue if there is a string, macro, diversion, or request named @var{xxx}. 7019219019Sgabor 7020219019Sgabor@item c @var{ch} 7021219019Sgabor@rqindex char 7022219019SgaborTrue if there is a character @var{ch} available; @var{ch} is either an 7023219019Sgabor@acronym{ASCII} character or a special character (@code{\(@var{ch}} or 7024219019Sgabor@code{\[@var{ch}]}); the condition is also true if @var{ch} has been 7025219019Sgabordefined by the @code{char} request. 7026219019Sgabor@end table 7027219019Sgabor 7028219019SgaborNote that these operators can't be combined with other operators like 7029219019Sgabor@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 7030219019Sgaborbetween the exclamation mark and the operator) can be used to negate 7031219019Sgaborthe result. 7032219019Sgabor 7033219019Sgabor@Example 7034219019Sgabor.nr xxx 1 7035219019Sgabor.ie !r xxx \ 7036219019Sgabortrue 7037219019Sgabor.el \ 7038219019Sgaborfalse 7039219019Sgabor @result{} false 7040219019Sgabor@endExample 7041219019Sgabor 7042219019SgaborA whitespace after @samp{!} always evaluates to zero (this bizarre 7043219019Sgaborbehaviour is due to compatibility with @acronym{UNIX} @code{troff}). 7044219019Sgabor 7045219019Sgabor@Example 7046219019Sgabor.nr xxx 1 7047219019Sgabor.ie ! r xxx \ 7048219019Sgabortrue 7049219019Sgabor.el \ 7050219019Sgaborfalse 7051219019Sgabor @result{} r xxx true 7052219019Sgabor@endExample 7053219019Sgabor 7054219019SgaborIt is possible to omit the whitespace before the argument to the 7055219019Sgabor@samp{r}, @samp{d}, and @samp{c} operators. 7056219019Sgabor 7057219019Sgabor@xref{Expressions}. 7058219019Sgabor 7059219019Sgabor@c --------------------------------------------------------------------- 7060219019Sgabor 7061219019Sgabor@node if-else, while, Operators in Conditionals, Conditionals and Loops 7062219019Sgabor@subsection if-else 7063219019Sgabor@cindex if-else 7064219019Sgabor 7065219019Sgabor@code{gtroff} has if-then-else constructs like other languages, although 7066219019Sgaborthe formatting can be painful. 7067219019Sgabor 7068219019Sgabor@Defreq {if, expr anything} 7069219019SgaborEvaluate the expression @var{expr}, and executes @var{anything} (the 7070219019Sgaborremainder of the line) if @var{expr} evaluates to non-zero (true). 7071219019Sgabor@var{anything} is interpreted as though it was on a line by itself 7072219019Sgabor(except that leading spaces are swallowed). @xref{Expressions}, for 7073219019Sgabormore info. 7074219019Sgabor 7075219019Sgabor@Example 7076219019Sgabor.nr xxx 1 7077219019Sgabor.nr yyy 2 7078219019Sgabor.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 7079219019Sgabor @result{} true 7080219019Sgabor@endExample 7081219019Sgabor@endDefreq 7082219019Sgabor 7083219019Sgabor@c XXX .nop request 7084219019Sgabor 7085219019Sgabor@Defreq {ie, expr anything} 7086219019Sgabor@Defreqx {el, anything} 7087219019SgaborUse the @code{ie} and @code{el} requests to write an if-then-else. 7088219019SgaborThe first request is the `if' part and the latter is the `else' part. 7089219019Sgabor 7090219019Sgabor@Example 7091219019Sgabor.ie n .ls 2 \" double spacing in nroff 7092219019Sgabor.el .ls 1 \" single spacing in troff 7093219019Sgabor@endExample 7094219019Sgabor@endDefreq 7095219019Sgabor 7096219019Sgabor@c this is a bug in makeinfo: you can't have `@{' as an argument 7097219019Sgabor@c to deffn 7098219019Sgabor 7099219019Sgabor@esindex \@{ 7100219019Sgabor@esindex \@} 7101219019Sgabor@c @Defesc {\\@@@{, , , } 7102219019Sgabor@c @Defescx {\\@@@}, , , } 7103219019SgaborIn many cases, an if (or if-else) construct needs to execute more than 7104219019Sgaborone request. This can be done using the @code{\@{} and @code{\@}} 7105219019Sgaborescapes. The following example shows the possible ways to use these 7106219019Sgaborescapes (note the position of the opening and closing braces). 7107219019Sgabor 7108219019Sgabor@Example 7109219019Sgabor.ie t \@{\ 7110219019Sgabor. ds lq `` 7111219019Sgabor. ds rq '' 7112219019Sgabor.\@} 7113219019Sgabor.el \ 7114219019Sgabor.\@{\ 7115219019Sgabor. ds lq " 7116219019Sgabor. ds rq "\@} 7117219019Sgabor@endExample 7118219019Sgabor@c @endDefesc 7119219019Sgabor 7120219019Sgabor@xref{Expressions}. 7121219019Sgabor 7122219019Sgabor@c --------------------------------------------------------------------- 7123219019Sgabor 7124219019Sgabor@node while, , if-else, Conditionals and Loops 7125219019Sgabor@subsection while 7126219019Sgabor@cindex while 7127219019Sgabor 7128219019Sgabor@code{gtroff} provides a looping construct using the @code{while} 7129219019Sgaborrequest, which is used much like the @code{if} (and related) requests. 7130219019Sgabor 7131219019Sgabor@Defreq {while, expr anything} 7132219019SgaborEvaluate the expression @var{expr}, and repeatedly execute 7133219019Sgabor@var{anything} (the remainder of the line) until @var{expr} evaluates 7134219019Sgaborto@w{ }0. 7135219019Sgabor 7136219019Sgabor@Example 7137219019Sgabor.nr a 0 1 7138219019Sgabor.while (\na < 9) \@{\ 7139219019Sgabor\n+a, 7140219019Sgabor.\@} 7141219019Sgabor\n+a 7142219019Sgabor @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 7143219019Sgabor@endExample 7144219019Sgabor 7145219019SgaborSome remarks. 7146219019Sgabor 7147219019Sgabor@rqindex de 7148219019Sgabor@itemize @bullet 7149219019Sgabor@item 7150219019SgaborThe body of a @code{while} request is treated like the body of a 7151219019Sgabor@code{de} request: @code{gtroff} temporarily stores it in a macro 7152219019Sgaborwhich is deleted after the loop has been exited. It can considerably 7153219019Sgaborslow down a macro if the body of the @code{while} request (within the 7154219019Sgabormacro) is large. Each time the macro is executed, the @code{while} 7155219019Sgaborbody is parsed and stored again as a temporary macro. 7156219019Sgabor 7157219019Sgabor@Example 7158219019Sgabor.de xxx 7159219019Sgabor. nr num 10 7160219019Sgabor. while (\\n[num] > 0) \@{\ 7161219019Sgabor. \" many lines of code 7162219019Sgabor. nr num -1 7163219019Sgabor. \@} 7164219019Sgabor.. 7165219019Sgabor@endExample 7166219019Sgabor 7167219019Sgabor@cindex recursive macros 7168219019Sgabor@cindex macros, recursive 7169219019Sgabor@noindent 7170219019SgaborThe traditional and ofter better solution (@acronym{UNIX} @code{troff} 7171219019Sgabordoesn't have the @code{while} request) is to use a recursive macro 7172219019Sgaborinstead which is parsed only once during its definition. 7173219019Sgabor 7174219019Sgabor@Example 7175219019Sgabor.de yyy 7176219019Sgabor. if (\\n[num] > 0) \@{\ 7177219019Sgabor. \" many lines of code 7178219019Sgabor. nr num -1 7179219019Sgabor. yyy 7180219019Sgabor. \@} 7181219019Sgabor.. 7182219019Sgabor. 7183219019Sgabor.de xxx 7184219019Sgabor. nr num 10 7185219019Sgabor. yyy 7186219019Sgabor.. 7187219019Sgabor@endExample 7188219019Sgabor 7189219019Sgabor@noindent 7190219019SgaborNote that the number of available recursion levels is set to@w{ }1000 7191219019Sgabor(this is a compile-time constant value of @code{gtroff}). 7192219019Sgabor 7193219019Sgabor@item 7194219019SgaborThe closing brace of a @code{while} body must end a line. 7195219019Sgabor 7196219019Sgabor@Example 7197219019Sgabor.if 1 \@{\ 7198219019Sgabor. nr a 0 1 7199219019Sgabor. while (\n[a] < 10) \@{\ 7200219019Sgabor. nop \n+[a] 7201219019Sgabor.\@}\@} 7202219019Sgabor @result{} unbalanced \@{ \@} 7203219019Sgabor@endExample 7204219019Sgabor@end itemize 7205219019Sgabor@endDefreq 7206219019Sgabor 7207219019Sgabor@rqindex while 7208219019Sgabor@cindex @code{break}, in a @code{while} loop 7209219019Sgabor@cindex @code{continue}, in a @code{while} loop 7210219019Sgabor@Defreq {break, } 7211219019SgaborBreak out of a @code{while} loop. Be sure not to confuse this with 7212219019Sgaborthe @code{br} request (causing a line break). 7213219019Sgabor@endDefreq 7214219019Sgabor 7215219019Sgabor@Defreq {continue, } 7216219019SgaborFinishes the current iteration of a @code{while} loop, immediately 7217219019Sgaborrestarting the next iteration. 7218219019Sgabor@endDefreq 7219219019Sgabor 7220219019Sgabor@xref{Expressions}. 7221219019Sgabor 7222219019Sgabor 7223219019Sgabor@c ===================================================================== 7224219019Sgabor 7225219019Sgabor@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 7226219019Sgabor@section Writing Macros 7227219019Sgabor@cindex writing macros 7228219019Sgabor@cindex macros, writing 7229219019Sgabor 7230219019SgaborA @dfn{macro} is a collection of text and embedded commands which can 7231219019Sgaborbe invoked multiple times. Use macros to define common operations. 7232219019Sgabor 7233219019Sgabor@Defreq {de, name [@Var{end}]} 7234219019SgaborDefine a new macro named @var{name}. @code{gtroff} copies subsequent 7235219019Sgaborlines (starting with the next one) into an internal buffer until it 7236219019Sgaborencounters the line @samp{..} (two dots). The optional second 7237219019Sgaborargument to @code{de} changes this to a macro to @samp{.@var{end}}. 7238219019Sgabor 7239219019SgaborNote that no leading whitespace is allowed in the line containing the 7240219019Sgaborending token (either @samp{..} or the macro @samp{.@var{end}}). 7241219019Sgabor 7242219019SgaborHere a small example macro called @samp{P} which causes a break and 7243219019Sgaborinserts some vertical space. It could be used to separate paragraphs. 7244219019Sgabor 7245219019Sgabor@Example 7246219019Sgabor.de P 7247219019Sgabor. br 7248219019Sgabor. sp .8v 7249219019Sgabor.. 7250219019Sgabor@endExample 7251219019Sgabor 7252219019Sgabor@c XXX add info about macro definitions in macros. 7253219019Sgabor 7254219019Sgabor@c XXX give example for end macro. 7255219019Sgabor 7256219019Sgabor@c XXX add info about indirect macro calls: 7257219019Sgabor@c 7258219019Sgabor@c .de xxx 7259219019Sgabor@c from yyy\c 7260219019Sgabor@c .. 7261219019Sgabor@c 7262219019Sgabor@c test \*[xxx] test 7263219019Sgabor@c => test from yyy test 7264219019Sgabor 7265219019Sgabor@c XXX info about common identifier pool for strings, macros, and 7266219019Sgabor@c diversions. 7267219019Sgabor@endDefreq 7268219019Sgabor 7269219019Sgabor@cindex appending, to a macro 7270219019Sgabor@Defreq {am, xx} 7271219019SgaborWorks similarly to @code{de} except it appends onto the macro named 7272219019Sgabor@var{xx}. So, to make the previously defined @samp{P} macro actually 7273219019Sgabordo indented instead of block paragraphs, add the necessary code to the 7274219019Sgaborexisting macro like this: 7275219019Sgabor 7276219019Sgabor@Example 7277219019Sgabor.am P 7278219019Sgabor.ti +5n 7279219019Sgabor.. 7280219019Sgabor@endExample 7281219019Sgabor@endDefreq 7282219019Sgabor 7283219019Sgabor@cindex alias 7284219019Sgabor@Defreq {als, new old} 7285219019SgaborCreate an alias named @var{new} for the request, string, macro, or 7286219019Sgabordiversion object named @var{old}. The new name and the old name are 7287219019Sgaborexactly equivalent (it is similar to a hard rather than a soft 7288219019Sgaborlink). If @var{old} is undefined, @code{gtroff} generates a warning of 7289219019Sgabortype @samp{mac} and ignores the request. 7290219019Sgabor 7291219019SgaborThe @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, 7292219019Sgaborand @code{as} requests only create a new object if the name 7293219019Sgaborof the macro, diversion or string diversion is currently 7294219019Sgaborundefined or if it is defined to be a request; normally 7295219019Sgaborthey modify the value of an existing object. 7296219019Sgabor@endDefreq 7297219019Sgabor 7298219019Sgabor@menu 7299219019Sgabor* Copy-in Mode:: 7300219019Sgabor* Parameters:: 7301219019Sgabor@end menu 7302219019Sgabor 7303219019Sgabor@c --------------------------------------------------------------------- 7304219019Sgabor 7305219019Sgabor@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 7306219019Sgabor@subsection Copy-in Mode 7307219019Sgabor@cindex copy-in mode 7308219019Sgabor@cindex mode, copy-in 7309219019Sgabor 7310219019Sgabor@esindex \n 7311219019Sgabor@esindex \$ 7312219019Sgabor@esindex \* 7313219019Sgabor@esindex \\ 7314219019Sgabor@esindex \@key{RET} 7315219019Sgabor@cindex @code{\n}, when reading text for a macro 7316219019Sgabor@cindex @code{\$}, when reading text for a macro 7317219019Sgabor@cindex @code{\*}, when reading text for a macro 7318219019Sgabor@cindex @code{\\}, when reading text for a macro 7319219019Sgabor@cindex \@key{RET}, when reading text for a macro 7320219019SgaborWhen @code{gtroff} reads in the text for a macro or diversion, it copies 7321219019Sgaborthe text (including request lines, but excluding escapes) into an 7322219019Sgaborinternal buffer. Escapes are converted into an internal form, 7323219019Sgaborexcept for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 7324219019Sgabor@code{\@key{RET}} which are evaluated and inserted into the text where 7325219019Sgaborthe escape was located. This is known as @dfn{copy-in} mode or 7326219019Sgabor@dfn{copy} mode. 7327219019Sgabor 7328219019SgaborWhat this means is that you can specify when these escapes are to be 7329219019Sgaborevaluated (either at copy-in time or at the time of use) by insulating 7330219019Sgaborthe escapes with an extra backslash. Compare this to the @code{\def} 7331219019Sgaborand @code{\edef} commands in @TeX{}. 7332219019Sgabor 7333219019SgaborThe following example prints the numbers 20 and@w{ }10: 7334219019Sgabor 7335219019Sgabor@Example 7336219019Sgabor.nr x 20 7337219019Sgabor.de y 7338219019Sgabor.nr x 10 7339219019Sgabor\&\nx 7340219019Sgabor\&\\nx 7341219019Sgabor.. 7342219019Sgabor.y 7343219019Sgabor@endExample 7344219019Sgabor 7345219019Sgabor@c --------------------------------------------------------------------- 7346219019Sgabor 7347219019Sgabor@node Parameters, , Copy-in Mode, Writing Macros 7348219019Sgabor@subsection Parameters 7349219019Sgabor@cindex parameters 7350219019Sgabor 7351219019Sgabor@vindex .$ 7352219019SgaborThe arguments to a macro can be examined using a variety of escapes. 7353219019SgaborThe number of arguments is available in the @code{.$} number register. 7354219019SgaborAny individual argument can be retrieved with one of the following 7355219019Sgaborescapes: 7356219019Sgabor 7357219019Sgabor@cindex copy-in mode, and macro arguments 7358219019Sgabor@Defesc {\\$, n, , } 7359219019Sgabor@Defescx {\\$, @lparen{}, nn, } 7360219019Sgabor@Defescx {\\$, @lbrack{}, nnn, @rbrack{}} 7361219019SgaborThe escapes @code{\$@var{n}}, @code{\$(@var{nn}} and 7362219019Sgabor@code{\$[@var{nnn}]} retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or 7363219019Sgabor@var{nnn}@dmn{th} argument. As usual, the first form only accepts a 7364219019Sgaborsingle number (larger than zero), the second a two-digit number (larger 7365219019Sgaboror equal to@w{ }10), and the third any positive integer value (larger 7366219019Sgaborthan zero). Macros can have an unlimited number of arguments. Note 7367219019Sgaborthat due to copy-in mode, use two backslashes on these in actual use to 7368219019Sgaborprevent interpolation until the macro is actually invoked. 7369219019Sgabor@endDefesc 7370219019Sgabor 7371219019Sgabor@Defreq {shift, [@Var{n}]} 7372219019SgaborShifts the arguments 1@w{ }position, or as 7373219019Sgabormany positions as specified by its argument. After executing this 7374219019Sgaborrequest, argument@w{ }@var{i} becomes argument @var{i}-@var{n}; 7375219019Sgaborarguments 1 to@w{ }@var{n} are no longer available. Shifting by 7376219019Sgabornegative amounts is currently undefined. 7377219019Sgabor@endDefreq 7378219019Sgabor 7379219019Sgabor@Defesc {\\$*, , , } 7380219019Sgabor@Defescx {\\$@@, , , } 7381219019SgaborIn some cases it is convenient to use all of the arguments at once (for 7382219019Sgaborexample, to pass the arguments along to another macro). The @code{\$*} 7383219019Sgaborescape concatenates all the arguments separated by spaces. A 7384219019Sgaborsimilar escape is @code{\$@@}, which concatenates all the 7385219019Sgaborarguments with each surrounded by double quotes, and separated by 7386219019Sgaborspaces. 7387219019Sgabor@endDefesc 7388219019Sgabor 7389219019Sgabor@rqindex als 7390219019Sgabor@cindex @code{als}, use with @code{\$0} 7391219019Sgabor@Defesc {\\$0, , , } 7392219019SgaborThe name used to invoke the current macro. 7393219019SgaborThe @code{als} request can make a macro have more than one name. 7394219019Sgabor 7395219019Sgabor@Example 7396219019Sgabor.de vl 7397219019Sgabor.ie \\n(.$=1 .ds Vl Pre-Release Version 7398219019Sgabor.el .ds Vl Version \\$3, \\$4. 7399219019Sgabor.. 7400219019Sgabor@endExample 7401219019Sgabor 7402219019Sgabor@noindent 7403219019SgaborThis would be called as 7404219019Sgabor 7405219019Sgabor@Example 7406219019Sgabor.vl $Id: groff.texinfo,v 1.77 2001/05/07 13:36:24 wlemb Exp $ 7407219019Sgabor@endExample 7408219019Sgabor@endDefesc 7409219019Sgabor 7410219019Sgabor@xref{Request Arguments}. 7411219019Sgabor 7412219019Sgabor 7413219019Sgabor@c ===================================================================== 7414219019Sgabor 7415219019Sgabor@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 7416219019Sgabor@section Page Motions 7417219019Sgabor@cindex page motions 7418219019Sgabor@cindex motions, page 7419219019Sgabor 7420219019Sgabor@cindex @code{sp}, as vertical page motion 7421219019Sgabor@Defreq {sp, [@Var{len}]} 7422219019SgaborMotions up and down the page can be done with the @code{sp} request. 7423219019SgaborHowever, this causes a break so that the actual effect is to move to the 7424219019Sgaborleft margin and then to the specified location. 7425219019Sgabor@endDefreq 7426219019Sgabor 7427219019Sgabor@Defreq {mk, [@Var{reg}]} 7428219019Sgabor@Defreqx {rt, reg} 7429219019SgaborThe request @code{mk} can be used to mark a location on a page, for 7430219019Sgabormovement to later. This request takes a register name as an argument in 7431219019Sgaborwhich to store the current page location. With no argument it 7432219019Sgaborstores the location in an internal register. The results of this can be 7433219019Sgaborused later by the @code{rt} or the @code{sp} request. The @code{rt} 7434219019Sgaborrequest returns @emph{upwards} to the location given in the register 7435219019Sgaborname given as an argument; with no argument it returns to the 7436219019Sgaborlocation marked with the @code{mk} request. 7437219019Sgabor 7438219019Sgabor@c XXX example 7439219019Sgabor@ignore 7440219019Sgabor@Example 7441219019Sgabor... dual column example ... 7442219019Sgabor@endExample 7443219019Sgabor@end ignore 7444219019Sgabor@endDefreq 7445219019Sgabor 7446219019SgaborThe following escapes give fine control of movements about the page. 7447219019Sgabor 7448219019Sgabor@cindex vertical motion 7449219019Sgabor@cindex motion, vertical 7450219019Sgabor@Defesc {\\v, ', e, '} 7451219019SgaborThe @code{\v'@var{e}'} escape enables arbitrary vertical motion from the 7452219019Sgaborcurrent location on the page. The argument@w{ }@var{e} specifies the 7453219019Sgabordistance to move; positive is downwards and negative upwards. The 7454219019Sgabordefault unit for this escape @samp{v}. Beware, however, that 7455219019Sgabor@code{gtroff} continues text processing at the point where the motion 7456219019Sgaborends, so you should always balance motions to avoid interference with 7457219019Sgabortext processing. 7458219019Sgabor@endDefesc 7459219019Sgabor 7460219019SgaborThere are some special case escapes for vertical motion. 7461219019Sgabor 7462219019Sgabor@ftable @code 7463219019Sgabor@item \r 7464219019Sgabormove upwards@w{ }1@dmn{v}. 7465219019Sgabor 7466219019Sgabor@item \u 7467219019Sgabormove upwards@w{ }.5@dmn{v}. 7468219019Sgabor 7469219019Sgabor@item \d 7470219019Sgabormove down@w{ }.5@dmn{v}. 7471219019Sgabor@end ftable 7472219019Sgabor 7473219019Sgabor@cindex inserting horizontal space 7474219019Sgabor@cindex horizontal space 7475219019Sgabor@cindex space, horizontal 7476219019Sgabor@Defesc {\\h, ', e, '} 7477219019SgaborThe @code{\h'@var{e}'} escape provides horizontal motions. The 7478219019Sgaborexpression@w{ }@var{e} indicates how far to move: positive is rightwards 7479219019Sgaborand negative leftwards. 7480219019Sgabor@c XXX Is there a default unit for this? 7481219019Sgabor@endDefesc 7482219019Sgabor 7483219019SgaborThere are a number of special case escapes for horizontal motion: 7484219019Sgabor 7485219019Sgabor@ftable @code 7486219019Sgabor@item \@key{SP} 7487219019SgaborAn unbreakable and unpaddable (i.e.@: not expanded during filling) 7488219019Sgaborspace. (Note: This is a backslash followed by a space.) 7489219019Sgabor 7490219019Sgabor@item \~ 7491219019SgaborAn unbreakable space that stretches like a normal inter-word space 7492219019Sgaborwhen a line is adjusted. 7493219019Sgabor 7494219019Sgabor@item \| 7495219019SgaborA 1/6@dmn{th} em space. Ignored for tty output devices (rounded to 7496219019Sgaborzero). 7497219019Sgabor 7498219019Sgabor@item \^ 7499219019SgaborA 1/12@dmn{th} em space. Ignored for tty output devices (rounded to 7500219019Sgaborzero). 7501219019Sgabor 7502219019Sgabor@item \0 7503219019SgaborA space the size of a digit. 7504219019Sgabor 7505219019Sgabor@item \& 7506219019Sgabor@cindex zero width space character 7507219019Sgabor@cindex character, zero width space 7508219019Sgabor@cindex space character, zero width 7509219019SgaborA zero width space. 7510219019Sgabor 7511219019Sgabor@item \) 7512219019SgaborLike @code{\&} except that it behaves like a character declared with the 7513219019Sgabor@code{cflags} request to be transparent for the purposes of end of 7514219019Sgaborsentence recognition. 7515219019Sgabor@end ftable 7516219019Sgabor 7517219019SgaborThe following string sets the @TeX{} logo: 7518219019Sgabor 7519219019Sgabor@Example 7520219019Sgabor.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 7521219019Sgabor@endExample 7522219019Sgabor 7523219019Sgabor@cindex width escape 7524219019Sgabor@cindex escape, width 7525219019Sgabor@Defesc {\\w, ', text, '} 7526219019SgaborUsed as @code{\w'@var{text}'}, 7527219019Sgaborreturns the width of the specified @var{text} in basic units. 7528219019SgaborThis allows horizontal movement based on the width of some 7529219019Sgaborarbitrary text (e.g.@: given as an argument to a macro). 7530219019Sgabor 7531219019Sgabor@c XXX example 7532219019Sgabor 7533219019Sgabor@ignore 7534219019Sgabor@Example 7535219019Sgabor... strlen example ... 7536219019Sgabor@endExample 7537219019Sgabor@end ignore 7538219019Sgabor 7539219019SgaborFont changes may occur in @var{text} which don't affect current 7540219019Sgaborsettings. 7541219019Sgabor 7542219019SgaborAfter use, @code{\w} sets several registers: 7543219019Sgabor 7544219019Sgabor@table @code 7545219019Sgabor@item st 7546219019Sgabor@itemx sb 7547219019Sgabor@vindex st 7548219019Sgabor@vindex sb 7549219019SgaborThe highest and lowest point, respectively, in @var{text}. 7550219019Sgabor 7551219019Sgabor@item rst 7552219019Sgabor@itemx rsb 7553219019Sgabor@vindex rst 7554219019Sgabor@vindex rsb 7555219019SgaborLike the @code{st} and @code{sb} registers, but takes account of the 7556219019Sgaborheights and depths of characters. 7557219019Sgabor 7558219019Sgabor@item ct 7559219019Sgabor@vindex ct 7560219019SgaborDefines the kinds of characters occurring in @var{text}: 7561219019Sgabor 7562219019Sgabor@table @asis 7563219019Sgabor@item 0 7564219019Sgaboronly short characters, no descenders or tall characters. 7565219019Sgabor 7566219019Sgabor@item 1 7567219019Sgaborat least one descender. 7568219019Sgabor 7569219019Sgabor@item 2 7570219019Sgaborat least one tall character. 7571219019Sgabor 7572219019Sgabor@item 3 7573219019Sgaborat least one each of a descender and a tall character. 7574219019Sgabor@end table 7575219019Sgabor 7576219019Sgabor@item ssc 7577219019Sgabor@vindex ssc 7578219019SgaborThe amount of horizontal space (possibly negative) that should be added 7579219019Sgaborto the last character before a subscript. 7580219019Sgabor 7581219019Sgabor@item skw 7582219019Sgabor@vindex skw 7583219019SgaborHow far to right of the center of the last character in the @code{\w} 7584219019Sgaborargument, the center of an accent from a roman font should be placed 7585219019Sgaborover that character. 7586219019Sgabor@end table 7587219019Sgabor@endDefesc 7588219019Sgabor 7589219019Sgabor@Defesc {\\k, ', x, '} 7590219019SgaborStores the current horizontal position in register @var{x}. 7591219019SgaborUse this, for example, to return to the beginning of a string 7592219019Sgaborfor highlighting or other decoration. 7593219019Sgabor@endDefesc 7594219019Sgabor 7595219019Sgabor@Defreg {.k} 7596219019SgaborA read-only number register containing the current horizontal output 7597219019Sgaborposition. 7598219019Sgabor@endDefreg 7599219019Sgabor 7600219019Sgabor@c XXX documentation 7601219019Sgabor 7602219019Sgabor 7603219019Sgabor@c ===================================================================== 7604219019Sgabor 7605219019Sgabor@node Drawing Requests, Traps, Page Motions, gtroff Reference 7606219019Sgabor@section Drawing Requests 7607219019Sgabor@cindex drawing requests 7608219019Sgabor@cindex requests for drawing 7609219019Sgabor 7610219019Sgabor@code{gtroff} provides a number of ways to draw lines and other figures 7611219019Sgaboron the page. Used in combination with the page motion commands (see 7612219019Sgabor@ref{Page Motions}, for more info), a wide variety of figures can be 7613219019Sgabordrawn. However, for complex drawings these operations can be quite 7614219019Sgaborcumbersome, and it may be wise to use graphic preprocessors like 7615219019Sgabor@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 7616219019Sgaborinformation. 7617219019Sgabor 7618219019SgaborAll drawing is done via escapes. 7619219019Sgabor 7620219019Sgabor@cindex drawing horizontal lines 7621219019Sgabor@cindex horizontal line, drawing 7622219019Sgabor@cindex line, horizontal, drawing 7623219019Sgabor@Defesc {\\l, ', l c, '} 7624219019SgaborDraws a line rightwards from the current 7625219019Sgaborlocation. The full syntax for this escape is: 7626219019Sgabor 7627219019Sgabor@Example 7628219019Sgabor\l'@var{l}@var{c}' 7629219019Sgabor@endExample 7630219019Sgabor 7631219019Sgabor@noindent 7632219019Sgaborwhere @var{l} is the length of the line to be drawn, starting at the 7633219019Sgaborcurrent location; positive numbers draw to the right, and negative 7634219019Sgabornumbers draw towards the left. This can also be specified absolutely 7635219019Sgabor(i.e.@: with a leading @samp{|}) which draws back to the beginning 7636219019Sgaborof the line. 7637219019Sgabor 7638219019Sgabor@cindex underscore character 7639219019Sgabor@cindex character, underscore 7640219019Sgabor@cindex line drawing character 7641219019Sgabor@cindex character for line drawing 7642219019SgaborThe optional second parameter @var{c} is a character to draw the line 7643219019Sgaborwith. If this second argument is not specified, @code{gtroff} uses 7644219019Sgaborthe underscore character. 7645219019Sgabor 7646219019Sgabor@cindex zero width space character 7647219019Sgabor@cindex character, zero width space 7648219019Sgabor@cindex space character, zero width 7649219019Sgabor@esindex \& 7650219019SgaborTo separate the two arguments (to prevent @code{gtroff} from 7651219019Sgaborinterpreting a drawing character as a scaling indicator) use @code{\&}. 7652219019Sgabor 7653219019SgaborHere a small useful example: 7654219019Sgabor 7655219019Sgabor@Example 7656219019Sgabor.de box 7657219019Sgabor\(br\\$*\(br\l'|0\(rn'\l'|0\(ul' 7658219019Sgabor.. 7659219019Sgabor@endExample 7660219019Sgabor 7661219019Sgabor@opindex | 7662219019Sgabor@noindent 7663219019SgaborNote that this works by outputting a box rule (a vertical line), then 7664219019Sgaborthe text given as an argument and then another box rule. Then the line 7665219019Sgabordrawing escapes both draw from the current location to the beginning of 7666219019Sgaborthe @emph{input} line. 7667219019Sgabor@endDefesc 7668219019Sgabor 7669219019Sgabor@cindex drawing vertical lines 7670219019Sgabor@cindex vertical line drawing 7671219019Sgabor@cindex line, vertical, drawing 7672219019Sgabor@cindex line drawing character 7673219019Sgabor@cindex character for line drawing 7674219019Sgabor@cindex box rule character 7675219019Sgabor@cindex character, box rule 7676219019Sgabor@Defesc {\\L, ', l c, '} 7677219019SgaborDraws vertical lines. Its parameters are 7678219019Sgaborsimilar to the @code{\l} escape. The 7679219019Sgabormovement is downwards for positive values, 7680219019Sgaborand upwards for negative values. The 7681219019Sgabordefault character is the box rule character. As with the vertical 7682219019Sgabormotion escapes, text processing blindly continues where the line 7683219019Sgaborends. 7684219019Sgabor 7685219019Sgabor@c XXX example 7686219019Sgabor 7687219019Sgabor@ignore 7688219019Sgabor@Example 7689219019Sgabor...box macro... 7690219019Sgabor@endExample 7691219019Sgabor@end ignore 7692219019Sgabor@endDefesc 7693219019Sgabor 7694219019Sgabor@Defesc {\\D, ', command arg @dots{}, '} 7695219019SgaborThe @code{\D} escape provides a variety of drawing functions. 7696219019SgaborWhile the previous escapes work on a character device, these 7697219019Sgaborescapes do not. 7698219019Sgabor 7699219019Sgabor@table @code 7700219019Sgabor@item \D'l @var{dx} @var{dy}' 7701219019SgaborDraw a line from the current location to the relative point specified by 7702219019Sgabor(@var{dx},@var{dy}). 7703219019Sgabor 7704219019Sgabor@c XXX example 7705219019Sgabor 7706219019Sgabor@ignore 7707219019Sgabor@Example 7708219019Sgabor...revised box macro... 7709219019Sgabor@endExample 7710219019Sgabor@end ignore 7711219019Sgabor 7712219019Sgabor@item \D'c @var{d}' 7713219019Sgabor@cindex circle drawing 7714219019Sgabor@cindex drawing a circle 7715219019SgaborDraw a circle with a diameter of @var{d} with the leftmost point at the 7716219019Sgaborcurrent position. 7717219019Sgabor 7718219019Sgabor@item \D'C @var{d}' 7719219019SgaborDraw a solid circle with the same parameters as an outlined circle. 7720219019Sgabor 7721219019Sgabor@item \D'e @var{dx} @var{dy}' 7722219019Sgabor@cindex drawing an ellipse 7723219019Sgabor@cindex ellipse drawing 7724219019SgaborDraw an ellipse with a horizontal diameter of @var{dx} and a vertical 7725219019Sgabordiameter of @var{dy} with the leftmost point at the current position. 7726219019Sgabor 7727219019Sgabor@item \D'E @var{dx} @var{dy}' 7728219019SgaborDraw a solid ellipse with the same parameters as an outlined ellipse. 7729219019Sgabor 7730219019Sgabor@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 7731219019Sgabor@cindex arc drawing 7732219019Sgabor@cindex drawing an arc 7733219019SgaborDraw an arc clockwise from the current location through the two 7734219019Sgaborspecified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}). 7735219019Sgabor 7736219019Sgabor@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7737219019Sgabor@cindex drawing a spline 7738219019Sgabor@cindex spline drawing 7739219019SgaborDraw a spline from the current location to (@var{dx1},@var{dy1}) and 7740219019Sgaborthen to (@var{dx2},@var{dy2}), and so on. 7741219019Sgabor 7742219019Sgabor@item \D'f @var{n}' 7743219019Sgabor@cindex gray shading 7744219019Sgabor@cindex shading 7745219019Sgabor@cindex shades for filling objects 7746219019SgaborSet the shade of gray to be used for filling solid objects to@w{ 7747219019Sgabor}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 7748219019Sgaborcorresponds solid white and 1000 to solid black, and values in between 7749219019Sgaborcorrespond to intermediate shades of gray. This applies only to solid 7750219019Sgaborcircles, solid ellipses and solid polygons. By default, a level of@w{ 7751219019Sgabor}1000 is used. 7752219019Sgabor 7753219019Sgabor@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7754219019Sgabor@cindex drawing a polygon 7755219019Sgabor@cindex polygon drawing 7756219019SgaborDraw a polygon from the current location to (@var{dx1},@var{dy1}) and 7757219019Sgaborthen to (@var{dx2},@var{dy2}) and so on. When the specified data points 7758219019Sgaborare exhausted, a line is drawn back to the starting point. 7759219019Sgabor 7760219019Sgabor@c XXX example 7761219019Sgabor 7762219019Sgabor@ignore 7763219019Sgabor@Example 7764219019Sgabor... box example (yes, again)... 7765219019Sgabor@endExample 7766219019Sgabor@end ignore 7767219019Sgabor 7768219019Sgabor@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 7769219019SgaborDraw a solid polygon with the same parameters as an outlined polygon. 7770219019Sgabor 7771219019Sgabor@c XXX example 7772219019Sgabor 7773219019Sgabor@ignore 7774219019Sgabor@Example 7775219019Sgabor... shaded box example ... 7776219019Sgabor@endExample 7777219019Sgabor@end ignore 7778219019Sgabor 7779219019Sgabor@item \D't @var{n}' 7780219019Sgabor@cindex line thickness 7781219019Sgabor@cindex thickness of lines 7782219019SgaborSet the current line thickness to @var{n} machine units. A value of 7783219019Sgaborzero selects the smallest available line thickness. A negative value 7784219019Sgabormakes the line thickness proportional to the current point size (this is 7785219019Sgaborthe default behaviour of @code{ditroff}). 7786219019Sgabor@end table 7787219019Sgabor@endDefesc 7788219019Sgabor 7789219019Sgabor@cindex pile, character 7790219019Sgabor@cindex character pile 7791219019Sgabor@Defesc {\\b, ', string, '} 7792219019Sgabor@dfn{Piles} a sequence of characters 7793219019Sgaborvertically, and centers it vertically on the current line. Use it 7794219019Sgaborto build large brackets and braces. 7795219019Sgabor 7796219019Sgabor@Example 7797219019Sgabor\b'\(lt\(bv\(lk\(bv\(lb' 7798219019Sgabor@endExample 7799219019Sgabor@endDefesc 7800219019Sgabor 7801219019Sgabor@xref{Drawing Functions}. 7802219019Sgabor 7803219019Sgabor 7804219019Sgabor@c ===================================================================== 7805219019Sgabor 7806219019Sgabor@node Traps, Diversions, Drawing Requests, gtroff Reference 7807219019Sgabor@section Traps 7808219019Sgabor@cindex traps 7809219019Sgabor 7810219019Sgabor@dfn{Traps} are locations, which, when reached, call a specified 7811219019Sgabormacro. These traps can occur at a given location on the page, at a 7812219019Sgaborgiven location in the current diversion, after a certain number of input 7813219019Sgaborlines or at the end of input. 7814219019Sgabor 7815219019Sgabor@menu 7816219019Sgabor* Page Location Traps:: 7817219019Sgabor* Diversion Traps:: 7818219019Sgabor* Input Line Traps:: 7819219019Sgabor* End-of-input Traps:: 7820219019Sgabor@end menu 7821219019Sgabor 7822219019Sgabor@c --------------------------------------------------------------------- 7823219019Sgabor 7824219019Sgabor@node Page Location Traps, Diversion Traps, Traps, Traps 7825219019Sgabor@subsection Page Location Traps 7826219019Sgabor@cindex page location traps 7827219019Sgabor@cindex traps, page location 7828219019Sgabor 7829219019Sgabor@dfn{Page location traps} perform an action when @code{gtroff} 7830219019Sgaborreaches a certain vertical location on the page. Page location 7831219019Sgabortraps have a variety of purposes, including: 7832219019Sgabor 7833219019Sgabor@itemize 7834219019Sgabor@item 7835219019Sgaborsetting headers and footers 7836219019Sgabor 7837219019Sgabor@item 7838219019Sgaborsetting body text in multiple columns 7839219019Sgabor 7840219019Sgabor@item 7841219019Sgaborsetting footnotes 7842219019Sgabor@end itemize 7843219019Sgabor 7844219019Sgabor@cindex vertical position trap enable register 7845219019Sgabor@Defreq {vpt, flag} 7846219019Sgabor@Defregx {.vpt} 7847219019SgaborEnables vertical position traps if @var{flag} is non-zero, or disables 7848219019Sgaborthem otherwise. Vertical position traps are traps set by the @code{wh} 7849219019Sgaboror @code{dt} requests. Traps set by the @code{it} request are not 7850219019Sgaborvertical position traps. The parameter that controls whether vertical 7851219019Sgaborposition traps are enabled is global. Initially vertical position traps 7852219019Sgaborare enabled. The current setting of this is available in the 7853219019Sgabor@code{.vpt} read-only number register. 7854219019Sgabor@endDefreq 7855219019Sgabor 7856219019Sgabor@Defreq {wh, dist macro} 7857219019SgaborSets a page location trap. Positive values for @var{dist} set 7858219019Sgaborthe trap relative to the top of the page; negative values set 7859219019Sgaborthe trap relative to the bottom of the page. 7860219019Sgabor 7861219019Sgabor@var{macro} is the name of the macro to execute when the 7862219019Sgabortrap is sprung. 7863219019Sgabor 7864219019Sgabor@cindex page headers 7865219019Sgabor@cindex page footers 7866219019Sgabor@cindex headers 7867219019Sgabor@cindex footers 7868219019SgaborThe following is a simple example of how many macro packages 7869219019Sgaborset headers and footers. 7870219019Sgabor 7871219019Sgabor@Example 7872219019Sgabor.de hd \" Page header 7873219019Sgabor'sp .5i 7874219019Sgabor.tl 'Title''date' 7875219019Sgabor'sp .3i 7876219019Sgabor.. 7877219019Sgabor.de fo \" Page footer 7878219019Sgabor'sp 1v 7879219019Sgabor.tl ''%'' 7880219019Sgabor'bp 7881219019Sgabor.. 7882219019Sgabor.wh 0 hd \" trap at top of the page 7883219019Sgabor.wh -1i fo \" trap one inch from bottom 7884219019Sgabor@endExample 7885219019Sgabor@endDefreq 7886219019Sgabor 7887219019Sgabor@cindex distance to next trap 7888219019Sgabor@cindex trap, distance 7889219019Sgabor@Defreg {.t} 7890219019SgaborA read-only number register holding the distance to the next trap. 7891219019Sgabor@endDefreg 7892219019Sgabor 7893219019Sgabor@cindex changing trap location 7894219019Sgabor@cindex trap, changing location 7895219019Sgabor@Defreq {ch, dist macro} 7896219019SgaborChanges the location of a trap. 7897219019SgaborThe first argument is the name of the macro to be invoked at 7898219019Sgaborthe trap, and the second argument is the new location for the trap 7899219019Sgabor(note that the parameters are specified the opposite of the @code{.wh} request). 7900219019SgaborThis is useful for building up footnotes in a diversion to allow more 7901219019Sgaborspace at the bottom of the page for them. 7902219019Sgabor 7903219019Sgabor@c XXX 7904219019Sgabor 7905219019Sgabor@ignore 7906219019Sgabor@Example 7907219019Sgabor... (simplified) footnote example ... 7908219019Sgabor@endExample 7909219019Sgabor@end ignore 7910219019Sgabor@endDefreq 7911219019Sgabor 7912219019Sgabor@Defreg {.ne} 7913219019SgaborThe read-only number register @code{.ne} contains the amount of space 7914219019Sgaborthat was needed in the last @code{ne} request that caused a trap to be 7915219019Sgaborsprung. Useful in conjunction with the @code{.trunc} register. 7916219019Sgabor@xref{Page Control}, for more information. 7917219019Sgabor@endDefreg 7918219019Sgabor 7919219019Sgabor@rqindex ne 7920219019Sgabor@cindex @code{ne}, and the @code{.trunc} register 7921219019Sgabor@Defreg {.trunc} 7922219019SgaborA read-only register containing the amount of vertical space truncated 7923219019Sgaborby the most recently sprung vertical position trap, or, if the trap was 7924219019Sgaborsprung by an @code{ne} request, minus the amount of vertical motion 7925219019Sgaborproduced by the @code{ne} request. In other words, at the point a trap 7926219019Sgaboris sprung, it represents the difference of what the vertical position 7927219019Sgaborwould have been but for the trap, and what the vertical position 7928219019Sgaboractually is. 7929219019Sgabor@endDefreg 7930219019Sgabor 7931219019Sgabor@c --------------------------------------------------------------------- 7932219019Sgabor 7933219019Sgabor@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 7934219019Sgabor@subsection Diversion Traps 7935219019Sgabor@cindex diversion traps 7936219019Sgabor@cindex traps, diversion 7937219019Sgabor 7938219019Sgabor@vindex .t 7939219019Sgabor@cindex @code{.t}, and diversions 7940219019Sgabor@Defreq {dt, dist macro} 7941219019SgaborSets a trap @emph{within} a diversion. 7942219019Sgabor@var{dist} is the first argument is the location of the trap 7943219019Sgabor(identical to the @code{.wh} request) 7944219019Sgaborand @var{macro} is the name of the macro to be invoked. The 7945219019Sgabornumber register @code{.t} still works within diversions. 7946219019Sgabor@xref{Diversions}, for more information. 7947219019Sgabor@endDefreq 7948219019Sgabor 7949219019Sgabor@c --------------------------------------------------------------------- 7950219019Sgabor 7951219019Sgabor@node Input Line Traps, End-of-input Traps, Diversion Traps, Traps 7952219019Sgabor@subsection Input Line Traps 7953219019Sgabor@cindex input line traps 7954219019Sgabor@cindex traps, input line 7955219019Sgabor 7956219019Sgabor@Defreq {it, n macro} 7957219019SgaborSets an input line trap. 7958219019Sgabor@var{n} is the number of lines of input which may be read before 7959219019Sgabor@dfn{springing} the trap, @var{macro} is the macro to be invoked. 7960219019SgaborRequest lines are not counted as input lines. 7961219019Sgabor 7962219019SgaborFor example, one possible use is to have a macro which prints the 7963219019Sgabornext @var{n}@w{ }lines in a bold font. 7964219019Sgabor 7965219019Sgabor@Example 7966219019Sgabor.de B 7967219019Sgabor.it \\$1 B-end 7968219019Sgabor.ft B 7969219019Sgabor.. 7970219019Sgabor.de B-end 7971219019Sgabor.ft R 7972219019Sgabor.. 7973219019Sgabor@endExample 7974219019Sgabor@endDefreq 7975219019Sgabor 7976219019Sgabor@c --------------------------------------------------------------------- 7977219019Sgabor 7978219019Sgabor@node End-of-input Traps, , Input Line Traps, Traps 7979219019Sgabor@subsection End-of-input Traps 7980219019Sgabor@cindex end-of-input traps 7981219019Sgabor@cindex traps, end-of-input 7982219019Sgabor 7983219019Sgabor@Defreq {em, macro} 7984219019SgaborSets a trap at the end of input. The @var{macro} 7985219019Sgaborspecified is executed after the last line of the 7986219019Sgaborinput file has been processed. 7987219019Sgabor 7988219019SgaborFor example, if the document had to have a section at the bottom of the 7989219019Sgaborlast page for someone to approve it, the @code{em} request could be 7990219019Sgaborused. 7991219019Sgabor 7992219019Sgabor@Example 7993219019Sgabor.de approval 7994219019Sgabor.ne 5v 7995219019Sgabor.sp |(\\n(.t-6v) 7996219019Sgabor.in +4i 7997219019Sgabor.lc _ 7998219019Sgabor.br 7999219019SgaborApproved:\t\a 8000219019Sgabor.sp 8001219019SgaborDate:\t\t\a 8002219019Sgabor.. 8003219019Sgabor.em approval 8004219019Sgabor@endExample 8005219019Sgabor@endDefreq 8006219019Sgabor 8007219019Sgabor 8008219019Sgabor@c ===================================================================== 8009219019Sgabor 8010219019Sgabor@node Diversions, Environments, Traps, gtroff Reference 8011219019Sgabor@section Diversions 8012219019Sgabor@cindex diversions 8013219019Sgabor 8014219019SgaborIn @code{gtroff} it is possible to @dfn{divert} text into a named 8015219019Sgaborstorage area. Due to the similarity to defining macros it is sometimes 8016219019Sgaborsaid to be stored in a macro. This is used for saving text for output 8017219019Sgaborat a later time, which is useful for keeping blocks of text on the same 8018219019Sgaborpage, footnotes, tables of contents and indices. 8019219019Sgabor 8020219019Sgabor@c XXX describe top-level diversion 8021219019Sgabor@c XXX index entry for top-level diversion 8022219019Sgabor 8023219019Sgabor@Defreq {di, macro} 8024219019Sgabor@Defreqx {da, macro} 8025219019SgaborBegins a diversion. Like the @code{de} 8026219019Sgaborrequest, it takes an argument of a macro name to divert subsequent text 8027219019Sgaborinto. The @code{da} macro appends to an existing diversion. 8028219019Sgabor 8029219019Sgabor@code{di} or @code{da} without an argument ends the diversion. 8030219019Sgabor 8031219019Sgabor@c XXX example 8032219019Sgabor 8033219019Sgabor@ignore 8034219019Sgabor@Example 8035219019Sgabor... end-note example ... 8036219019Sgabor@endExample 8037219019Sgabor@end ignore 8038219019Sgabor@endDefreq 8039219019Sgabor 8040219019Sgabor@vindex nl 8041219019Sgabor@vindex .h 8042219019Sgabor@cindex nested diversions 8043219019Sgabor@cindex diversion, nested 8044219019Sgabor@Defreg {.z} 8045219019Sgabor@Defregx {.d} 8046219019SgaborDiversions may be nested. The read-only number register @code{.z} 8047219019Sgaborcontains the name of the current diversion (this is a string-valued 8048219019Sgaborregister). The read-only number register @code{.d} contains the current 8049219019Sgaborvertical place in the diversion. If not in a diversion it is the same 8050219019Sgaboras the register @code{nl}. 8051219019Sgabor@endDefreg 8052219019Sgabor 8053219019Sgabor@c XXX more info 8054219019Sgabor 8055219019Sgabor@Defreg {.h} 8056219019SgaborThe @dfn{high-water mark} on the current page. It corresponds to the 8057219019Sgabortext baseline of the lowest line on the page. This is a read-only 8058219019Sgaborregister. 8059219019Sgabor@endDefreg 8060219019Sgabor 8061219019Sgabor@Defreg {dn} 8062219019Sgabor@Defregx {dl} 8063219019SgaborAfter completing a diversion, the read-write number registers @code{dn} 8064219019Sgaborand @code{dl} contain the vertical and horizontal size of the diversion. 8065219019Sgabor 8066219019Sgabor@example 8067219019Sgabor@group 8068219019Sgabor.\" Center text both horizontally & vertically 8069219019Sgabor.de (c 8070219019Sgabor.br 8071219019Sgabor.nf 8072219019Sgabor.di @@c 8073219019Sgabor.. 8074219019Sgabor@end group 8075219019Sgabor@group 8076219019Sgabor.de )c 8077219019Sgabor.br 8078219019Sgabor.di 8079219019Sgabor.nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v) 8080219019Sgabor.sp \\n(@@su 8081219019Sgabor.ce 1000 8082219019Sgabor.nf 8083219019Sgabor.@c 8084219019Sgabor.br 8085219019Sgabor.ce 0 8086219019Sgabor.sp \\n(@@su 8087219019Sgabor.br 8088219019Sgabor.fi 8089219019Sgabor.rr @@s 8090219019Sgabor.. 8091219019Sgabor@end group 8092219019Sgabor@end example 8093219019Sgabor@endDefreg 8094219019Sgabor 8095219019Sgabor@cindex transparent output 8096219019Sgabor@cindex output, transparent 8097219019Sgabor@Defesc {\\!, , , } 8098219019Sgabor@Defescx {\\?, , @Var{anything}, \\?} 8099219019SgaborPrevents requests, macros and escapes from being 8100219019Sgaborinterpreted when read into a diversion. This takes the given text 8101219019Sgaborand @dfn{transparently} embeds it into the diversion. This is useful for 8102219019Sgabormacros which shouldn't be invoked until the diverted text is actually 8103219019Sgaboroutput. 8104219019Sgabor 8105219019Sgabor@c XXX anything is read in copy mode. (what about \! ??) 8106219019Sgabor 8107219019SgaborThe @code{\!} escape transparently embeds text up to 8108219019Sgaborand including the end of the line. 8109219019SgaborThe @code{\?} escape transparently embeds text until the next 8110219019Sgaboroccurrence of the @code{\?} escape. For example: 8111219019Sgabor 8112219019Sgabor@Example 8113219019Sgabor\?@var{anything}\? 8114219019Sgabor@endExample 8115219019Sgabor 8116219019Sgabor@noindent 8117219019Sgabor@var{anything} may not contain newlines; use @code{\!} to embed 8118219019Sgabornewlines in a diversion. The escape sequence @code{\?} is also 8119219019Sgaborrecognized in copy mode and turned into a single internal code; it is 8120219019Sgaborthis code that terminates anything. Thus the following example 8121219019Sgaborprints@w{ }4. 8122219019Sgabor 8123219019Sgabor@Example 8124219019Sgabor.nr x 1 8125219019Sgabor.nf 8126219019Sgabor.di d 8127219019Sgabor\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 8128219019Sgabor.di 8129219019Sgabor.nr x 2 8130219019Sgabor.di e 8131219019Sgabor.d 8132219019Sgabor.di 8133219019Sgabor.nr x 3 8134219019Sgabor.di f 8135219019Sgabor.e 8136219019Sgabor.di 8137219019Sgabor.nr x 4 8138219019Sgabor.f 8139219019Sgabor@endExample 8140219019Sgabor@endDefesc 8141219019Sgabor 8142219019Sgabor@cindex unformatting diversions 8143219019Sgabor@cindex diversion, unformatting 8144219019Sgabor@Defreq {asciify, div} 8145219019Sgabor@dfn{Unformats} the diversion specified by @var{div} 8146219019Sgaborin such a way that @acronym{ASCII} and space characters that 8147219019Sgaborwere formatted and diverted are treated like ordinary input 8148219019Sgaborcharacters when the diversion is reread. It can be also used for gross 8149219019Sgaborhacks; for example, the following sets register @code{n} to@w{ }1. 8150219019Sgabor 8151219019Sgabor@Example 8152219019Sgabor.tr @@. 8153219019Sgabor.di x 8154219019Sgabor@@nr n 1 8155219019Sgabor.br 8156219019Sgabor.di 8157219019Sgabor.tr @@@@ 8158219019Sgabor.asciify x 8159219019Sgabor.x 8160219019Sgabor@endExample 8161219019Sgabor 8162219019Sgabor@xref{Copy-in Mode}. 8163219019Sgabor@endDefreq 8164219019Sgabor 8165219019Sgabor 8166219019Sgabor@c ===================================================================== 8167219019Sgabor 8168219019Sgabor@node Environments, Suppressing output, Diversions, gtroff Reference 8169219019Sgabor@section Environments 8170219019Sgabor@cindex environments 8171219019Sgabor 8172219019SgaborIt happens frequently that some text should be printed in a certain 8173219019Sgaborformat regardless of what may be in effect at the time, for example, in 8174219019Sgabora trap invoked macro to print headers and footers. To solve this 8175219019Sgabor@code{gtroff} processes text in @dfn{environments}. An 8176219019Sgaborenvironment contains most of the parameters that control text 8177219019Sgaborprocessing. It is possible to switch amongst these environments; by 8178219019Sgabordefault @code{gtroff} processes text in environment@w{ }0. The 8179219019Sgaborfollowing is the information kept in an environment. 8180219019Sgabor 8181219019Sgabor@itemize @bullet 8182219019Sgabor@item 8183219019Sgaborfont parameters (size, family, style, character height and slant, space 8184219019Sgaborand sentence space size) 8185219019Sgabor 8186219019Sgabor@item 8187219019Sgaborpage parameters (line length, title length, vertical spacing, 8188219019Sgaborline spacing, indentation, line numbering, hyphenation data) 8189219019Sgabor 8190219019Sgabor@item 8191219019Sgaborfill and adjust mode 8192219019Sgabor 8193219019Sgabor@item 8194219019Sgabortab stops, tab and leader characters, escape character, no-break and 8195219019Sgaborhyphen indicators, margin character data 8196219019Sgabor 8197219019Sgabor@item 8198219019Sgaborpartially collected lines 8199219019Sgabor@end itemize 8200219019Sgabor 8201219019SgaborThese environments may be given arbitrary names (see @ref{Identifiers}, 8202219019Sgaborfor more info). Old versions of @code{troff} only had environments 8203219019Sgabornamed @samp{0}, @samp{1} and@w{ }@samp{2}. 8204219019Sgabor 8205219019Sgabor@cindex switch environments 8206219019Sgabor@cindex current environment number/name register 8207219019Sgabor@Defreq {ev, env} 8208219019Sgabor@Defregx {.ev} 8209219019SgaborSwitches to another environment. The argument @var{env} is the name of 8210219019Sgaborthe environment to switch to. With no argument, @code{gtroff} switches 8211219019Sgaborback to the previous environment. There is no limit on the number of 8212219019Sgabornamed environments; they are created the first time that they are 8213219019Sgaborreferenced. The @code{.ev} read-only register contains the name or 8214219019Sgabornumber of the current environment. This is a string-valued register. 8215219019Sgabor 8216219019SgaborNote that a call to @code{ev} (with argument) pushes the previously 8217219019Sgaboractive environment onto a stack. If, say, environments @samp{foo}, 8218219019Sgabor@samp{bar}, and @samp{zap} are called (in that order), the first 8219219019Sgabor@code{ev} request without parameter switches back to environment 8220219019Sgabor@samp{bar} (which is popped off the stack), and a second call 8221219019Sgaborswitches back to environment @samp{foo}. 8222219019Sgabor 8223219019Sgabor@c XXX example 8224219019Sgabor 8225219019Sgabor@ignore 8226219019Sgabor@Example 8227219019Sgabor... page break macro, revised ... 8228219019Sgabor@endExample 8229219019Sgabor@end ignore 8230219019Sgabor 8231219019SgaborHere is an example: 8232219019Sgabor 8233219019Sgabor@Example 8234219019Sgabor.ev footnote-env 8235219019Sgabor.fam N 8236219019Sgabor.ps 6 8237219019Sgabor.vs 8 8238219019Sgabor.ll -.5i 8239219019Sgabor.ev 8240219019Sgabor 8241219019Sgabor... 8242219019Sgabor 8243219019Sgabor.ev footnote-env 8244219019Sgabor\(dg Note the large, friendly letters. 8245219019Sgabor.ev 8246219019Sgabor@endExample 8247219019Sgabor@endDefreq 8248219019Sgabor 8249219019Sgabor@cindex copy environment 8250219019Sgabor@Defreq {evc, env} 8251219019SgaborCopies the environment @var{env} into the current environment. 8252219019Sgabor@endDefreq 8253219019Sgabor 8254219019Sgabor 8255219019Sgabor@c ===================================================================== 8256219019Sgabor 8257219019Sgabor@node Suppressing output, I/O, Environments, gtroff Reference 8258219019Sgabor@section Suppressing output 8259219019Sgabor@cindex suppressing output 8260219019Sgabor 8261219019Sgabor@Defesc {\\O, , num, } 8262219019SgaborDisables or enables output depending on the value of @var{num}: 8263219019Sgabor 8264219019Sgabor@table @samp 8265219019Sgabor@item \O0 8266219019SgaborDisable any ditroff glyphs from being emitted to the device driver. 8267219019Sgabor 8268219019Sgabor@item \O1 8269219019SgaborEnable output of glyphs. 8270219019Sgabor@end table 8271219019Sgabor 8272219019Sgabor@vindex opminx 8273219019Sgabor@vindex opminy 8274219019Sgabor@vindex opmaxx 8275219019Sgabor@vindex opmaxy 8276219019Sgabor@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 8277219019Sgabor@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 8278219019Sgabor@xref{Register Index}. These four registers mark the top left and 8279219019Sgaborbottom right hand corners of a box which encompasses all written glyphs. 8280219019Sgabor 8281219019SgaborThe following two forms of @code{\O} are specific to @code{grohtml}. 8282219019Sgabor 8283219019Sgabor@table @samp 8284219019Sgabor@item \O2 8285219019SgaborDisable any ditroff glyphs from being emitted to the device driver. Also 8286219019Sgaborwrite out to @code{stderr} the page number and four registers encompassing 8287219019Sgaborthe glyphs previously written since the last call to @code{\O}. 8288219019Sgabor 8289219019Sgabor@item \O3 8290219019SgaborEnable output of glyphs (the default). Also write out to @code{stderr} 8291219019Sgaborthe page number and four registers encompassing the glyphs previously 8292219019Sgaborwritten since the last call to @code{\O}. 8293219019Sgabor@end table 8294219019Sgabor@endDefesc 8295219019Sgabor 8296219019Sgabor 8297219019Sgabor@c ===================================================================== 8298219019Sgabor 8299219019Sgabor@node I/O, Postprocessor Access, Suppressing output, gtroff Reference 8300219019Sgabor@section I/O 8301219019Sgabor@cindex i/o 8302219019Sgabor@cindex input and output requests 8303219019Sgabor@cindex requests for input and output 8304219019Sgabor@cindex output and input requests 8305219019Sgabor 8306219019Sgabor@code{gtroff} has several requests for including files: 8307219019Sgabor 8308219019Sgabor@cindex including a file 8309219019Sgabor@cindex file inclusion 8310219019Sgabor@Defreq {so, file} 8311219019SgaborReads in the specified @var{file} and 8312219019Sgaborincludes it in place of the @code{so} request. This is quite useful for 8313219019Sgaborlarge documents, e.g.@: keeping each chapter in a separate file. 8314219019Sgabor@xref{gsoelim}, for more information. 8315219019Sgabor@endDefreq 8316219019Sgabor 8317219019Sgabor@Defreq {mso, file} 8318219019SgaborIdentical to the @code{so} request except that @code{gtroff} 8319219019Sgaborsearches for the specified 8320219019Sgabor@var{file} in the same directories as macro files for the 8321219019Sgaborthe @option{-m} command line option. If the file name to be included 8322219019Sgaborhas the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 8323219019Sgaborto include @file{tmac.@var{name}} and vice versa. 8324219019Sgabor@endDefreq 8325219019Sgabor 8326219019Sgabor@cindex transparent output 8327219019Sgabor@cindex output, transparent 8328219019Sgabor@Defreq {cf, file} 8329219019Sgabor@Defreqx {trf, file} 8330219019SgaborTransparently outputs the contents of @var{file}. Each line is output 8331219019Sgaboras it were preceded by @code{\!}; however, the lines are not subject to 8332219019Sgaborcopy mode interpretation. If the file does not end with a newline, then 8333219019Sgabora newline is added. For example, to define a macro@w{ }@code{x} 8334219019Sgaborcontaining the contents of file@w{ }@file{f}, use 8335219019Sgabor 8336219019Sgabor@Example 8337219019Sgabor.di x 8338219019Sgabor.trf f 8339219019Sgabor.di 8340219019Sgabor@endExample 8341219019Sgabor 8342219019SgaborThe request @w{@code{.cf @var{filename}}}, when used in a diversion, 8343219019Sgaborembeds an object in the diversion which, when reread, causes the 8344219019Sgaborcontents of @var{filename} to be transparently copied through to the 8345219019Sgaboroutput. 8346219019Sgabor 8347219019SgaborIn @acronym{UNIX} @code{troff}, the contents of @var{filename} 8348219019Sgaboris immediately copied through to the output regardless of whether there 8349219019Sgaboris a current diversion; this behaviour is so anomalous that it must be 8350219019Sgaborconsidered a bug. This request causes a line break. 8351219019Sgabor 8352219019Sgabor@rqindex trf 8353219019SgaborWith @code{trf}, unlike @code{cf}, the file cannot contain characters 8354219019Sgaborsuch as NUL that are not valid @code{gtroff} input characters 8355219019Sgabor(@pxref{Identifiers}). This request causes a line break. 8356219019Sgabor@endDefreq 8357219019Sgabor 8358219019Sgabor@Defreq {nx, } 8359219019SgaborForces @code{gtroff} to continue processing of 8360219019Sgaborthe file specified as an argument. 8361219019Sgabor@endDefreq 8362219019Sgabor 8363219019Sgabor@Defreq {rd, } 8364219019SgaborThe @code{rd} request reads from standard input, and includes what is 8365219019Sgaborread as though it were part of the input file. Text is read until a 8366219019Sgaborblank line is encountered. 8367219019Sgabor@endDefreq 8368219019Sgabor 8369219019Sgabor@cindex form letters 8370219019Sgabor@cindex letters, form 8371219019SgaborUsing the @code{nx} and @code{rd} requests, 8372219019Sgaborit is easy to set up form letters. The form 8373219019Sgaborletter template is constructed like this: 8374219019Sgabor 8375219019Sgabor@Example 8376219019Sgabor.ce 8377219019Sgabor\*(td 8378219019Sgabor.sp 2 8379219019Sgabor.nf 8380219019Sgabor.rd 8381219019Sgabor.sp 8382219019Sgabor.rd 8383219019Sgabor.fi 8384219019SgaborBody of letter. 8385219019Sgabor.bp 8386219019Sgabor.nx repeat.let 8387219019Sgabor@endExample 8388219019Sgabor 8389219019Sgabor@rqindex ex 8390219019Sgabor@noindent 8391219019SgaborWhen this is run, the following file should be redirected in. Note that 8392219019Sgaborrequests included in this file are executed as though they were part of 8393219019Sgaborthe form letter. The last block of input is the @code{ex} requests 8394219019Sgaborwhich tells groff to stop processing. If this was not there, groff 8395219019Sgaborwould not know when to stop. 8396219019Sgabor 8397219019Sgabor@Example 8398219019SgaborTrent A. Fisher 8399219019Sgabor708 NW 19th Av., #202 8400219019SgaborPortland, OR 97209 8401219019Sgabor 8402219019SgaborDear Trent, 8403219019Sgabor 8404219019SgaborLen Adollar 8405219019Sgabor4315 Sierra Vista 8406219019SgaborSan Diego, CA 92103 8407219019Sgabor 8408219019SgaborDear Mr. Adollar, 8409219019Sgabor 8410219019Sgabor.ex 8411219019Sgabor@endExample 8412219019Sgabor 8413219019Sgabor@Defreq {pi, pipe} 8414219019SgaborPipes the output of @code{gtroff} to the shell command(s) 8415219019Sgaborspecified by @var{pipe}. This request must occur before 8416219019Sgabor@code{gtroff} has a chance to print anything. 8417219019Sgabor@endDefreq 8418219019Sgabor 8419219019Sgabor@Defreq {sy, cmds} 8420219019Sgabor@Defregx {systat} 8421219019SgaborIn @dfn{unsafe} mode, executes the shell command(s) specified by 8422219019Sgabor@var{cmds}. The output is not saved anyplace, so it is up to the user 8423219019Sgaborto do so. 8424219019Sgabor 8425219019Sgabor@c XXX add info about safer and unsafe mode 8426219019Sgabor 8427219019SgaborFor example, the following example introduces the current time 8428219019Sgaborinto a document: 8429219019Sgabor 8430219019Sgabor@cindex time, current 8431219019Sgabor@cindex current time 8432219019Sgabor@pindex perl 8433219019Sgabor@Example 8434219019Sgabor.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 8435219019Sgabor (localtime(time))[2,1,0]' > /tmp/x\n[$$] 8436219019Sgabor.so /tmp/x\n[$$] 8437219019Sgabor.sy rm /tmp/x\n[$$] 8438219019Sgabor\nH:\nM:\nS 8439219019Sgabor@endExample 8440219019Sgabor 8441219019Sgabor@noindent 8442219019SgaborNote that this works by having the @code{perl} script (run by @code{sy}) 8443219019Sgaborprint out the @code{nr} requests which set the number registers 8444219019Sgabor@samp{H}, @samp{M} and @samp{S}, and then reads those commands in with 8445219019Sgaborthe @code{so} request. 8446219019Sgabor 8447219019Sgabor@cindex @code{system()} return value register 8448219019SgaborThe @code{systat} read-write number register contains the return value 8449219019Sgaborof the @code{system()} function executed by the last @code{sy} request. 8450219019Sgabor@endDefreq 8451219019Sgabor 8452219019Sgabor@Defreq {open, stream file} 8453219019Sgabor@Defreqx {opena, stream file} 8454219019SgaborOpens the specified @var{file} for writing and 8455219019Sgaborassociates the specified @var{stream} with it. 8456219019Sgabor 8457219019SgaborThe @code{opena} is like @code{open}, but if the file exists, append to 8458219019Sgaborit instead of truncating it. 8459219019Sgabor@endDefreq 8460219019Sgabor 8461219019Sgabor@cindex copy-in mode, and @code{write} requests 8462219019Sgabor@cindex mode, copy-in, and @code{write} requests 8463219019Sgabor@Defreq {write, stream data} 8464219019SgaborWrites to the file associated with the specified @var{stream}. 8465219019SgaborThe stream must previously have 8466219019Sgaborbeen the subject of an open request. The remainder of the line is 8467219019Sgaborinterpreted as the @code{ds} request reads its second argument: A 8468219019Sgaborleading @samp{"} is stripped, and it is read in copy-in mode. 8469219019Sgabor@endDefreq 8470219019Sgabor 8471219019Sgabor@Defreq {close, stream} 8472219019SgaborCloses the specified @var{stream}; 8473219019Sgaborthe stream is no longer an acceptable argument to the 8474219019Sgabor@code{write} request. 8475219019Sgabor 8476219019Sgabor@c XXX example 8477219019Sgabor 8478219019Sgabor@ignore 8479219019Sgabor@Example 8480219019Sgabor... example of open write &c... 8481219019Sgabor@endExample 8482219019Sgabor@end ignore 8483219019Sgabor@endDefreq 8484219019Sgabor 8485219019Sgabor@Defesc {\\V, ', xxx, '} 8486219019SgaborInterpolates the contents of the specified 8487219019Sgaborenvironment variable, as returned by the function @code{getenv}. 8488219019SgaborSpecify the argument to @code{\V} as an identifier, i.e.@: 8489219019Sgabor@samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V} 8490219019Sgaboris interpreted in copy-in mode. 8491219019Sgabor@endDefesc 8492219019Sgabor 8493219019Sgabor 8494219019Sgabor@c ===================================================================== 8495219019Sgabor 8496219019Sgabor@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 8497219019Sgabor@section Postprocessor Access 8498219019Sgabor@cindex postprocessor access 8499219019Sgabor@cindex access of postprocessor 8500219019Sgabor 8501219019SgaborThere are two escapes which give information directly to the 8502219019Sgaborpostprocessor. This is particularly useful for embedding 8503219019Sgabor@sc{PostScript} into the final document. 8504219019Sgabor 8505219019Sgabor@Defesc {\\X, ', xxx, '} 8506219019SgaborEmbeds its argument into the @code{gtroff} 8507219019Sgaboroutput preceded with @w{@samp{x X}}. 8508219019Sgabor@endDefesc 8509219019Sgabor 8510219019Sgabor@Defesc {\\Y, ', xxx, '} 8511219019SgaborThe @code{\Y} escape is called with an identifier (i.e.@: 8512219019Sgabor@code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is 8513219019Sgaborapproximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the 8514219019Sgaborcontents of the string or macro @var{xxx} are not interpreted; also it 8515219019Sgaboris permitted for @var{xxx} to have been defined as a macro and thus 8516219019Sgaborcontain newlines (it is not permitted for the argument to @code{\X} to 8517219019Sgaborcontain newlines). The inclusion of newlines requires an extension to 8518219019Sgaborthe @acronym{UNIX} @code{troff} output format, and confuses drivers 8519219019Sgaborthat do not know about this extension. 8520219019Sgabor@endDefesc 8521219019Sgabor 8522219019Sgabor@xref{Output Devices}. 8523219019Sgabor 8524219019Sgabor 8525219019Sgabor@c ===================================================================== 8526219019Sgabor 8527219019Sgabor@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 8528219019Sgabor@section Miscellaneous 8529219019Sgabor@cindex miscellaneous 8530219019Sgabor 8531219019SgaborThis section documents parts of @code{gtroff} which cannot (yet) be 8532219019Sgaborcategorized elsewhere in this manual. 8533219019Sgabor 8534219019Sgabor@cindex line numbers 8535219019Sgabor@cindex numbers, line 8536219019Sgabor@Defreq {nm, start inc space indent} 8537219019SgaborPrints line numbers in the left margin. 8538219019Sgabor@var{start} is the line number of the @emph{next} 8539219019Sgaboroutput line; this defaults to@w{ }1. @var{inc} indicates on 8540219019Sgaborwhich lines numbers are printed, i.e.@: 5 means put line numbers on 8541219019Sgaborevery 5@w{ }lines; this defaults to@w{ }1. @var{space} is the 8542219019Sgaborspace to be left between the number and the text; this defaults to@w{ 8543219019Sgabor}1. The fourth argument is the indentation of the line numbers. 8544219019SgaborWithout arguments, line numbers are turned off. 8545219019Sgabor@endDefreq 8546219019Sgabor 8547219019Sgabor@c XXX xref ln register 8548219019Sgabor 8549219019Sgabor@Defreq {nn, [@Var{skip}]} 8550219019SgaborTemporarily turns off line numbering. The 8551219019Sgaborargument is the number of lines not to be numbered; this defaults 8552219019Sgaborto@w{ }1. 8553219019Sgabor 8554219019Sgabor@c XXX (does this disable incrementing or display?) 8555219019Sgabor 8556219019Sgabor@c XXX example 8557219019Sgabor 8558219019Sgabor@ignore 8559219019Sgabor@Example 8560219019Sgabor... line numbering example ... 8561219019Sgabor@endExample 8562219019Sgabor@end ignore 8563219019Sgabor@endDefreq 8564219019Sgabor 8565219019Sgabor@cindex margin characters 8566219019Sgabor@cindex characters for margins 8567219019Sgabor@Defreq {mc, char dist} 8568219019SgaborPrints margin characters to the right of the text. 8569219019SgaborThe first argument is the character to be 8570219019Sgaborprinted, and the second argument is the distance away from the main body 8571219019Sgabortext. With no arguments the margin characters are turned off. If this 8572219019Sgaboroccurs before a break, no margin character is printed. 8573219019Sgabor 8574219019Sgabor@pindex nrchbar 8575219019Sgabor@pindex changebar 8576219019SgaborThis is quite useful for indicating text that has changed, and, in fact, 8577219019Sgaborthere are programs available for doing this (they are called 8578219019Sgabor@code{nrchbar} and @code{changebar} and can be found in any 8579219019Sgabor@samp{comp.sources.unix} archive. 8580219019Sgabor 8581219019Sgabor@c XXX example 8582219019Sgabor 8583219019Sgabor@ignore 8584219019Sgabor@Example 8585219019Sgabor... margin char example ... 8586219019Sgabor@endExample 8587219019Sgabor@end ignore 8588219019Sgabor@endDefreq 8589219019Sgabor 8590219019Sgabor@pindex soelim 8591219019Sgabor@cindex multi-file documents 8592219019Sgabor@cindex documents, multi-file 8593219019Sgabor@Defreq {lf, line filename} 8594219019SgaborA debugging aid for 8595219019Sgabordocuments which are split into many files, then put together 8596219019Sgaborwith @code{soelim} and other preprocessors. The second argument is the 8597219019Sgaborname of the file and the first argument is the input line number in 8598219019Sgaborthat file. This way @code{gtroff} can produce error messages which are 8599219019Sgaborintelligible to the user. 8600219019Sgabor 8601219019Sgabor@c XXX example 8602219019Sgabor 8603219019Sgabor@ignore 8604219019Sgabor@Example 8605219019Sgabor... example of soelim'ed doc ... 8606219019Sgabor@endExample 8607219019Sgabor@end ignore 8608219019Sgabor@endDefreq 8609219019Sgabor 8610219019Sgabor 8611219019Sgabor@c ===================================================================== 8612219019Sgabor 8613219019Sgabor@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 8614219019Sgabor@section @code{gtroff} Internals 8615219019Sgabor 8616219019Sgabor@cindex input token 8617219019Sgabor@cindex token, input 8618219019Sgabor@cindex output node 8619219019Sgabor@cindex node, output 8620219019Sgabor@code{gtroff} processes input in three steps. One or more input 8621219019Sgaborcharacters are converted to an @dfn{input token}. Then, one or more 8622219019Sgaborinput tokens are converted to an @dfn{output node}. Finally, output 8623219019Sgabornodes are converted to the intermediate output language understood by 8624219019Sgaborall output devices. 8625219019Sgabor 8626219019SgaborFor example, the input string @samp{fi\[:u]} is converted in a 8627219019Sgaborcharacter token @samp{f}, a character token @samp{i}, and a special 8628219019Sgabortoken @samp{:u} (representing u@w{ }umlaut). Later on, the character 8629219019Sgabortokens @samp{f} and @samp{i} are merged to a single output node 8630219019Sgaborrepresenting the ligature glyph @samp{fi}; the same happens with 8631219019Sgabor@samp{:u}. All output glyph nodes are `processed' which means that 8632219019Sgaborthey are invariably associated with a given font, font size, advance 8633219019Sgaborwidth, etc. During the formatting process, @code{gtroff} itself adds 8634219019Sgaborvarious nodes to control the data flow. 8635219019Sgabor 8636219019SgaborMacros, diversions, and strings collect elements in two chained lists: 8637219019Sgabora list of input tokens which have been passed unprocessed, and a list 8638219019Sgaborof output nodes. Consider the following the diversion. 8639219019Sgabor 8640219019Sgabor@Example 8641219019Sgabor.di xxx 8642219019Sgabora 8643219019Sgabor\!b 8644219019Sgaborc 8645219019Sgabor.br 8646219019Sgabor.di 8647219019Sgabor@endExample 8648219019Sgabor 8649219019Sgabor@noindent 8650219019SgaborIt contains these elements. 8651219019Sgabor 8652219019Sgabor@multitable {@i{vertical size node}} {token list} {element number} 8653219019Sgabor@item node list @tab token list @tab element number 8654219019Sgabor 8655219019Sgabor@item @i{line start node} @tab --- @tab 1 8656219019Sgabor@item @i{glyph node @code{a}} @tab --- @tab 2 8657219019Sgabor@item @i{word space node} @tab --- @tab 3 8658219019Sgabor@item --- @tab @code{b} @tab 4 8659219019Sgabor@item --- @tab @code{\n} @tab 5 8660219019Sgabor@item @i{glyph node @code{c}} @tab --- @tab 6 8661219019Sgabor@item @i{vertical size node} @tab --- @tab 7 8662219019Sgabor@item @i{vertical size node} @tab --- @tab 8 8663219019Sgabor@item --- @tab @code{\n} @tab 9 8664219019Sgabor@end multitable 8665219019Sgabor 8666219019Sgabor@esindex \v 8667219019Sgabor@rqindex unformat 8668219019Sgabor@noindent 8669219019SgaborElements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two 8670219019Sgabor(which are always present) specify the vertical extent of the last 8671219019Sgaborline, possibly modified by @code{\v}. The @code{br} request finishes 8672219019Sgaborthe current partial line, inserting a newline input token which is 8673219019Sgaborsubsequently converted to a space when the diversion is reread. Note 8674219019Sgaborthat the word space node has a fixed width which isn't stretchable 8675219019Sgaboranymore. To convert horizontal space nodes back to input tokens, use 8676219019Sgaborthe @code{unformat} request. 8677219019Sgabor 8678219019SgaborMacros only contain elements in the token list (and the node list is 8679219019Sgaborempty); diversions and strings can contain elements in both lists. 8680219019Sgabor 8681219019Sgabor 8682219019Sgabor@c ===================================================================== 8683219019Sgabor 8684219019Sgabor@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 8685219019Sgabor@section Debugging 8686219019Sgabor@cindex debugging 8687219019Sgabor 8688219019Sgabor@code{gtroff} is not easy to debug, but there are some useful features 8689219019Sgaborand strategies for debugging. 8690219019Sgabor 8691219019Sgabor@Defreq {tm, string} 8692219019SgaborSends the @var{string} to the standard error stream; 8693219019Sgaborthis is very useful for printing debugging output among other things. 8694219019Sgabor@endDefreq 8695219019Sgabor 8696219019Sgabor@cindex aborting 8697219019Sgabor@Defreq {ab, [@Var{string}]} 8698219019SgaborSimilar to the @code{tm} request, except that 8699219019Sgaborit causes @code{gtroff} to stop processing. With no argument it 8700219019Sgaborprints @samp{User Abort}. 8701219019Sgabor@endDefreq 8702219019Sgabor 8703219019Sgabor@cindex @code{ex}, use in debugging 8704219019Sgabor@cindex exiting 8705219019Sgabor@Defreq {ex, } 8706219019SgaborThe @code{ex} request also causes @code{gtroff} to stop processing 8707219019Sgaborif encountered at the topmost level; see also @ref{I/O}. 8708219019Sgabor@endDefreq 8709219019Sgabor 8710219019SgaborWhen doing something involved it is useful to leave the debugging 8711219019Sgaborstatements in the code and have them turned on by a command line flag. 8712219019Sgabor 8713219019Sgabor@Example 8714219019Sgabor.if \n(DB .tm debugging output 8715219019Sgabor@endExample 8716219019Sgabor 8717219019Sgabor@noindent 8718219019SgaborTo activate these statements say 8719219019Sgabor 8720219019Sgabor@Example 8721219019Sgaborgroff -rDB=1 file 8722219019Sgabor@endExample 8723219019Sgabor 8724219019Sgabor@c XXX .tm1, .tmc requests 8725219019Sgabor 8726219019SgaborIf it is known in advance that there will be many errors and no useful 8727219019Sgaboroutput, @code{gtroff} can be forced to suppress formatted output with 8728219019Sgaborthe @option{-z} flag. 8729219019Sgabor 8730219019Sgabor@cindex dumping symbol table 8731219019Sgabor@cindex symbol table, dumping 8732219019Sgabor@Defreq {pm, } 8733219019SgaborThe @code{pm} request prints out the entire symbol table on @code{stderr}. 8734219019Sgabor@endDefreq 8735219019Sgabor 8736219019Sgabor@cindex dumping number registers 8737219019Sgabor@cindex number registers, dumping 8738219019Sgabor@Defreq {pnr, } 8739219019SgaborPrints the names and contents of all 8740219019Sgaborcurrently defined number registers on @code{stderr}. 8741219019Sgabor@endDefreq 8742219019Sgabor 8743219019Sgabor@cindex dumping traps 8744219019Sgabor@cindex traps, dumping 8745219019Sgabor@Defreq {ptr, } 8746219019SgaborPrints the names and positions of all traps 8747219019Sgabor(not including input line traps and diversion traps) on @code{stderr}. 8748219019SgaborEmpty slots in the page trap list are printed as well, because they can 8749219019Sgaboraffect the priority of subsequently planted traps. 8750219019Sgabor@endDefreq 8751219019Sgabor 8752219019Sgabor@cindex flush output 8753219019Sgabor@cindex output, flush 8754219019Sgabor@cindex interactive use of @code{gtroff} 8755219019Sgabor@cindex @code{gtroff}, interactive use 8756219019Sgabor@Defreq {fl, } 8757219019SgaborInstructs @code{gtroff} to flush its output 8758219019Sgaborimmediately. The intent is for interactive use. 8759219019Sgabor@code{gtroff}; there is little other use for it. This 8760219019Sgaborrequest causes a line break. 8761219019Sgabor@endDefreq 8762219019Sgabor 8763219019Sgabor@cindex backtrace of input stack 8764219019Sgabor@cindex input stack, backtrace 8765219019Sgabor@Defreq {backtrace, } 8766219019SgaborThe @code{backtrace} request prints a backtrace of the input stack 8767219019Sgaborto the standard error stream. 8768219019Sgabor@endDefreq 8769219019Sgabor 8770219019Sgabor@cindex warnings 8771219019Sgabor@code{gtroff} has command line options for printing out more warnings 8772219019Sgabor(@option{-w}) and for printing backtraces (@option{-b}) when a warning 8773219019Sgaboror an error occurs. The most verbose level of warnings is @option{-ww}. 8774219019Sgabor 8775219019Sgabor@cindex level of warnings 8776219019Sgabor@cindex warnings, level 8777219019Sgabor@Defreq {warn, [@Var{flags}]} 8778219019Sgabor@Defregx {.warn} 8779219019SgaborControls the level of warnings checked for. The @var{flags} are the sum 8780219019Sgaborof the numbers associated with each warning that is to be enabled; all 8781219019Sgaborother warnings are disabled. The number associated with each warning is 8782219019Sgaborlisted below. For example, @w{@code{.warn 0}} disables all warnings, 8783219019Sgaborand @w{@code{.warn 1}} disables all warnings except that about missing 8784219019Sgaborcharacters. If an argument is not given, all warnings are enabled. 8785219019Sgabor 8786219019SgaborThe read-only number register @code{.warn} contains the current warning 8787219019Sgaborlevel. 8788219019Sgabor@endDefreq 8789219019Sgabor 8790219019Sgabor@menu 8791219019Sgabor* Warnings:: 8792219019Sgabor@end menu 8793219019Sgabor 8794219019Sgabor@c --------------------------------------------------------------------- 8795219019Sgabor 8796219019Sgabor@node Warnings, , Debugging, Debugging 8797219019Sgabor@subsection Warnings 8798219019Sgabor@cindex warnings 8799219019Sgabor 8800219019SgaborThe warnings that can be given to @code{gtroff} are divided into the 8801219019Sgaborfollowing categories. The name associated with each warning is used by 8802219019Sgaborthe @option{-w} and @option{-W} options; the number is used by the 8803219019Sgabor@code{warn} request and by the @code{.warn} register. 8804219019Sgabor 8805219019Sgabor@table @samp 8806219019Sgabor@item char 8807219019Sgabor@itemx 1 8808219019SgaborNon-existent characters. This is enabled by default. 8809219019Sgabor 8810219019Sgabor@item number 8811219019Sgabor@itemx 2 8812219019SgaborInvalid numeric expressions. This is enabled by default. 8813219019Sgabor@xref{Expressions}. 8814219019Sgabor 8815219019Sgabor@item break 8816219019Sgabor@itemx 4 8817219019Sgabor@cindex fill mode 8818219019Sgabor@cindex mode, fill 8819219019SgaborIn fill mode, lines which could not be broken so that their length was 8820219019Sgaborless than the line length. This is enabled by default. 8821219019Sgabor 8822219019Sgabor@item delim 8823219019Sgabor@itemx 8 8824219019SgaborMissing or mismatched closing delimiters. 8825219019Sgabor 8826219019Sgabor@item el 8827219019Sgabor@itemx 16 8828219019Sgabor@rqindex ie 8829219019Sgabor@rqindex el 8830219019SgaborUse of the @code{el} request with no matching @code{ie} request. 8831219019Sgabor@xref{if-else}. 8832219019Sgabor 8833219019Sgabor@item scale 8834219019Sgabor@itemx 32 8835219019SgaborMeaningless scaling indicators. 8836219019Sgabor 8837219019Sgabor@item range 8838219019Sgabor@itemx 64 8839219019SgaborOut of range arguments. 8840219019Sgabor 8841219019Sgabor@item syntax 8842219019Sgabor@itemx 128 8843219019SgaborDubious syntax in numeric expressions. 8844219019Sgabor 8845219019Sgabor@item di 8846219019Sgabor@itemx 256 8847219019Sgabor@rqindex di 8848219019Sgabor@rqindex da 8849219019Sgabor@cindex @code{di}, debugging 8850219019Sgabor@cindex @code{da}, debugging 8851219019SgaborUse of @code{di} or @code{da} without an argument when there is no 8852219019Sgaborcurrent diversion. 8853219019Sgabor 8854219019Sgabor@item mac 8855219019Sgabor@itemx 512 8856219019Sgabor@rqindex de 8857219019Sgabor@c XXX more index entries 8858219019SgaborUse of undefined strings, macros and diversions. When an undefined 8859219019Sgaborstring, macro or diversion is used, that string is automatically defined 8860219019Sgaboras empty. So, in most cases, at most one warning is given for each 8861219019Sgaborname. 8862219019Sgabor 8863219019Sgabor@item reg 8864219019Sgabor@itemx 1024 8865219019Sgabor@rqindex nr 8866219019Sgabor@c XXX more index entries 8867219019SgaborUse of undefined number registers. When an undefined number register is 8868219019Sgaborused, that register is automatically defined to have a value of@w{ }0. 8869219019SgaborA definition is automatically made with a value of@w{ }0. So, in most 8870219019Sgaborcases, at most one warning is given for use of a particular name. 8871219019Sgabor 8872219019Sgabor@item tab 8873219019Sgabor@itemx 2048 8874219019SgaborUse of a tab character where a number was expected. 8875219019Sgabor 8876219019Sgabor@item right-brace 8877219019Sgabor@itemx 4096 8878219019Sgabor@esindex \@} 8879219019Sgabor@cindex @code{\@}}, debugging 8880219019SgaborUse of @code{\@}} where a number was expected. 8881219019Sgabor 8882219019Sgabor@item missing 8883219019Sgabor@itemx 8192 8884219019SgaborRequests that are missing non-optional arguments. 8885219019Sgabor 8886219019Sgabor@item input 8887219019Sgabor@itemx 16384 8888219019SgaborIllegal input characters. 8889219019Sgabor 8890219019Sgabor@item escape 8891219019Sgabor@itemx 32768 8892219019SgaborUnrecognized escape sequences. When an unrecognized escape sequence is 8893219019Sgaborencountered, the escape character is ignored. 8894219019Sgabor 8895219019Sgabor@item space 8896219019Sgabor@itemx 65536 8897219019Sgabor@cindex compatibility mode 8898219019SgaborMissing space between a request or macro and its argument. This warning 8899219019Sgaboris given when an undefined name longer than two characters is 8900219019Sgaborencountered, and the first two characters of the name make a defined 8901219019Sgaborname. The request or macro is not invoked. When this warning is 8902219019Sgaborgiven, no macro is automatically defined. This is enabled by default. 8903219019SgaborThis warning never occurs in compatibility mode. 8904219019Sgabor 8905219019Sgabor@item font 8906219019Sgabor@itemx 131072 8907219019SgaborNon-existent fonts. This is enabled by default. 8908219019Sgabor 8909219019Sgabor@item all 8910219019SgaborAll warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 8911219019Sgaborintended that this covers all warnings that are useful with traditional 8912219019Sgabormacro packages. 8913219019Sgabor 8914219019Sgabor@item w 8915219019SgaborAll warnings. 8916219019Sgabor@end table 8917219019Sgabor 8918219019Sgabor 8919219019Sgabor@c ===================================================================== 8920219019Sgabor 8921219019Sgabor@node Implementation Differences, Summary, Debugging, gtroff Reference 8922219019Sgabor@section Implementation Differences 8923219019Sgabor@cindex implementation differences 8924219019Sgabor@cindex differences in implementation 8925219019Sgabor@cindex incompatibilities with Unix @code{troff} 8926219019Sgabor@cindex compatibility mode 8927219019Sgabor@cindex mode, compatibility 8928219019Sgabor 8929219019SgaborGNU @code{troff} has a number of features which cause incompatibilities 8930219019Sgaborwith documents written with old versions of @code{troff}. 8931219019Sgabor 8932219019Sgabor@cindex long names 8933219019Sgabor@cindex names, long 8934219019SgaborLong names cause some incompatibilities. @acronym{UNIX} @code{troff} 8935219019Sgaborinterprets 8936219019Sgabor 8937219019Sgabor@Example 8938219019Sgabor.dsabcd 8939219019Sgabor@endExample 8940219019Sgabor 8941219019Sgabor@esindex \* 8942219019Sgabor@esindex \n 8943219019Sgabor@cindex @code{\*}, incompatibilities with Unix @code{troff} 8944219019Sgabor@cindex @code{\n}, incompatibilities with Unix @code{troff} 8945219019Sgabor@rqindex cp 8946219019Sgabor@vindex .C 8947219019Sgabor@noindent 8948219019Sgaboras defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 8949219019Sgabor@code{troff} interprets this as a call of a macro named 8950219019Sgabor@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 8951219019Sgabor@code{\*[} or @code{\n[} as references to a string or number register 8952219019Sgaborcalled @samp{[}. In GNU @code{troff}, however, this is normally 8953219019Sgaborinterpreted as the start of a long name. In compatibility mode GNU 8954219019Sgabor@code{troff} interprets long names in the traditional way 8955219019Sgabor(which means that they are not recognized as names). 8956219019SgaborCompatibility mode can be turned on with the @option{-C} command line 8957219019Sgaboroption, and turned on or off with the @code{cp} request. The number 8958219019Sgaborregister @code{.C} is@w{ }1 if compatibility mode is on, 0@w{ 8959219019Sgabor}otherwise. 8960219019Sgabor 8961219019Sgabor@esindex \A 8962219019Sgabor@esindex \| 8963219019Sgabor@esindex \^ 8964219019Sgabor@esindex \& 8965219019Sgabor@esindex \@{ 8966219019Sgabor@esindex \@} 8967219019Sgabor@esindex \@key{SP} 8968219019Sgabor@esindex \' 8969219019Sgabor@esindex \` 8970219019Sgabor@esindex \- 8971219019Sgabor@esindex \_ 8972219019Sgabor@esindex \! 8973219019Sgabor@esindex \% 8974219019Sgabor@esindex \c 8975219019SgaborGNU @code{troff} does not allow the use of the escape sequences 8976219019Sgabor@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 8977219019Sgabor@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 8978219019Sgabor@code{\%}, and @code{\c} in names of strings, macros, diversions, number 8979219019Sgaborregisters, fonts or environments; @acronym{UNIX} @code{troff} does. The 8980219019Sgabor@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 8981219019Sgaboravoiding use of these escape sequences in names. 8982219019Sgabor 8983219019Sgabor@cindex fractional point sizes 8984219019Sgabor@cindex point sizes, fractional 8985219019Sgabor@rqindex ps 8986219019Sgabor@cindex @code{ps}, incompatibilities with Unix @code{troff} 8987219019SgaborFractional point sizes cause one noteworthy incompatibility. In 8988219019Sgabor@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 8989219019Sgaborindicators and thus 8990 8991@Example 8992.ps 10u 8993@endExample 8994 8995@noindent 8996sets the point size to 10@w{ }points, whereas in GNU @code{troff} it 8997sets the point size to 10@w{ }scaled points. @xref{Fractional Type 8998Sizes}, for more information. 8999 9000@rqindex bd 9001@rqindex cs 9002@rqindex tkf 9003@rqindex tr 9004@rqindex fp 9005@cindex @code{bd}, incompatibilities with Unix @code{troff} 9006@cindex @code{cs}, incompatibilities with Unix @code{troff} 9007@cindex @code{tkf}, incompatibilities with Unix @code{troff} 9008@cindex @code{tr}, incompatibilities with Unix @code{troff} 9009@cindex @code{fp}, incompatibilities with Unix @code{troff} 9010@cindex input and output characters, compatibility with Unix 9011@cindex output characters, compatibility with Unix 9012@cindex characters, input and output, compatibility with Unix 9013In GNU @code{troff} there is a fundamental difference between 9014unformatted, input characters, and formatted, output characters. 9015Everything that affects how an output character is output is stored 9016with the character; once an output character has been constructed it is 9017unaffected by any subsequent requests that are executed, including 9018@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 9019Normally output characters are constructed from input characters at the 9020moment immediately before the character is added to the current output 9021line. Macros, diversions and strings are all, in fact, the same type of 9022object; they contain lists of input characters and output characters in 9023any combination. An output character does not behave like an input 9024character for the purposes of macro processing; it does not inherit any 9025of the special properties that the input character from which it was 9026constructed might have had. For example, 9027 9028@Example 9029.di x 9030\\\\ 9031.br 9032.di 9033.x 9034@endExample 9035 9036@esindex \e 9037@esindex \! 9038@esindex \? 9039@cindex @code{\e}, incompatibilities with Unix @code{troff} 9040@cindex @code{\!}, incompatibilities with Unix @code{troff} 9041@cindex @code{\?}, incompatibilities with Unix @code{troff} 9042@cindex transparent output, incompatibilities with Unix @code{troff} 9043@cindex output, transparent, incompatibilities with Unix @code{troff} 9044@noindent 9045prints @samp{\\} in GNU @code{troff}; each pair of input backslashes 9046is turned into one output backslash and the resulting output backslashes 9047are not interpreted as escape characters when they are reread. 9048@acronym{UNIX} @code{troff} would interpret them as escape characters 9049when they were reread and would end up printing one @samp{\}. The 9050correct way to obtain a printable backslash is to use the @code{\e} 9051escape sequence: This always prints a single instance of the current 9052escape character, regardless of whether or not it is used in a 9053diversion; it also works in both GNU @code{troff} and @acronym{UNIX} 9054@code{troff}. To store, for some reason, an escape sequence in a 9055diversion that will be interpreted when the diversion is reread, either 9056use the traditional @code{\!} transparent output facility, or, if this 9057is unsuitable, the new @code{\?} escape sequence. 9058 9059@c XXX .tl compatibility mode -> input stack level 9060@c XXX .if compatibility mode -> input stack level 9061 9062@xref{Diversions}, for more information. 9063 9064 9065@c ===================================================================== 9066 9067@node Summary, , Implementation Differences, gtroff Reference 9068@section Summary 9069@cindex summary 9070 9071@c XXX documentation 9072 9073 9074 9075@c ===================================================================== 9076@c ===================================================================== 9077 9078@node Preprocessors, Output Devices, gtroff Reference, Top 9079@chapter Preprocessors 9080@cindex preprocessors 9081 9082This chapter describes all preprocessors that come with @code{groff} or 9083which are freely available. 9084 9085@menu 9086* geqn:: 9087* gtbl:: 9088* gpic:: 9089* ggrn:: 9090* grap:: 9091* grefer:: 9092* gsoelim:: 9093@end menu 9094 9095 9096@c ===================================================================== 9097 9098@node geqn, gtbl, Preprocessors, Preprocessors 9099@section @code{geqn} 9100@cindex @code{eqn} 9101@cindex @code{geqn} 9102 9103@c XXX 9104 9105@menu 9106* Invoking geqn:: 9107@end menu 9108 9109@c --------------------------------------------------------------------- 9110 9111@node Invoking geqn, , geqn, geqn 9112@subsection Invoking @code{geqn} 9113@cindex invoking @code{geqn} 9114@cindex @code{geqn}, invoking 9115 9116@c XXX 9117 9118 9119@c ===================================================================== 9120 9121@node gtbl, gpic, geqn, Preprocessors 9122@section @code{gtbl} 9123@cindex @code{tbl} 9124@cindex @code{gtbl} 9125 9126@c XXX 9127 9128@menu 9129* Invoking gtbl:: 9130@end menu 9131 9132@c --------------------------------------------------------------------- 9133 9134@node Invoking gtbl, , gtbl, gtbl 9135@subsection Invoking @code{gtbl} 9136@cindex invoking @code{gtbl} 9137@cindex @code{gtbl}, invoking 9138 9139@c XXX 9140 9141 9142@c ===================================================================== 9143 9144@node gpic, ggrn, gtbl, Preprocessors 9145@section @code{gpic} 9146@cindex @code{pic} 9147@cindex @code{gpic} 9148 9149@c XXX 9150 9151@menu 9152* Invoking gpic:: 9153@end menu 9154 9155@c --------------------------------------------------------------------- 9156 9157@node Invoking gpic, , gpic, gpic 9158@subsection Invoking @code{gpic} 9159@cindex invoking @code{gpic} 9160@cindex @code{gpic}, invoking 9161 9162@c XXX 9163 9164 9165@c ===================================================================== 9166 9167@node ggrn, grap, gpic, Preprocessors 9168@section @code{ggrn} 9169@cindex @code{grn} 9170@cindex @code{ggrn} 9171 9172@c XXX 9173 9174@menu 9175* Invoking ggrn:: 9176@end menu 9177 9178@c --------------------------------------------------------------------- 9179 9180@node Invoking ggrn, , ggrn, ggrn 9181@subsection Invoking @code{ggrn} 9182@cindex invoking @code{ggrn} 9183@cindex @code{ggrn}, invoking 9184 9185@c XXX 9186 9187 9188@c ===================================================================== 9189 9190@node grap, grefer, ggrn, Preprocessors 9191@section @code{grap} 9192@cindex @code{grap} 9193 9194A free implementation of @code{grap}, written by Ted Faber, 9195is available as an extra package from the following address: 9196 9197@display 9198@url{http://www.lunabase.org/~faber/Vault/software/grap/} 9199@end display 9200 9201 9202@c ===================================================================== 9203 9204@node grefer, gsoelim, grap, Preprocessors 9205@section @code{grefer} 9206@cindex @code{refer} 9207@cindex @code{grefer} 9208 9209@c XXX 9210 9211@menu 9212* Invoking grefer:: 9213@end menu 9214 9215@c --------------------------------------------------------------------- 9216 9217@node Invoking grefer, , grefer, grefer 9218@subsection Invoking @code{grefer} 9219@cindex invoking @code{grefer} 9220@cindex @code{grefer}, invoking 9221 9222@c XXX 9223 9224 9225@c ===================================================================== 9226 9227@node gsoelim, , grefer, Preprocessors 9228@section @code{gsoelim} 9229@cindex @code{soelim} 9230@cindex @code{gsoelim} 9231 9232@c XXX 9233 9234@menu 9235* Invoking gsoelim:: 9236@end menu 9237 9238@c --------------------------------------------------------------------- 9239 9240@node Invoking gsoelim, , gsoelim, gsoelim 9241@subsection Invoking @code{gsoelim} 9242@cindex invoking @code{gsoelim} 9243@cindex @code{gsoelim}, invoking 9244 9245@c XXX 9246 9247 9248 9249@c ===================================================================== 9250@c ===================================================================== 9251 9252@node Output Devices, File formats, Preprocessors, Top 9253@chapter Output Devices 9254@cindex output devices 9255@cindex devices for output 9256 9257@c XXX 9258 9259@menu 9260* Special Characters:: 9261* grotty:: 9262* grops:: 9263* grodvi:: 9264* grolj4:: 9265* grolbp:: 9266* grohtml:: 9267* gxditview:: 9268@end menu 9269 9270 9271@c ===================================================================== 9272 9273@node Special Characters, grotty, Output Devices, Output Devices 9274@section Special Characters 9275@cindex special characters 9276@cindex characters, special 9277 9278@c XXX 9279 9280@xref{Font Files}. 9281 9282 9283@c ===================================================================== 9284 9285@node grotty, grops, Special Characters, Output Devices 9286@section @code{grotty} 9287@cindex @code{grotty} 9288 9289@c XXX 9290 9291@menu 9292* Invoking grotty:: 9293@end menu 9294 9295@c --------------------------------------------------------------------- 9296 9297@node Invoking grotty, , grotty, grotty 9298@subsection Invoking @code{grotty} 9299@cindex invoking @code{grotty} 9300@cindex @code{grotty}, invoking 9301 9302@c XXX 9303 9304 9305@c ===================================================================== 9306 9307@node grops, grodvi, grotty, Output Devices 9308@section @code{grops} 9309@cindex @code{grops} 9310 9311@c XXX 9312 9313@menu 9314* Invoking grops:: 9315* Embedding PostScript:: 9316@end menu 9317 9318@c --------------------------------------------------------------------- 9319 9320@node Invoking grops, Embedding PostScript, grops, grops 9321@subsection Invoking @code{grops} 9322@cindex invoking @code{grops} 9323@cindex @code{grops}, invoking 9324 9325@c XXX 9326 9327@c --------------------------------------------------------------------- 9328 9329@node Embedding PostScript, , Invoking grops, grops 9330@subsection Embedding @sc{PostScript} 9331@cindex embedding postscript 9332@cindex postscript, embedding 9333 9334@c XXX 9335 9336 9337@c ===================================================================== 9338 9339@node grodvi, grolj4, grops, Output Devices 9340@section @code{grodvi} 9341@cindex @code{grodvi} 9342 9343@c XXX 9344 9345@menu 9346* Invoking grodvi:: 9347@end menu 9348 9349@c --------------------------------------------------------------------- 9350 9351@node Invoking grodvi, , grodvi, grodvi 9352@subsection Invoking @code{grodvi} 9353@cindex invoking @code{grodvi} 9354@cindex @code{grodvi}, invoking 9355 9356@c XXX 9357 9358 9359@c ===================================================================== 9360 9361@node grolj4, grolbp, grodvi, Output Devices 9362@section @code{grolj4} 9363@cindex @code{grolj4} 9364 9365@c XXX 9366 9367@menu 9368* Invoking grolj4:: 9369@end menu 9370 9371@c --------------------------------------------------------------------- 9372 9373@node Invoking grolj4, , grolj4, grolj4 9374@subsection Invoking @code{grolj4} 9375@cindex invoking @code{grolj4} 9376@cindex @code{grolj4}, invoking 9377 9378@c XXX 9379 9380 9381@c ===================================================================== 9382 9383@node grolbp, grohtml, grolj4, Output Devices 9384@section @code{grolbp} 9385@cindex @code{grolbp} 9386 9387@c XXX 9388 9389@menu 9390* Invoking grolbp:: 9391@end menu 9392 9393@c --------------------------------------------------------------------- 9394 9395@node Invoking grolbp, , grolbp, grolbp 9396@subsection Invoking @code{grolbp} 9397@cindex invoking @code{grolbp} 9398@cindex @code{grolbp}, invoking 9399 9400@c XXX 9401 9402 9403@c ===================================================================== 9404 9405@node grohtml, gxditview, grolbp, Output Devices 9406@section @code{grohtml} 9407@cindex @code{grohtml} 9408 9409@c XXX 9410 9411@menu 9412* Invoking grohtml:: 9413@end menu 9414 9415@c --------------------------------------------------------------------- 9416 9417@node Invoking grohtml, , grohtml, grohtml 9418@subsection Invoking @code{grohtml} 9419@cindex invoking @code{grohtml} 9420@cindex @code{grohtml}, invoking 9421 9422@c XXX 9423 9424 9425@c ===================================================================== 9426 9427@node gxditview, , grohtml, Output Devices 9428@section @code{gxditview} 9429@cindex @code{gxditview} 9430 9431@c XXX 9432 9433@menu 9434* Invoking gxditview:: 9435@end menu 9436 9437@c --------------------------------------------------------------------- 9438 9439@node Invoking gxditview, , gxditview, gxditview 9440@subsection Invoking @code{gxditview} 9441@cindex invoking @code{gxditview} 9442@cindex @code{gxditview}, invoking 9443 9444@c XXX 9445@c X11's xditview 9446 9447 9448 9449@c ===================================================================== 9450@c ===================================================================== 9451 9452@node File formats, Installation, Output Devices, Top 9453@chapter File formats 9454@cindex file formats 9455@cindex formats, file 9456 9457@c XXX 9458 9459@menu 9460* gtroff Output:: 9461* Font Files:: 9462@end menu 9463 9464 9465@c ===================================================================== 9466 9467@node gtroff Output, Font Files, File formats, File formats 9468@section @code{gtroff} Output 9469@cindex @code{gtroff} output 9470@cindex output, @code{gtroff} 9471 9472This section describes the format output of GNU @code{troff}. The 9473output format used by GNU @code{troff} is very similar -- but 9474not identical -- to that used by 9475@acronym{UNIX} device-independent @code{troff} (@code{ditroff}). 9476 9477@menu 9478* Output Format:: 9479* Device Control:: 9480* Drawing Functions:: 9481* Line Continuation:: 9482@end menu 9483 9484@c --------------------------------------------------------------------- 9485 9486@node Output Format, Device Control, gtroff Output, gtroff Output 9487@subsection Output Format 9488@cindex output format 9489@cindex format of output 9490 9491@cindex 8-bit input 9492@cindex input, 8-bit 9493The output format is text based, as opposed to a binary format (like 9494@TeX{} DVI). The output format is @w{8-bit} clean, thus single 9495characters can have the eighth bit set, as can the names of fonts and 9496special characters. 9497 9498The output format consists of single command characters with attached 9499parameters which are separated from subsequent text by whitespace or a 9500newline. 9501 9502The names of characters and fonts can be of arbitrary length; drivers 9503should not assume that they are only two characters long (as 9504@code{ditroff} does). 9505 9506When a character is to be printed, that character is always in the 9507current font. Unlike @code{ditroff}, it is not necessary for drivers to 9508search special fonts to find a character. 9509 9510@table @code 9511@item H@var{n} 9512@c XXX 9513 9514@item V@var{n} 9515@c XXX 9516 9517@item h@var{n} 9518@c XXX 9519 9520@item v@var{n} 9521@c XXX 9522 9523@item c@var{n} 9524@c XXX 9525 9526@item C@var{n} 9527@c XXX 9528 9529@item @var{nn}@var{c} 9530@c XXX 9531 9532@item t@var{xxx} 9533@var{xxx} is any sequence of characters terminated by a space or a 9534newline; the first character should be printed at the current position, 9535the the current horizontal position should be increased by the width of 9536the first character, and so on for each character. The width of the 9537character is that given in the font file, appropriately scaled for the 9538current point size, and rounded so that it is a multiple of the 9539horizontal resolution. Special characters cannot be printed using this 9540command. 9541 9542@kindex tcommand 9543@pindex DESC@r{, and @code{tcommand}} 9544This command is only allowed if the @samp{tcommand} line is present in 9545the @file{DESC} file. 9546 9547@item u@var{n} @var{xxx} 9548This is same as the @samp{t} command except that after printing each 9549character, the current horizontal position is increased by the sum of 9550the width of that character and@w{ }@var{n}. 9551 9552This command is only allowed if the @samp{tcommand} line is present in 9553the @file{DESC} file. 9554 9555@item n@var{a}@var{b} 9556@c XXX 9557 9558@item p@var{n} 9559@c XXX 9560 9561@item s@var{n} 9562@kindex sizescale 9563@pindex DESC@r{, and @code{sizescale}} 9564The argument to the @samp{s} command is in scaled points (units of 9565points/@var{n}, where @var{n} is the argument to the @samp{sizescale} 9566command in the @file{DESC} file). 9567 9568@item f@var{n} 9569@item x @dots{} \n 9570Device control. 9571@c XXX more info 9572 9573@item D@var{c} @var{x}@dots{}\n 9574@c XXX 9575@end table 9576 9577@c --------------------------------------------------------------------- 9578 9579@node Device Control, Drawing Functions, Output Format, gtroff Output 9580@subsection Device Control 9581@cindex device control 9582@cindex control of devices 9583 9584The @samp{x} command is normally followed by a letter or word indicating 9585the function to perform, followed by white space separated arguments. 9586 9587The first argument can be abbreviated to the first letter. 9588 9589@table @code 9590@item x init 9591@c XXX 9592 9593@item x T 9594@c XXX 9595 9596@item x res @var{n} @var{h} @var{v} 9597@c XXX 9598 9599@item x H 9600@c XXX more info 9601The argument to the @w{@samp{x Height}} command is also in scaled 9602points. 9603@end table 9604 9605The first three output commands are guaranteed to be: 9606 9607@Example 9608x T device 9609x res n h v 9610x init 9611@endExample 9612 9613@noindent 9614For example, the input 9615 9616@Example 9617crunchy \fH\s+2frog\s0\fP!? 9618@endExample 9619 9620@noindent 9621produces 9622 9623@c XXX example 9624 9625@ignore 9626@Example 9627... sample output here ... 9628@endExample 9629@end ignore 9630 9631@c --------------------------------------------------------------------- 9632 9633@node Drawing Functions, Line Continuation, Device Control, gtroff Output 9634@subsection Drawing Functions 9635@cindex drawing functions 9636@cindex functions for drawing 9637 9638@pindex gpic 9639The @samp{D} drawing command has been extended. These extensions are 9640used by GNU @code{pic} only if the @option{-x} option is given. 9641 9642@xref{Drawing Requests}. 9643 9644@table @code 9645@c XXX ... 9646@item Df @var{n} 9647Set the shade of gray to be used for filling solid objects to@w{ 9648}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 9649corresponds solid white and 1000 to solid black, and values in between 9650correspond to intermediate shades of gray. This applies only to solid 9651circles, solid ellipses and solid polygons. By default, a level of@w{ 9652}1000 is used. Whatever color a solid object has, it should 9653completely obscure everything beneath it. A value greater than@w{ }1000 9654or less than@w{ }0 can also be used: this means fill with the shade of 9655gray that is currently being used for lines and text. Normally this 9656is black, but some drivers may provide a way of changing this. 9657 9658@item DC @var{d} 9659Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost 9660point at the current position. 9661 9662@item DE @var{dx} @var{dy} 9663Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a 9664vertical diameter of@w{ }@var{dy} with the leftmost point at the current 9665position. 9666 9667@item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn} 9668Draw a polygon with automatic closure. The first vertex is at the 9669current position, the second vertex at an offset (@var{dx1},@var{dy1}) 9670from the current position, the second vertex at an offset 9671(@var{dx2},@var{dy2}) from the first vertex, and so on up to the 9672@var{n}@dmn{th} vertex. At the moment, GNU @code{pic} only uses this 9673command to generate triangles and rectangles. 9674 9675@item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn} 9676Like @code{Dp} but draw a solid rather than outlined polygon. 9677 9678@item Dt @var{n} 9679@cindex line thickness 9680@cindex thickness of lines 9681Set the current line thickness to @var{n}@w{ }machine units. 9682Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness 9683proportional to the current point size; drivers should continue to do 9684this if no @code{Dt} command has been given, or if a @code{Dt} command 9685has been given with a negative value of@w{ }@var{n}. A zero value of@w{ 9686}@var{n} selects the smallest available line thickness. 9687@end table 9688 9689@esindex \D 9690A difficulty arises in how the current position should be changed after 9691the execution of these commands. This is not of great importance since 9692the code generated by GNU @code{pic} does not depend on this. Given a 9693drawing command of the form 9694 9695@Example 9696\D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}' 9697@endExample 9698 9699@esindex \w 9700@vindex st 9701@vindex sb 9702@noindent 9703where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or 9704@samp{~}, @acronym{UNIX} @code{troff} treats each x@w{ }value 9705as a horizontal quantity, and each y@w{ }value as a vertical 9706quantity; it assumes that the width of the drawn object is the sum of 9707all x@w{ }values, and that the height is the sum of all y@w{ }values. 9708(The assumption about the height can be seen by examining the @code{st} 9709and @code{sb} registers after using such a @code{D}@w{ }command in a 9710@code{\w} escape sequence.) This rule also holds for all the original 9711drawing commands with the exception of @code{De}. For the sake of 9712compatibility GNU @code{troff} also follows this rule, even though it 9713produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to 9714a lesser extent, @code{DE}@w{ }commands. Thus after executing a 9715@code{D}@w{ }command of the form 9716 9717@Example 9718D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn} 9719@endExample 9720 9721@noindent 9722the current position should be increased horizontally by the sum of all 9723x@w{ }values and vertically by the sum of all y@w{ }values. 9724 9725@c --------------------------------------------------------------------- 9726 9727@node Line Continuation, , Drawing Functions, gtroff Output 9728@subsection Line Continuation 9729@cindex line continuation in output commands 9730@cindex output commands, line continuation 9731 9732There is a continuation convention which permits the argument to the 9733@w{@samp{x X}} command to contain newlines: When outputting the argument 9734to the @w{@samp{x X}} command, GNU @code{troff} follows each newline 9735in the argument with a @samp{+} character (as usual, it terminates 9736the entire argument with a newline); thus if the line after the line 9737containing the @w{@samp{x X}} command starts with @samp{+}, then the 9738newline ending the line containing the @w{@samp{x X}} command should be 9739treated as part of the argument to the @w{@samp{x X}} command, the 9740@samp{+} should be ignored, and the part of the line following the 9741@samp{+} should be treated like the part of the line following the 9742@w{@samp{x X}} command. 9743 9744 9745@c ===================================================================== 9746 9747@node Font Files, , gtroff Output, File formats 9748@section Font Files 9749@cindex font files 9750@cindex files, font 9751 9752The @code{gtroff} font format is roughly a superset of the 9753@code{ditroff} font format. Unlike the @code{ditroff} font format, 9754there is no associated binary format; all files are text files. The 9755font files for device @var{name} are stored in a directory 9756@file{dev@var{name}}. There are two types of file: a device description 9757file called @file{DESC} and for each font@w{ }@var{f} a font file 9758called@w{ }@file{@var{f}}. 9759 9760@menu 9761* DESC File Format:: 9762* Font File Format:: 9763@end menu 9764 9765@c --------------------------------------------------------------------- 9766 9767@node DESC File Format, Font File Format, Font Files, Font Files 9768@subsection @file{DESC} File Format 9769@cindex @file{DESC} file format 9770@cindex font description file format 9771@cindex format of font description file 9772@pindex DESC@r{ file format} 9773 9774The @file{DESC} file can contain the following types of line: 9775 9776@table @code 9777@item res @var{n} 9778@kindex res 9779There are @var{n} machine units per inch. 9780 9781@item hor @var{n} 9782@kindex hor 9783The horizontal resolution is @var{n} machine units. 9784 9785@item vert @var{n} 9786@kindex vert 9787The vertical resolution is @var{n} machine units. 9788 9789@item sizescale @var{n} 9790@kindex sizescale 9791The scale factor for point sizes. By default this has a value of@w{ }1. 9792One scaled point is equal to one point/@var{n}. The arguments to the 9793@code{unitwidth} and @code{sizes} commands are given in scaled points. 9794@xref{Fractional Type Sizes}, for more information. 9795 9796@item unitwidth @var{n} 9797@kindex unitwidth 9798Quantities in the font files are given in machine units for fonts whose 9799point size is @var{n}@w{ }scaled points. 9800 9801@item tcommand 9802@kindex tcommand 9803This means that the postprocessor can handle the @samp{t} and @samp{u} 9804output commands. 9805 9806@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 9807@kindex sizes 9808This means that the device has fonts at @var{s1}, @var{s2}, @dots{} 9809@var{sn} scaled points. The list of sizes must be terminated by a@w{ 9810}0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The 9811list can extend over more than one line. 9812 9813@item styles @var{S1} @var{S2} @dots{} @var{Sm} 9814@kindex styles 9815The first @var{m}@w{ }font positions are associated with styles 9816@var{S1} @dots{} @var{Sm}. 9817 9818@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 9819@kindex fonts 9820Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 9821@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 9822styles. This command may extend over more than one line. A font name 9823of@var{ }0 means no font is mounted on the corresponding font position. 9824 9825@item family @var{fam} 9826@kindex family 9827The default font family is @var{fam}. 9828 9829@item charset 9830@kindex charset 9831This line and everything following in the file are ignored. It is 9832allowed for the sake of backwards compatibility. 9833@end table 9834 9835The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines 9836are mandatory. Other commands are ignored by @code{gtroff} but may be 9837used by postprocessors to store arbitrary information about the device 9838in the @file{DESC} file. 9839 9840@c XXX add other commands resp. xrefs to output devices 9841@c XXX add obsolete commands 9842 9843@c --------------------------------------------------------------------- 9844 9845@node Font File Format, , DESC File Format, Font Files 9846@subsection Font File Format 9847@cindex font file format 9848@cindex format of font files 9849 9850A font file has two sections. The first section is a sequence of lines 9851each containing a sequence of blank delimited words; the first word in 9852the line is a key, and subsequent words give a value for that key. 9853 9854@table @code 9855@item name @var{f} 9856@kindex name 9857The name of the font is@w{ }@var{f}. 9858 9859@item spacewidth @var{n} 9860@kindex spacewidth 9861The normal width of a space is@w{ }@var{n}. 9862 9863@item slant @var{n} 9864@kindex slant 9865The characters of the font have a slant of @var{n}@w{ }degrees. 9866(Positive means forward.) 9867 9868@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 9869@kindex ligatures 9870Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 9871possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 9872@samp{ffl}. For backwards compatibility, the list of ligatures may be 9873terminated with a@w{ }0. The list of ligatures may not extend over more 9874than one line. 9875 9876@item special 9877@kindex special 9878The font is special; this means that when a character is requested that 9879is not present in the current font, it is searched for in any 9880special fonts that are mounted. 9881@end table 9882 9883Other commands are ignored by @code{gtroff} but may be used by 9884postprocessors to store arbitrary information about the font in the font 9885file. 9886 9887@cindex comments in font files 9888@cindex font files, comments 9889@kindex # 9890The first section can contain comments which start with the @samp{#} 9891character and extend to the end of a line. 9892 9893The second section contains one or two subsections. It must contain a 9894@code{charset} subsection and it may also contain a @code{kernpairs} 9895subsection. These subsections can appear in any order. Each 9896subsection starts with a word on a line by itself. 9897 9898@kindex charset 9899The word @code{charset} starts the character set subsection. The 9900@code{charset} line is followed by a sequence of lines. Each line gives 9901information for one character. A line comprises a number of fields 9902separated by blanks or tabs. The format is 9903 9904@c XXX fix it for new HTML additions 9905 9906@Example 9907@var{name} @var{metrics} @var{type} @var{code} @var{comment} 9908@endExample 9909 9910@cindex 8-bit input 9911@cindex input, 8-bit 9912@esindex \N 9913@kindex --- 9914@noindent 9915@var{name} identifies the character: If @var{name} is a single 9916character@w{ }@var{c} then it corresponds to the @code{gtroff} input 9917character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is 9918a single character, then it corresponds to the @code{gtroff} input 9919character@w{ }\@var{c}; otherwise it corresponds to the groff input 9920character @samp{\[@var{name}]}. (If it is exactly two characters 9921@var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff} 9922supports 8-bit characters; however some utilities have difficulties with 9923eight-bit characters. For this reason, there is a convention that the 9924name @samp{char@var{n}} is equivalent to the single character whose code 9925is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the 9926character with code@w{ }163 which is the pounds sterling sign in @w{ISO 9927Latin-1} character set. The name @samp{---} is special and indicates 9928that the character is unnamed; such characters can only be used by means 9929of the @code{\N} escape sequence in @code{gtroff}. 9930 9931@c XXX input encodings vs. output encodings 9932 9933The @var{type} field gives the character type: 9934 9935@table @code 9936@item 1 9937the character has an descender, for example, `p'; 9938 9939@item 2 9940the character has an ascender, for example, `b'; 9941 9942@item 3 9943the character has both an ascender and a descender, for example, `('. 9944@end table 9945 9946The @var{code} field gives the code which the postprocessor uses to 9947print the character. The character can also be input to @code{gtroff} 9948using this code by means of the @code{\N} escape sequence. The code can 9949be any integer. If it starts with @samp{0} it is interpreted as 9950octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 9951hexadecimal. 9952 9953Anything on the line after the @var{code} field is ignored. 9954 9955The @var{metrics} field has the form: 9956 9957@Example 9958@var{width}[,@var{height}[,@var{depth}[,@var{italic_correction} 9959 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]] 9960@endExample 9961 9962@noindent 9963There must not be any spaces between these subfields (it has been split 9964here into two lines for better legibility only). Missing subfields are 9965assumed to be@w{ }0. The subfields are all decimal integers. Since 9966there is no associated binary format, these values are not required to 9967fit into a variable of type @samp{char} as they are in @code{ditroff}. 9968The @var{width} subfield gives the width of the character. The 9969@var{height} subfield gives the height of the character (upwards is 9970positive); if a character does not extend above the baseline, it should 9971be given a zero height, rather than a negative height. The @var{depth} 9972subfield gives the depth of the character, that is, the distance below 9973the lowest point below the baseline to which the character extends 9974(downwards is positive); if a character does not extend below above the 9975baseline, it should be given a zero depth, rather than a negative depth. 9976The @var{italic_correction} subfield gives the amount of space that 9977should be added after the character when it is immediately to be 9978followed by a character from a roman font. The 9979@var{left_italic_correction} subfield gives the amount of space that 9980should be added before the character when it is immediately to be 9981preceded by a character from a roman font. The 9982@var{subscript_correction} gives the amount of space that should be 9983added after a character before adding a subscript. This should be less 9984than the italic correction. 9985 9986A line in the @code{charset} section can also have the format 9987 9988@Example 9989@var{name} " 9990@endExample 9991 9992@noindent 9993This indicates that @var{name} is just another name for the character 9994mentioned in the preceding line. 9995 9996@kindex kernpairs 9997The word @code{kernpairs} starts the kernpairs section. This contains a 9998sequence of lines of the form: 9999 10000@Example 10001@var{c1} @var{c2} @var{n} 10002@endExample 10003 10004@noindent 10005This means that when character @var{c1} appears next to character 10006@var{c2} the space between them should be increased by@w{ }@var{n}. 10007Most entries in the kernpairs section have a negative value for@w{ 10008}@var{n}. 10009 10010 10011 10012@c ===================================================================== 10013@c ===================================================================== 10014 10015@node Installation, Request Index, File formats, Top 10016@chapter Installation 10017@cindex installation 10018 10019@c XXX 10020 10021 10022 10023@c ===================================================================== 10024@c ===================================================================== 10025 10026@node Request Index, Escape Index, Installation, Top 10027@chapter Request Index 10028 10029Requests appear without the leading control character (normally either 10030@samp{.} or @samp{'}). 10031 10032@printindex rq 10033 10034 10035 10036@c ===================================================================== 10037@c ===================================================================== 10038 10039@node Escape Index, Operator Index, Request Index, Top 10040@chapter Escape Index 10041 10042@printindex es 10043 10044 10045 10046@c ===================================================================== 10047@c ===================================================================== 10048 10049@node Operator Index, Register Index, Escape Index, Top 10050@chapter Operator Index 10051 10052@printindex op 10053 10054 10055 10056@c ===================================================================== 10057@c ===================================================================== 10058 10059@node Register Index, Macro Index, Operator Index, Top 10060@chapter Register Index 10061 10062@printindex vr 10063 10064 10065 10066@c ===================================================================== 10067@c ===================================================================== 10068 10069@node Macro Index, String Index, Register Index, Top 10070@chapter Macro Index 10071 10072@printindex ma 10073 10074 10075 10076@c ===================================================================== 10077@c ===================================================================== 10078 10079@node String Index, Glyph Name Index, Macro Index, Top 10080@chapter String Index 10081 10082@printindex st 10083 10084 10085 10086@c ===================================================================== 10087@c ===================================================================== 10088 10089@node Glyph Name Index, Font File Keyword Index, String Index, Top 10090@chapter Glyph Name Index 10091 10092A glyph name @code{xx} consisting of exactly two characters can be 10093accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 10094accessed as @samp{\[xxx]}. 10095 10096@printindex gl 10097 10098 10099 10100@c ===================================================================== 10101@c ===================================================================== 10102 10103@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 10104@chapter Font File Keyword Index 10105 10106@printindex ky 10107 10108 10109 10110@c ===================================================================== 10111@c ===================================================================== 10112 10113@node Program and File Index, Concept Index, Font File Keyword Index, Top 10114@chapter Program and File Index 10115 10116@printindex pg 10117 10118 10119 10120@c ===================================================================== 10121@c ===================================================================== 10122 10123@node Concept Index, , Program and File Index, Top 10124@chapter Concept Index 10125 10126@printindex cp 10127 10128 10129 10130@summarycontents 10131@contents 10132@bye 10133