groff.texinfo revision 55839
1219019Sgabor\input texinfo @c -*-texinfo-*- 2219019Sgabor@c %**start of header (This is for running Texinfo on a region.) 3219019Sgabor@setfilename groff 4219019Sgabor@settitle The GNU Troff Manual 5219019Sgabor@setchapternewpage odd 6219019Sgabor@footnotestyle separate 7219019Sgabor@c %**end of header (This is for running Texinfo on a region.) 8219019Sgabor 9219019Sgabor 10219019Sgabor@dircategory Miscellaneous 11219019Sgabor@direntry 12219019Sgabor* Groff: (groff). The GNU troff document formatting system. 13219019Sgabor@end direntry 14219019Sgabor 15219019Sgabor 16219019Sgabor@smallbook 17219019Sgabor 18219019Sgabor 19219019Sgabor@iftex 20219019Sgabor@finalout 21219019Sgabor@end iftex 22219019Sgabor 23219019Sgabor 24219019Sgabor@ifinfo 25219019SgaborThis Info file documents GNU troff version 1.12. 26219019Sgabor 27219019SgaborPublished by the Free Software Foundation 28219019Sgabor59 Temple Place, Suite 330 29219019SgaborBoston, MA 02111-1307 USA 30219019Sgabor 31219019SgaborCopyright (C) 1994, 1999 Free Software Foundation, Inc. 32219019Sgabor 33219019SgaborPermission is granted to make and distribute verbatim copies of this 34219019Sgabormanual provided the copyright notice and this permission notice are 35219019Sgaborpreserved on all copies. 36219019Sgabor 37219019Sgabor@ignore 38219019SgaborPermission is granted to process this file through TeX and print the 39219019Sgaborresults, provided the printed document carries copying permission notice 40219019Sgaboridentical to this one except for the removal of this paragraph (this 41219019Sgaborparagraph not being relevant to the printed manual). 42219019Sgabor 43219019Sgabor@end ignore 44219019SgaborPermission is granted to copy and distribute modified versions of this 45219019Sgabormanual under the conditions for verbatim copying, provided that the 46219019Sgaborentire resulting derived work is distributed under the terms of a 47219019Sgaborpermission notice identical to this one. 48219019Sgabor 49219019SgaborPermission is granted to copy and distribute translations of this manual 50219019Sgaborinto another language, under the above conditions for modified versions, 51219019Sgaborexcept that this permission notice may be stated in a translation 52219019Sgaborapproved by the Foundation. 53219019Sgabor 54219019SgaborPermission is granted to copy and distribute modified versions of this 55219019Sgabormanual under the conditions for verbatim copying, provided also that the 56219019Sgaborsection entitled ``GNU General Public License'' is included exactly as 57219019Sgaborin the original, and provided that the entire resulting derived work is 58219019Sgabordistributed under the terms of a permission notice identical to this 59219019Sgaborone. 60219019Sgabor 61219019SgaborPermission is granted to copy and distribute translations of this manual 62219019Sgaborinto another language, under the above conditions for modified versions, 63219019Sgaborexcept that the section entitled ``GNU General Public License'' may be 64219019Sgaborincluded in a translation approved by the Free Software Foundation 65219019Sgaborinstead of in the original English. 66219019Sgabor@end ifinfo 67219019Sgabor 68219019Sgabor 69219019Sgabor@titlepage 70219019Sgabor@title groff 71219019Sgabor@subtitle The GNU implementation of @code{groff} 72219019Sgabor@subtitle Edition 1.12 73219019Sgabor@subtitle October 1999 74219019Sgabor@author by Trent A.@w{ }Fisher 75219019Sgabor@author and the maintainer of groff 76219019Sgabor 77219019Sgabor@c Include the Distribution inside the titlepage environment so 78219019Sgabor@c that headings are turned off. Headings on and off do not work. 79219019Sgabor 80219019Sgabor@page 81219019Sgabor@vskip 0pt plus 1filll 82219019SgaborCopyright @copyright{} 1994, 1999 Free Software Foundation, Inc. 83219019Sgabor 84219019Sgabor@sp 2 85219019SgaborVersion 1.13 of @code{groff}, @* 86219019SgaborOctober 1999 87219019Sgabor@sp 2 88219019SgaborPublished by the Free Software Foundation @* 89219019Sgabor59 Temple Place, Suite 330 @* 90219019SgaborBoston, MA 02111-1307 USA 91219019Sgabor 92219019Sgabor 93219019SgaborPermission is granted to make and distribute verbatim copies of this 94219019Sgabormanual provided the copyright notice and this permission notice are 95219019Sgaborpreserved on all copies. 96219019Sgabor 97219019SgaborPermission is granted to copy and distribute modified versions of this 98219019Sgabormanual under the conditions for verbatim copying, provided also that the 99219019Sgaborsection entitled ``GNU General Public License'' is included 100219019Sgaborexactly as in the original, and provided that the entire resulting 101219019Sgaborderived work is distributed under the terms of a permission notice 102219019Sgaboridentical to this one. 103219019Sgabor 104219019SgaborPermission is granted to copy and distribute translations of this manual 105219019Sgaborinto another language, under the above conditions for modified versions, 106219019Sgaborexcept that the section entitled ``GNU General Public License'' may be 107219019Sgaborincluded in a translation approved by the Free Software Foundation 108219019Sgaborinstead of in the original English. 109219019Sgabor 110219019SgaborCover art by Etienne Suvasa. 111219019Sgabor@end titlepage 112219019Sgabor@page 113219019Sgabor 114219019Sgabor 115219019Sgabor 116219019Sgabor@node Top, Copying, (dir), (dir) 117219019Sgabor 118219019Sgabor@ifinfo 119219019SgaborThis Info file documents groff version 1.13, the GNU implementation of 120219019Sgaborthe troff typesetting system. 121219019Sgabor 122219019SgaborThis is an in-progress document; contributions, comments, or 123219019Sgaborcontributions are welcome. Send them to bug-groff@@gnu.org. 124219019Sgabor@end ifinfo 125219019Sgabor 126219019Sgabor@menu 127219019Sgabor* Copying:: 128219019Sgabor* Introduction:: 129219019Sgabor* Invoking groff:: 130219019Sgabor* Tutorial for Macro Users:: 131219019Sgabor* -man:: 132219019Sgabor* -ms:: 133219019Sgabor* -me:: 134219019Sgabor* -mm:: 135219019Sgabor* Programming Tutorial:: 136219019Sgabor* geqn:: 137219019Sgabor* gtbl:: 138219019Sgabor* gpic:: 139219019Sgabor* grap:: 140219019Sgabor* grefer:: 141219019Sgabor* gsoelim:: 142219019Sgabor* Devices:: 143219019Sgabor* File formats:: 144219019Sgabor* Installation:: 145219019Sgabor* Request Index:: 146219019Sgabor* Register Index:: 147219019Sgabor* String Index:: 148219019Sgabor* Macro Index:: 149219019Sgabor* Program Index:: 150219019Sgabor* Concept Index:: 151219019Sgabor@end menu 152219019Sgabor 153219019Sgabor 154219019Sgabor 155219019Sgabor@node Copying, Introduction, Top, Top 156219019Sgabor@cindex copying 157219019Sgabor@unnumbered GNU GENERAL PUBLIC LICENSE 158219019Sgabor@center Version 2, June 1991 159219019Sgabor 160219019Sgabor@display 161219019SgaborCopyright @copyright{} 1989, 1991 Free Software Foundation, Inc. 162219019Sgabor59 Temple Place, Suite 330, Boston, MA 02111, USA 163219019Sgabor 164219019SgaborEveryone is permitted to copy and distribute verbatim copies of this 165219019Sgaborlicense document, but changing it is not allowed. 166219019Sgabor@end display 167219019Sgabor 168219019Sgabor@unnumberedsec Preamble 169219019Sgabor 170219019SgaborThe licenses for most software are designed to take away your freedom to 171219019Sgaborshare and change it. By contrast, the GNU General Public License is 172219019Sgaborintended to guarantee your freedom to share and change free software -- 173219019Sgaborto make sure the software is free for all its users. This General 174219019SgaborPublic License applies to most of the Free Software Foundation's 175219019Sgaborsoftware and to any other program whose authors commit to using it. 176219019Sgabor(Some other Free Software Foundation software is covered by the GNU 177219019SgaborLibrary General Public License instead.) You can apply it to your 178219019Sgaborprograms, too. 179219019Sgabor 180219019SgaborWhen we speak of free software, we are referring to freedom, not price. 181219019SgaborOur General Public Licenses are designed to make sure that you have the 182219019Sgaborfreedom to distribute copies of free software (and charge for this 183219019Sgaborservice if you wish), that you receive source code or can get it if you 184219019Sgaborwant it, that you can change the software or use pieces of it in new 185219019Sgaborfree programs; and that you know you can do these things. 186219019Sgabor 187219019SgaborTo protect your rights, we need to make restrictions that forbid anyone 188219019Sgaborto deny you these rights or to ask you to surrender the rights. These 189219019Sgaborrestrictions translate to certain responsibilities for you if you 190219019Sgabordistribute copies of the software, or if you modify it. 191219019Sgabor 192219019SgaborFor example, if you distribute copies of such a program, whether gratis 193219019Sgaboror for a fee, you must give the recipients all the rights that you have. 194219019SgaborYou must make sure that they, too, receive or can get the source code. 195219019SgaborAnd you must show them these terms so they know their rights. 196219019Sgabor 197219019SgaborWe protect your rights with two steps: (1)@w{ }copyright the software, 198219019Sgaborand (2)@w{ }offer you this license which gives you legal permission to 199219019Sgaborcopy, distribute and/or modify the software. 200219019Sgabor 201219019SgaborAlso, for each author's protection and ours, we want to make certain 202219019Sgaborthat everyone understands that there is no warranty for this free 203219019Sgaborsoftware. If the software is modified by someone else and passed on, we 204219019Sgaborwant its recipients to know that what they have is not the original, so 205219019Sgaborthat any problems introduced by others will not reflect on the original 206219019Sgaborauthors' reputations. 207219019Sgabor 208219019SgaborFinally, any free program is threatened constantly by software patents. 209219019SgaborWe wish to avoid the danger that redistributors of a free program will 210219019Sgaborindividually obtain patent licenses, in effect making the program 211219019Sgaborproprietary. To prevent this, we have made it clear that any patent 212219019Sgabormust be licensed for everyone's free use or not licensed at all. 213219019Sgabor 214219019SgaborThe precise terms and conditions for copying, distribution and 215219019Sgabormodification follow. 216219019Sgabor 217219019Sgabor@iftex 218219019Sgabor@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 219219019Sgabor@end iftex 220219019Sgabor@ifinfo 221219019Sgabor@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 222219019Sgabor@end ifinfo 223219019Sgabor 224219019Sgabor@enumerate 0 225219019Sgabor@item 226219019SgaborThis License applies to any program or other work which contains a 227219019Sgabornotice placed by the copyright holder saying it may be distributed under 228219019Sgaborthe terms of this General Public License. The ``Program'', below, 229219019Sgaborrefers to any such program or work, and a ``work based on the Program'' 230219019Sgabormeans either the Program or any derivative work under copyright law: 231219019Sgaborthat is to say, a work containing the Program or a portion of it, either 232219019Sgaborverbatim or with modifications and/or translated into another language. 233219019Sgabor(Hereinafter, translation is included without limitation in the term 234219019Sgabor``modification''.) Each licensee is addressed as ``you''. 235219019Sgabor 236219019SgaborActivities other than copying, distribution and modification are not 237219019Sgaborcovered by this License; they are outside its scope. The act of running 238219019Sgaborthe Program is not restricted, and the output from the Program is 239219019Sgaborcovered only if its contents constitute a work based on the Program 240219019Sgabor(independent of having been made by running the Program). Whether that 241219019Sgaboris true depends on what the Program does. 242219019Sgabor 243219019Sgabor@item 244219019SgaborYou may copy and distribute verbatim copies of the Program's source code 245219019Sgaboras you receive it, in any medium, provided that you conspicuously and 246219019Sgaborappropriately publish on each copy an appropriate copyright notice and 247219019Sgabordisclaimer of warranty; keep intact all the notices that refer to this 248219019SgaborLicense and to the absence of any warranty; and give any other 249219019Sgaborrecipients of the Program a copy of this License along with the Program. 250219019Sgabor 251219019SgaborYou may charge a fee for the physical act of transferring a copy, and 252219019Sgaboryou may at your option offer warranty protection in exchange for a fee. 253219019Sgabor 254219019Sgabor@item 255219019SgaborYou may modify your copy or copies of the Program or any portion of it, 256219019Sgaborthus forming a work based on the Program, and copy and distribute such 257219019Sgabormodifications or work under the terms of Section@w{ }1 above, provided 258219019Sgaborthat you also meet all of these conditions: 259219019Sgabor 260219019Sgabor@enumerate a 261219019Sgabor@item 262219019SgaborYou must cause the modified files to carry prominent notices stating 263219019Sgaborthat you changed the files and the date of any change. 264219019Sgabor 265219019Sgabor@item 266219019SgaborYou must cause any work that you distribute or publish, that in whole or 267219019Sgaborin part contains or is derived from the Program or any part thereof, to 268219019Sgaborbe licensed as a whole at no charge to all third parties under the terms 269219019Sgaborof this License. 270219019Sgabor 271219019Sgabor@item 272219019SgaborIf the modified program normally reads commands interactively when run, 273219019Sgaboryou must cause it, when started running for such interactive use in the 274219019Sgabormost ordinary way, to print or display an announcement including an 275219019Sgaborappropriate copyright notice and a notice that there is no warranty (or 276219019Sgaborelse, saying that you provide a warranty) and that users may 277219019Sgaborredistribute the program under these conditions, and telling the user 278219019Sgaborhow to view a copy of this License. (Exception: if the Program itself 279219019Sgaboris interactive but does not normally print such an announcement, your 280219019Sgaborwork based on the Program is not required to print an announcement.) 281219019Sgabor@end enumerate 282219019Sgabor 283219019SgaborThese requirements apply to the modified work as a whole. If 284219019Sgaboridentifiable sections of that work are not derived from the Program, and 285219019Sgaborcan be reasonably considered independent and separate works in 286219019Sgaborthemselves, then this License, and its terms, do not apply to those 287219019Sgaborsections when you distribute them as separate works. But when you 288219019Sgabordistribute the same sections as part of a whole which is a work based on 289219019Sgaborthe Program, the distribution of the whole must be on the terms of this 290219019SgaborLicense, whose permissions for other licensees extend to the entire 291219019Sgaborwhole, and thus to each and every part regardless of who wrote it. 292219019Sgabor 293219019SgaborThus, it is not the intent of this section to claim rights or contest 294219019Sgaboryour rights to work written entirely by you; rather, the intent is to 295219019Sgaborexercise the right to control the distribution of derivative or 296219019Sgaborcollective works based on the Program. 297219019Sgabor 298219019SgaborIn addition, mere aggregation of another work not based on the Program 299219019Sgaborwith the Program (or with a work based on the Program) on a volume of a 300219019Sgaborstorage or distribution medium does not bring the other work under the 301219019Sgaborscope of this License. 302219019Sgabor 303219019Sgabor@item 304219019SgaborYou may copy and distribute the Program (or a work based on it, under 305219019SgaborSection@w{ }2) in object code or executable form under the terms of 306219019SgaborSections 1 and 2 above provided that you also do one of the following: 307219019Sgabor 308219019Sgabor@enumerate a 309219019Sgabor@item 310219019SgaborAccompany it with the complete corresponding machine-readable source 311219019Sgaborcode, which must be distributed under the terms of Sections 1 and 2 312219019Sgaborabove on a medium customarily used for software interchange; or, 313219019Sgabor 314219019Sgabor@item 315219019SgaborAccompany it with a written offer, valid for at least three years, to 316219019Sgaborgive any third party, for a charge no more than your cost of physically 317219019Sgaborperforming source distribution, a complete machine-readable copy of the 318219019Sgaborcorresponding source code, to be distributed under the terms of Sections 319219019Sgabor1 and 2 above on a medium customarily used for software interchange; or, 320219019Sgabor 321219019Sgabor@item 322219019SgaborAccompany it with the information you received as to the offer to 323219019Sgabordistribute corresponding source code. (This alternative is allowed only 324219019Sgaborfor noncommercial distribution and only if you received the program in 325219019Sgaborobject code or executable form with such an offer, in accord with 326219019SgaborSubsection b above.) 327219019Sgabor@end enumerate 328219019Sgabor 329219019SgaborThe source code for a work means the preferred form of the work for 330219019Sgabormaking modifications to it. For an executable work, complete source 331219019Sgaborcode means all the source code for all modules it contains, plus any 332219019Sgaborassociated interface definition files, plus the scripts used to control 333219019Sgaborcompilation and installation of the executable. However, as a special 334219019Sgaborexception, the source code distributed need not include anything that is 335219019Sgabornormally distributed (in either source or binary form) with the major 336219019Sgaborcomponents (compiler, kernel, and so on) of the operating system on 337219019Sgaborwhich the executable runs, unless that component itself accompanies the 338219019Sgaborexecutable. 339219019Sgabor 340219019SgaborIf distribution of executable or object code is made by offering access 341219019Sgaborto copy from a designated place, then offering equivalent access to copy 342219019Sgaborthe source code from the same place counts as distribution of the source 343219019Sgaborcode, even though third parties are not compelled to copy the source 344219019Sgaboralong with the object code. 345219019Sgabor 346219019Sgabor@item 347219019SgaborYou may not copy, modify, sublicense, or distribute the Program except 348219019Sgaboras expressly provided under this License. Any attempt otherwise to 349219019Sgaborcopy, modify, sublicense or distribute the Program is void, and will 350219019Sgaborautomatically terminate your rights under this License. However, 351219019Sgaborparties who have received copies, or rights, from you under this License 352219019Sgaborwill not have their licenses terminated so long as such parties remain 353219019Sgaborin full compliance. 354219019Sgabor 355219019Sgabor@item 356219019SgaborYou are not required to accept this License, since you have not signed 357219019Sgaborit. However, nothing else grants you permission to modify or distribute 358219019Sgaborthe Program or its derivative works. These actions are prohibited by 359219019Sgaborlaw if you do not accept this License. Therefore, by modifying or 360219019Sgabordistributing the Program (or any work based on the Program), you 361219019Sgaborindicate your acceptance of this License to do so, and all its terms and 362219019Sgaborconditions for copying, distributing or modifying the Program or works 363219019Sgaborbased on it. 364219019Sgabor 365219019Sgabor@item 366219019SgaborEach time you redistribute the Program (or any work based on the 367219019SgaborProgram), the recipient automatically receives a license from the 368219019Sgabororiginal licensor to copy, distribute or modify the Program subject to 369219019Sgaborthese terms and conditions. You may not impose any further restrictions 370219019Sgaboron the recipients' exercise of the rights granted herein. You are not 371219019Sgaborresponsible for enforcing compliance by third parties to this License. 372219019Sgabor 373219019Sgabor@item 374219019SgaborIf, as a consequence of a court judgment or allegation of patent 375219019Sgaborinfringement or for any other reason (not limited to patent issues), 376219019Sgaborconditions are imposed on you (whether by court order, agreement or 377219019Sgaborotherwise) that contradict the conditions of this License, they do not 378219019Sgaborexcuse you from the conditions of this License. If you cannot 379219019Sgabordistribute so as to satisfy simultaneously your obligations under this 380219019SgaborLicense and any other pertinent obligations, then as a consequence you 381219019Sgabormay not distribute the Program at all. For example, if a patent license 382219019Sgaborwould not permit royalty-free redistribution of the Program by all those 383219019Sgaborwho receive copies directly or indirectly through you, then the only way 384219019Sgaboryou could satisfy both it and this License would be to refrain entirely 385219019Sgaborfrom distribution of the Program. 386219019Sgabor 387219019SgaborIf any portion of this section is held invalid or unenforceable under 388219019Sgaborany particular circumstance, the balance of the section is intended to 389219019Sgaborapply and the section as a whole is intended to apply in other 390219019Sgaborcircumstances. 391219019Sgabor 392219019SgaborIt is not the purpose of this section to induce you to infringe any 393219019Sgaborpatents or other property right claims or to contest validity of any 394219019Sgaborsuch claims; this section has the sole purpose of protecting the 395219019Sgaborintegrity of the free software distribution system, which is implemented 396219019Sgaborby public license practices. Many people have made generous 397219019Sgaborcontributions to the wide range of software distributed through that 398219019Sgaborsystem in reliance on consistent application of that system; it is up to 399219019Sgaborthe author/donor to decide if he or she is willing to distribute 400219019Sgaborsoftware through any other system and a licensee cannot impose that 401219019Sgaborchoice. 402219019Sgabor 403219019SgaborThis section is intended to make thoroughly clear what is believed to be 404219019Sgabora consequence of the rest of this License. 405219019Sgabor 406219019Sgabor@item 407219019SgaborIf the distribution and/or use of the Program is restricted in certain 408219019Sgaborcountries either by patents or by copyrighted interfaces, the original 409219019Sgaborcopyright holder who places the Program under this License may add an 410219019Sgaborexplicit geographical distribution limitation excluding those countries, 411219019Sgaborso that distribution is permitted only in or among countries not thus 412219019Sgaborexcluded. In such case, this License incorporates the limitation as if 413219019Sgaborwritten in the body of this License. 414219019Sgabor 415219019Sgabor@item 416219019SgaborThe Free Software Foundation may publish revised and/or new versions of 417219019Sgaborthe General Public License from time to time. Such new versions will be 418219019Sgaborsimilar in spirit to the present version, but may differ in detail to 419219019Sgaboraddress new problems or concerns. 420219019Sgabor 421219019SgaborEach version is given a distinguishing version number. If the Program 422219019Sgaborspecifies a version number of this License which applies to it and ``any 423219019Sgaborlater version'', you have the option of following the terms and 424219019Sgaborconditions either of that version or of any later version published by 425219019Sgaborthe Free Software Foundation. If the Program does not specify a version 426219019Sgabornumber of this License, you may choose any version ever published by the 427219019SgaborFree Software Foundation. 428219019Sgabor 429219019Sgabor@item 430219019SgaborIf you wish to incorporate parts of the Program into other free programs 431219019Sgaborwhose distribution conditions are different, write to the author to ask 432219019Sgaborfor permission. For software which is copyrighted by the Free Software 433219019SgaborFoundation, write to the Free Software Foundation; we sometimes make 434219019Sgaborexceptions for this. Our decision will be guided by the two goals of 435219019Sgaborpreserving the free status of all derivatives of our free software and 436219019Sgaborof promoting the sharing and reuse of software generally. 437219019Sgabor 438219019Sgabor@iftex 439219019Sgabor@heading NO WARRANTY 440219019Sgabor@end iftex 441219019Sgabor@ifinfo 442219019Sgabor@center NO WARRANTY 443219019Sgabor@end ifinfo 444219019Sgabor 445219019Sgabor@item 446219019SgaborBECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR 447219019SgaborTHE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN 448219019SgaborOTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 449219019SgaborPROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER 450219019SgaborEXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 451219019SgaborWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. 452219019SgaborTHE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH 453219019SgaborYOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 454219019SgaborNECESSARY SERVICING, REPAIR OR CORRECTION. 455219019Sgabor 456219019Sgabor@item 457219019SgaborIN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 458219019SgaborWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 459219019SgaborREDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 460219019SgaborDAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL 461219019SgaborDAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM 462219019Sgabor(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED 463219019SgaborINACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF 464219019SgaborTHE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR 465219019SgaborOTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 466219019Sgabor@end enumerate 467219019Sgabor 468219019Sgabor@iftex 469219019Sgabor@heading END OF TERMS AND CONDITIONS 470219019Sgabor@end iftex 471219019Sgabor@ifinfo 472219019Sgabor@center END OF TERMS AND CONDITIONS 473219019Sgabor@end ifinfo 474219019Sgabor 475219019Sgabor 476219019Sgabor@page 477219019Sgabor@unnumberedsec How to Apply These Terms to Your New Programs 478219019Sgabor 479219019SgaborIf you develop a new program, and you want it to be of the greatest 480219019Sgaborpossible use to the public, the best way to achieve this is to make it 481219019Sgaborfree software which everyone can redistribute and change under these 482219019Sgaborterms. 483219019Sgabor 484219019SgaborTo do so, attach the following notices to the program. It is safest to 485219019Sgaborattach them to the start of each source file to most effectively convey 486219019Sgaborthe exclusion of warranty; and each file should have at least the 487219019Sgabor``copyright'' line and a pointer to where the full notice is found. 488219019Sgabor 489219019Sgabor@smallexample 490219019Sgabor@var{one line to give the program's name and an idea of what it does.} 491219019SgaborCopyright (C) 19@var{yy} @var{name of author} 492219019Sgabor 493219019SgaborThis program is free software; you can redistribute it and/or modify it 494219019Sgaborunder the terms of the GNU General Public License as published by the 495219019SgaborFree Software Foundation; either version 2 of the License, or (at your 496219019Sgaboroption) any later version. 497219019Sgabor 498219019SgaborThis program is distributed in the hope that it will be useful, but 499219019SgaborWITHOUT ANY WARRANTY; without even the implied warranty of 500219019SgaborMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU 501219019SgaborGeneral Public License for more details. 502219019Sgabor 503219019SgaborYou should have received a copy of the GNU General Public License along 504219019Sgaborwith this program; if not, write to the Free Software Foundation, Inc., 505219019Sgabor59 Temple Place, Suite 330, Boston, MA 02111, USA. 506219019Sgabor@end smallexample 507219019Sgabor 508219019SgaborAlso add information on how to contact you by electronic and paper mail. 509219019Sgabor 510219019SgaborIf the program is interactive, make it output a short notice like this 511219019Sgaborwhen it starts in an interactive mode: 512219019Sgabor 513219019Sgabor@smallexample 514219019SgaborGnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} 515219019SgaborGnomovision comes with ABSOLUTELY NO WARRANTY; for details type 516219019Sgabor`show w'. This is free software, and you are welcome to redistribute it 517219019Sgaborunder certain conditions; type `show c' for details. 518219019Sgabor@end smallexample 519219019Sgabor 520219019SgaborThe hypothetical commands @samp{show w} and @samp{show c} should show 521219019Sgaborthe appropriate parts of the General Public License. Of course, the 522219019Sgaborcommands you use may be called something other than @samp{show w} and 523219019Sgabor@samp{show c}; they could even be mouse-clicks or menu items---whatever 524219019Sgaborsuits your program. 525219019Sgabor 526219019SgaborYou should also get your employer (if you work as a programmer) or your 527219019Sgaborschool, if any, to sign a ``copyright disclaimer'' for the program, if 528219019Sgabornecessary. Here is a sample; alter the names: 529219019Sgabor 530219019Sgabor@smallexample 531219019Sgabor@group 532219019SgaborYoyodyne, Inc., hereby disclaims all copyright 533219019Sgaborinterest in the program `Gnomovision' 534219019Sgabor(which makes passes at compilers) written 535219019Sgaborby James Hacker. 536219019Sgabor 537219019Sgabor@var{signature of Ty Coon}, 1 April 1989 538219019SgaborTy Coon, President of Vice 539219019Sgabor@end group 540219019Sgabor@end smallexample 541219019Sgabor 542219019SgaborThis General Public License does not permit incorporating your program 543219019Sgaborinto proprietary programs. If your program is a subroutine library, you 544219019Sgabormay consider it more useful to permit linking proprietary applications 545219019Sgaborwith the library. If this is what you want to do, use the GNU Library 546219019SgaborGeneral Public License instead of this License. 547219019Sgabor 548219019Sgabor 549219019Sgabor 550219019Sgabor@node Introduction, Invoking groff, Copying, Top 551219019Sgabor@chapter Introduction 552219019Sgabor@cindex introduction 553219019Sgabor 554219019SgaborGNU @code{troff} (or @code{groff}) is a system for typesetting 555219019Sgabordocuments. @code{troff} is very flexible and has been in existence (and 556219019Sgaboruse) for about 3@w{ }decades. It is quite widespread and firmly 557219019Sgaborentrenched in the @sc{Unix} community. 558219019Sgabor 559219019Sgabor 560219019Sgabor 561219019Sgabor@menu 562219019Sgabor* What Is groff?:: 563219019Sgabor* History:: 564219019Sgabor* groff Capabilities:: 565219019Sgabor* Macro Packages:: 566219019Sgabor* Preprocessors:: 567219019Sgabor* Postprocessors:: 568219019Sgabor* Credits:: 569219019Sgabor@end menu 570219019Sgabor 571219019Sgabor@node What Is groff?, History, Introduction, Introduction 572219019Sgabor@section What Is @code{groff}? 573219019Sgabor@cindex what is @code{groff}? 574219019Sgabor@cindex @code{groff} -- what is it? 575219019Sgabor 576219019Sgabor 577219019Sgabor@code{groff} is of an older generation of document preparation systems, 578219019Sgaborwhich operate more like compilers than the more recent interactive 579219019SgaborWYSIWYG @footnote{What You See Is What You Get} systems. @code{groff} 580219019Sgaborand its contemporary counterpart, @TeX{}, both work using a @dfn{batch} 581219019Sgaborparadigm: The input (or @dfn{source}) files are normal text files with 582219019Sgaborembedded formatting commands. These files can then be processed by 583219019Sgabor@code{groff} to produce a typeset document on a variety of devices. 584219019Sgabor 585219019SgaborLikewise, @code{groff} should not be confused with a @dfn{word 586219019Sgaborprocessor}, since that term connotes an integrated system which includes 587219019Sgaboran editor and a text formatter. Also, many word processors follow the 588219019SgaborWYSIWYG paradigm which was discussed earlier. 589219019Sgabor 590219019SgaborAlthough WYSIWYG systems may be easier to use, they have a number of 591219019Sgabordisadvantages compared to @code{troff}: 592219019Sgabor 593219019Sgabor@itemize @bullet{} 594219019Sgabor@item 595219019SgaborThey must be used on a bitmapped display to do any operations on your 596219019Sgabordocument. 597219019Sgabor@item 598219019SgaborMost of the WYSIWYG systems are either non-free or are not very 599219019Sgaborportable. 600219019Sgabor@item 601219019Sgabor@code{troff} is firmly entrenched in all @sc{Unix} systems. 602219019Sgabor@item 603219019SgaborIt is difficult to have a wide range of capabilities available within 604219019Sgaborthe confines of a GUI/window system. 605219019Sgabor@item 606219019SgaborIt is more difficult to make global changes to a document. 607219019Sgabor@end itemize 608219019Sgabor 609219019Sgabor@quotation 610219019Sgabor``GUIs normally make it simple to accomplish simple actions and 611219019Sgaborimpossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 612219019Sgabor@code{comp.unix.wizards}) 613219019Sgabor@end quotation 614219019Sgabor 615219019Sgabor 616219019Sgabor 617219019Sgabor@node History, groff Capabilities, What Is groff?, Introduction 618219019Sgabor@section History 619219019Sgabor@cindex history 620219019Sgabor 621219019Sgabor@code{troff} can trace its origins back to a formatting program called 622219019Sgabor@code{runoff} which ran on MIT's CTSS system. This name came from the 623219019Sgaborcommon phrase of the time ``I'll run off a document.'' 624219019Sgabor 625219019SgaborThe first version of @sc{Unix} was developed on a PDP-7 which was 626219019Sgaborsitting around Bell Labs. In 1971 the developers wanted to get a PDP-11 627219019Sgaborfor further work on the operating system. In order to justify the cost 628219019Sgaborfor this system, they proposed that they would implement a document 629219019Sgaborformatting system for the AT&T patents division. This first formatting 630219019Sgaborprogram was a reimplementation of @code{runoff}. In accordance with 631219019Sgabor@sc{Unix}'s penchant for abreviations, it was named @code{roff} (an 632219019Sgaborabreviation of @code{runoff}). 633219019Sgabor 634219019SgaborWhen they needed a more flexible language, a new version of @code{roff} 635219019Sgaborcalled @code{nroff} (Newer @code{roff}) was written. It had a much more 636219019Sgaborcomplicated syntax, but provided the basis for all future versions. 637219019SgaborWhen they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{ 638219019Sgabor}Ossanna wrote a version of @code{nroff} which would drive it. It was 639219019Sgabordubbed @code{troff} for typesetter @code{roff}, although many people 640219019Sgaborhave speculated that it actually means Times @code{roff} because of 641219019Sgabor@code{troff}'s use of the Times font family by default. As such, the 642219019Sgaborname @code{troff} is pronounced t-roff rather than trough. 643219019Sgabor 644219019SgaborWith @code{troff} came @code{nroff} (they were actually the same program 645219019Sgaborexcept for some @samp{#ifdefs}), which was for producing output for line 646219019Sgaborprinters and ascii terminals. It understood everything @code{troff} 647219019Sgabordid, and ignored the commands which were not aplicable (i.e.@: font 648219019Sgaborchanges). 649219019Sgabor 650219019SgaborSince there are several things which cannot be done easily in 651219019Sgabor@code{troff}, work on several preprocessors began. These programs would 652219019Sgabortransform certain parts of a document into @code{troff}, which made a 653219019Sgaborvery natural use of pipes in @sc{Unix}. 654219019Sgabor 655219019SgaborThe @code{eqn} preprocessor allowed mathematical formul@ae{} to be 656219019Sgaborspecified in a much simpler and more intuitive manner. @code{tbl} is a 657219019Sgaborpreprocessor for formatting tables. The @code{refer} preprocessor (and 658219019Sgaborthe similar program, @code{bib}) processes citations in a document 659219019Sgaboraccording to a bibliographic database. 660219019Sgabor 661219019SgaborUnfortunately, Ossanna's @code{troff} was written in PDP-11 assembly 662219019Sgaborlanguage and produced output specifically for the CAT phototypesetter. 663219019SgaborHe rewrote it in C, although it was now 7000@w{ }lines of uncommented 664219019Sgaborcode and still dependent on the CAT. As the CAT became less common, and 665219019Sgaborwas no longer supported by the manufacturer, the need to make it support 666219019Sgaborother devices became a priority. However, before this could be done, he 667219019Sgaborwas killed in an auto accident. 668219019Sgabor 669219019Sgabor@pindex ditroff 670219019SgaborSo, Brian Kernighan took on the task of rewriting @code{troff}. The 671219019Sgabornewly rewritten version produced a device independent code which was 672219019Sgaborvery easy for postprocessors to read and translate to the appropriate 673219019Sgaborprinter codes. Also, this new version of @code{troff} (called 674219019Sgabor@code{ditroff}) had several extentions, which included drawing 675219019Sgaborfunctions. 676219019Sgabor 677219019SgaborDue to the additional abilities of the new version of @code{troff}, 678219019Sgaborseveral new preprocessors appeared. The @code{pic} preprocessor 679219019Sgaborprovides a wide range of drawing functions. Likewise the @code{ideal} 680219019Sgaborpreprocessor did the same, although via a much different paradigm. The 681219019Sgabor@code{grap} preprocessor took specifications for graphs, but, unlike 682219019Sgaborother preprocessors, produced @code{pic} code. 683219019Sgabor 684219019SgaborJames Clark began work on a GNU implementation of @code{ditroff} in 685219019Sgaborearly@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released 686219019SgaborJune@w{ }1990. @code{groff} included 687219019Sgabor 688219019Sgabor@itemize @bullet{} 689219019Sgabor@item 690219019SgaborA replacement for @code{ditroff} with many extentions. 691219019Sgabor@item 692219019SgaborThe @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 693219019Sgabor@item 694219019SgaborPostprocessors for ascii devices, PostScript, @TeX{} DVI, and X@w{ 695219019Sgabor}windows. GNU @code{troff} also eliminated the need for a separate 696219019Sgabor@code{nroff} program with a postprocessor which would produce ascii 697219019Sgaboroutput. 698219019Sgabor@item 699219019SgaborA version of the @code{-me} macros and an implementation of the 700219019Sgabor@code{-man} macros. 701219019Sgabor@end itemize 702219019Sgabor 703219019SgaborAlso, a front-end was included which could construct the, sometimes 704219019Sgaborpainfully long, pipelines required for all the post- and preprocessors. 705219019Sgabor 706219019SgaborDevelopment of GNU @code{troff} progressed rapidly, and saw the 707219019Sgaboradditions of a replacement for @code{refer}, an implementation of the 708219019Sgabor@code{-ms} and @code{-mm} macros, and a program to deduce how to format 709219019Sgabora document (@code{grog}). 710219019Sgabor 711219019SgaborIt was declared a stable (i.e.@: non beta) package with the release of 712219019Sgaborversion@w{ }1.04 around November@w{ }1991. 713219019Sgabor 714219019Sgabor 715219019Sgabor 716219019Sgabor@node groff Capabilities, Macro Packages, History, Introduction 717219019Sgabor@section @code{groff} Capabilities 718219019Sgabor@cindex @code{groff} capabilities 719219019Sgabor@cindex capabilities of @code{groff} 720219019Sgabor 721219019SgaborSo what exactly is @code{groff} capable of doing? @code{groff} provides 722219019Sgabora wide range of low-level text formatting operations. Using these, you 723219019Sgaborcan perform a wide range of formatting tasks, such as footnotes, table 724219019Sgaborof contents, multiple columns, etc. 725219019Sgabor 726219019Sgabor@itemize @bullet{} 727219019Sgabor@item 728219019SgaborText filling, adjusting, and centering 729219019Sgabor@item 730219019SgaborHyphenation 731219019Sgabor@item 732219019SgaborPage control 733219019Sgabor@item 734219019SgaborFont and character size control 735219019Sgabor@item 736219019SgaborVertical spacing (i.e.@: double spacing) 737219019Sgabor@item 738219019SgaborLine length and indenting 739219019Sgabor@item 740219019SgaborMacros, strings, diversions, and traps 741219019Sgabor@item 742219019SgaborNumber registers 743219019Sgabor@item 744219019SgaborTabs, leaders, and fields 745219019Sgabor@item 746219019SgaborInput and output conventions and character translation 747219019Sgabor@item 748219019SgaborOverstrike, bracket, line drawing, and zero-width functions 749219019Sgabor@item 750219019SgaborLocal horizontal and vertical motions and the width function 751219019Sgabor@item 752219019SgaborThree-part titles 753219019Sgabor@item 754219019SgaborOutput line numbering 755219019Sgabor@item 756219019SgaborConditional acceptance of input 757219019Sgabor@item 758219019SgaborEnvironment switching 759219019Sgabor@item 760219019SgaborInsertions from the standard input 761219019Sgabor@item 762219019SgaborInput/output file switching 763219019Sgabor@item 764219019SgaborOutput and error messages 765219019Sgabor@end itemize 766219019Sgabor 767219019Sgabor 768219019Sgabor@node Macro Packages, Preprocessors, groff Capabilities, Introduction 769219019Sgabor@section Macro Packages 770219019Sgabor@cindex macro packages 771219019Sgabor 772219019SgaborSince @code{groff} provides such low level facilities, it can be quite 773219019Sgabordifficult to use by itself. However, @code{groff} provides a 774219019Sgabor@dfn{macro} facility which allows you to specify how certain routine 775219019Sgaboroperations (e.g.@w{ }starting paragraphs, printing headers and footers, 776219019Sgaboretc.)@: should be done. These macros can be collected together into a 777219019Sgabor@dfn{macro package}. There are a number of macro packages available; 778219019Sgaborthe most common (and the ones described in this manual) are @code{-man}, 779219019Sgabor@code{-me}, @code{-ms}, and @code{-mm}. 780219019Sgabor 781219019Sgabor 782219019Sgabor@node Preprocessors, Postprocessors, Macro Packages, Introduction 783219019Sgabor@section Preprocessors 784219019Sgabor@cindex preprocessors 785219019Sgabor 786219019SgaborAlthough @code{groff} provides most functions needed to format a 787219019Sgabordocument, some operations would be unwieldy (i.e.@: drawing pictures). 788219019SgaborTherefore, programs called preprocessors were written which understand 789219019Sgabortheir own language and produce the necessary groff operations. These 790219019Sgaborpreprocessors are able to differentiate their own input from the rest of 791219019Sgaborthe document via markers. 792219019Sgabor 793219019SgaborTo use a preprocessor, @sc{Unix} pipes are used to feed the output from 794219019Sgaborthe preprocessor into @code{groff}. Any number of preprocessors may be 795219019Sgaborused on a given document; in this case, the preprocessors are linked 796219019Sgabortogether into one pipeline. However, in @code{groff}, the user does not 797219019Sgaborneed to construct the pipe, but only tell @code{groff} what 798219019Sgaborpreprocessors to use. 799219019Sgabor 800219019Sgabor@code{groff} currently has preprocessors for producing tables 801219019Sgabor(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 802219019Sgabor(@code{pic}), and for processing bibliographies (@code{refer}). An 803219019Sgaborassociated program which is useful when dealing with preprocessors is 804219019Sgabor@code{soelim}. 805219019Sgabor 806219019SgaborThere are other preprocessors in existence, but there are, 807219019Sgaborunfortunately, no free implementations available. They are for drawing 808219019Sgaborpictures (@code{ideal} and @code{gremlin}), for drawing graphs 809219019Sgabor(@code{grap}), and chemical structures (@code{chem}). 810219019Sgabor 811219019Sgabor 812219019Sgabor@node Postprocessors, Credits, Preprocessors, Introduction 813219019Sgabor@section Postprocessors 814219019Sgabor@cindex postprocessors 815219019Sgabor 816219019Sgabor@code{groff} actually produces device independent code which may be fed 817219019Sgaborinto a postprocessor which will produce output for a particular device. 818219019SgaborCurrently, @code{groff} has postprocessors for PostScript, ascii 819219019Sgaborterminals, X@w{ }windows (for previewing), @TeX{} DVI format, and HTML. 820219019Sgabor 821219019Sgabor 822219019Sgabor@node Credits, , Postprocessors, Introduction 823219019Sgabor@section Credits 824219019Sgabor@cindex credits 825219019Sgabor 826219019Sgabor 827219019SgaborLarge portions of this manual were taken from existing documents, most 828219019Sgabornotably, the manual pages for the @code{groff} package by James Clark, 829219019Sgaborand Eric Allman's papers on the @code{-me} macro package. 830219019Sgabor 831219019Sgabor 832219019Sgabor 833219019Sgabor@node Invoking groff, Tutorial for Macro Users, Introduction, Top 834219019Sgabor@chapter Invoking @code{groff} 835219019Sgabor@cindex invoking @code{groff} 836219019Sgabor@cindex @code{groff} invocation 837219019Sgabor 838219019Sgabor 839219019Sgabor@pindex groff 840219019Sgabor@pindex gtroff 841219019SgaborThis section focuses on how to invoke the @code{groff} front end. This 842219019Sgaborfront end takes care of the details of constructing the pipeline among 843219019Sgaborthe preprocessors, @code{gtroff} and the postprocessor. 844219019Sgabor 845219019SgaborIt has become a tradition that GNU programs get the prefix @dfn{g} to 846219019Sgabordistinguish it from its original counterparts provided by the host 847219019Sgabor(@pxref{Environment}, for more details). Thus, for example, @code{geqn} 848219019Sgaboris GNU @code{eqn}. On operating systems like Linux or the Hurd, which 849219019Sgabordon't contain proprietary software, this prefix is omitted since GNU 850219019Sgabor@code{troff} is the only used incarnation of @code{troff}. Exception: 851219019Sgabor@code{groff} is never replaced by `roff'. 852219019Sgabor 853219019Sgabor 854219019Sgabor@menu 855219019Sgabor* Options:: 856219019Sgabor* Environment:: 857219019Sgabor* Invocation Examples:: 858219019Sgabor@end menu 859219019Sgabor 860219019Sgabor@node Options, Environment, Invoking groff, Invoking groff 861219019Sgabor@section Options 862219019Sgabor@cindex options 863219019Sgabor 864219019Sgabor 865219019Sgabor@pindex groff 866219019Sgabor@pindex gtroff 867219019Sgabor@pindex gpic 868219019Sgabor@pindex geqn 869219019Sgabor@pindex gtbl 870219019Sgabor@pindex grefer 871219019Sgabor@pindex gsoelim 872219019Sgabor@code{groff} is a front-end to the groff document formatting system. 873219019SgaborNormally it runs the @code{gtroff} program and a postprocessor 874219019Sgaborappropriate for the selected device. The default device is @samp{ps}. 875219019SgaborIt can optionally preprocess with any of @code{gpic}, @code{geqn}, 876219019Sgabor@code{gtbl}, @code{grefer}, or @code{gsoelim}. 877219019Sgabor 878219019SgaborThis section only documents options to the @code{groff} front end. Many 879219019Sgaborof the arguments to @code{groff} are passed on to @code{gtroff}, 880219019Sgabortherefore those are also included. Arguments to pre- or postprocessors 881219019Sgaborcan be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 882219019Sgaborgtbl}, @ref{Invoking grefer}, @ref{Invoking gsoelim}, @ref{Invoking 883219019Sgaborgrotty}, @ref{Invoking grops}, @ref{Invoking grohtml}, @ref{Invoking 884219019Sgaborgrodvi}, and @ref{Invoking gxditview} 885219019Sgabor 886219019SgaborThe command line format for @code{groff} is: 887219019Sgabor 888219019Sgabor@example 889219019Sgaborgroff [ -abehilpstvzCENRSVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 890219019Sgabor [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 891219019Sgabor [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 892219019Sgabor [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] 893219019Sgabor [ @var{files}@dots{} ] 894219019Sgabor@end example 895219019Sgabor 896219019SgaborThe command line format for @code{gtroff} is as follows. As you can 897219019Sgaborsee, many of the options to @code{groff} are actually passed on to 898219019Sgabor@code{gtroff}. 899219019Sgabor 900219019Sgabor@example 901219019Sgaborgtroff [ -abivzCER ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 902219019Sgabor [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 903219019Sgabor [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 904219019Sgabor [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 905219019Sgabor@end example 906219019Sgabor 907219019SgaborOptions without an argument can be grouped behind a single @samp{-}. A 908219019Sgaborfilename of @samp{-} denotes the standard input. 909219019Sgabor 910219019Sgabor@pindex grog 911219019SgaborThe @code{grog} command can be used to guess the correct @code{groff} 912219019Sgaborcommand to use to format a file. 913219019Sgabor 914219019Sgabor@table @samp 915219019Sgabor@item -h 916219019SgaborPrint a help message. 917219019Sgabor@item -e 918219019SgaborPreprocess with @code{geqn}. 919219019Sgabor@item -t 920219019SgaborPreprocess with @code{gtbl}. 921219019Sgabor@item -p 922219019SgaborPreprocess with @code{gpic}. 923219019Sgabor@item -s 924219019SgaborPreprocess with @code{gsoelim}. 925219019Sgabor@item -R 926219019SgaborPreprocess with @code{grefer}. No mechanism is provided for passing 927219019Sgaborarguments to @code{grefer} because most @code{grefer} options have 928219019Sgaborequivalent commands which can be included in the file. @xref{grefer}, 929219019Sgaborfor more details. 930219019Sgabor 931219019Sgabor@pindex troffrc 932219019SgaborNote that @code{gtroff} also accepts a @samp{-R} option, which is not 933219019Sgaboraccessible via @code{groff}. This option prevents the loading of the 934219019Sgabor@file{troffrc} file. 935219019Sgabor@item -v 936219019SgaborMake programs run by @code{groff} print out their version number. 937219019Sgabor@item -V 938219019SgaborPrint the pipeline on stdout instead of executing it. 939219019Sgabor@item -z 940219019SgaborSuppress output from @code{gtroff}. Only error messages will be printed. 941219019Sgabor@item -Z 942219019SgaborDo not postprocess the output of @code{gtroff}. Normally @code{groff} 943219019Sgaborwill automatically run the appropriate postprocessor. 944219019Sgabor@item -P@var{arg} 945219019SgaborPass @var{arg} to the postprocessor. Each argument should be passed 946219019Sgaborwith a separate @samp{-P} option. Note that groff does not prepend 947219019Sgabor@samp{-} to @var{arg} before passing it to the postprocessor. 948219019Sgabor@item -l 949219019SgaborSend the output to a printer. The command used for this is specified by 950219019Sgaborthe print command in the device description file. 951219019Sgabor@item -L@var{arg} 952219019SgaborPass @var{arg} to the spooler. Each argument should be passed with a 953219019Sgaborseparate @samp{-L} option. Note that @code{groff} does not prepend a 954219019Sgabor@samp{-} to @var{arg} before passing it to the postprocessor. 955219019Sgabor@item -T@var{dev} 956219019SgaborPrepare output for device @var{dev}. The default device is @samp{ps}. 957219019SgaborThe following are the output devices currently available: 958219019Sgabor@table @samp 959219019Sgabor@item ps 960219019SgaborFor PostScript printers and previewers. 961219019Sgabor@item dvi 962219019SgaborFor TeX dvi format. 963219019Sgabor@item X75 964219019SgaborFor a 75 dpi X11 previewer. 965219019Sgabor@item X100 966219019SgaborFor a 100dpi X11 previewer. 967219019Sgabor@item ascii 968219019SgaborFor typewriter-like devices. 969219019Sgabor@item latin1 970219019SgaborFor typewriter-like devices using the ISO Latin-1 character set. 971219019Sgabor@item lj4 972219019SgaborFor an HP LaserJet4-compatible (or other PCL5-compatible) printer. 973219019Sgabor@item html 974219019SgaborTo produce HTML output. 975219019Sgabor@end table 976219019Sgabor 977219019SgaborThe postprocessor to be used for a device is specified by the 978219019Sgabor@code{postpro} command in the device description file. (@xref{Font 979219019SgaborFiles}, for more info.) This can be overridden with the @samp{-X} 980219019Sgaboroption. 981219019Sgabor@item -X 982219019SgaborPreview with @code{gxditview} instead of using the usual postprocessor. 983219019SgaborThis is unlikely to produce good results except with @samp{-Tps}. 984219019Sgabor@item -N 985219019SgaborDon't allow newlines with @code{eqn} delimiters. This is the same as 986219019Sgaborthe @samp{-N} option in @code{geqn}. 987219019Sgabor@item -S 988219019SgaborSafer mode. Pass the @samp{-S} option to @code{gpic} and use the 989219019Sgabor@samp{-msafer} macros with @code{gtroff}. 990219019Sgabor@item -a 991219019SgaborGenerate an ASCII approximation of the typeset output. 992219019Sgabor@item -b 993219019SgaborPrint a backtrace with each warning or error message. This backtrace 994219019Sgaborshould help track down the cause of the error. The line numbers given 995219019Sgaborin the backtrace may not always be correct: @code{troff}'s idea of line 996219019Sgabornumbers gets confused by @code{as} or @code{am} requests. 997219019Sgabor@item -i 998219019SgaborRead the standard input after all the named input files have been 999219019Sgaborprocessed. 1000219019Sgabor@item -w@var{name} 1001219019SgaborEnable warning @var{name}. Available warnings are described in 1002219019Sgabor@ref{Debugging}. Multiple @samp{-w} options are allowed. 1003219019Sgabor@item -W@var{name} 1004219019SgaborInhibit warning @var{name}. Multiple @samp{-W} options are allowed. 1005219019Sgabor@item -E 1006219019SgaborInhibit all error messages. 1007219019Sgabor@item -C 1008219019SgaborEnable compatibility mode. 1009219019Sgabor@item -d@var{cs} 1010219019Sgabor@itemx -d@var{name}=s 1011219019SgaborDefine @var{c} or @var{name} to be a string @var{s}; @var{c} must be a 1012219019Sgaborone-letter @var{name}. 1013219019Sgabor@item -f@var{fam} 1014219019SgaborUse @var{fam} as the default font family. 1015219019Sgabor@item -m@var{name} 1016219019SgaborRead in the file @file{tmac.@var{name}}. Normally this will be searched 1017219019Sgaborfor in @code{groff}'s lib directory. 1018219019Sgabor@item -n@var{num} 1019219019SgaborNumber the first page @var{num}. 1020219019Sgabor@item -o@var{list} 1021219019SgaborOutput only pages in @var{list}, which is a comma-separated list of page 1022219019Sgaborranges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means 1023219019Sgaborprint every page between @var{m} and @var{n}, @samp{-@var{n}} means 1024219019Sgaborprint every page up to @var{n}, @samp{@var{n}-} means print every page 1025219019Sgaborfrom @var{n}. @code{troff} will exit after printing the last page in 1026219019Sgaborthe list. 1027219019Sgabor@item -r@var{cn} 1028219019Sgabor@itemx -r@var{name}=@var{n} 1029219019SgaborSet number register @var{c} or @var{name} to @var{n}; @var{c} must be a 1030219019Sgaborone-letter @var{name}; @var{n} can be any troff numeric expression. 1031219019Sgabor@item -F@var{dir} 1032219019SgaborSearch @var{dir} for subdirectories dev@var{name} (@var{name} is the 1033219019Sgaborname of the device) for the @file{DESC} file and font files before the 1034219019Sgabornormal directory. 1035219019Sgabor@item -M@var{dir} 1036219019SgaborSearch directory @var{dir} for macro files before the normal directory. 1037219019Sgabor@end table 1038219019Sgabor 1039219019Sgabor 1040219019Sgabor 1041219019Sgabor@node Environment, Invocation Examples, Options, Invoking groff 1042219019Sgabor@section Environment 1043219019Sgabor@cindex environment 1044219019Sgabor 1045219019Sgabor 1046219019SgaborThere are also several environment variables which can modify groff's 1047219019Sgaborbehavior. 1048219019Sgabor 1049219019Sgabor@table @code 1050219019Sgabor@item GROFF_COMMAND_PREFIX 1051219019SgaborIf this is set to @var{X}, then @code{groff} will run 1052219019Sgabor@var{X}@code{troff} instead of @code{gtroff}. This also applies to 1053219019Sgabor@code{tbl}, @code{pic}, @code{eqn}, @code{refer}, and @code{soelim}. It 1054219019Sgabordoes not apply to @code{grops}, @code{grodvi}, @code{grotty}, 1055219019Sgabor@code{grohtml}, @code{grolj4}, and @code{gxditview}. 1056219019Sgabor@item GROFF_TMAC_PATH 1057219019SgaborA colon separated list of directories in which to search for macro 1058219019Sgaborfiles. 1059219019Sgabor@item GROFF_TYPESETTER 1060219019SgaborDefault device. 1061219019Sgabor@item GROFF_FONT_PATH 1062219019SgaborA colon separated list of directories in which to search for the 1063219019Sgabor@code{dev}@var{name} directory. 1064219019Sgabor@item PATH 1065219019SgaborThe search path for commands executed by groff. 1066219019Sgabor@item GROFF_TMPDIR 1067219019SgaborThe directory in which temporary files will be created. If this is not 1068219019Sgaborset and @code{TMPDIR} is set, temporary files will be created in that 1069219019Sgabordirectory. Otherwise temporary files will be created in @code{/tmp}. 1070219019SgaborThe @code{grops} and @code{grefer} commands can create temporary files. 1071219019Sgabor@end table 1072219019Sgabor 1073219019Sgabor 1074219019Sgabor@node Invocation Examples, , Environment, Invoking groff 1075219019Sgabor@section Invocation Examples 1076219019Sgabor@cindex invocation examples 1077219019Sgabor@cindex examples of invocation 1078219019Sgabor 1079219019Sgabor 1080219019SgaborThis section will list several common uses of @code{groff} and the 1081219019Sgaborcommand line which will accomplish it. 1082219019Sgabor 1083219019Sgabor@example 1084219019Sgaborgroff file 1085219019Sgaborgroff -X -me file 1086219019Sgaborgroff -mm -rD1 -z file 1087219019Sgaborgroff -tps -me file | lpr -Plw2 1088219019Sgabor... any more?? ... 1089219019Sgabor@end example 1090219019Sgabor 1091219019Sgabor@subsection @code{grog} 1092219019Sgabor 1093219019Sgabor@code{grog} reads files and guesses which of the @code{groff} 1094219019Sgaborpreprocessors and/or macro packages are are required for formatting 1095219019Sgaborthem, and prints the @code{groff} command including those options on the 1096219019Sgaborstandard output. The options generated are one of @samp{-e}, 1097219019Sgabor@samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-s}, 1098219019Sgaborand @samp{-t}. 1099219019Sgabor 1100219019SgaborA filename of @samp{-} is taken to refer to the standard input. If no 1101219019Sgaborfiles are specified the standard input will be read. Any specified 1102219019Sgaboroptions will be included in the printed command. No space is allowed 1103219019Sgaborbetween options and their arguments. For example, 1104219019Sgabor 1105219019Sgabor@example 1106219019Sgaborgrog -Tdvi paper.ms 1107219019Sgabor@end example 1108219019Sgabor 1109219019Sgaborwill guess the approriate command to print @file{paper.ms} and then run 1110219019Sgaborit after adding the @samp{-Tdvi} option. 1111219019Sgabor 1112219019Sgabor 1113219019Sgabor@node Tutorial for Macro Users, -man, Invoking groff, Top 1114219019Sgabor@chapter Tutorial for Macro Users 1115219019Sgabor@cindex tutorial for macro users 1116219019Sgabor@cindex macro tutorial for users 1117219019Sgabor@cindex user's tutorial for macros 1118219019Sgabor@cindex user's macro tutorial 1119219019Sgabor 1120219019SgaborMost users tend to use a macro package to format their papers. This 1121219019Sgabormeans that the whole breadth of @code{groff} is not neccessary for most 1122219019Sgaborpeople. This chapter covers the material needed to efficiently use a 1123219019Sgabormacro package. 1124219019Sgabor 1125219019Sgabor 1126219019Sgabor@menu 1127219019Sgabor* Basics:: 1128219019Sgabor* Common Features:: 1129219019Sgabor@end menu 1130219019Sgabor 1131219019Sgabor@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1132219019Sgabor@section Basics 1133219019Sgabor@cindex basics 1134219019Sgabor 1135219019Sgabor 1136219019SgaborThis section covers some of the basic concepts you will need to 1137219019Sgaborunderstand to use a macro package.@footnote{This section is derived from 1138219019Sgabor@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman} 1139219019SgaborReferences are made throughout to more detailed information, if desired. 1140219019Sgabor 1141219019Sgabor@code{groff} reads an input file prepared by the user and outputs a 1142219019Sgaborformatted paper suitable for publication or framing. The input consists 1143219019Sgaborof text, or words to be printed, and embedded commands (@dfn{requests} 1144219019Sgaborand @dfn{escapes}), which tell @code{groff} how to format the printed 1145219019Sgaborcopy. For more detail on this @pxref{Embedded Commands}. 1146219019Sgabor 1147The word @dfn{argument} is used in this manual to mean a word or number 1148which appears on the same line as a request which modifies the meaning 1149of that request. For example, the request 1150 1151@example 1152.sp 1153@end example 1154 1155@noindent 1156spaces one line, but 1157 1158@example 1159.sp 4 1160@end example 1161 1162@noindent 1163spaces four lines. The number@w{ }4 is an argument to the @code{sp} 1164request which says to space four lines instead of one. Arguments are 1165separated from the request and from each other by spaces. More details 1166on this can be found in @ref{Request Arguments}. 1167 1168The primary function of @code{groff} is to collect words from input 1169lines, fill output lines with those words, justify the right hand margin 1170by inserting extra spaces in the line, and output the result. For 1171example, the input: 1172 1173@example 1174Now is the time 1175for all good men 1176to come to the aid 1177of their party. 1178Four score and seven 1179years ago,... 1180@end example 1181 1182@noindent 1183will be read, packed onto output lines, and justified to produce: 1184 1185@quotation 1186Now is the time for all good men to come to the aid of their party. 1187Four score and seven years ago,... 1188@end quotation 1189 1190@cindex break 1191@cindex line break 1192Sometimes you may want to start a new output line even though the line 1193you are on is not yet full; for example, at the end of a paragraph. To 1194do this you can cause a @dfn{break}, which starts a new output line. 1195Some requests cause a break automatically, as do blank input lines and 1196input lines beginning with a space. 1197 1198Not all input lines are text to be formatted. Some of the input lines 1199are requests which describe how to format the text. Requests always 1200have a period or an apostrophe (@samp{'}) as the first character of the 1201input line. 1202 1203The text formatter also does more complex things, such as automatically 1204numbering pages, skipping over page boundaries putting footnotes in the 1205correct place, and so forth. 1206 1207Here a few hints for preparing text for input to @code{groff}. First, 1208keep the input lines short. Short input lines are easier to edit, and 1209@code{groff} will pack words onto longer lines for you anyhow. In 1210keeping with this, it is helpful to begin a new line after every period, 1211comma, or phrase, since common corrections are to add or delete 1212sentences or phrases. Secondly, do not hyphenate words at the end of 1213lines -- @code{groff} is smart enough to hyphenate words for you as 1214needed, but is not smart enough to take hyphens out and join a word back 1215together. Also, words such as ``mother-in-law'' should not be broken 1216over a line, since then you will get a space where not wanted, such as 1217``mother- in-law''. 1218 1219@findex ls 1220@cindex double spacing 1221@cindex spacing 1222Groff will double space output text automatically if you use the request 1223@samp{.ls 2}. You can revert to single spaced mode by typing @samp{.ls 12241}. 1225 1226A number of requests allow you to change the way the printed copy looks, 1227sometimes called the @dfn{layout} of the output page. Most of these 1228requests adjust the placing of @dfn{white space} (blank lines or 1229spaces). 1230 1231@findex bp 1232@cindex new page 1233The @samp{.bp} request starts a new page. 1234 1235@findex sp 1236@cindex blank lines 1237@cindex empty lines 1238The request @samp{.sp @var{N}} leaves @var{N} lines of blank space. 1239@var{N} can be omitted (meaning skip a single line) or can be of the 1240form @var{N}i (for @var{N} inches) or @var{N}c (for @var{N} 1241centimeters). For example, the input: 1242 1243@example 1244.sp 1.5i 1245My thoughts on the subject 1246.sp 1247@end example 1248 1249@noindent 1250leaves one and a half inches of space, followed by the line ``My 1251thoughts on the subject'', followed by a single blank line. 1252 1253@findex ce 1254@cindex centering lines 1255Text lines can be centered by using the @samp{.ce} request. The line 1256after @samp{.ce} is centered (horizontally) on the page. To center more 1257than one line, use @samp{.ce @var{N}} (where @var{N} is the number of 1258lines to center), followed by the @var{N} lines. If you want to center 1259many lines but don't want to count them, type: 1260 1261@example 1262.ce 1000 1263lines to center 1264.ce 0 1265@end example 1266 1267@noindent 1268The @samp{.ce 0} request tells @code{groff} to center zero more lines, 1269in other words, stop centering. 1270 1271@findex br 1272@cindex line break 1273@cindex break 1274All of these requests cause a break; that is, they always start a new 1275line. If you want to start a new line without performing any other 1276action, use @samp{.br}. 1277 1278 1279@node Common Features, , Basics, Tutorial for Macro Users 1280@section Common Features 1281@cindex common features 1282@cindex features, common 1283 1284 1285Groff provides very low level operations for formatting a document. 1286There are many common routine operations which are done in all documents. 1287These common operations are written into @dfn{macros} and collected into a 1288@dfn{macro package}. 1289 1290All macro packages provide certain common capabilities which fall 1291into the following categories. 1292 1293@subsection Paragraphs 1294@cindex paragraphs 1295 1296One of the most common and most used capability is starting a 1297paragraph. There are a number of different types of paragraphs, 1298any of which can be initiated with macros supplied by the macro 1299package. Normally paragraphs start with a blank line and the first 1300line indented, like the text in this manual. There are also block 1301style paragraphs, which omit the indentation: 1302 1303@example 1304Some men look at constitutions with sanctimonious 1305reverence, and deem them like the ark of the covenant, too 1306sacred to be touched. 1307@end example 1308 1309And there are also indented paragraphs which begin with a tag or label 1310at the margin and the remaining text indented. 1311 1312@example 1313one This is the first paragraph. Notice how the first 1314 line of the resulting paragraph lines up with the 1315 other lines in the paragraph. 1316longlabel 1317 This paragraph had a long label. The first 1318 character of text on the first line will not line up 1319 with the text on second and subsequent lines, 1320 although they will line up with each other. 1321@end example 1322 1323A variation of this is a bulleted list.... 1324 1325@subsection Sections and Chapters 1326 1327Most macro packages supply some form of section headers. 1328The simplest kind is simply the heading on a line by itself in bold 1329type. Others supply automatically numbered section heading or 1330different heading styles at different levels. 1331Some, more sophisticated, macro packages supply macros for starting 1332chapters and appendicies. 1333 1334@subsection Headers and Footers 1335 1336Every macro packages gives you some way to manipulate the headers and 1337footers (or @dfn{titles} on each page. Some packages will allow you 1338to have different ones on the even and odd pages (for material 1339printed in a book form). 1340The titles are called three-part titles, that is, there is a 1341left-justified part, a centered part, and a right-justified part. 1342An automatically generated page number may be put in any of these 1343fields with the @samp{%} character. 1344 1345@subsection Page Layout 1346 1347Most macro packages let you specify top and bottom margins and other 1348details about the appearance of the printed pages. 1349 1350@subsection Displays 1351@cindex displays 1352 1353Displays are sections of text to be set off from the body 1354of the paper. Major quotes, tables, and figures are types of 1355displays, as are all the examples used in this document. 1356 1357@cindex quotes, major 1358@cindex major quotes 1359Major quotes are quotes which are several lines long, 1360and hence are set in from the rest of the text without 1361quote marks around them. 1362 1363@cindex list 1364A list is an indented, single spaced, unfilled display. Lists should 1365be used when the material to be printed 1366should not be filled and justified like normal text, such 1367as columns of figures or the examples used in this paper. 1368 1369@cindex keep 1370A keep is a display of lines which are kept on a single page if 1371possible. An example of where you would use a 1372keep might be a diagram. Keeps differ from lists in that 1373lists may be broken over a page boundary whereas keeps will 1374not. 1375 1376@cindex keep, floating 1377@cindex floating keep 1378Floating keeps move relative to the text. Hence, they 1379are good for things which will be referred to by name, such 1380as ``See figure 3''. A floating keep will appear at the bottom of the 1381current page if it will fit; otherwise, it will 1382appear at the top of the next page. Meanwhile, the surrounding text 1383will `flow' around the keep, thus leaving now blank areas. 1384 1385@subsection Footnotes and annotations 1386@cindex footnotes 1387@cindex annotations 1388 1389There are a number of requests to save text for later 1390printing. Footnotes are printed at the bottom of the current 1391page. Delayed text is intended to be a variant form of foot- 1392note; the text is printed only when explicitly called for, 1393such as at the end of each chapter. 1394 1395Delayed text is very similar to a footnote except that 1396it is printed when called for explicitly. This allows a 1397list of references to appear (for example) at the end of 1398each chapter, as is the convention in some disciplines. 1399 1400Most macro packages which supply this functionality also supply a 1401means of automatically numbering either type of annotation. 1402 1403@subsection Table of Contents 1404 1405Tables of contents are a type of 1406delayed text having a tag (usually the page number) attached 1407to each entry after a row of dots. The table accumulates 1408throughought the paper until printed, usually after the paper has 1409ended. Many macro packages will provide the abilitly to have several 1410tables of contents (i.e. one standard one, one for tables, &c.) 1411 1412@subsection Indexes 1413 1414While some macro packages will use the term @dfn{index}, none 1415actually provide that functionality. The facilities they call 1416indexes are actually more appropriate for tables of contents. 1417 1418@subsection Paper formats 1419 1420Some macro packages provide stock formats for various kinds of 1421documents. Many of them provide a common format for the title and 1422opening pages of a technical paper. The -mm macros in particular 1423provide formats for letters and memorandums. 1424 1425@subsection Multiple Columns 1426 1427Some macro packages (except -man) provide the ability to have two or 1428more columns on a page. 1429 1430@subsection Font and Size changes 1431 1432The builtin font and size functions are not always intuitive, so all 1433macro packages provide macros to make these operations simpler. 1434 1435@subsection Predefined Strings 1436 1437Most macro packages provide various predefined strings for a variety 1438of uses, examples are sub- and super-scripts, printable dates, quotes 1439and various special characters. 1440 1441@subsection Preprocessor Support 1442 1443All macro packages provide support for the various preprocessors. 1444 1445@subsection Configuration and Customization 1446 1447Some macro packages provide means of customizing many of details of 1448how the package behaves. This ranges from setting the default type 1449size to changing the appearance of section headers. 1450 1451 1452@node -man, -ms, Tutorial for Macro Users, Top 1453@chapter -man 1454@cindex @code{-man} 1455 1456 1457 1458@node -ms, -me, -man, Top 1459@chapter -ms 1460@cindex @code{-ms} 1461 1462 1463 1464@node -me, -mm, -ms, Top 1465@chapter -me 1466@cindex @code{-me} 1467 1468 1469 1470@node -mm, Programming Tutorial, -me, Top 1471@chapter -mm 1472@cindex @code{-mm} 1473 1474 1475 1476@node Programming Tutorial, geqn, -mm, Top 1477@chapter Programming Tutorial 1478@cindex programming tutorial 1479@cindex tutorial for programming 1480 1481This chapter covers @strong{all} of the facilities of groff. 1482If you are intending to use a macro package, you probably do not want 1483to read this chapter. 1484 1485 1486@menu 1487* Text:: 1488* Input Conventions:: 1489* Measurements:: 1490* Expressions:: 1491* Identifiers:: 1492* Embedded Commands:: 1493* Registers:: 1494* Manipulating Filling and Adjusting:: 1495* Manipulating Hyphenation:: 1496* Manipulating Spacing:: 1497* Tabs and Fields:: 1498* Character Translations:: 1499* Line Layout:: 1500* Page Layout:: 1501* Page Control:: 1502* Fonts:: 1503* Sizes:: 1504* Strings:: 1505* Conditionals and Loops:: 1506* Writing Macros:: 1507* Page Motions:: 1508* Drawing Functions:: 1509* Traps:: 1510* Diversions:: 1511* Environments:: 1512* I/O:: 1513* Postprocessor Access:: 1514* Miscellany:: 1515* Debugging:: 1516* Implementation Differences:: 1517* Summary:: 1518@end menu 1519 1520@node Text, Input Conventions, Programming Tutorial, Programming Tutorial 1521@section Text 1522@cindex text 1523 1524@code{groff} input files contain text with control commands 1525interspersed throughout. But, even without control codes, 1526@code{groff} will still do several things with your text: 1527filling and adjusting, 1528adding additional space after sentences, 1529hyphenating 1530and 1531inserting implicit line breaks. 1532 1533 1534@menu 1535* Filling and Adjusting:: 1536* Hyphenation:: 1537* Sentences:: 1538* Tab Stops:: 1539* Implicit Line Breaks:: 1540@end menu 1541 1542@node Filling and Adjusting, Hyphenation, Text, Text 1543@subsection Filling and Adjusting 1544@cindex filling and adjusting 1545@cindex adjusting and filling 1546 1547 1548When troff reads in text it collects words from input and fits as many 1549of them together on one output line as it can. This is known as 1550@dfn{filling}. 1551 1552Once troff has a @dfn{filled} line it will try to @dfn{adjust} it. 1553which means it will widen the spacing between words until 1554the text reaches the right margin (in the default adjustment mode). 1555Extra spaces between words are preserved, but 1556spaces at the end of lines are ignored. 1557Spaces at the front of a line will cause a @dfn{break} 1558(breaks will be explained in @ref{Implicit Line Breaks}) 1559 1560@c distribute these through the text 1561@xref{Manipulating Filling and Adjusting} 1562 1563@node Hyphenation, Sentences, Filling and Adjusting, Text 1564@subsection Hyphenation 1565@cindex hyphenation 1566 1567 1568Since the odds of finding a set of words, for every output line, 1569which will fit nicely on a 1570line without inserting excessive amounts of space between words 1571is not great, 1572troff will hyphenate words so that lines can be justified 1573without there being too much space between words. 1574It uses an internal hyphenation algorithm, to indicate which words can 1575be hyphenated and how to do so. 1576When a word is hyphenated the first part of the word will be added 1577to the current filled line being output (with an attached hyphen), 1578and the other portion will be added to the next line to be filled. 1579 1580@c distribute these through the text 1581@xref{Manipulating Hyphenation} 1582 1583@node Sentences, Tab Stops, Hyphenation, Text 1584@subsection Sentences 1585@cindex sentences 1586 1587 1588Although it is often debated, 1589some typesetting rules say there should be different amounts of space 1590after various puctuation marks. 1591For example, a period at the end of a sentence 1592should have twice as much space following it 1593as would a comma or a period as part of an abbreviation. 1594 1595@cindex sentence spaces 1596@cindex spaces between sentences 1597Troff does this by flagging certain characters (normally 1598@samp{!}, @samp{?} and @samp{.}) 1599as @dfn{end of sentence} characters. 1600When troff encounters one of these characters at the end of a line it 1601will append two @dfn{sentence spaces} in the formatted output. 1602(thus, one of the conventions mentioned in @ref{Input Conventions}). 1603 1604@c also describe how characters like ) are treated here -jjc 1605@c gotta do some research on this -trent 1606 1607 1608 1609@node Tab Stops, Implicit Line Breaks, Sentences, Text 1610@subsection Tab Stops 1611@cindex tab stops 1612@cindex stops, tabulator 1613 1614 1615Groff translates tabs in the input into movements to the next tab 1616stop. These tab stops are initially located every half inch across 1617the page. 1618Using this you can make simple tables. However, this can often be 1619deceptive as the appearance (and width) of your text on a terminal and 1620the results from groff can vary greatly. 1621 1622Also, a possible sticking point is that lines beginning with tab 1623characters will still be filled, again producing unexpected results. 1624For example, the following input 1625 1626@example 1627 1 2 3 1628 4 5 1629@end example 1630 1631@noindent 1632will produce 1633 1634@example 1635 1 2 3 4 5 1636@end example 1637 1638@c Tab stops are with respect to the input line. -jjc 1639@c did that last section address that?? -trent 1640 1641 1642 1643@c distribute these through the text 1644@xref{Tabs and Fields} 1645 1646@node Implicit Line Breaks, , Tab Stops, Text 1647@subsection Implicit Line Breaks 1648@cindex implicit line breaks 1649@cindex implicit breaks of lines 1650@cindex line, implicit breaks 1651@cindex break 1652@cindex break, implicit 1653@cindex line break 1654 1655An important concept in troff is the @dfn{break}. When a @dfn{break} 1656occurs, troff will output the partially filled line (unadjusted), 1657and resume collecting and filling text on the next output line. 1658 1659@cindex blank line 1660@cindex empty line 1661@cindex line, blank 1662There are several ways to cause a break in troff. 1663A blank line will not only cause a break, but it will also cause a 1664one line vertical space (effectively a blank line) to be output. 1665 1666A line which begins with a space will cause a break and the space 1667will be output at the beginning of the next line. 1668Note that this space isn't adjusted, even in fill mode. 1669 1670The end of file will also cause a break (otherwise the last line of 1671your document may vanish!) 1672 1673Certain @dfn{requests} also cause breaks, implicitly or explicity. 1674This will be discussed later. 1675 1676@c distribute these through the text 1677@xref{Manipulating Filling and Adjusting} 1678 1679@node Input Conventions, Measurements, Text, Programming Tutorial 1680@section Input Conventions 1681@cindex input conventions 1682@cindex conventions for input 1683 1684 1685Since groff does filling automatically, it is traditional in groff not 1686to try and type things in as nicely formatted paragraphs. These are 1687some conventions commonly used when typing groff text: 1688 1689@itemize @bullet{} 1690@item 1691Break lines after punctuation, particularily at the ends of 1692sentences, and in other logical places. Keep separate phrases on 1693lines by themselves, as entire phrases are often added or deleted 1694when editing. 1695@item 1696Try to keep lines less than 40-60 characters, 1697to allow space for inserting more text. 1698@item 1699Do not try to do any formatting in a WYSIWYG manner (i.e. don't 1700try and use spaces to get proper indentation). 1701@end itemize 1702 1703 1704@node Measurements, Expressions, Input Conventions, Programming Tutorial 1705@section Measurements 1706@cindex measurements 1707 1708 1709@cindex units of measurement 1710@cindex basic units 1711@cindex machine units 1712Troff (like any other programs) requires numeric parameters to 1713specify various measurements. Most numeric parameters 1714@footnote{those that specify vertical or horizontal motion or a type 1715size} may have a measurement unit attached. 1716These units are specified as a single 1717character which immediately follows the number or expression. 1718Each of these units are understood, by troff, to be a multiple of its 1719@dfn{basic unit}. So, whenever a different measurement unit is 1720specified troff converts this into its basic units. 1721This basic unit, represented by a @samp{u} is a 1722device dependent measurement which is quite small, ranging from 17231/75th to 1/72000th of an inch. 1724 1725Some of the measurement units are compleatly independent of any of 1726the current settings (e.g. type size) of groff. 1727 1728@table @samp 1729@item i 1730@cindex inch 1731Inches. An antiquated measurement unit still in use in certain 1732backwards countries. 1733@item c 1734@cindex centimeter 1735Centimeters. 1736@item p 1737@cindex points 1738Points. This is a typesetter's measurement used for measure type size. 1739It is 72 points to an inch. 1740@item P 1741@cindex pica 1742Pica. Another typesetting measurement. 6 Picas to an inch. 1743@item s 1744@item z 1745@end table 1746 1747The other measurements understood by troff are dependent on settings 1748currently in effect in troff. These are very useful for specifying 1749measurements which should look proper with any size of text. 1750 1751@table @samp 1752@item m 1753@cindex em 1754Ems. This unit is equal to the current font size in points. 1755So called because it is @emph{approximately} the width of the letter 1756@samp{m} in the current font. 1757@item n 1758@cindex en 1759Ens. This is half of an em. 1760@item v 1761@cindex vertical space 1762@cindex space, vertical 1763Vertical space. This is equivalent to the current line spacing. 1764@xref{Sizes}, for more information about this. 1765@item M 1766100ths of an em. 1767@end table 1768 1769@c distribute these through the text 1770@xref{Fractional Type Sizes} 1771 1772@menu 1773* Default Units:: 1774@end menu 1775 1776@node Default Units, , Measurements, Measurements 1777@subsection Default Units 1778@cindex default units 1779@cindex units, default 1780 1781 1782Many requests take a default unit. While this can be helpful at 1783times, it can cause strange errors in some expressions. 1784For example, the line length request expects em's. 1785Here are several attempts to get 3.5 inches and the results: 1786 1787@example 17883.5i @result{} 3.5i 17897/2 @result{} 0i 17907/2i @result{} 0i 17917i/2 @result{} .1i 17927i/2u @result{} 3.5i 1793@end example 1794 1795As you can see, the safest way to specify measurements is to always 1796attach a scaling indicator. 1797 1798@node Expressions, Identifiers, Measurements, Programming Tutorial 1799@section Expressions 1800@cindex expressions 1801 1802 1803Troff has most of operators common to other languages: 1804 1805@itemize @bullet 1806@item 1807Arithmetic: +, -, /, *, % 1808@item 1809Comparison: <, >, >=, <=, =, == (the last two are the same) 1810@item 1811Logical: &, : 1812@item 1813Unary operators: -, +, ! (if/while only??) 1814@item 1815Maximum and minimum: >?, <? 1816@item 1817Scaling: (@var{c};@var{e}) 1818Evaluate @var{e} using @var{c} as the default scaling indicator. 1819If @var{c} is missing, ignore scaling indicators in the 1820evaluation of @var{e}. 1821@end itemize 1822 1823Parenthesis may be used as in any other language. 1824However, in groff they are necessary to ensure order of evaluation. 1825Groff has no operator precedence, 1826expressions are evaluated left to right. 1827This means that @samp{3+5*4} is evaluated as if it were parenthesized 1828like @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may expect. 1829 1830For many requests which cause a motion on the page, the unary 1831operators work differently. 1832The @samp{+} and @samp{-} operators indicate a motion relative to the 1833current position (down or up, respectively). The @samp{|} operator 1834indicates an absolute position on the page or input line. (????) 1835@code{+} and @code{-} are also treated differently by @code{nr} (?) 1836 1837Due to the way arguments are parsed, spaces are not allowed in 1838expressions, unless the entire expression is surrounded by parenthesis. 1839 1840@c distribute these through the text 1841@xref{Request Arguments} 1842@c distribute these through the text 1843@xref{Conditionals and Loops} 1844 1845@node Identifiers, Embedded Commands, Expressions, Programming Tutorial 1846@section Identifiers 1847@cindex identifiers 1848 1849Like any other language troff, has rules for properly formed 1850identifiers. 1851In troff an identifier can be made up of most any printable 1852character. 1853The only exception is characters which are interpreted by troff 1854(backslash, square bracket and ?). So, for example, any of the following 1855are valid. 1856 1857@example 1858br 1859PP 1860(l 1861end-list 1862@@_ 1863@end example 1864 1865You can test whether an identifier is valid in groff with the 1866@code{\A} escape. It expands to 1 or 0 according whether its argument 1867(given in quotes) is or is not acceptable as the name of a string, 1868macro, diversion, number register, environment or font. It will return 18690 if no argument is given. This is useful if you want to lookup user 1870input in some sort of associative table. 1871 1872Identifiers in groff can be any length, but, in some contexts, 1873groff needs to told 1874where identifiers end and text begins (and in different ways 1875depending on their length) 1876 1877@itemize @bullet{} 1878@item 1879Single character 1880@item 1881Two characters 1882Must be prefixed with @samp{(} in some situations. 1883@item 1884Arbitrary length (groff only) 1885Must be bracketed with @samp{[}, @samp{]} in some situations. 1886Any length identifier can be put in brackets. 1887@end itemize 1888 1889Unlike many other programming languages, undefined identifiers are 1890silently ignored or expanded to nothing. 1891 1892 1893@c distribute these through the text 1894@xref{Interpolating Registers} 1895@c distribute these through the text 1896@xref{Strings} 1897 1898@node Embedded Commands, Registers, Identifiers, Programming Tutorial 1899@section Embedded Commands 1900@cindex embedded commands 1901@cindex commands, embedded 1902 1903 1904With most documents you need more funtionality beyond filling, 1905adjusting and implicit line breaking. 1906In order to gain further functionality, groff allows commands to be 1907embeded into your text, in two ways. 1908 1909The first is a @dfn{request} which takes up an entire line, and does 1910some large scale operation (e.g. break lines, start new pages). 1911 1912The other is an @dfn{escape} which can be embedded anywhere 1913in your text, or even as an argument to a request. (Not always?) 1914Escapes generally do more minor operations like sub- and super- 1915scripts, print a symbol, &c. 1916 1917 1918 1919@menu 1920* Requests:: 1921* Macros:: 1922* Escapes:: 1923@end menu 1924 1925@node Requests, Macros, Embedded Commands, Embedded Commands 1926@subsection Requests 1927@cindex requests 1928 1929 1930@cindex control character 1931@cindex character, control 1932A request line begins with a control character, 1933which is either a single quote (@samp{'}) or a period (@samp{.}). 1934These can be changed @pxref{Character Translations}, for details. 1935After this there may be optional tabs or spaces followed by an 1936identifier which is the name of the request. 1937This may be followed by any number of space separated arguments. 1938 1939@findex \& 1940If you want to begin a line with a control character without it being 1941interpreted, precede it with a @code{\&}. This represents a zero 1942width space, which means it will not affect you output. 1943 1944In most cases you will use the period as a control character. 1945Several requests will cause a break, using the single quote control 1946character will prevent this. 1947 1948 1949@menu 1950* Request Arguments:: 1951@end menu 1952 1953@node Request Arguments, , Requests, Requests 1954@subsubsection Request Arguments 1955@cindex request arguments 1956@cindex arguments to requests 1957 1958 1959Argument to requests (and macros) are processed much like the shell: 1960The line is split into arguments according to spaces. 1961An argument which is intended to contain spaces can either be enclosed 1962in quotes (single or double), or have the spaces @dfn{escaped} with 1963backslashes. 1964 1965So, for example: 1966 1967@example 1968.uh The Mouse Problem 1969.uh "The Mouse Problem" 1970.uh The\ Mouse\ Problem 1971@end example 1972 1973The first line is the @code{.uh} macro being called with 3 arguments, 1974@samp{The}, @samp{Mouse}, and @samp{Problem}. 1975The latter two have the same effect or calling the @code{.uh} macro 1976with one argument @samp{The Mouse Problem}. 1977 1978Note, however, that the @code{.ds} request works differently. 1979 1980@c distribute these through the text 1981@xref{Strings} 1982 1983@node Macros, Escapes, Requests, Embedded Commands 1984@subsection Macros 1985@cindex macros 1986 1987 1988Troff has a @dfn{macro} facility for defining a series of lines which 1989can be invoked by name. 1990They are called in the same manner as requests 1991and arguments may be passed in the same manner. 1992 1993 1994@c distribute these through the text 1995@xref{Writing Macros} 1996@c distribute these through the text 1997@xref{Request Arguments} 1998 1999@node Escapes, , Macros, Embedded Commands 2000@subsection Escapes 2001@cindex escapes 2002 2003 2004@findex \e 2005@findex \\ 2006Escapes may occur anywhere in the input to groff. 2007They begin with a backslash and are followed by a single character 2008which indicates the function to be performed. 2009If you want to have a backslash appear in your document, you should 2010use the escape sequence @code{\e}. Merely escaping the backslash 2011with another backslash will work in @emph{some} curcumstances. 2012 2013Many escapes have no parameters, those that do, do so in one of two 2014ways. For escapes which require an identifier there must be a way for 2015groff to tell where the identifier ends and the text begins. 2016It assumes that the next single character is the identifier, but if 2017that character is an open parenthesis, it takes the next two 2018characters as the identifier; and if the next character is an open 2019bracket, all characters until a close bracket are taken as the 2020identifier. Note that in the second case there is no closing 2021parenthesis. For example: 2022 2023@example 2024\fB 2025\n(XX 2026\*[TeX] 2027@end example 2028 2029Other escapes may require several arguments and/or some special 2030format. In these cases the @dfn{argument} is enclosed in single 2031quotes (not required??) and the enclosing text is decoded according 2032to what that escape expects. 2033 2034@example 2035\l'1.5i\(bu' 2036@end example 2037 2038@findex \\ 2039@findex \e 2040@findex \E 2041If you want to have a backslash appear in your output, you can use several 2042escapes: @code{\\}, @code{\e} or @code{\E}. 2043These are very similar, and only differ with respect to being used in 2044macros or diversions (@xref{Copy-in Mode}, and @ref{Diversions}, for 2045more information) 2046 2047 2048 2049@c distribute these through the text 2050@xref{Identifiers} 2051 2052@menu 2053* Comments:: 2054@end menu 2055 2056@node Comments, , Escapes, Escapes 2057@subsubsection Comments 2058@cindex comments 2059 2060 2061@findex \" 2062Probably one of the most@footnote{Unfortunately, this is a lie. But 2063hopefully future troff hackers will believe it :-)} 2064common forms of escapes is the comment. 2065They begin with the @code{\"} escape and end at the end of the input 2066line. 2067 2068This may sound simple, but it can be tricky to keep the comments from 2069interfering with the apperarance of your final outupt. 2070 2071If the escape is to the right of some text or a request, that portion 2072of the line will be ignored, but the space leading up to it will be 2073noticed by groff. This only affects the @code{.ds} request (any 2074others?). 2075 2076One possibly irritating idiosyncracy is that you mustn't use tabs to 2077line up your comments. 2078Tabs are not treated as white space between request and macro 2079arguments. 2080 2081If you have a comment on a line by itself, it will be treated as a 2082blank line, because after eliminating the comment, that is all that 2083remains. So, it is common to start the line with @code{.\"} which 2084will cause the line to be treated as an undefined request. 2085 2086Another commenting scheme seen sometimes is three consecutive single 2087quotes (@code{'''}) at the begining of a line. This works, but groff 2088will give a warning about an undefined macro, which is harmless, but 2089irritating. 2090 2091@findex \# 2092Now to avoid all this groff has a new comment mechanism using the 2093@code{\#} escape. This escape works the same as @code{\"} except 2094that the newline is also ignored. 2095 2096@findex ig 2097For large blocks of text, the @code{ig} request may be useful. 2098@c distribute these through the text 2099@xref{Strings} 2100 2101@node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial 2102@section Registers 2103@cindex registers 2104 2105 2106Registers are groff's numeric variables. groff has a number of 2107builtin registers, supplying anything from the date to details of 2108formatting parameters. 2109 2110@c distribute these through the text 2111@xref{Identifiers} 2112 2113@menu 2114* Setting Registers:: 2115* Interpolating Registers:: 2116* Auto-increment:: 2117* Assigning Formats:: 2118* Builtin Registers:: 2119@end menu 2120 2121@node Setting Registers, Interpolating Registers, Registers, Registers 2122@subsection Setting Registers 2123@cindex setting registers 2124@cindex registers, setting 2125 2126 2127@findex nr 2128@findex \R 2129Registers are defined/set via the @code{nr} 2130request or the @code{\R} escape, for example, the following two lines 2131are equivalent: 2132 2133@example 2134.nr a 1 2135\R'a 1' 2136@end example 2137 2138@findex rr 2139The @code{rr} request will 2140remove the register specified by the argument. 2141 2142@findex rnn 2143The @code{rnn} request will rename a number register. 2144The format is @samp{.rnn @var{x} @var{y}}, which will 2145rename number register @var{x} to @var{y}. 2146 2147@findex aln 2148Aliases can be created for a number register. The format is 2149@samp{.aln @var{xx} @var{yy}}, which will create an alias @var{xx} for 2150number register object named @var{yy}. The new name and the old name 2151will be exactly equivalent. If @var{yy} is undefined, a warning of 2152type @samp{reg} will be generated, and the request will be ignored. 2153@xref{Debugging}, for information about warnings. 2154 2155 2156@node Interpolating Registers, Auto-increment, Setting Registers, Registers 2157@subsection Interpolating Registers 2158@cindex interpolating registers 2159@cindex registers, interpolating 2160 2161 2162@findex \n 2163Numeric registers are @dfn{interpolated} via the @code{\n} escape. 2164@c the following is wrong. Should I say any more than the above?? 2165@c This means that the value of the number register in expanded in-place 2166@c on the input line before any other actions, i.e. before requests and 2167@c escapes are interpreted. 2168 2169@example 2170.nr as \na+\na 2171\n(as 2172@end example 2173 2174 2175@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 2176@subsection Auto-increment 2177@cindex auto-increment 2178@cindex increment, automatic 2179 2180Number registers can also be auto incremented/decremented. You can 2181specify the increment/decrement factor with third argument to the 2182@code{nr} request. The default value is 0. For example: 2183 2184@example 2185.nr a 0 1 2186.nr xx 0 5 2187\n+a, \n+a, \n+a, \n+a, \n+a 2188.br 2189\n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx 2190@end example 2191 2192Produces: 2193 2194@example 21951, 2, 3, 4, 5 21965, 10, 15, 20, 25 2197@end example 2198 2199If you want to change the increment factor without changing the value 2200of a register, the following can be used. 2201 2202@example 2203.nr a \na 10 2204@end example 2205 2206 2207@node Assigning Formats, Builtin Registers, Auto-increment, Registers 2208@subsection Assigning Formats 2209@cindex assigning formats 2210@cindex formats, assigning 2211 2212 2213@findex af 2214When a register is used in the text of an input file 2215(as opposed to part of an expression) 2216it is textually replaced (or interpolated) with a representation of 2217that number. 2218This output format can be changed to a variety of formats 2219(numbers, roman numerals, etc) 2220This is done using the @code{af} request. 2221The first argument to @code{af} is the name of the number register to 2222be changed, 2223and the second argument is the output format. 2224The following output formats are available: 2225 2226@table @samp 2227@item 1 2228This is the default format, decimal numbers: 22291, 2, 3, @dots{} 2230@item 001 2231Decimal numbers with as many leading zeros as specified. 2232So, @samp{001} would result in 001, 002, 003, @dots{} 2233@item I 2234@cindex roman numerals 2235@cindex numerals, roman 2236Upper-case roman numerals: 22370, I, II, III, IV, @dots{} 2238@item i 2239Lower-case roman numerals: 22400, i, ii, iii, iv, @dots{} 2241@item A 2242Upper-case letters: 2243A, B, C, @dots{}, Z, AA, AB, @dots{} 2244@item a 2245Lower-case letters: 2246a, b, c, @dots{}, z, aa, ab, @dots{} 2247@end table 2248 2249The following example will produce @samp{10, X, j, 010}. 2250 2251@example 2252.nr a 10 2253.af a 1 \" the default format 2254\na, 2255.af a I 2256\na, 2257.af a a 2258\na, 2259.af a 001 2260\na 2261@end example 2262 2263@findex \g 2264The @code{\g} escape returns the current format of the specified 2265register. For example, @samp{\ga} after the following example would 2266produce @samp{001}. 2267 2268 2269 2270@node Builtin Registers, , Assigning Formats, Registers 2271@subsection Builtin Registers 2272@cindex builtin registers 2273@cindex registers, builtin 2274 2275 2276The following are some builtin registers, which are not listed 2277elsewhere in this manual. Any registers which begin with a @samp{.} 2278are read-only. A compleat listing of all builtin registers can be 2279found in @ref{Register Index}. 2280 2281@table @code 2282@item .H 2283@vindex .H 2284Horizontal resolution in basic units. 2285@item .V 2286@vindex .V 2287Vertical resolution in basic units. 2288@item dw 2289@vindex dw 2290Day of the week (1-7). 2291@item dy 2292@vindex dy 2293Day of the year (1-31). 2294@item mo 2295@vindex mo 2296Current month (1-12). 2297@item yr 2298@vindex yr 2299Last two digits of the current year (see you in 7 years :-) 2300@item .c 2301@vindex .c 2302@itemx c. 2303@vindex c. 2304The current @emph{input} line number. 2305@item ln 2306@vindex ln 2307The current @emph{output} line number. 2308@item .x 2309@vindex .x 2310The major version number. For example, if the version number is 1.03 2311then @code{.x} will contain 1. 2312@item .y 2313@vindex .y 2314The minor version number. For example, if the version number is 1.03 2315then @code{.y} will contain 03. 2316@item .g 2317@vindex .g 2318Always 1. 2319Macros should use this to determine whether they are running 2320under GNU troff. 2321@item .A 2322@vindex .A 2323If the current output device is ascii, this is set to 1, 2324zero otherwise. 2325@item .P 2326@vindex .P 2327This register indicates whether the current page is actualy being 2328printed, i.e. if the @samp{-o} option is being used to only print 2329selected pages. 2330@xref{Options}, for more information. 2331@end table 2332 2333@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial 2334@section Manipulating Filling and Adjusting 2335@cindex manipulating filling and adjusting 2336@cindex filling and adjusting, manipulating 2337@cindex adjusting and filling, manipulating 2338 2339 2340@findex br 2341@cindex break 2342@cindex line break 2343Several ways of causing @dfn{breaks} were given in 2344@ref{Implicit Line Breaks}. 2345The @code{br} request will likewise cause a break. 2346Several other requests will also cause breaks, implicitly. 2347They are 2348@code{bp}, 2349@code{ce}, 2350@code{fi}, 2351@code{fl}, 2352@code{in}, 2353@code{nf}, 2354@code{sp} and 2355@code{ti}. 2356 2357@findex nf 2358@findex fi 2359@vindex .u 2360Initially, groff will fill and ajust text to both margins. 2361Filling can be disabled via the @code{nf} request 2362and re-enabled with the @code{fi} request. 2363These implicitly disable and re-enable adjusting. 2364Both of these will cause break in text currently being filled. 2365The number register @code{.u} is equal to 1 in fill mode and 0 in 2366no-fill mode. 2367 2368@findex ad 2369@findex na 2370@vindex .j 2371Adjusting can be disabled with the @code{ad} request and re-enabled 2372with the @code{na} request. 2373The @code{ad} request takes a single argument to indicate how to 2374adjust text. 2375The current adjustment mode is available in the number register 2376@code{.j}. 2377 2378@table @samp 2379@item l 2380@cindex ragged-right 2381Adjust text to the left margin. This produces what is traditionally 2382called ragged-right text. 2383@item r 2384Adjust text to the right margin. 2385@item c 2386Center filled text. 2387@item b 2388@itemx n 2389Justify to both margins. This is groff's default. 2390@end table 2391 2392With no argument to @code{ad}, troff will adjust lines the same way 2393it was the last time it was filling. For example: 2394 2395@example 2396text 2397.ad r 2398text 2399.ad c 2400text 2401.na 2402text 2403.ad \" back to centering 2404text 2405@end example 2406 2407@findex \p 2408The escape @code{\p} will cause a break and cause the remaining text 2409to be adjusted. 2410 2411@findex ss 2412The @code{ss} request allows you to change the minimum size of a 2413space between filled words. 2414This request takes it's units as one twelfth of the 2415spacewidth parameter for the current font. Initially both the word 2416space size and the sentence space size are 12. 2417 2418When two arguments are given to the @code{ss} request, the second argument 2419gives the sentence space size. If the second argument is not given, the 2420sentence space size will be the same as the word space size. 2421The sentence space size 2422is used in two circumstances: if the end of a sentence occurs at the end 2423of a line in fill mode, then both an inter-word space and a sentence 2424space will be added; if two spaces follow the end of a sentence in the 2425middle of a line, then the second space will be a sentence space. Note 2426that the behaviour of @sc{Unix} troff will be exactly that exhibited by GNU 2427troff if a second argument is never given to the @code{ss} request. In GNU 2428troff, as in @sc{Unix} troff, you should always follow a sentence with either 2429a newline or two spaces. 2430 2431@vindex .ss 2432@vindex .sss 2433The number registers @code{.ss} and @code{.sss} are 2434the values of the parameters set by the first and second 2435arguments of the @code{ss} request. 2436 2437@findex ce 2438The @code{ce} request will center text. 2439While the @samp{ad c} request will also center text, it has the side 2440effect of filling the text. The @code{.ce} request will not fill the 2441text it affects. 2442This request causes a break. 2443 2444With no arguments, @code{ce} will fill the next line of text. 2445The single argument @code{ce} takes is a number indicating the 2446number of lines to be centered. With no argument centering is 2447disabled. 2448 2449A common idiom is to turn on centering for a large number of lines, 2450and then turn off centering when you are done with the centered text. 2451This is useful for any request which takes a number of lines as an 2452argument. 2453 2454@example 2455.ce 1000 2456replace this 2457with 2458something 2459more interesting 2460@dots{} 2461.ce 0 2462@end example 2463 2464@vindex .ce 2465The @code{.ce} number register contains the number of lines remaining 2466to be centered, as set by the @code{ce} request. 2467 2468 2469@findex rj 2470@vindex .rj 2471A similar request is @code{rj} request which will justify unfilled 2472text to the right margin. Its arguments are identical to the 2473@code{ce} request. 2474The @code{.rj} number register is 2475the number of lines to be right-justified as set by the @code{rj} 2476request. 2477 2478 2479 2480@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial 2481@section Manipulating Hyphenation 2482@cindex manipulating hyphenation 2483@cindex hyphenation, manipulating 2484 2485 2486As discussed in @ref{Hyphenation}, groff will hyphenate words. 2487There are a number of ways to modify the how hyphenation is done. 2488 2489@findex nh 2490@findex hy 2491@vindex .hy 2492This hyphenation can be turned off with the @code{nh} request, and 2493turned back on with the @code{hy} request. However, troff's 2494hyphenation facilities are far more flexible than this. The @code{hy} 2495request can be used to tell troff to restrict hypenation to certain 2496cases. The request takes a single numeric argument. 2497The current hyphenation restrictions can be found in the number 2498register @code{.hy} 2499 2500@table @samp 2501@item 1 2502The default argument, which 2503indicates to hyphenate without restrictions. 2504@item 2 2505Do not hyphenate the last word on a page or column. 2506@item 4 2507Do not hyphenate the last two characters of a word. 2508@item 8 2509Do not hyphenate the first two characters of a word. 2510@end table 2511 2512@findex hlm 2513@vindex .hlc 2514@vindex .hlm 2515The @code{hlm} request will 2516set the maximum number of consecutive hyphenated lines to the value 2517given as the first argument. 2518If this number is 2519negative, there is no maximum. The default value is -1. 2520This value is 2521associated with the current environment. Only lines output from an 2522environment count towards the maximum associated with that environment. 2523Hyphens resulting from @code{\%} are counted; explicit hyphens are not. 2524The current setting of this is available in the @code{.hlm} request. 2525Also the number of immediately preceding consecutive hyphenated lines 2526are available in the number register @code{.hlc}. 2527 2528@findex hw 2529The @code{hw} request allows you to specify how a specific word is 2530to be hyphenated. It takes only one argument which is the word with 2531hyphens at the hyphenation points. For example: 2532@samp{.hw in-sa-lub-rious}. 2533@c In old versions of troff there was a 2534@c limited amount of space to store such information, fortunately, 2535@c with groff, this is no longer a restriction. 2536 2537@findex \% 2538@cindex hyphenation character 2539@cindex character, hyphenation 2540You can also tell troff how to hyphenate words on the fly with the 2541use of the @code{\%} escape, also known as the @dfn{hyphenation 2542character}. Preceding a word with this character will prevent it 2543from being hyphenated, putting it in a word will indicate to troff 2544that the word may be hyphenated at that point. Note that this 2545mechanism will only affect one word, if you want to change the 2546hyphenation of a word for the entire document, use the @code{hw} 2547request. 2548 2549@findex hc 2550The @code{hc} request allows you to change the hyphenation character. 2551The character specified as an argument will then work the same as the 2552@code{\%} escape, and, thus, no longer appear in the output. Without 2553an argument it will return the hyphenation character to @code{\%}. 2554 2555@findex hpf 2556To further customize hyphenation the @code{hpf} request will read in 2557a file of hyphenation patterns. 2558This file will be searched for in the 2559same way that @file{tmac.@var{name}} is searched for when the 2560@samp{-m@var{name}} option is specified. 2561 2562It should have the same format as the argument to the 2563\patterns primitive in @TeX{}; the letters appearing in this file are 2564interpreted as hyphenation codes. 2565A @samp{%} character in the patterns file 2566introduces a comment that continues to the end of the line. 2567 2568@findex hla 2569@findex hpf 2570@pindex troffrc 2571The set of 2572hyphenation patterns is associated with the current language set by the 2573@code{hla} request. The @code{hpf} request is usually invoked by the 2574@file{troffrc} file. 2575 2576@findex hcode 2577@code{.hcode @var{c1 code1 c2 code2...}} 2578Set the hyphenation code of character @var{c1} to code1 and that of 2579@var{c2} to @var{code2}. 2580A hyphenation code must be a single input character (not a 2581special character) other than a digit or a space. Initially each 2582lower-case letter has a hyphenation code, which is itself, and each 2583upper-case letter has a hyphenation code which is the lower case 2584version of itself. 2585 2586@findex hym 2587@vindex .hym 2588The @code{hym} request will set the hyphenation margin to the value 2589given as the first argument: when the current adjustment mode is not 2590@samp{b}, the line will not be hyphenated if the line is no more than 2591that amount short. 2592The default hyphenation margin is 0. The default scaling 2593indicator for this request is m. The hyphenation margin is associated 2594with the current environment. The current hyphenation margin is 2595available in the @code{.hym} register. 2596 2597@findex hys 2598@vindex .hys 2599The @code{hys} request set the hyphenation space to the value given as 2600the first argument: when the current adjustment mode is b, don't 2601hyphenate the line if the line can be justified by adding no more than 2602that amount of extra space to each word space. The default 2603hyphenation space is 0. The default scaling indicator for this 2604request is m. The hyphenation space is associated with the current 2605environment. The current hyphenation space is available in the 2606@code{.hys} register. 2607 2608@findex shc 2609The @code{shc} request will set the soft hyphen character to the 2610argument given as an argument. If the argument is omitted, the soft 2611hyphen character will be set to the default @code{\(hy}. The soft 2612hyphen character is the character which will be inserted when a word 2613is hyphenated at a line break. If the soft hyphen character does not 2614exist in the font of the character immediately preceding a potential 2615break point, then the line will not be broken at that point. Neither 2616definitions (specified with the @code{char} request) nor translations 2617(specified with the @code{tr} request) are considered when finding the soft 2618hyphen character. 2619 2620@findex hla 2621@vindex .hla 2622@pindex troffrc 2623The @code{hla} request will set the current hyphenation language to 2624that given by the first argument. Hyphenation exceptions specified 2625with the @code{hw} request and hyphenation patterns specified with the 2626@code{hpf} request are both associated with the current hyphenation 2627language. The @code{hla} request is usually invoked by the 2628@file{troffrc} file. The current hyphenation language is available 2629in the number register @code{.hla}. 2630 2631 2632 2633@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial 2634@section Manipulating Spacing 2635@cindex manipulating spacing 2636@cindex spacing, manipulating 2637 2638 2639@findex sp 2640The @code{sp} request will cause troff to space downwards the 2641distance specified as the first argument. With no argument it will 2642advance 1 line. 2643A negative argument will cause troff to move up the page the 2644specified distance. 2645If the argument is preceded by a @samp{|} troff will move that 2646distance from the top of the page. 2647 2648@findex ls 2649@vindex .L 2650Often you may want your output to be double or triple spaced. 2651The @code{ls} request will cause troff to output @var{n}-1 blank 2652lines after each line of text, where @var{n} is the argument given to 2653the @code{ls} request. With no argument troff will go back to single 2654spacing. The number register @code{.L} contains the current line 2655spacing setting. 2656 2657@findex \x 2658@vindex .a 2659Sometimes, extra vertical spacing is only needed occasionaly, 2660i.e. to allow space for a tall construct (like an equation). 2661The @code{\x} escape will do this. 2662The escape is given a numerical argument (like @samp{\x'3p'}). 2663If this number is positive extra vertical space will be inserted 2664below the current line. A negative number will add space above. 2665If this escape is used multiple times on the same line, the maximum 2666values are used. 2667The @code{.a} number register contains the most recent 2668extra vertical @strong{emph} line space. 2669 2670@example 2671... example of inline equation ... 2672@end example 2673 2674@findex ns 2675@findex rs 2676@cindex no-space mode 2677@cindex mode, no-space 2678Spacing (via either @code{sp} or via blank lines) can be disabled 2679with the @code{ns} request. This will enable @dfn{no-space mode}. 2680This mode will end when actual text is output or the @code{rs} 2681request is encountered. No-space mode will also prevent requests to 2682advance to the next page unless they are accompanied by a page number 2683(@pxref{Page Control}, for more information.) 2684 2685 2686@node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial 2687@section Tabs and Fields 2688@cindex tabs and fields 2689@cindex fields and tabs 2690 2691 2692@findex \t 2693Tab stops are much like those on a typewriter: a tab character (or the 2694@code{\t} escape) on input will cause horizontal motion to the next 2695tab stop. 2696 2697@findex ta 2698Tab stops can be changed with the @code{ta} request. 2699This request takes a series of numbers as arguments which indicate 2700where each tab stop is to be (overriding any previous settings). 2701These can be specified absolutely, 2702i.e. as the distance from the left margin. 2703For example, the following wil set tab stops every one inch. 2704 2705@example 2706.ta 1i 2i 3i 4i 5i 6i 2707@end example 2708 2709Tab stops can also be specified relatively (using a leading @samp{+}) 2710which means that the specified tab stop will be set that distance 2711from the previous tab stop. For example the following is equivalent 2712to the previous example. 2713 2714@example 2715.ta 1i +1i +1i +1i +1i +1i 2716@end example 2717 2718After the specified tab stops repeat values may be set for tabs beyond 2719the last one specified. This is most commonly used to specify tabs 2720set at equal intervals. The compleat syntax for setting tabs is 2721@code{ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2} 2722@dots{} @var{rn}} This will set tabs at positions @var{n1}, @var{n2}, 2723@dots{}, @var{nn} and then set tabs at @var{nn}+@var{r1}, 2724@var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} and then at 2725@var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, @dots{}, 2726@var{nn}+@var{rn}+@var{rn}, and so on. For example the following is, 2727yet again, the same as the previous examples. 2728 2729@example 2730.ta T 1i 2731@end example 2732 2733The material in each tab column may be justified to the right or left 2734or centered in the column. This is specified by appending an 2735@samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop. 2736The default justification is @samp{L}. 2737 2738@example 2739.ta 1i 2iC 2iR 2740@end example 2741 2742@vindex .tabs 2743The number register @code{.tabs} contains 2744a string representation of the current tab settings suitable for use as 2745an argument to the @code{ta} request. 2746 2747@findex tc 2748Normally troff will fill the space to the next tab stop with spaces. 2749In some cases you may wish to change this. The @code{tc} request 2750will do this. With no argument troff will revert to using spaces. 2751 2752@subsection Leaders 2753@cindex leaders 2754 2755@findex lc 2756Sometimes you may wish to use the @code{tc} request to fill a tab 2757stop with a given character, but also, you want to use normal tab 2758stops on the rest of the line. For this groff provides an alternate 2759tab mechanism, called @dfn{leaders} which will do just that. 2760They are used exclusively to produce a repeated run of characters to 2761the next tab stop. 2762 2763You can declare what character will be repeated with the @code{lc} 2764request. If you do not give it an argument, the leaders will act the 2765same as tabs. 2766 2767@findex \a 2768The difference is that a leader is invoked by using the @code{\a} 2769escape. 2770 2771@cindex table of contents 2772@cindex contents, table of 2773So for a table of contents you may want to have tab stops defined so 2774that the section number is one tab stop, the title is the second with 2775the remaining space being filled with a line of dots and then the 2776page number slightly separated from the dots. 2777 2778@example 2779.lc . 2780.ta .5iR 5i +.25i 27811.1\tFoo\a\t12 2782@end example 2783 2784@subsection Fields 2785@cindex fields 2786 2787@findex fc 2788Fields are a more general way of laying out tabular data. 2789@code{fc} 2790 2791@node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial 2792@section Character Translations 2793@cindex character translations 2794@cindex translations of characters 2795 2796 2797@findex cc 2798@findex c2 2799The control character (@samp{.}) and the no-break control character 2800(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 2801respectively. 2802The single argument is the new character to be used, with no argument 2803the normal control character is restored. 2804 2805@findex ec 2806@findex eo 2807The @code{eo} request will compleatly disable the escape mechanism. 2808The @code{ec} request can be used to change the escape character from 2809the default @samp{\} to what is specified as an argument. 2810 2811@findex tr 2812The @code{tr} request will translate characters. 2813 2814@findex trnt 2815@findex \! 2816@code{trnt} 2817This is the same as the @code{tr} request except that the 2818translations do not 2819apply to text that is transparently throughput into a diversion with 2820@code{\!}. @xref{Diversions}, for more information. 2821For example, 2822 2823@example 2824.tr ab 2825.di x 2826\!.tm a 2827.di 2828.x 2829@end example 2830 2831will print @samp{b}; if @code{trnt} is used instead of @code{tr} it 2832will print @samp{a}. 2833 2834 2835@node Line Layout, Page Layout, Character Translations, Programming Tutorial 2836@section Line Layout 2837@cindex line layout 2838@cindex layout, line 2839 2840 2841@cindex dimensions, line 2842@cindex line dimensions 2843The following drawing shows the dimensions which troff uses for 2844placing a line of output onto the page. They are labeled with the 2845request which manipulates that dimension. 2846 2847@example 2848@group 2849 | -->| in |<-- | 2850 -->| po |<-----------ll------------>| 2851 +----+----+----------------------+----+ 2852 | : : : | 2853 +----+----+----------------------+----+ 2854@end group 2855@end example 2856 2857These dimensions are: 2858 2859@ftable @code 2860@item po 2861@vindex .o 2862@dfn{Page offset}--This is the leftmost postition of text on the final 2863output. This can be adjusted with the @code{po} request, and the 2864current setting can be found in the builtin number register @code{.o} 2865Note, that this request does not cause a break, so changing the page 2866offset in the middle of text being filled may not do what you expect. 2867@item in 2868@vindex .i 2869@dfn{Indentation}--This is the distance from the left margin where text 2870will be printed. This can be adjusted with the @code{in} request, and 2871the current setting can be found in the builtin number register. 2872@code{.i} 2873This request causes a break. 2874 2875@findex ti 2876@findex .in 2877There is also the request @code{ti} which will cause one output line 2878to be indented, after which the indentation returns to 0. 2879This request causes a break. 2880The number register @code{.in} is the indent that applies to the 2881current output line. 2882@item ll 2883@findex .l 2884@findex .ll 2885@dfn{Line length}--This is the distance from the left margin to right 2886margin. This can be adjusted with the @code{.ll} request, and the 2887current setting can be found in the builtin number register @code{.l} 2888Note, as the figure implies, line length is not affected by the current 2889indentation. 2890The number register @code{.ll} is 2891the line length that applies to the current output line. 2892@end ftable 2893 2894@example 2895.in +.5i 2896.ll -.5i 2897A bunch of really boring text which should 2898be indented from both margins. 2899replace me with a better (and more) example! 2900.in -.5i 2901.ll +.5i 2902@end example 2903 2904 2905@node Page Layout, Page Control, Line Layout, Programming Tutorial 2906@section Page Layout 2907@cindex page layout 2908@cindex layout, page 2909 2910 2911Troff provides some very primitive operations for controlling page 2912layout. 2913 2914@findex pl 2915@vindex .p 2916Troff lets you specify the @dfn{page length} via the @code{pl} request. 2917This is the length of the physical output page. 2918The current setting can 2919be found in the builtin number register @code{.p}. Note that this only 2920specifies the size of the page, not the not the top and bottom margins. 2921Those are not done by groff directly, @xref{Traps}, for further 2922information on how to do this. 2923 2924@cindex headers 2925@cindex footers 2926@cindex titles 2927Troff provides several operations which help in setting up top and 2928bottom titles (or headers and footers) 2929 2930@findex tl 2931The @code{tl} request will print a @dfn{title line}, which consists 2932of three parts: a left justified portion, a centered portion and a 2933right justified portion. The argument to @code{tl} is specified as 2934@code{'@var{left}'@var{center}'@var{right}'} 2935The @samp{%} character is replaced with the current page number. 2936 2937@findex lt 2938@vindex .lt 2939The title line is printed using its own line length, which is 2940specified with the @code{lt} request. The current setting of this is 2941available in the @code{.lt} number register. 2942 2943@findex pn 2944The @code{pn} request will change the page number of the @emph{next} 2945page. The only argument is the page number. 2946 2947@vindex % 2948@vindex .pn 2949The current page number is stored in the number register @code{%}. 2950The number register @code{.pn} contains the 2951number of the next page: 2952either the value set by a @code{pn} request, or 2953the number of the current page plus 1. 2954 2955@findex pc 2956The @code{pc} request will change the page number character (used by 2957the @code{tl} request) to a different character. With no argument, 2958this mechanism is disabled. 2959 2960 2961@c distribute these through the text 2962@xref{Traps} 2963 2964@node Page Control, Fonts, Page Layout, Programming Tutorial 2965@section Page Control 2966@cindex page control 2967@cindex control, page 2968 2969 2970@findex bp 2971To stop processing the current page, and move to the next page, you 2972can invoke the @code{bp} request. This request will also cause a 2973break. This request can also take an argument of what the next page 2974should be numbered. 2975The only difference 2976between @code{bp} and @code{pn} is that @code{pn} does not cause a 2977break or actually eject a page. 2978 2979@example 2980.de newpage 2981'bp 2982'sp .5i 2983.tl 'left top'center top'right top' 2984'sp .3i 2985.. 2986@end example 2987 2988@cindex orphan 2989@findex ne 2990Often you may want to make sure that you have a certain amount of 2991space before a new page occurs. This is most useful to make sure 2992that there is not a single @dfn{orphan} line left at the bottom of a 2993page. The @code{ne} request will ensure that there is a certain 2994distance, specified by the first argument, before the next page is 2995triggered (@pxref{Traps}, for further information). 2996The default unit for @code{ne} is v's and the default argument 2997is 1v. 2998 2999For example, to make sure that no fewer than 2 lines get orphaned, 3000you can do the following before each paragraph. 3001 3002@example 3003.ne 2 3004.ti +5n 3005text 3006@end example 3007 3008@findex sv 3009@findex os 3010The @code{sv} is similar to the @code{ne} request, it reserves the 3011specified amount of vertical space. If the desired amount of space 3012exists before the next trap (bottom page boundary), the space will be 3013output immediately. If there is not enough space, it is stored for 3014later output via the @code{os} request. 3015The default argument is 1v and the default units are v's. 3016 3017 3018@node Fonts, Sizes, Page Control, Programming Tutorial 3019@section Fonts 3020@cindex fonts 3021 3022 3023@findex ft 3024@findex \f 3025Groff gives you the ability to switch fonts at any point in your 3026text. There are two ways to do this, via the @code{ft} request and 3027the @code{\f} escape. 3028 3029Fonts are generaly specified as uppercase strings, which are usually 30301 to 4 characters representing an abreviation of acronym of the font 3031name. 3032 3033The basic set of fonts are R, I, B, and BI. These are Times Roman, 3034Italic, Bold, and Bold Italic. There is also at least one symbol 3035font which contains various special symbols (greek, mathematics). 3036These latter fonts cannot be used directly, but should be used via an 3037escape. 3038 3039 3040@menu 3041* Changing Fonts:: 3042* Font Families:: 3043* Font Positions:: 3044* Using Symbols:: 3045* Artificial Fonts:: 3046* Ligatures and Kerning:: 3047@end menu 3048 3049@node Changing Fonts, Font Families, Fonts, Fonts 3050@subsection Changing Fonts 3051@cindex changing fonts 3052@cindex fonts, changing 3053 3054 3055@findex ft 3056You can change fonts with both the @code{ft} request. 3057With no arguments it 3058will switch to the previous font (also known as P). 3059 3060@example 3061eggs, bacon, 3062.ft B 3063spam 3064.ft 3065and sausage. 3066@end example 3067 3068@findex \f 3069The @code{\f} escape is useful for changing fonts in the middle of words 3070 3071@example 3072eggs, bacon, \fBspam\fP and sausage. 3073@end example 3074 3075Both of the above examples will produce the same output. 3076 3077Sometimes when putting letters of different fonts, you need more or 3078less space at such boundaries. There are two escapes to help with 3079this. 3080 3081@findex \/ 3082The @code{\/} escape 3083increases the width of the preceding character so that the spacing 3084between that character and the following character will be correct if 3085the following character is a roman character. For example, if an italic 3086f is immediately followed by a roman right parenthesis, then in many 3087fonts the top right portion of the f will overlap the top left of the 3088right parenthesis. 3089It is a good idea to use this escape sequence 3090whenever an italic character is immediately followed by a roman 3091character without any intervening space. 3092 3093@c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids this problem. 3094 3095@findex \, 3096The @code{\,} escape 3097modifies the spacing of the following character so that the spacing 3098between that character and the preceding character will correct if the 3099preceding character is a roman character. 3100It is a good idea 3101to use this escape sequence whenever a roman character is immediately 3102followed by an italic character without any intervening space. 3103 3104@c For example, inserting \, between the parenthesis and the f changes (f to (f. 3105 3106@findex ftr 3107The @code{ftr} request will translate fonts, it is called as 3108@samp{.ftr @var{F G}}, which 3109Translate font @var{F} to @var{G}. 3110Whenever a font named @var{F} is referred to in @code{\f} 3111escape sequence, 3112or in the @code{ft}, @var{ul}, @var{bd}, @var{cs}, @var{tkf}, 3113@var{special}, @var{fspecial}, @var{fp}, 3114or @var{sty} requests, font @var{G} will be used. If @var{G} is 3115missing, or equal to @var{F} then font @var{F} will not be translated. 3116 3117 3118@node Font Families, Font Positions, Changing Fonts, Fonts 3119@subsection Font Families 3120@cindex font families 3121@cindex families, font 3122 3123 3124Due to the variety of fonts available, groff has added the concept of 3125font families. Each of these families has four styles (R, I, B and BI), 3126 3127The fonts are specified as the concatenation of the font family and 3128style. Specifying a font without the family part will cause groff to 3129use that style of the current family. 3130By default, groff uses the Times family. 3131 3132This way, you can just use the basic four fonts and select a 3133different font family on the command line. 3134 3135@findex fam 3136@vindex .fam 3137You can also switch font families with the @code{fam} request 3138The current font family is available in the number register 3139@code{.fam}. 3140This is a string-valued register. 3141 3142@example 3143spam, 3144.fam H 3145spam, 3146.ft B 3147spam, 3148.fam T 3149spam, 3150.ft AR 3151baked beans, 3152.ft R 3153and spam. 3154@end example 3155 3156 3157 3158@node Font Positions, Using Symbols, Font Families, Fonts 3159@subsection Font Positions 3160@cindex font positions 3161@cindex positions, font 3162 3163 3164For the sake of old phototypesetters and compatability with old 3165versions of troff, groff has the concept of font 3166@dfn{positions}, on which various fonts are mounted. 3167The last one or two are reserved for the symbol font(s). 3168 3169@findex fp 3170New fonts can be mounted with the @code{fp} request. 3171These numeric positions can then be referred to with font changing commands. 3172When groff starts it is using font number one. 3173 3174@example 3175.fp 1 H 3176.fp 2 HI 3177.fp 3 HB 3178wink, wink, 3179.ft 2 3180nudge, nudge, 3181.ft 3182.ft 3 3183say no more! 3184.ft 3185@end example 3186 3187(note that after these font changes have taken place the original 3188font is restored.) 3189 3190@vindex .f 3191The current font in use, as a font position. 3192This can be useful to remember the current font, for later recall. 3193 3194@example 3195.nr save-font \n(.f 3196... lots 'o text ... 3197.ft \n[save-font] 3198@end example 3199 3200@vindex .fp 3201The number of the next free font position is available in the number 3202register @code{.fp}. This is useful when mounting a new font, like so: 3203 3204@example 3205.fp \n[.fp] NEATOFONT 3206@end example 3207 3208@pindex DESC 3209Fonts not listed in the @file{DESC} file are automatically mounted on 3210the next available font position when they are referenced. 3211If a font is to be 3212mountfed explicitly with the @code{fp} request on an unused font position, it 3213should be mounted on the first unused font position, which can be found 3214in the @code{.fp} register; although troff does not enforce this strictly, 3215it will not allow a font to be mounted at a position whose number is 3216much greater than that of any currently used position. 3217 3218The @code{fp} request has an optional third argument. 3219This argument gives the 3220external name of the font, which is used for finding the font 3221description file. The second argument gives the internal name of the 3222font which is used to refer to the font in troff after it has been 3223mounted. If there is no third argument then the internal name will be 3224used as the external name. This feature allows you to use fonts with 3225long names in compatibility mode. 3226 3227 3228 3229@node Using Symbols, Artificial Fonts, Font Positions, Fonts 3230@subsection Using Symbols 3231@cindex using symbols 3232@cindex symbols, using 3233 3234 3235@findex \( 3236@findex \[ 3237Symbols can be inserted by using a special escape sequence. 3238This escape is simply the escape character (a backslash) followed by 3239an identifier. The symbol identifiers have to be two or more 3240characters, since single characters conflict with all the other 3241escapes. The identifier can be either preceded by a parenthesis if 3242it is two character, or surrounded by square brackets. 3243So, the symbol for pi can be produced either by @code{\(*p} or 3244@code{\[*p]}. 3245 3246@example 3247area = \(*p\fIr\fP\u2\d 3248@end example 3249 3250@findex \C 3251The escape @code{\C'@var{xxx}'} will typeset character named 3252@var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}. 3253But @code{\C} has the advantage that it is compatible with recent 3254versions of ditroff and is available in compatibility mode. 3255 3256@findex \N 3257The escape @code{\N'@var{n}'} will typeset the character with code 3258@var{n} in the current font. @var{n} can be any integer. Most devices only 3259have characters with codes between 0 and 255. If the current font 3260does not contain a character with that code, special fonts will not be 3261searched. The @code{\N} escape sequence can be conveniently used on 3262conjunction with the @code{char} request: 3263 3264@example 3265.char \[phone] \f(ZD\N'37' 3266@end example 3267 3268The code of each character is given in the fourth column in the font 3269description file after the charset command. It is possible to include 3270unnamed characters in the font description file by using a name of 3271@samp{---}; the @code{\N} escape sequence is the only way to use these. 3272 3273@findex cflags 3274Each character has certain properties associated with it. 3275These properties can be modified with the @code{cflags} request. 3276The first argument is the the sum of the desired flags and the 3277remaining arguments are the characters to have those properties. 3278@table @code 3279@item 1 3280the character ends sentences (initially characters @samp{.?!} have this 3281property); 3282@item 2 3283lines can be broken before the character (initially no characters have 3284this property); 3285@item 4 3286lines can be broken after the character (initially characters 3287@samp{-\(hy\(em} have this property); 3288@item 8 3289the character overlaps horizontally (initially characters 3290@samp{\(ul\(rn\(ru} have this property); 3291@item 16 3292the character overlaps vertically (initially character @samp{\(br} has 3293this property); 3294@item 32 3295an end of sentence character followed by any number of characters with 3296this property will be treated as the end of a sentence if followed by a 3297newline or two spaces; in other words the character is transparent for 3298the purposes of end of sentence recognition; this is the same as having 3299a zero space factor in @TeX{} (initially characters 3300@samp{"')]*\(dg\(rq} have this property). 3301@end table 3302 3303@findex char 3304You can create new characters with the @code{char} request. It is 3305called as @samp{.char @var{c} @var{string}} Define character @var{c} 3306to be @var{string}. Every time character @var{c} needs to be printed, 3307@var{string} will be processed in a temporary environment and the 3308result will be wrapped up into a single object. Compatibility mode 3309will be turned off and the escape character will be set to \ while 3310@var{string} is being processed. Any emboldening, constant spacing or 3311track kerning will be applied to this object rather than to individual 3312characters in @var{string}. A character defined by this request can 3313be used just like a normal character provided by the output device. 3314In particular other characters can be translated to it with the 3315@code{tr} request; it can be made the leader character by the 3316@code{lc} request; repeated patterns can be drawn with the character 3317using the @code{\l} and @code{\L} escape sequences; words containing 3318the character can be hyphenated correctly, if the @code{hcode} request 3319is used to give the character a hyphenation code. There is a special 3320anti-recursion feature: use of character within the character's 3321definition will be handled like normal characters not defined with 3322@code{char}. 3323 3324@findex rchar 3325A character definition can be removed with the @code{rchar} request. Its 3326arguments are the characters to be removed. This undoes the effect of 3327a @code{char} request. 3328 3329@c distribute these through the text 3330@xref{Special Characters} 3331 3332@node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts 3333@subsection Artificial Fonts 3334@cindex artificial fonts 3335@cindex fonts, artificial 3336 3337 3338There are a number of requests for artificially creating fonts. 3339These are largely vestigal remains from the days when output devices 3340did not have a wide variety of fonts, and when nroff and troff were 3341separate programs. 3342These are no longer necessary in GNU Troff. 3343 3344@findex ul 3345The @code{ul} request will print subsequent lines in italics on a 3346device capable of it, or underline the text on an ascii output device. 3347The single argument is the number of lines to be ``underlined,'' 3348with no argument, the next line will be underlined. 3349 3350@findex cu 3351The @code{cu} request is similar to @code{ul} ... 3352 3353@findex uf 3354The @code{uf} request will set the underline font used by @code{ul} 3355and @code{cu}. 3356 3357@findex bd 3358The @code{bd} request artificially creates a bold font by printing 3359each character twice, slightly offset. 3360The first argument specifies the font to embolden, and the second is 3361the number of basic units, minus one, by which the two characters 3362will be offset. If the second argument is missing, emboldening will 3363be turned off. 3364 3365 3366@node Ligatures and Kerning, , Artificial Fonts, Fonts 3367@subsection Ligatures and Kerning 3368@cindex ligatures and kerning 3369@cindex kerning and ligatures 3370 3371 3372@findex lg 3373@vindex .lg 3374@code{lg} 3375@code{.lg} 3376The current ligature mode. 3377 3378What is kerning?? 3379 3380If the font description file contains pairwise kerning information, 3381characters from that font will be kerned. Kerning between two 3382characters can be inhibited by placing a @code{\&} between them. 3383 3384@findex kern 3385@vindex .kern 3386@code{kern} 3387If n is non-zero or missing, enable pairwise kerning, otherwise disable 3388it. 3389@code{.kern} 33901 if pairwise kerning is enabled, 0 otherwise. 3391 3392@findex tkf 3393.tkf f s1 n1 s2 n2 3394Enable track kerning for font f. When the current font is f the width 3395of every character will be increased by an amount between n1 and n2; 3396when the current point size is less than or equal to s1 the width will 3397be increased by n1; when it is greater than or equal to s2 the width 3398will be increased by n2; when the point size is greater than or equal to 3399s1 and less than or equal to s2 the increase in width is a linear 3400function of the point size. 3401 3402 3403@node Sizes, Strings, Fonts, Programming Tutorial 3404@section Sizes 3405@cindex sizes 3406 3407 3408@cindex baseline 3409Groff uses two dimensions with each line of text, type size and 3410vertical spacing. The type size is the height from the text 3411@dfn{baseline} to the top of the tallest character (decenders may drop 3412below this baseline). Vertical spacing is the amount of space groff 3413allows for a line of text, normally, this is about 20% larger than the 3414current type size. Ratios smaller than this can result in 3415hard-to-read text, larger that this, it will spread your text out more 3416vertically (useful for term papers). By default, troff uses 10 point 3417type on 12 point spacing. 3418 3419@cindex leading 3420The difference between type size and vertical spacing is known, by 3421typesetters, as @dfn{leading}. 3422 3423 3424@menu 3425* Changing Type Sizes:: 3426* Fractional Type Sizes:: 3427@end menu 3428 3429@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 3430@subsection Changing Type Sizes 3431@cindex changing type sizes 3432@cindex type sizes, changing 3433 3434 3435@findex ps 3436@findex vs 3437@findex \s 3438@vindex .s 3439@vindex .v 3440Using the @code{ps} request and the @code{\s} escape you can change 3441the type size. The @code{vs} request will change the vertical 3442spacing. The default unit for the @code{ps} and @code{vs} requests are 3443points. 3444The number registers @code{.s} and @code{.v} contain the current 3445type size and vertical spacing. 3446 3447These requests take parameters in units of points. You can specify 3448sizes as an absolute size, or as a relative change from the current 3449size. The size 0 means go back to the previous size. With no 3450argument it will revert to the previous size. 3451 3452@example 3453snap, snap, 3454.ps +2 3455grin, grin, 3456.ps +2 3457wink, wink, \s+2nudge, nudge,\s+8 say no more! 3458.ps 10 3459@end example 3460 3461The @code{\s} escape may be called in a variety of ways. 3462Much like other escapes there must be a way to determine where the 3463argument ends and the text begins. 3464Any of the following forms are valid: 3465@code{\s@var{n}}, 3466@code{\s+@var{n}}, 3467@code{\s-@var{n}}, 3468@code{\s(@var{nn}}, 3469@code{\s+(@var{nn}}, 3470@code{\s-(@var{nn}}, 3471@code{\s[+@var{nnn}]}, 3472@code{\s[-@var{nnn}]}, 3473@code{\s+[@var{nnn}]}, 3474@code{\s-[@var{nnn}]}. 3475 3476Some devices may only have certain permissible sizes, in which case 3477groff will round to the nearest permissible size. 3478 3479@example 3480... .sz macro example?? ... 3481@end example 3482 3483@node Fractional Type Sizes, , Changing Type Sizes, Sizes 3484@subsection Fractional Type Sizes 3485@cindex fractional type sizes 3486@cindex type sizes, fractional 3487 3488 3489A @dfn{scaled point} is equal to 1/@var{sizescale} points, where 3490@var{sizescale} is specified in the @file{DESC} file (1 by default.) 3491There is a new scale indicator @samp{z} which has the effect of 3492multiplying by @var{sizescale}. Requests and escape sequences in 3493troff interpret arguments that represent a pointsize as being in units 3494of scaled points, but they evaluate each such argument using a default 3495scale indicator of @samp{z}. Arguments treated in this way are the 3496argument to the @code{ps} request, the third argument to the @code{cs} 3497request, the second and fourth arguments to the @code{tkf} request, 3498the argument to the @code{\H} escape sequence, and those variants of 3499the @code{\s} escape sequence that take a numeric expression as their 3500argument. 3501 3502For example, suppose @var{sizescale} is 1000; then a scaled point will be 3503equivalent to a millipoint; the request @samp{.ps 10.25} is equivalent to 3504@samp{.ps 10.25z} and so sets the pointsize to 10250 scaled points, which is 3505equal to 10.25 points. 3506 3507The number register @code{\n(.s} returns the pointsize in points as 3508decimal fraction. There is also a new number register @code{\n[.ps]} 3509that returns the pointsize in scaled points. 3510 3511It would make no sense to use the @samp{z} scale indicator in a 3512numeric expression whose default scale indicator was neither @samp{u} 3513nor @samp{z}, and so troff disallows this. Similarily it would make 3514no sense to use a scaling indicator other than @samp{z} or @samp{u} in a 3515numeric expression whose default scale indicator was @samp{z}, and so 3516troff disallows this as well. 3517 3518There is also new scale indicator @samp{s} which multiplies by the 3519number of units in a scaled point. So, for example, @samp{\n[.ps]s} 3520is equal to 1m. Be sure not to confuse the @samp{s} and @samp{z} 3521scale indicators. 3522 3523@code{\s'+@var{n}'} 3524@code{\s'-@var{n}'} 3525@code{\s+'@var{n}'} 3526@code{\s-'@var{n}'} 3527Set the point size to @var{n} scaled points; @var{n} is a numeric 3528expression with a default scale indicator of @samp{z}. 3529 3530@code{\n[.ps]} 3531The current pointsize in scaled points. 3532 3533@code{\n[.psr]} 3534The last-requested pointsize in scaled points. 3535 3536@code{\n[.sr]} 3537The last requested pointsize in points as a decimal fraction. This is a 3538string-valued register. 3539 3540 3541@c distribute these through the text 3542@xref{Font Files} 3543 3544@node Strings, Conditionals and Loops, Sizes, Programming Tutorial 3545@section Strings 3546@cindex strings 3547 3548 3549@findex ds 3550Groff has string variables, which are entirely for user convenience 3551(i.e. there are no builtin strings) They are defined via the 3552@code{ds} request. 3553 3554@example 3555.ds UX \s-1UNIX\s0\u\s-3tm\s0\d 3556@end example 3557 3558@findex \* 3559The are interpolated, or expanded in-place, via the @code{\*} escape: 3560 3561@example 3562The \*(UX Operating System 3563@end example 3564 3565Will produce: 3566 3567@example 3568The UNIXtm Operating System 3569@end example 3570 3571If the string named by the @code{\*} does not exist, the escape will 3572be replaced by nothing. 3573 3574@cindex comments, with @code{ds} 3575NOTE: Unlike other requests the third argument takes up the entire 3576line including trailing spaces. This means that comments on a line 3577with such a request can introduce unwanted space into a string. 3578 3579@example 3580.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" trademark of you-know-who 3581@end example 3582 3583Instead you should either put the comment on another line or 3584have the comment escape adjacent with the end of the string. 3585 3586@example 3587.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" trademark of you-know-who 3588@end example 3589 3590If you need leading space you can start the string with a double 3591quote. No trailing quote is needed, in fact any trailing quote is 3592included in your string. 3593 3594@cindex canibalism 3595@example 3596.ds sign " Yours in a white wine sauce, 3597@end example 3598 3599@findex as 3600@cindex appending to strings 3601@cindex strings, appending 3602You can also append onto a string with the @code{as} request. 3603It works the same as the @code{ds} request except that it appends the 3604second argument onto the string named by the first argument. 3605 3606@example 3607.as sign " with shallots, onions and garlic, 3608@end example 3609 3610@findex \@key{ret} 3611Strings are not limited to a sigle line of text. A string can span 3612several lines by escaping the newlines with a backslash. The 3613resulting string will be stored @emph{without} the newlines. 3614 3615@example 3616.ds foo lots and lots \ 3617of text are on these \ 3618next several lines 3619@end example 3620 3621@findex rn 3622@code{rn} 3623 3624@findex rm 3625@code{rm} 3626 3627@findex als 3628@code{als} 3629 3630@findex chop 3631@code{chop} 3632 3633@c distribute these through the text 3634@xref{Identifiers} 3635@c distribute these through the text 3636@xref{Comments} 3637 3638@node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial 3639@section Conditionals and Loops 3640@cindex conditionals and loops 3641@cindex loops and conditionals 3642 3643 3644@findex if 3645@findex while 3646In @code{if} and @code{while} requests, there are several more operators 3647available: 3648 3649@table @code 3650@item e 3651@itemx o 3652True if the current page is even or odd numbered (respectively) 3653@item n 3654@itemx t 3655True if the document is being processed by 3656nroff (or an ascii device) or troff. 3657@item '@var{xxx}'@var{yyy}' 3658True if the string @var{xxx} is equal to the string @var{yyy}. 3659Other characters can be used in place of the single quotes. 3660(Which?) 3661The strings are `formatted' before being compared. (?) 3662@item r@var{xxx} 3663True if there is a number register named @var{xxx}. 3664@item d@var{xxx} 3665True if there is a string, macro, diversion, or request named @var{xxx}. 3666@item c@var{ch} 3667True if there is a character @var{ch} available; @var{ch} is 3668either an ASCII character or a special character @code{\(@var{ch}} or 3669@code{\[@var{ch}]}; the condition will also be true if @var{ch} has been 3670defined by the @code{char} request. 3671@end table 3672 3673 3674@menu 3675* if-else:: 3676* while:: 3677@end menu 3678 3679@node if-else, while, Conditionals and Loops, Conditionals and Loops 3680@subsection if-else 3681@cindex if-else 3682 3683 3684Troff has if-then-else constructs like other languages, although 3685the formatting can be painful. 3686 3687@findex if 3688The @code{if} request is troff's if statement, it is called as 3689@samp{.if @var{expr} @var{anything}}, where @var{expr} is the 3690expression to be evaluated, 3691and @var{anything} (the remainder of the line) 3692which will be executed if 3693the @var{expr} evaluates to non-zero (true). 3694@var{anything} will be interpreted as though it was on a line by 3695itself. 3696@xref{Expressions}, for more info. 3697 3698Here are some examples: 3699 3700@example 3701.if t .ls 2 \" double spacing in troff 3702.if 0 .ab how'd this happen?? 3703@end example 3704 3705@findex ie 3706@findex el 3707An if-then-else is written using two requests @code{ie} and @code{el} 3708the first request is the if part and the latter is the else part. 3709 3710@example 3711.ie 3712.el 3713@end example 3714 3715@findex \@{ 3716@findex \@} 3717In many cases you will want more than one request to be executed as a 3718result of any of these requests, this can be done using the \@{ and 3719\@} escapes. 3720The following example shows the possible ways to use these escapes. 3721 3722@example 3723.ie t \@{\ 3724. ds lq `` 3725. ds rq '' 3726.\@} 3727.el \ 3728.\@{\ 3729. ds lq " 3730. ds rq "\@} 3731.ds qq " 3732@end example 3733 3734 3735@c distribute these through the text 3736@xref{Expressions} 3737 3738@node while, , if-else, Conditionals and Loops 3739@subsection while 3740@cindex while 3741 3742 3743@findex while 3744Groff provides a looping construct using the @code{while} request, 3745which is used much like the @code{if} (and related) requests. 3746The first argument is an expression which will be evaluated. 3747The @code{while} request will interpret the remainder of the line 3748until the expression evaluates to 0 or false. 3749 3750@example 3751.nr a 0 1 3752.while (\na<9) \&\n+a, 3753\&\n+a 3754@end example 3755 3756The preceding example produces: 3757 3758@example 37591, 2, 3, 4, 5, 6, 7, 8, 9, 10 3760@end example 3761 3762@findex break 3763@findex continue 3764The @code{break} request will 3765@dfn{break} out of a while loop. 3766Be sure not to confuse this with the @code{.br} request. 3767The @code{continue} request will 3768finish the current iteration of a while loop. 3769 3770@c distribute these through the text 3771@xref{Expressions} 3772 3773@node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial 3774@section Writing Macros 3775@cindex writing macros 3776@cindex macros, writing 3777 3778 3779@findex de 3780A macro is a collection of text and embedded commands which can be 3781invoked multiple times. Macros are used for defining common operations. 3782Macros are defined using the @code{de} request. This request takes 3783a name for the macro as the first argument. Subsequent lines are 3784copied into an internal buffer until the line @code{..} is 3785encountered. The optional second argument to @code{de} can change 3786this ending token. 3787 3788For example, suppose at the beginning of each paragraph, you want 3789cause a break, move down a partial line and indent the first line. 3790Such a macro could be defined as follows: 3791 3792@example 3793.de P 3794.br 3795.sp .8v 3796.. 3797@end example 3798 3799@findex am 3800The @code{am} request works similarily to @code{de} except it appends 3801onto the macro named by the first argument. So, if we decide we want 3802our previously @code{P} macro to actually do indented instead of 3803block paragraphs we can add the necessary code to our existing macro. 3804 3805@example 3806.am P 3807.ti +5n 3808.. 3809@end example 3810 3811@findex als 3812@cindex aliases, macro 3813@cindex macro aliases 3814Macros can be aliased with the @code{als} request. 3815 3816@findex rn 3817@code{rn} 3818 3819@findex rm 3820@code{rm} 3821 3822@findex chop 3823@code{chop} 3824 3825 3826@menu 3827* Copy-in Mode:: 3828* Parameters:: 3829@end menu 3830 3831@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 3832@subsection Copy-in Mode 3833@cindex copy-in mode 3834@cindex mode, copy-in 3835 3836 3837@findex \n 3838@findex \$ 3839@findex \* 3840@findex \\ 3841@findex \@key{RET} 3842When troff reads in the test for a macro or diversion it copies the 3843text (including request lines) into an internal buffer, except for 3844escapes. Escapes will be converted into an internal form, except for 3845@code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which 3846are evaluated and inserted into the text where the escape was located. 3847This is known as @dfn{copy-in} mode. 3848 3849What this means is that you can specify when these escapes are to be 3850evaluated (copy-in time or time of use) by insulating the escapes 3851with an extra backslash. 3852 3853For example, the following will result in the numbers 20 and 10 being 3854printed. 3855 3856@example 3857.nr x 20 3858.de y 3859.nr x 10 3860\&\nx 3861\&\\nx 3862.. 3863.y 3864@end example 3865 3866 3867 3868@node Parameters, , Copy-in Mode, Writing Macros 3869@subsection Parameters 3870@cindex parameters 3871 3872 3873@findex \$ 3874@vindex .$ 3875The arguments to a macro can be examined using a variety of escapes. 3876The number of arguments is available in the @code{.$} number register. 3877Any individual argument can be retrieved with one of the following 3878escapes: 3879 3880The escapes @code{\$@var{n}}, @code{\$(@var{nn}} 3881and @code{\$[@var{nnn}]} 3882will result in the @var{n}th, @var{nn}th or @var{nnn}th 3883argument. Macros can have a unlimited number of arguments. 3884Note that due to copy-in mode, you will want to have two backslashes 3885on these in actual use, since you do not want them interpolated until 3886the macro is actually invoked. 3887 3888@findex shift 3889The request @code{shift} will shift the arguments 1 position, or as 3890many positions as specified by the first argument. 3891After executing this request, argument 3892@var{i} will become argument @var{i}-@var{n}; arguments 1 to @var{n} 3893will no longer be available. 3894Shifting by negative amounts is currently undefined. 3895 3896@findex \$* 3897@findex \$@@ 3898In some cases you will want to just use all of the arguments at once. 3899For example if you pass the arguments along to another macro. 3900The @code{\$*} escape is 3901the concatenation of all the arguments separated by spaces. 3902A similar escape is @code{\$@@}, 3903which is 3904the concatenation of all the arguments with each surrounded 3905by double quotes, and separated by spaces. 3906 3907@findex \$0 3908@findex als 3909The @code{\$0} escape is 3910the name by which the current macro was invoked. The @code{als} 3911request can make a macro have more than one name. 3912 3913@example 3914.de vl 3915.ie \\n(.$=1 .ds Vl Pre-Release Version 3916.el .ds Vl Version \\$3, \\$4. 3917.. 3918@end example 3919 3920This would be called as 3921 3922@example 3923.vl $Id: groff.texinfo,v 1.5 1999/12/09 09:42:29 wlemb Exp $ 3924@end example 3925 3926 3927@c distribute these through the text 3928@xref{Request Arguments} 3929 3930@node Page Motions, Drawing Functions, Writing Macros, Programming Tutorial 3931@section Page Motions 3932@cindex page motions 3933@cindex motions, page 3934 3935 3936@findex sp 3937Motions up and down the page can be done with the @code{sp} request. 3938However, this causes a break so that the actual effect is to move to 3939the left margin and then to the specified location. 3940 3941@findex mk 3942@findex rt 3943The request @code{mk} can be used to mark a location on a page, for 3944movement to later. This request takes a register name as an 3945argument in which to store the current page location, with no 3946argument it will store the location in an internal register. 3947The results of this can be used later by the @code{rt} or the 3948@code{sp} request. The @code{rt} request will return 3949@strong{upwards} to the location given in the register name given as 3950an argument, with no argument it will return to the location marked 3951with the @code{mk} request 3952 3953@example 3954... dual column example ... 3955@end example 3956 3957There are escapes which will give you much finer control of movements 3958about the page. 3959 3960@findex \v 3961The @code{\v'@var{e}'} will let you do arbitrary vertical motion from 3962the current location on the page. The argument @var{e} specifies the 3963distance to move, positive is downwards and negative upwards. The 3964default unit for this escape is vertical spaces, @code{v}'s. Beware, 3965however, that troff will leave text processing to continue wherever 3966the motion ends, so if you don't want to interfere with text 3967processing, make sure your motions are balanced. 3968 3969There are some special case escapes for vertical motion. 3970 3971@ftable @code 3972@item \r 3973move upwards 1v. 3974@item \u 3975move upwards .5v. 3976@item \d 3977move down .5v. 3978@end ftable 3979 3980@findex \h 3981Horizontal motions can be done via the @code{\h'@var{e}'} escape. 3982The expression @var{e} indicates how far to move: positive is 3983rightwards and negative leftwards. 3984 3985There are a number of special case escapes for horizontal motion: 3986 3987@ftable @code 3988@item \@key{SP} 3989An unbreakable and unpadable (i.e. not expanded during filling) space. 3990(Note: it is a backslash followed by a space.) 3991@item \~ 3992This produces an unbreakable space that stretches like a normal 3993interword space when a line is adjusted. 3994@item \| 3995a 1/6th em space. 3996@item \^ 3997a 1/12th em space. 3998@item \0 3999a space the size of a digit. 4000@item \& 4001A zero width space. 4002@item \) 4003Like @code{\&} except that it behaves like a character declared with 4004the @code{cflags} request to be transparent for the purposes of end 4005of sentence recognition. 4006@end ftable 4007 4008@example 4009... tex logo example ... 4010@end example 4011 4012@findex \w 4013@cindex width escape 4014@cindex escape, width 4015Often you will want to do horizontal movement based on the width of 4016some arbitrary text (e.g. given as an argument to a macro). 4017For that, there is the escape @code{\w'@var{text}'} which will 4018interpolate to the width of the given @var{text} in basic units. 4019 4020@example 4021... strlen example ... 4022@end example 4023 4024Font changes may occur in @var{text} and not affect current settings. 4025 4026Also after use, @code{\w} sets several registers: 4027 4028@table @code 4029@item st 4030@vindex st 4031@itemx sb 4032@vindex sb 4033The highest and lowest point, respectively, in @var{text}. 4034@item rst 4035@vindex rst 4036@itemx rsb 4037@vindex rsb 4038Like the @code{st} and @code{sb} registers, but takes account of the 4039heights and depths of characters. 4040@item ct 4041@vindex ct 4042is set according to what kinds of characters occur in @var{text}. 4043@table @asis 4044@item 0 4045all short characters, no decenders or tall characters. 4046@item 1 4047decender 4048@item 2 4049tall character 4050@item 3 4051both a decender and a tall character 4052@end table 4053@item ssc 4054@vindex ssc 4055The amount of horizontal space (possibly negative) that should be 4056added to the last character before a subscript. 4057@item skw 4058@vindex skw 4059How far to right of the center of the last character in the @code{\w} 4060argument, the center of an accent from a roman font should be 4061placed over that character. 4062@end table 4063 4064@findex \k 4065@vindex .k 4066@code{\k} 4067@code{.k} 4068 4069@node Drawing Functions, Traps, Page Motions, Programming Tutorial 4070@section Drawing Functions 4071@cindex drawing functions 4072@cindex functions for drawing 4073 4074 4075Groff provides a number of ways to draw lines, and other figures on 4076the page. Used in combination with the page motion commands 4077(@pxref{Page Motions}, for more info) you can draw a wide variety of 4078figures. However, for complex drawings these operations can be quite 4079cumbersome, and it may be wise to use the pic preprocessor. 4080@xref{gpic}, for more information. 4081 4082All drawing is done via escapes. 4083 4084@findex \l 4085The @code{\l} will draw a line rightwards from the current location. 4086The full syntax for this escape is @samp{\l'@var{l}@var{c}'}, where 4087@var{l} is the length of the line to be drawn, starting at the 4088current location, positive numbers will draw to the right, and 4089negative will draw towards the left. This can also be specified 4090absolutely (i.e. with a leading |) which will draw back to the 4091begining of the line. 4092 4093The optional second parameter @var{c} is a character to draw the line 4094with. If this second argument is not specified, troff will use the 4095underscore character. 4096 4097If you need to separate the two arguments (to prevent troff from 4098interpreting a drawing character as a scaling indicator), you can 4099separate them with @code{\&}. 4100 4101And now, for a useful example: 4102 4103@example 4104.de box 4105\(br\\$*\(br\l'|0\(rn'\l'|0\(ul' 4106.. 4107@end example 4108 4109Note that this works by outputing a box rule (a vertical line), then 4110the text given as an argument and then another box rule. 4111Then the line drawing escapes both draw from the current location to 4112the beginning of the @emph{input} line. 4113 4114@findex \L 4115Vertical lines are drawn using the @code{\L} escape. It's parameters 4116are specified the same as the @code{\l} escape. If the length is 4117positive, the movement will be downwards, and upwards for negative. 4118The default character is the box rule character. 4119As with the vertical motion escapes, text processing will blindly 4120continue where the line ends. 4121 4122@example 4123...box macro... 4124@end example 4125 4126@findex \D 4127More flexible drawing functions are available via the @code{\D} 4128escape. While the previous escapes will work on an ascii device, 4129these escapes will not. 4130 4131@table @code 4132@item \D'l @var{x} @var{y}' 4133Draw a line from the current location to the relative point specified 4134by @var{x}, @var{y}. 4135 4136@example 4137...revised box macro... 4138@end example 4139 4140@item \D'c @var{d}' 4141Draw a circle with a diameter of @var{d} with the leftmost point at 4142the current position. 4143@item \D'C @var{d}' 4144Draw a solid circle with the same parameters as an outlined circle. 4145@item \D'e @var{dx} @var{dy}' 4146Draw an ellipse with a horizontal diameter of @var{dx} and a vertical 4147diameter of @var{dy} with the leftmost point at the current position. 4148@item \D'E @var{dx} @var{dy}' 4149Draw a solid elipse with the same parameters as an outlined elipse. 4150@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 4151Draw an arc clockwise from the current location through the two 4152specified locations. 4153@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 4154Draw a spline from the current location to 4155@var{dx1}, @var{dy1} and then to @var{dx2}, @var{dy2}, and so on. 4156@item \D'f @var{n}' 4157Set the shade of gray to be used for filling solid objects to @var{n}; 4158@var{n} must be an integer between 0 and 1000, where 0 corresponds 4159solid white and 1000 to solid black, and values in between correspond 4160to intermediate shades of gray. This applies only to solid circles, 4161solid ellipses and solid polygons. By default, a level of 1000 will 4162be used. 4163@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 4164Draw a polygon from the current location to @var{dx1}, @var{dy1} 4165and then to @var{dx2}, @var{dy2} and so on. When the specified data 4166points are exhausted, a line is drawn back to the starting point. 4167 4168@example 4169... box example (yes, again)... 4170@end example 4171 4172@itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 4173Draw a solid polygon with the same parameters as an outlined polygon. 4174 4175@example 4176... shaded box example ... 4177@end example 4178 4179@item \D't @var{n}' 4180Set the current line thickness to @var{n} machine units. 4181A value of zero selects the smallest available line thickness. 4182 4183@end table 4184 4185Current position 4186 4187@findex \b 4188@cindex pile, character 4189@cindex character pile 4190The @code{\b} escape will @dfn{pile} a sequence of characters 4191vertically, and center it vertically on the current line. 4192This can be used to build large brackets and braces. 4193 4194@example 4195\b'\(lt\(bv\(lk\(bv\(lb' 4196@end example 4197 4198 4199 4200 4201@node Traps, Diversions, Drawing Functions, Programming Tutorial 4202@section Traps 4203@cindex traps 4204 4205 4206Traps are locations, which, when reached, will call a specified macro. 4207These traps can occur at a given location on the page, at a given 4208location in the current diversion, after a certain number of input 4209lines or at the end of input. 4210 4211@findex ch 4212Any of these traps can be changed after they have been set with the 4213@code{ch} request. The first arguemnt is the name of the trap or 4214macro, and the second is the new value for that trap. 4215 4216 4217@menu 4218* Page Location Traps:: 4219* Diversion Traps:: 4220* Input Line Traps:: 4221* End-of-input Traps:: 4222@end menu 4223 4224@node Page Location Traps, Diversion Traps, Traps, Traps 4225@subsection Page Location Traps 4226@cindex page location traps 4227@cindex traps, page location 4228 4229 4230Page location traps are frequently used for page headers and 4231footers. The following is a simple example of this. 4232 4233@example 4234.de hd \" Page header 4235'sp .5i 4236.tl 'Title''date' 4237'sp .3i 4238.. 4239.de fo \" Page footer 4240'sp 1v 4241.tl ''%'' 4242'bp 4243.. 4244.wh 0 hd \" top of the page 4245.wh -1i fo \" one inch from bottom 4246@end example 4247 4248@vindex .t 4249The number register @code{.t} is the distance to the next trap. 4250 4251@findex ch 4252The location of a trap can be changed later on with the @code{ch} 4253request. 4254The first argument is the name of the macro to be invoked at the trap 4255and the second argument is the new location for the trap. 4256This is useful when you are building up footnotes in a diversion, and 4257you need to allow more space at the bottom of the page for them. 4258 4259@example 4260... (simplified) footnote example ... 4261@end example 4262 4263@findex vpt 4264@findex wh 4265@findex dt 4266@vindex .vpt 4267The @code{vpt} request will enable vertical position traps if the argment is 4268non-zero, disable them otherwise. Vertical position traps are traps 4269set by the @code{wh} or @code{dt} requests. Traps set by the 4270@code{it} request are not vertical position traps. The parameter that 4271controls whether vertical position traps are enabled is global. 4272Initially vertical position traps are enabled. The current setting of 4273this is available in the number register @code{.vpt}. 4274 4275@vindex .trunc 4276@findex ne 4277The number register @code{.trunc} contains 4278the amount of vertical space truncated by the most recently 4279sprung vertical position trap, or, if the trap was sprung by a 4280@code{ne} request, minus the amount of vertical motion produced by 4281the @code{ne} request. In other words, at the point a trap is 4282sprung, it represents the difference of what the vertical position 4283would have been but for the trap, and what the vertical position 4284actually is. 4285 4286@vindex .ne 4287The number register @code{.ne} contains 4288the amount of space that was needed in the last @code{ne} request that caused 4289a trap to be sprung. Useful in conjunction with the @code{.trunc} 4290register. @xref{Page Control}, for more information. 4291 4292 4293 4294@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 4295@subsection Diversion Traps 4296@cindex diversion traps 4297@cindex traps, diversion 4298 4299 4300@findex dt 4301@vindex .t 4302Traps can also be set @emph{within} a diversion using the @code{dt} 4303request. Like @code{wh} the first argument is the location of the 4304trap and the second argument is the name of the macro to be invoked. 4305The number register @code{.t} will still work within diversions. 4306@xref{Diversions}, for more information. 4307 4308@node Input Line Traps, End-of-input Traps, Diversion Traps, Traps 4309@subsection Input Line Traps 4310@cindex input line traps 4311@cindex traps, input line 4312 4313 4314@findex it 4315The @code{it} request will set an input line trap. The format for 4316calling this is @samp{.it @var{n} @var{name}}, where @var{n} is the 4317number of lines of input which may be read before @dfn{springing} the 4318trap, @var{name} is the macro to be invoked. Request lines are not 4319counted as input lines. 4320 4321For example, one possible use is to have a macro which will print the 4322next @var{n} lines in a bold font. 4323 4324@example 4325.de B 4326.it B-end \\$1 4327.ft B 4328.. 4329.de B-end 4330.ft R 4331.. 4332@end example 4333 4334@node End-of-input Traps, , Input Line Traps, Traps 4335@subsection End-of-input Traps 4336@cindex end-of-input traps 4337@cindex traps, end-of-input 4338 4339 4340@findex em 4341The @code{em} request will set a trap at the end of input. 4342The macro specified as an arguement will be executed after the last 4343line of the input file has been processed. 4344 4345For example, if your document had to have a section at the bottom of 4346the last page for someone to approve you document, you could set it 4347up with @code{em}. 4348 4349@example 4350.de approval 4351.ne 5v 4352.sp |(\\n(.t-6v) 4353.in +4i 4354.lc _ 4355.br 4356Approved:\t\a 4357.sp 4358Date:\t\t\a 4359.. 4360.em approval 4361@end example 4362 4363 4364@node Diversions, Environments, Traps, Programming Tutorial 4365@section Diversions 4366@cindex diversions 4367 4368 4369In Troff you can divert text into a named storage area, due to the 4370similarity to defining macros it is sometimes said to be stored in a 4371macro. This is used for saving text for output at a later time, 4372which is useful for keeping blocks of text on the same page, 4373footnotes, tables of contents and indexes. 4374 4375@findex di 4376@findex da 4377Diversion is initiated by the @code{di} request, like the @code{de} 4378request it takes an argument of a macro name to divert subsequent 4379text to into. The @code{da} macro will append to an existing diversion. 4380 4381@example 4382... end-note example ... 4383@end example 4384 4385@vindex .z 4386@vindex .d 4387@vindex nl 4388@vindex .h 4389Diversions may be nested. 4390The number register @code{.z} contains the name of the current diversion. 4391The number register @code{.d} contains the current vertical place in 4392the diversion. If not in a diversion it is the same as the register 4393@code{nl}. 4394@code{.h} 4395 4396@vindex dn 4397@vindex dl 4398After compleating a diversion, the builtin number registers @code{dn} 4399and @code{dl} contain the vertical and horizontal size of the diversion. 4400 4401@example 4402.\" Center text both horizontally & vertically 4403.de (c 4404.br 4405.nf 4406.di @@c 4407.. 4408.de )c 4409.br 4410.di 4411.nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v) 4412.sp \\n(@@su 4413.ce 1000 4414.nf 4415.@c 4416.br 4417.ce 0 4418.sp \\n(@@su 4419.br 4420.fi 4421.rr @@s 4422.. 4423@end example 4424 4425@findex \! 4426Requests, macros and escapes are interpreted when read into a 4427diversion. 4428There are two ways to prevent this, either way will take the given 4429text and @dfn{transparently} embed it into the diversion. 4430The first method is to prefix the line with @code{\!}. This will 4431cause the entire line to be transparently inserted into the diversion. 4432This is useful for macros you do not want invoked until the diverted 4433text is actually output. 4434 4435@c anything is read in copy mode. (what about \! ??) 4436 4437@findex \? 4438The other way is to surround the text by the @code{\?} escape, i.e. 4439@samp{\?@var{anything}\?}. 4440@var{anything} may not contain 4441newlines; use @code{\!} if you want to embed newlines in a diversion. The 4442escape sequence @code{\?} is also recognised in copy mode and turned into a 4443single internal code; it is this code that terminates anything. Thus 4444the followin example will print 4. 4445 4446@example 4447.nr x 1 4448.nf 4449.di d 4450\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 4451.di 4452.nr x 2 4453.di e 4454.d 4455.di 4456.nr x 3 4457.di f 4458.e 4459.di 4460.nr x 4 4461.f 4462@end example 4463 4464@findex rn 4465@code{rn} 4466 4467@findex rm 4468@code{rm} 4469 4470@findex als 4471@code{als} 4472 4473@findex chop 4474@code{chop} 4475 4476@findex asciify 4477@code{asciify} 4478This request only exists in order to make it possible to make certain 4479gross hacks work with GNU troff. It @dfn{unformats} the diversion 4480specified as an argument in 4481such a way that ASCII characters that were formatted and diverted 4482will be treated like ordinary input characters when the diversion is 4483reread. For example, the following will set register @code{n} to 1. 4484 4485@example 4486.tr @@. 4487.di x 4488@@nr\ n\ 1 4489.br 4490.di 4491.tr @@@@ 4492.asciify x 4493.x 4494@end example 4495 4496 4497@c distribute these through the text 4498@xref{Copy-in Mode} 4499 4500@node Environments, I/O, Diversions, Programming Tutorial 4501@section Environments 4502@cindex environments 4503 4504 4505Often you will need to print some text in a certain format regardless 4506of what may be in effect at the time, for example, in a trap invoked 4507macro to print headers and footers. 4508To solve this groff has @dfn{environments} in which text is processed. 4509An environment contains most of the parameters that control 4510text processing. You can switch amongst these environments, by 4511default groff processes text in environment 0. 4512The following is the information kept in an environment. 4513 4514@itemize @bullet{} 4515@item 4516Type size 4517@item 4518Font (family and style) 4519@item 4520Page parameters 4521@item 4522Fill/adjust mode 4523@item 4524Tab stops 4525@item 4526Partially collected lines 4527@end itemize 4528 4529These environments may be given arbitrary names 4530(@pxref{Identifiers}, for more info.) 4531Old versions of troff only had environments named 0, 1 and 2. 4532 4533@findex ev 4534@vindex .ev 4535The @code{ev} request will switch among these environments. 4536The single argument is the name of the environment to switch to, with 4537no argument groff will switch back to the previous enviroment. 4538There is no limit on the number of named environments; 4539they will be created the first time that they are referenced. 4540The @code{.ev} number register contains 4541the name or number of the current environment. This is a string-valued 4542register. 4543 4544@example 4545... page break macro, revised ... 4546@end example 4547 4548@example 4549.ev footnote-env 4550.fam N 4551.ps 6 4552.vs 8 4553.ll -.5i 4554.ev 4555... 4556.ev footnote-env 4557\(dg Note the large, friendly letters. 4558.ev 4559@end example 4560 4561 4562 4563 4564@node I/O, Postprocessor Access, Environments, Programming Tutorial 4565@section I/O 4566@cindex i/o 4567 4568 4569@findex so 4570The @code{so} request will read in the file given as an argument and 4571include it in place of the @code{so} request. This is quite useful 4572for large documents, i.e. keeping each chapter in a separate file. 4573@xref{gsoelim}, for more information. 4574 4575@findex mso 4576The @code{mso} request is 4577the same as the @code{so} request except that file is searched for in 4578the same way that @file{tmac.@var{name}} is searched for when the 4579@samp{-m@var{name}} option is specified. 4580 4581@findex cf 4582@findex trf 4583The @code{cf} and @code{trf} requests are to include a file. 4584It will transparently output the contents of file filename. Each 4585line is output 4586as it would be were it preceded by @code{\!}; however, the lines are not 4587subject to copy-mode interpretation. If the file does not end with a 4588newline, then a newline will be added. For example, you can define a 4589macro @code{x} containing the contents of file @file{f}, using 4590 4591@example 4592.di x 4593.trf f 4594.di 4595@end example 4596 4597.cf filename 4598When used in a diversion, this will embed in the diversion an object 4599which, when reread, will cause the contents of filename to be 4600transparently copied through to the output. In @sc{Unix} troff, the contents 4601of filename is immediately copied through to the output regardless of 4602whether there is a current diversion; this behaviour is so anomalous 4603that it must be considered a bug. 4604 4605 4606With @code{trf}, unlike @code{cf}, the file cannot contain characters 4607such as NUL that are not legal troff input characters. 4608 4609@findex nx 4610The @code{nx} request will force groff to continue processing of the 4611file specified as an argument. 4612 4613@findex rd 4614The @code{rd} request will read from standard input, and include what 4615is read as though it were part of the input file. Text is read until 4616a blank line is encountered. 4617 4618@cindex form letters 4619@cindex letters, form 4620Using these two requests you can set up form letters. 4621The form letter template is constructed like this: 4622 4623@example 4624.ce 4625\*(td 4626.sp 2 4627.nf 4628.rd 4629.sp 4630.rd 4631.fi 4632Body of letter. 4633.bp 4634.nx repeat.let 4635@end example 4636 4637@findex ex 4638When this is run, the following file should be redirected in. 4639Note that requests included in this file are executed as though they 4640were part of the form letter. The last block of input is the 4641@code{ex} requests which tells groff to stop processing. If this was 4642not there, groff would not know when to stop. 4643 4644@cindex Beagle Brothers 4645@example 4646Trent A. Fisher 4647708 NW 19th Av., #202 4648Portland, OR 97209 4649 4650Dear Trent, 4651 4652Len Adollar 46534315 Sierra Vista 4654San Diego, CA 92103 4655 4656Dear Mr. Adollar, 4657 4658.ex 4659@end example 4660 4661@findex pi 4662@code{pi} 4663 4664@findex sy 4665The @code{sy} request will allow arbitrary system commands to be 4666executed from within a groff document. The output is not saved 4667anyplace, so it is up to you to do so. 4668 4669For example, the following example will introduce the current time 4670into your document: 4671 4672@cindex time 4673@pindex perl 4674@example 4675.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 4676 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 4677.so /tmp/x\n[$$] 4678.sy rm /tmp/x\n[$$] 4679\nH:\nM:\nS 4680@end example 4681 4682Note that this works by having the perl script (run by @code{sy}) 4683print out the @code{nr} requests which will set the number registers 4684@samp{H}, @samp{M} and @samp{S}, and then reads those commands in 4685with the @code{so} request. 4686 4687@vindex systat 4688The @code{systat} number register contains 4689The return value of the @code{system()} function executed by the last 4690@code{sy} request. 4691 4692@findex open 4693The @code{open} request will open 4694a file (specified as the second argument) for writing and associate 4695the stream (specified as the first argument) with it. 4696 4697@findex opena 4698The @code{opena} is 4699like open, but if filename exists, append to it instead of truncating 4700it. 4701 4702@findex write 4703@findex ds 4704@cindex copy-in mode 4705@cindex mode, copy-in 4706The @code{write} request will write to the file associated with the 4707stream specified by the first argument. The stream must previously 4708have been the subject of an open request. The remainder of the line 4709in interpreted as the @code{ds} request reads its second argument: a 4710leading @code{"} will be stripped, and it will be read in copy-in mode. 4711 4712@findex close 4713The @code{close} request will 4714close the stream specified by the first argument; stream will no 4715longer be an acceptable argument to the @code{write} request. 4716 4717@example 4718... example of open write &c... 4719@end example 4720 4721@findex \v 4722The @code{\V} escape will 4723interpolate the contents of the specified environment variable, as returned 4724by getenv(3). 4725The argument to @code{\V} is specified as an identifier, i.e. 4726@samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. 4727@code{\V} is interpreted in copy-in mode. 4728 4729 4730@node Postprocessor Access, Miscellany, I/O, Programming Tutorial 4731@section Postprocessor Access 4732@cindex postprocessor access 4733@cindex access of postprocessor 4734 4735 4736There are two escapes which will allow you to give information 4737directly to the postprocessor. This is particularly useful for 4738embedding PostScript into your final document. 4739 4740@findex \X 4741The @code{\X} escape will embed its argument into the gtroff output 4742preceded with @samp{x X}. 4743 4744@findex \Y 4745The @code{\Y} escape is called with an identifier (i.e. 4746@code{\Y@var{x}}, 4747@code{\Y(@var{xx}} or 4748@code{\Y[@var{xxx}]}). 4749This is approximately equivalent to @samp{\X'\*[@var{xxx}]'}. 4750However the contents 4751of the string or macro @var{xxx} are not interpreted; also it is 4752permitted for 4753@var{xxx} to have been defined as a macro and thus contain newlines 4754(it is not permitted for the argument to @code{\X} to contain newlines). 4755The inclusion of 4756newlines requires an extetension to the @sc{Unix} troff output format, and will 4757confuse drivers that do not know about this extension. 4758 4759 4760@c distribute these through the text 4761@xref{Devices} 4762 4763@node Miscellany, Debugging, Postprocessor Access, Programming Tutorial 4764@section Miscellany 4765@cindex miscellany 4766 4767 4768This section contains parts of troff which cannot (yet) be 4769categorized elsewhere in this manual. 4770 4771@findex nm 4772Line numbers can be printed in the left margin 4773using the @code{nm} request. 4774The first argument is the line number of the @emph{next} output line, 4775this defaults to 1. 4776The second argument indicates on which lines numbers will be printed, 4777i.e. 5 means put line numbers on every 5 lines, this defaults to 1. 4778The third argument is the space to be left between the number and 4779your text, this defaults to 1. 4780The fourth argument is the indentation of the line numbers. 4781Without arguments, line numbers are turned off. 4782 4783@findex nn 4784The @code{nn} request will temporarily turn off line numbering. 4785The first argument is the number of lines not to be numbered, 4786this defaults to 1. (does this disable incrementing or display?) 4787 4788@example 4789... line numbering example ... 4790@end example 4791 4792@findex mc 4793margin characters can be automatically printed to the right of your 4794text with the @code{mc} request. 4795The first argument is the character to be printed and the second 4796argument is the distance away from your text. 4797With no arguments the margin characters are turned off. 4798If this occurs before a break, no margin character will be printed. 4799 4800This is quite useful for indicating text that has changed, and, in 4801fact, there are programs available for doing this (they are called 4802@code{nrchbar} and @code{changebar} and can be found in any 4803@samp{comp.sources.unix} archive. 4804 4805@example 4806... margin char example ... 4807@end example 4808 4809@findex lf 4810@pindex soelim 4811The @code{lf} primary reason for existence is to make debugging 4812documents which are split into many files, which are then put 4813together with @code{soelim} and other preprocessors. 4814The first argument is the name of the file and the second argument is 4815the input line number in that file. 4816This way troff can produce error messages which are intelligible to 4817the user. 4818 4819@example 4820... example of soelim'ed doc ... 4821@end example 4822 4823@node Debugging, Implementation Differences, Miscellany, Programming Tutorial 4824@section Debugging 4825@cindex debugging 4826 4827 4828Troff is not easy to debug, but there are some useful features and 4829strategies for debugging. 4830 4831@itemize @bullet{} 4832@item 4833@findex tm 4834The @code{tm} request will send output to stderr, this is very useful for 4835printing debugging output. 4836@item 4837When doing something involved it is useful to leave the debugging 4838statements in the code and have them turned on by a command line 4839flag. 4840 4841@example 4842.if \n(DB .tm debugging output 4843@end example 4844 4845Then you can activate these statements with: 4846 4847@example 4848groff -rDB=1 file 4849@end example 4850 4851@item 4852@findex ab 4853The @code{ab} request is similar to the @code{tm} request, 4854except that it will cause groff to stop processing. 4855With no argument it will print @samp{User Abort}. 4856@item 4857@findex ex 4858The @code{ex} request will also cause groff to stop processing. 4859@item 4860If you know you are going to get many errors and no useful output, 4861you can tell groff to suppress formatted output with the @samp{-z} 4862flag. 4863@item 4864@findex pm 4865The @code{pm} request will dump out the entire symbol table. 4866@item 4867@findex pnr 4868The @code{pnr} request will print the names and contents of all 4869currently defined number registers on stderr. 4870@item 4871@findex ptr 4872The @code{ptr} request will 4873print the names and positions of all traps (not including input line 4874traps and diversion traps) on stderr. Empty slots in the page trap list 4875are printed as well, because they can affect the priority of 4876subsequently planted traps. 4877@item 4878@findex fl 4879The @code{fl} request instructs groff to flush its output immediately. 4880The intention is that this be used when using troff interactively. 4881There is little other use for it. 4882@item 4883@findex backtrace 4884The @code{backtrace} request will 4885print a backtrace of the input stack on stderr. 4886@item 4887Groff has command line options for printing out more warnings 4888(@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or 4889an error occurs. The most verbose level of warnings is @samp{-ww}. 4890@item 4891@findex warn 4892@vindex .warn 4893The @code{warn} request controls the level of warnings checked for. 4894The one argument is the sum of the numbers associated with each 4895warning that is to be enabled; all other warnings will be disabled. 4896The number associated with each warning is listed below. 4897For example, @code{.warn 0} will disable all warnings, and 4898@code{.warn 1} will disable 4899all warnings except that about missing characters. If an argument 4900is not given, all warnings will be enabled. 4901The number register @code{.warn} contains the current warning level. 4902@end itemize 4903 4904@subsection Warnings 4905@cindex warnings 4906 4907The warnings that can be given by troff are divided into the 4908following categories. The name associated with each warning is used 4909by the @samp{-w} and @samp{-W} options; the number is used by the 4910@code{warn} request, and by the @code{.warn} register. 4911 4912@table @samp 4913@item char 4914@itemx 1 4915Non-existent characters. This is enabled by default. 4916@item number 4917@itemx 2 4918Invalid numeric expressions. This is enabled by default. 4919@item break 4920@itemx 4 4921In fill mode, lines which could not be broken so that 4922their length was less than the line length. This is 4923enabled by default. 4924@item delim 4925@itemx 8 4926Missing or mismatched closing delimiters. 4927@item el 4928@itemx 16 4929Use of the @code{el} request with no matching @code{ie} request. 4930@xref{if-else}, for more information. 4931@item scale 4932@itemx 32 4933Meaningless scaling indicators. 4934@item range 4935@itemx 64 4936Out of range arguments. 4937@item syntax 4938@itemx 128 4939Dubious syntax in numeric expressions. 4940@item di 4941@itemx 256 4942@findex di 4943@findex da 4944Use of @code{di} or @code{da} without an argument when there is no 4945current diversion. 4946@item mac 4947@itemx 512 4948Use of undefined strings, macros and diversions. 4949When an undefined string, macro or diversion is used, 4950that string is automatically defined as empty. So, 4951in most cases, at most one warning will be given for 4952each name. 4953@item reg 4954@itemx 1024 4955Use of undefined number registers. When an undefined 4956number register is used, that register is 4957automatically defined to have a value of 0. a 4958definition is automatically made with a value of 0. 4959So, in most cases, at most one warning will be given 4960for use of a particular name. 4961@item tab 4962@itemx 2048 4963Use of a tab character where a number was expected. 4964@item right-brace 4965@itemx 4096 4966@findex \@} 4967Use of @code{\@}} where a number was expected. 4968@item missing 4969@itemx 8192 4970Requests that are missing non-optional arguments. 4971@item input 4972@itemx 16384 4973Illegal input characters. 4974@item escape 4975@itemx 32768 4976Unrecognized escape sequences. When an unrecognized 4977escape sequence is encountered, the escape character 4978is ignored. 4979@item space 4980@itemx 65536 4981Missing space between a request or macro and its 4982argument. This warning will be given when an 4983undefined name longer than two characters is 4984encountered, and the first two characters of the name 4985make a defined name. The request or macro will not 4986be invoked. When this warning is given, no macro is 4987automatically defined. This is enabled by default. 4988This warning will never occur in compatibility mode. 4989@item font 4990@itemx 131072 4991Non-existent fonts. This is enabled by default. 4992@item all 4993All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 4994intended that this covers 4995all warnings that are useful with traditional macro packages. 4996@item w 4997All warnings. 4998@end table 4999 5000 5001@node Implementation Differences, Summary, Debugging, Programming Tutorial 5002@section Implementation Differences 5003@cindex implementation differences 5004@cindex differences in implementation 5005 5006 5007GNU troff has a number of features which cause incompatibilites with 5008documents written with old versions of troff. 5009 5010Long names cause some incompatibilities. @sc{Unix} troff will interpret 5011 5012@example 5013.dsabcd 5014@end example 5015 5016@findex \* 5017@findex \n 5018@findex cp 5019@vindex .C 5020as defining a string @samp{ab} with contents @samp{cd}. 5021Normally, GNU troff will interpret this as a call of a macro named 5022@code{dsabcd}. Also @sc{Unix} troff will interpret @code{\*[} or 5023@code{\n[} as references to a string or number register called 5024@samp{[}. In GNU troff, however, this will normally be interpreted as the 5025start of a long name. In compatibility mode GNU troff will interpret 5026these things in the traditional way. In compatibility mode, however, 5027long names are not recognised. Compatibility mode can be turned on with 5028the @samp{-C} command line option, and turned on or off with the 5029@code{cp} request. 5030The number register @code{.C} is 1 if compatibility mode is on, 0 otherwise. 5031 5032@findex \A 5033GNU troff does not allow the use of the escape sequences 5034@samp{\| \^ \& \@} \@{ \@key{SP} \' \` \- \_ \! \% \c} in names of 5035strings, macros, 5036diversions, number registers, fonts or environments; @sc{Unix} troff does. 5037The @code{\A} escape sequence may be helpful in avoiding use of these escape 5038sequences in names. 5039 5040@cindex fractional point sizes 5041@cindex point sizes, fractional 5042@findex ps 5043Fractional pointsizes cause one noteworthy incompatibility. In @sc{Unix} 5044troff the @code{ps} request ignores scale indicators and so 5045 5046@example 5047.ps 10u 5048@end example 5049 5050will set the pointsize to 10 points, whereas in GNU troff it will set 5051the pointsize to 10 scaled points. 5052@xref{Fractional Type Sizes}, for more information. 5053 5054@findex bd 5055@findex cs 5056@findex tkf 5057@findex tr 5058@findex fp 5059In GNU troff there is a fundamental difference between unformatted, 5060input characters, and formatted, output characters. Everything that 5061affects how an output character will be output is stored with the 5062character; once an output character has been constructed it is 5063unaffected by any subsequent requests that are executed, including 5064@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} 5065requests. Normally output characters are constructed 5066from input characters at the moment immediately before the character is 5067added to the current output line. Macros, diversions and strings are 5068all, in fact, the same type of object; they contain lists of input 5069characters and output characters in any combination. An output 5070character does not behave like an input character for the purposes of 5071macro processing; it does not inherit any of the special properties that 5072the input character from which it was constructed might have had. For 5073example, 5074 5075@example 5076.di x 5077\\\\ 5078.br 5079.di 5080.x 5081@end example 5082 5083@findex \e 5084@findex \! 5085@findex \? 5086will print @samp{\\} in GNU troff; each pair of input backslashes is 5087turned into one 5088output backslash and the resulting output backslashes are not 5089interpreted as escape 5090characters when they are reread. @sc{Unix} troff would interpret them as 5091escape characters when they were reread and would end up printing one 5092@samp{\}. 5093The correct way to obtain a printable backslash is to use the 5094@code{\e} escape 5095sequence: this will always print a single instance of the current escape 5096character, regardless of whether or not it is used in a diversion; it 5097will also work in both GNU troff and @sc{Unix} troff. If you wish for some 5098reason to store in a diversion an escape sequence that will be 5099interpreted when the diversion is reread, you can either use the 5100traditional @code{\!} transparent output facility, or, if this is unsuitable, 5101the new @code{\?} escape sequence. @xref{Diversions}, for more information. 5102 5103 5104@node Summary, , Implementation Differences, Programming Tutorial 5105@section Summary 5106@cindex summary 5107 5108 5109@node geqn, gtbl, Programming Tutorial, Top 5110@chapter @code{geqn} 5111@cindex @code{eqn} 5112@cindex @code{geqn} 5113 5114 5115@menu 5116* Invoking geqn:: 5117@end menu 5118 5119@node Invoking geqn, , geqn, geqn 5120@section Invoking @code{geqn} 5121@cindex invoking @code{geqn} 5122@cindex @code{geqn}, invoking 5123 5124 5125 5126@node gtbl, gpic, geqn, Top 5127@chapter @code{gtbl} 5128@cindex @code{tbl} 5129@cindex @code{gtbl} 5130 5131 5132@menu 5133* Invoking gtbl:: 5134@end menu 5135 5136@node Invoking gtbl, , gtbl, gtbl 5137@section Invoking @code{gtbl} 5138@cindex invoking @code{gtbl} 5139@cindex @code{gtbl}, invoking 5140 5141 5142@node gpic, grap, gtbl, Top 5143@chapter @code{gpic} 5144@cindex @code{pic} 5145@cindex @code{gpic} 5146 5147 5148@menu 5149* Invoking gpic:: 5150@end menu 5151 5152@node Invoking gpic, , gpic, gpic 5153@section Invoking @code{gpic} 5154@cindex invoking @code{gpic} 5155@cindex @code{gpic}, invoking 5156 5157 5158 5159@node grap, grefer, gpic, Top 5160@chapter @code{grap} 5161@cindex @code{grap} 5162 5163 5164 5165@node grefer, gsoelim, grap, Top 5166@chapter @code{grefer} 5167@cindex @code{refer} 5168@cindex @code{grefer} 5169 5170 5171@menu 5172* Invoking grefer:: 5173@end menu 5174 5175@node Invoking grefer, , grefer, grefer 5176@section Invoking @code{grefer} 5177@cindex invoking @code{grefer} 5178@cindex @code{grefer}, invoking 5179 5180 5181 5182@node gsoelim, Devices, grefer, Top 5183@chapter @code{gsoelim} 5184@cindex @code{soelim} 5185@cindex @code{gsoelim} 5186 5187 5188@menu 5189* Invoking gsoelim:: 5190@end menu 5191 5192@node Invoking gsoelim, , gsoelim, gsoelim 5193@section Invoking @code{gsoelim} 5194@cindex invoking @code{gsoelim} 5195@cindex @code{gsoelim}, invoking 5196 5197 5198 5199@node Devices, File formats, gsoelim, Top 5200@chapter Devices 5201@cindex devices 5202 5203 5204 5205@menu 5206* Special Characters:: 5207* grotty:: 5208* grops:: 5209* grodvi:: 5210* grolj4:: 5211* grohtml:: 5212* gxditview:: 5213@end menu 5214 5215@node Special Characters, grotty, Devices, Devices 5216@section Special Characters 5217@cindex special characters 5218@cindex characters, special 5219 5220 5221@c distribute these through the text 5222@xref{Font Files} 5223 5224@node grotty, grops, Special Characters, Devices 5225@section @code{grotty} 5226@cindex @code{grotty} 5227 5228 5229 5230@menu 5231* Invoking grotty:: 5232@end menu 5233 5234@node Invoking grotty, , grotty, grotty 5235@subsection Invoking @code{grotty} 5236@cindex invoking @code{grotty} 5237@cindex @code{grotty}, invoking 5238 5239 5240 5241@node grops, grodvi, grotty, Devices 5242@section @code{grops} 5243@cindex @code{grops} 5244 5245 5246 5247@menu 5248* Invoking grops:: 5249* Embedding PostScript:: 5250@end menu 5251 5252@node Invoking grops, Embedding PostScript, grops, grops 5253@subsection Invoking @code{grops} 5254@cindex invoking @code{grops} 5255@cindex @code{grops}, invoking 5256 5257 5258 5259@node Embedding PostScript, , Invoking grops, grops 5260@subsection Embedding PostScript 5261@cindex embedding postscript 5262@cindex postscript, embedding 5263 5264 5265 5266@node grodvi, grolj4, grops, Devices 5267@section @code{grodvi} 5268@cindex @code{grodvi} 5269 5270 5271 5272@menu 5273* Invoking grodvi:: 5274@end menu 5275 5276@node Invoking grodvi, , grodvi, grodvi 5277@subsection Invoking @code{grodvi} 5278@cindex invoking @code{grodvi} 5279@cindex @code{grodvi}, invoking 5280 5281 5282 5283@node grolj4, grohtml, grodvi, Devices 5284@section @code{grolj4} 5285@cindex @code{grolj4} 5286 5287 5288 5289@menu 5290* Invoking grolj4:: 5291@end menu 5292 5293@node Invoking grolj4, , grolj4, grolj4 5294@subsection Invoking @code{grolj4} 5295@cindex invoking @code{grolj4} 5296@cindex @code{grolj4}, invoking 5297 5298 5299 5300@node grohtml, gxditview, grolj4, Devices 5301@section @code{grohtml} 5302@cindex @code{grohtml} 5303 5304 5305 5306@menu 5307* Invoking grohtml:: 5308@end menu 5309 5310@node Invoking grohtml, , grohtml, grohtml 5311@subsection Invoking @code{grohtml} 5312@cindex invoking @code{grohtml} 5313@cindex @code{grohtml}, invoking 5314 5315 5316 5317@node gxditview, , grohtml, Devices 5318@section @code{gxditview} 5319@cindex @code{gxditview} 5320 5321 5322 5323@menu 5324* Invoking gxditview:: 5325@end menu 5326 5327@node Invoking gxditview, , gxditview, gxditview 5328@subsection Invoking @code{gxditview} 5329@cindex invoking @code{gxditview} 5330@cindex @code{gxditview}, invoking 5331 5332 5333 5334@node File formats, Installation, Devices, Top 5335@chapter File formats 5336@cindex file formats 5337@cindex formats, file 5338 5339 5340 5341@menu 5342* gtroff Output:: 5343* Font Files:: 5344@end menu 5345 5346@node gtroff Output, Font Files, File formats, File formats 5347@section @code{gtroff} Output 5348@cindex @code{gtroff} output 5349@cindex output, @code{gtroff} 5350 5351 5352This section describes the format output by GNU troff. The output 5353format used by GNU troff is very similar to that used by @sc{Unix} 5354device-independent troff. 5355 5356The output format is ascii based, as opposed to a binary format (like 5357@TeX{} dvi). 5358The output format is 8 bit clean, thus single characters can have the 5359eighth bit set, as can the names of fonts and special characters. 5360 5361The output format consists of single command characters with attached 5362parameters which are separated from subsequent text by whitespace, or 5363a newline. 5364 5365The names of characters and fonts an be of arbitrary length; drivers 5366should not assume that they will be only two characters long (as 5367device-independent troff did). 5368 5369When a character is to be printed, that character will always be in the 5370current font. 5371Unlike device-independent troff, it is not necessary for 5372drivers to search special fonts to find a character. 5373 5374@table @code 5375@item H@var{n} 5376@item V@var{n} 5377@item h@var{n} 5378@item v@var{n} 5379@item c@var{n} 5380@item C@var{n} 5381@item @var{nn}@var{c} 5382@item t@var{xxx} 5383@var{xxx} is any sequence of characters terminated by a space or a 5384newline; the first character should be printed at the current 5385position, the the current horizontal position should be increased by 5386the width of the first character, and so on for each character. 5387The width of the character is that given in the font file, 5388appropriately scaled for the current point size, 5389and rounded so that it is a multiple of the horizontal resolution. 5390Special characters cannot be printed using this command. 5391 5392This command is only allowed if the @samp{tcommand} line is present 5393in the @file{DESC} file. 5394@item u@var{n} @var{xxx} 5395@pindex DESC 5396This is same as the @code{t} command except that after printing each 5397character, the current horizontal position is increased by the sum of 5398the width of that character and @code{n}. 5399 5400This command is only allowed if the @samp{tcommand} line is present 5401in the @file{DESC} file. 5402@item n@var{a}@var{b} 5403@item p@var{n} 5404@item s@var{n} 5405The argument to the s command is in scaled points (units of points/n, 5406where n is the argument to the sizescale command in the DESC file.) 5407@item f@var{n} 5408@item x @dots{} \n 5409Device control. 5410@item D@var{c} @var{x}@dots{}\n 5411@end table 5412 5413@subsection Device Control 5414 5415The @code{x} command is normally followed by a letter or word 5416indicating the function to perform, followed by white space separated 5417arguments. 5418 5419The first argument can be abreviated to the first letter. 5420 5421@table @code 5422@item x init 5423@item x T 5424@item x res @var{n} @var{h} @var{v} 5425@item x H 5426The argument to the x Height command is also in scaled points. 5427@end table 5428 5429The first three output commands are guaranteed to be: 5430 5431@example 5432x T device 5433x res n h v 5434x init 5435@end example 5436 5437For example, the input @samp{crunchy \fH\s+2frog\s0\fP!?} will produce: 5438 5439@example 5440... sample output here ... 5441@end example 5442 5443@subsection Drawing Functions 5444 5445The D drawing command has been extended. These extensions will only be 5446used by GNU pic if the -x option is given. 5447 5448@table @code 5449... 5450@item Df n\n 5451Set the shade of gray to be used for filling solid objects to n; n must 5452be an integer between 0 and 1000, where 0 corresponds solid white and 54531000 to solid black, and values in between correspond to intermediate 5454shades of gray. This applies only to solid circles, solid ellipses and 5455solid polygons. By default, a level of 1000 will be used. Whatever 5456color a solid object has, it should completely obscure everything 5457beneath it. A value greater than 1000 or less than 0 can also be used: 5458this means fill with the shade of gray that is currently being used for 5459lines and text. Normally this will be black, but some drivers may 5460provide a way of changing this. 5461@item DC d\n 5462Draw a solid circle with a diameter of d with the leftmost point at the 5463current position. 5464@item DE dx dy\n 5465Draw a solid ellipse with a horizontal diameter of dx and a vertical 5466diameter of dy with the leftmost point at the current position. 5467@item Dp $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub 5468n$\n 5469Draw a polygon with, for $i = 1 ,..., n+1$, the i-th vertex at the 5470current position $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. At 5471the moment, GNU pic only uses this command to generate triangles and 5472rectangles. 5473@item DP $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub 5474n$\n 5475Like Dp but draw a solid rather than outlined polygon. 5476@item Dt n\n 5477Set the current line thickness to n machine units. Traditionally @sc{Unix} 5478troff drivers use a line thickness proportional to the current point 5479size; drivers should continue to do this if no Dt command has been 5480given, or if a Dt command has been given with a negative value of n. A 5481zero value of n selects the smallest available line thickness. 5482@end table 5483 5484A difficulty arises in how the current position should be changed after 5485the execution of these commands. This is not of great importance since 5486the code generated by GNU pic does not depend on this. Given a drawing 5487command of the form 5488 5489\D'c $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$' 5490 5491where c is not one of c, e, l, a or ~, @sc{Unix} troff will treat each of the 5492$x sub i$ as a horizontal quantity, and each of the $y sub i$ as a 5493vertical quantity and will assume that the width of the drawn object is 5494$sum from i=1 to n x sub i$, and that the height is $sum from i=1 to n y 5495sub i$. (The assumption about the height can be seen by examining the 5496st and sb registers after using such a D command in a \w escape 5497sequence.) This rule also holds for all the original drawing commands 5498with the exception of De. For the sake of compatibility GNU troff also 5499follows this rule, even though it produces an ugly result in the case of 5500the Df, Dt, and, to a lesser extent, DE commands. Thus after executing 5501a D command of the form 5502 5503Dc $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\n 5504 5505the current position should be increased by $( sum from i=1 to n x sub i 5506, sum from i=1 to n y sub i )$. 5507 5508@subsection Line Continuation 5509 5510There is a continuation convention which permits the argument to the x X 5511command to contain newlines: when outputting the argument to the x X 5512command, GNU troff will follow each newline in the argument with a + 5513character (as usual, it will terminate the entire argument with a 5514newline); thus if the line after the line containing the x X command 5515starts with +, then the newline ending the line containing the x X 5516command should be treated as part of the argument to the x X command, 5517the + should be ignored, and the part of the line following the + should 5518be treated like the part of the line following the x X command. 5519 5520 5521 5522 5523@node Font Files, , gtroff Output, File formats 5524@section Font Files 5525@cindex font files 5526@cindex files, font 5527 5528 5529The groff font format is roughly a superset of the ditroff font 5530format. Unlike the ditroff font format, there is no associated binary 5531format. The font files for device name are stored in a directory 5532@file{dev@var{name}}. There are two types of file: a device 5533description file called @file{DESC} and for each font @samp{F} a font 5534file called @file{F}. These are text files; there is no associated 5535binary format. 5536 5537@subsection @file{DESC} file format 5538@pindex DESC 5539 5540The @file{DESC} file can contain the following types of line: 5541 5542@table @code 5543@item res @var{n} 5544There are @var{n} machine units per inch. 5545@item hor @var{n} 5546The horizontal resolution is @var{n} machine units. 5547@item vert @var{n} 5548The vertical resolution is @var{n} machine units. 5549@item sizescale @var{n} 5550The scale factor for pointsizes. By default this has a value of 1. One 5551scaled point is equal to one point/@var{n}. The arguments to the 5552@code{unitwidth} and @code{sizes} commands are given in scaled points. 5553@xref{Fractional Type Sizes}, for more information. 5554@item unitwidth @var{n} 5555Quantities in the font files are given in machine units for fonts whose 5556point size is @var{n} scaled points. 5557@item tcommand 5558This means that the postprocessor can handle the @code{t} and 5559@code{u} output commands. 5560@item sizes @var{s1} @var{s2}@dots{}@var{sn} 0 5561This means that the device has fonts at @var{s1}, @var{s2}, 5562@dots{}@var{sn} scaled points. The list of sizes must be terminated 5563by a 0. Each @var{si} can also be a range of 5564sizes @var{m}-@var{n}. The list can extend over more than one line. 5565@item styles @var{S1 S2@dots{}Sm} 5566The first @var{m} font positions will be associated with styles 5567@var{S1}@dots{}@var{Sm}. 5568@item fonts @var{n} @var{F1 F2 F3@dots{}Fn} 5569Fonts @var{F1@dots{}Fn} will be mounted in the font positions 5570@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} 5571is the number of styles. This command may extend over more than one 5572line. A font name of 0 will cause no font to be mounted on the 5573corresponding font position. 5574@item family @var{fam} 5575The default font family is @var{fam}. 5576@item charset 5577This line and everything following in the file are ignored. It is 5578allowed for the sake of backwards compatibility. 5579@end table 5580 5581The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines 5582are compulsory. Other commands are ignored by troff but may be used 5583by postprocessors to store arbitrary information about the device in 5584the @file{DESC} file. 5585 5586 5587@subsection Font file format 5588 5589A font file has two sections. The first section is a sequence of lines 5590each containing a sequence of blank delimited words; the first word in 5591the line is a key, and subsequent words give a value for that key. 5592 5593@table @code 5594@item name @var{F} 5595The name of the font is @var{F}. 5596@item spacewidth @var{n} 5597The normal width of a space is @var{n}. 5598@item slant @var{n} 5599The characters of the font have a slant of @var{n} degrees. 5600(Positive means forward.) 5601@item ligatures @var{lig1} @var{lig2}@dots{}@var{lign} [0] 5602Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 5603possible ligatures are ff, fi, fl and ffl. For backwards 5604compatibiliy, the list of ligatures may be terminated with a 0. The 5605list of ligatures may not extend over more than one line. 5606@item special 5607The font is special; this means that when a character is requested that 5608is not present in the current font, it will be searched for in any 5609special fonts that are mounted. 5610@end table 5611 5612Other commands are ignored by troff but may be used by postprocessors to 5613store arbitrary information about the font in the font file. 5614 5615The first section can contain comments which start with the # character 5616and extend to the end of a line. 5617 5618The second section contains one or two subsections. It must contain a 5619@code{charset} subsection and it may also contain a @code{kernpairs} 5620subsection. These subsections can appear in any order. Each 5621subsection starts with a word on a line by itself. 5622 5623The word @code{charset} starts the @code{charset} subsection. The 5624@code{charset} line is followed by a sequence of lines. Each line 5625gives information for one character. A line comprises a number of 5626fields separated by blanks or tabs. The format is 5627 5628@display 5629@var{name} @var{metrics} @var{type} @var{code} @var{comment} 5630@end display 5631 5632@var{name} identifies the character: if @var{name} is a single 5633character @var{c} then it corresponds to the groff input character 5634@var{c}; if it is of the form @samp{\@var{c}} where @var{c} is a 5635single character, then it corresponds to the groff input character 5636@samp{\@var{c}}; otherwise it corresponds to the groff input character 5637@samp{\[@var{name}]} (if it is exactly two characters @var{xx} it can 5638be entered as @samp{\(@var{xx}}.) Groff supports eight bit characters; 5639however some utilities has difficulties with eight bit characters. 5640For this reason, there is a convention that the @var{name} 5641@samp{char@var{n}} is equivalent to the single character whose code is 5642@var{n}. For example, @samp{char163} would be equivalent to the 5643character with @var{code} 163 which is the pounds sterling sign in ISO 5644Latin-1 character set. The name @samp{---} is special and indicates 5645that the character is unnamed; such characters can only be used by 5646means of the @code{\N} escape sequence in troff. 5647 5648The @var{type} field gives the character type: 5649 5650@table @code 5651@item 1 5652means the character has an descender, for example, p; 5653@item 2 5654means the character has an ascender, for example, b; 5655@item 3 5656means the character has both an ascender and a descender, for example, 5657@samp{(}. 5658@end table 5659 5660The @var{code} field gives the code which the postprocessor uses to 5661print the character. The character can also be input to groff using 5662this code by means of the @code{\N} escape sequence. The code can be any 5663integer. If it starts with a 0 it will be interpreted as octal; if it 5664starts with 0x or 0X it will be intepreted as hexdecimal. 5665 5666Anything on the line after the @var{code} field will be ignored. 5667 5668The @var{metrics} field has the form: 5669 5670@smallexample 5671@var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]} 5672@end smallexample 5673 5674There must not be any spaces between these subfields. Missing 5675subfields are assumed to be 0. The subfields are all decimal 5676integers. Since there is no associated binary format, these values 5677are not required to fit into a variable of type @samp{char} as they 5678are in ditroff. The @var{width} subfields gives the width of the 5679character. The @var{height} subfield gives the height of the 5680character (upwards is positive); if a character does not extend above 5681the baseline, it should be given a zero height, rather than a negative 5682height. The @var{depth} subfield gives the depth of the character, 5683that is, the distance below the lowest point below the baseline to 5684which the character extends (downwards is positive); if a character 5685does not extend below above the baseline, it should be given a zero 5686depth, rather than a negative depth. The @var{italic_correction} 5687subfield gives the amount of space that should be added after the 5688character when it is immediately to be followed by a character from a 5689roman font. The @var{left_italic_correction} subfield gives the 5690amount of space that should be added before the character when it is 5691immediately to be preceded by a character from a roman font. The 5692@var{subscript_correction} gives the amount of space that should be 5693added after a character before adding a subscript. This should be less 5694than the italic correction. 5695 5696A line in the @code{charset} section can also have the format 5697 5698@example 5699@var{name} " 5700@end example 5701 5702This indicates that @var{name} is just another name for the character 5703mentioned in the preceding line. 5704 5705The word @code{kernpairs} starts the kernpairs section. This contains a 5706sequence of lines of the form: 5707 5708@display 5709@var{c1 c2 n} 5710@end display 5711 5712This means that when character @var{c1} appears next to character 5713@var{c2} the space between them should be increased by @var{n}. Most 5714entries in kernpairs section will have a negative value for @var{n}. 5715 5716 5717 5718@node Installation, Request Index, File formats, Top 5719@chapter Installation 5720@cindex installation 5721 5722 5723 5724@node Request Index, Register Index, Installation, Top 5725@chapter Request Index 5726 5727@printindex fn 5728 5729 5730@node Register Index, String Index, Request Index, Top 5731@chapter Register Index 5732 5733@printindex vr 5734 5735 5736@node String Index, Macro Index, Register Index, Top 5737@chapter String Index 5738 5739 5740 5741@node Macro Index, Program Index, String Index, Top 5742@chapter Macro Index 5743 5744 5745 5746@node Program Index, Concept Index, Macro Index, Top 5747@chapter Program Index 5748 5749@printindex pg 5750 5751 5752 5753@node Concept Index, , Program Index, Top 5754@chapter Concept Index 5755 5756@printindex cp 5757 5758 5759 5760@summarycontents 5761@contents 5762@bye 5763