groff.texinfo revision 55839
155839Sasmodai\input texinfo @c -*-texinfo-*- 255839Sasmodai@c %**start of header (This is for running Texinfo on a region.) 355839Sasmodai@setfilename groff 455839Sasmodai@settitle The GNU Troff Manual 555839Sasmodai@setchapternewpage odd 655839Sasmodai@footnotestyle separate 755839Sasmodai@c %**end of header (This is for running Texinfo on a region.) 855839Sasmodai 955839Sasmodai 1055839Sasmodai@dircategory Miscellaneous 1155839Sasmodai@direntry 1255839Sasmodai* Groff: (groff). The GNU troff document formatting system. 1355839Sasmodai@end direntry 1455839Sasmodai 1555839Sasmodai 1655839Sasmodai@smallbook 1755839Sasmodai 1855839Sasmodai 1955839Sasmodai@iftex 2055839Sasmodai@finalout 2155839Sasmodai@end iftex 2255839Sasmodai 2355839Sasmodai 2455839Sasmodai@ifinfo 2555839SasmodaiThis Info file documents GNU troff version 1.12. 2655839Sasmodai 2755839SasmodaiPublished by the Free Software Foundation 2855839Sasmodai59 Temple Place, Suite 330 2955839SasmodaiBoston, MA 02111-1307 USA 3055839Sasmodai 3155839SasmodaiCopyright (C) 1994, 1999 Free Software Foundation, Inc. 3255839Sasmodai 3355839SasmodaiPermission is granted to make and distribute verbatim copies of this 3455839Sasmodaimanual provided the copyright notice and this permission notice are 3555839Sasmodaipreserved on all copies. 3655839Sasmodai 3755839Sasmodai@ignore 3855839SasmodaiPermission is granted to process this file through TeX and print the 3955839Sasmodairesults, provided the printed document carries copying permission notice 4055839Sasmodaiidentical to this one except for the removal of this paragraph (this 4155839Sasmodaiparagraph not being relevant to the printed manual). 4255839Sasmodai 4355839Sasmodai@end ignore 4455839SasmodaiPermission is granted to copy and distribute modified versions of this 4555839Sasmodaimanual under the conditions for verbatim copying, provided that the 4655839Sasmodaientire resulting derived work is distributed under the terms of a 4755839Sasmodaipermission notice identical to this one. 4855839Sasmodai 4955839SasmodaiPermission is granted to copy and distribute translations of this manual 5055839Sasmodaiinto another language, under the above conditions for modified versions, 5155839Sasmodaiexcept that this permission notice may be stated in a translation 5255839Sasmodaiapproved by the Foundation. 5355839Sasmodai 5455839SasmodaiPermission is granted to copy and distribute modified versions of this 5555839Sasmodaimanual under the conditions for verbatim copying, provided also that the 5655839Sasmodaisection entitled ``GNU General Public License'' is included exactly as 5755839Sasmodaiin the original, and provided that the entire resulting derived work is 5855839Sasmodaidistributed under the terms of a permission notice identical to this 5955839Sasmodaione. 6055839Sasmodai 6155839SasmodaiPermission is granted to copy and distribute translations of this manual 6255839Sasmodaiinto another language, under the above conditions for modified versions, 6355839Sasmodaiexcept that the section entitled ``GNU General Public License'' may be 6455839Sasmodaiincluded in a translation approved by the Free Software Foundation 6555839Sasmodaiinstead of in the original English. 6655839Sasmodai@end ifinfo 6755839Sasmodai 6855839Sasmodai 6955839Sasmodai@titlepage 7055839Sasmodai@title groff 7155839Sasmodai@subtitle The GNU implementation of @code{groff} 7255839Sasmodai@subtitle Edition 1.12 7355839Sasmodai@subtitle October 1999 7455839Sasmodai@author by Trent A.@w{ }Fisher 7555839Sasmodai@author and the maintainer of groff 7655839Sasmodai 7755839Sasmodai@c Include the Distribution inside the titlepage environment so 7855839Sasmodai@c that headings are turned off. Headings on and off do not work. 7955839Sasmodai 8055839Sasmodai@page 8155839Sasmodai@vskip 0pt plus 1filll 8255839SasmodaiCopyright @copyright{} 1994, 1999 Free Software Foundation, Inc. 8355839Sasmodai 8455839Sasmodai@sp 2 8555839SasmodaiVersion 1.13 of @code{groff}, @* 8655839SasmodaiOctober 1999 8755839Sasmodai@sp 2 8855839SasmodaiPublished by the Free Software Foundation @* 8955839Sasmodai59 Temple Place, Suite 330 @* 9055839SasmodaiBoston, MA 02111-1307 USA 9155839Sasmodai 9255839Sasmodai 9355839SasmodaiPermission is granted to make and distribute verbatim copies of this 9455839Sasmodaimanual provided the copyright notice and this permission notice are 9555839Sasmodaipreserved on all copies. 9655839Sasmodai 9755839SasmodaiPermission is granted to copy and distribute modified versions of this 9855839Sasmodaimanual under the conditions for verbatim copying, provided also that the 9955839Sasmodaisection entitled ``GNU General Public License'' is included 10055839Sasmodaiexactly as in the original, and provided that the entire resulting 10155839Sasmodaiderived work is distributed under the terms of a permission notice 10255839Sasmodaiidentical to this one. 10355839Sasmodai 10455839SasmodaiPermission is granted to copy and distribute translations of this manual 10555839Sasmodaiinto another language, under the above conditions for modified versions, 10655839Sasmodaiexcept that the section entitled ``GNU General Public License'' may be 10755839Sasmodaiincluded in a translation approved by the Free Software Foundation 10855839Sasmodaiinstead of in the original English. 10955839Sasmodai 11055839SasmodaiCover art by Etienne Suvasa. 11155839Sasmodai@end titlepage 11255839Sasmodai@page 11355839Sasmodai 11455839Sasmodai 11555839Sasmodai 11655839Sasmodai@node Top, Copying, (dir), (dir) 11755839Sasmodai 11855839Sasmodai@ifinfo 11955839SasmodaiThis Info file documents groff version 1.13, the GNU implementation of 12055839Sasmodaithe troff typesetting system. 12155839Sasmodai 12255839SasmodaiThis is an in-progress document; contributions, comments, or 12355839Sasmodaicontributions are welcome. Send them to bug-groff@@gnu.org. 12455839Sasmodai@end ifinfo 12555839Sasmodai 12655839Sasmodai@menu 12755839Sasmodai* Copying:: 12855839Sasmodai* Introduction:: 12955839Sasmodai* Invoking groff:: 13055839Sasmodai* Tutorial for Macro Users:: 13155839Sasmodai* -man:: 13255839Sasmodai* -ms:: 13355839Sasmodai* -me:: 13455839Sasmodai* -mm:: 13555839Sasmodai* Programming Tutorial:: 13655839Sasmodai* geqn:: 13755839Sasmodai* gtbl:: 13855839Sasmodai* gpic:: 13955839Sasmodai* grap:: 14055839Sasmodai* grefer:: 14155839Sasmodai* gsoelim:: 14255839Sasmodai* Devices:: 14355839Sasmodai* File formats:: 14455839Sasmodai* Installation:: 14555839Sasmodai* Request Index:: 14655839Sasmodai* Register Index:: 14755839Sasmodai* String Index:: 14855839Sasmodai* Macro Index:: 14955839Sasmodai* Program Index:: 15055839Sasmodai* Concept Index:: 15155839Sasmodai@end menu 15255839Sasmodai 15355839Sasmodai 15455839Sasmodai 15555839Sasmodai@node Copying, Introduction, Top, Top 15655839Sasmodai@cindex copying 15755839Sasmodai@unnumbered GNU GENERAL PUBLIC LICENSE 15855839Sasmodai@center Version 2, June 1991 15955839Sasmodai 16055839Sasmodai@display 16155839SasmodaiCopyright @copyright{} 1989, 1991 Free Software Foundation, Inc. 16255839Sasmodai59 Temple Place, Suite 330, Boston, MA 02111, USA 16355839Sasmodai 16455839SasmodaiEveryone is permitted to copy and distribute verbatim copies of this 16555839Sasmodailicense document, but changing it is not allowed. 16655839Sasmodai@end display 16755839Sasmodai 16855839Sasmodai@unnumberedsec Preamble 16955839Sasmodai 17055839SasmodaiThe licenses for most software are designed to take away your freedom to 17155839Sasmodaishare and change it. By contrast, the GNU General Public License is 17255839Sasmodaiintended to guarantee your freedom to share and change free software -- 17355839Sasmodaito make sure the software is free for all its users. This General 17455839SasmodaiPublic License applies to most of the Free Software Foundation's 17555839Sasmodaisoftware and to any other program whose authors commit to using it. 17655839Sasmodai(Some other Free Software Foundation software is covered by the GNU 17755839SasmodaiLibrary General Public License instead.) You can apply it to your 17855839Sasmodaiprograms, too. 17955839Sasmodai 18055839SasmodaiWhen we speak of free software, we are referring to freedom, not price. 18155839SasmodaiOur General Public Licenses are designed to make sure that you have the 18255839Sasmodaifreedom to distribute copies of free software (and charge for this 18355839Sasmodaiservice if you wish), that you receive source code or can get it if you 18455839Sasmodaiwant it, that you can change the software or use pieces of it in new 18555839Sasmodaifree programs; and that you know you can do these things. 18655839Sasmodai 18755839SasmodaiTo protect your rights, we need to make restrictions that forbid anyone 18855839Sasmodaito deny you these rights or to ask you to surrender the rights. These 18955839Sasmodairestrictions translate to certain responsibilities for you if you 19055839Sasmodaidistribute copies of the software, or if you modify it. 19155839Sasmodai 19255839SasmodaiFor example, if you distribute copies of such a program, whether gratis 19355839Sasmodaior for a fee, you must give the recipients all the rights that you have. 19455839SasmodaiYou must make sure that they, too, receive or can get the source code. 19555839SasmodaiAnd you must show them these terms so they know their rights. 19655839Sasmodai 19755839SasmodaiWe protect your rights with two steps: (1)@w{ }copyright the software, 19855839Sasmodaiand (2)@w{ }offer you this license which gives you legal permission to 19955839Sasmodaicopy, distribute and/or modify the software. 20055839Sasmodai 20155839SasmodaiAlso, for each author's protection and ours, we want to make certain 20255839Sasmodaithat everyone understands that there is no warranty for this free 20355839Sasmodaisoftware. If the software is modified by someone else and passed on, we 20455839Sasmodaiwant its recipients to know that what they have is not the original, so 20555839Sasmodaithat any problems introduced by others will not reflect on the original 20655839Sasmodaiauthors' reputations. 20755839Sasmodai 20855839SasmodaiFinally, any free program is threatened constantly by software patents. 20955839SasmodaiWe wish to avoid the danger that redistributors of a free program will 21055839Sasmodaiindividually obtain patent licenses, in effect making the program 21155839Sasmodaiproprietary. To prevent this, we have made it clear that any patent 21255839Sasmodaimust be licensed for everyone's free use or not licensed at all. 21355839Sasmodai 21455839SasmodaiThe precise terms and conditions for copying, distribution and 21555839Sasmodaimodification follow. 21655839Sasmodai 21755839Sasmodai@iftex 21855839Sasmodai@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 21955839Sasmodai@end iftex 22055839Sasmodai@ifinfo 22155839Sasmodai@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 22255839Sasmodai@end ifinfo 22355839Sasmodai 22455839Sasmodai@enumerate 0 22555839Sasmodai@item 22655839SasmodaiThis License applies to any program or other work which contains a 22755839Sasmodainotice placed by the copyright holder saying it may be distributed under 22855839Sasmodaithe terms of this General Public License. The ``Program'', below, 22955839Sasmodairefers to any such program or work, and a ``work based on the Program'' 23055839Sasmodaimeans either the Program or any derivative work under copyright law: 23155839Sasmodaithat is to say, a work containing the Program or a portion of it, either 23255839Sasmodaiverbatim or with modifications and/or translated into another language. 23355839Sasmodai(Hereinafter, translation is included without limitation in the term 23455839Sasmodai``modification''.) Each licensee is addressed as ``you''. 23555839Sasmodai 23655839SasmodaiActivities other than copying, distribution and modification are not 23755839Sasmodaicovered by this License; they are outside its scope. The act of running 23855839Sasmodaithe Program is not restricted, and the output from the Program is 23955839Sasmodaicovered only if its contents constitute a work based on the Program 24055839Sasmodai(independent of having been made by running the Program). Whether that 24155839Sasmodaiis true depends on what the Program does. 24255839Sasmodai 24355839Sasmodai@item 24455839SasmodaiYou may copy and distribute verbatim copies of the Program's source code 24555839Sasmodaias you receive it, in any medium, provided that you conspicuously and 24655839Sasmodaiappropriately publish on each copy an appropriate copyright notice and 24755839Sasmodaidisclaimer of warranty; keep intact all the notices that refer to this 24855839SasmodaiLicense and to the absence of any warranty; and give any other 24955839Sasmodairecipients of the Program a copy of this License along with the Program. 25055839Sasmodai 25155839SasmodaiYou may charge a fee for the physical act of transferring a copy, and 25255839Sasmodaiyou may at your option offer warranty protection in exchange for a fee. 25355839Sasmodai 25455839Sasmodai@item 25555839SasmodaiYou may modify your copy or copies of the Program or any portion of it, 25655839Sasmodaithus forming a work based on the Program, and copy and distribute such 25755839Sasmodaimodifications or work under the terms of Section@w{ }1 above, provided 25855839Sasmodaithat you also meet all of these conditions: 25955839Sasmodai 26055839Sasmodai@enumerate a 26155839Sasmodai@item 26255839SasmodaiYou must cause the modified files to carry prominent notices stating 26355839Sasmodaithat you changed the files and the date of any change. 26455839Sasmodai 26555839Sasmodai@item 26655839SasmodaiYou must cause any work that you distribute or publish, that in whole or 26755839Sasmodaiin part contains or is derived from the Program or any part thereof, to 26855839Sasmodaibe licensed as a whole at no charge to all third parties under the terms 26955839Sasmodaiof this License. 27055839Sasmodai 27155839Sasmodai@item 27255839SasmodaiIf the modified program normally reads commands interactively when run, 27355839Sasmodaiyou must cause it, when started running for such interactive use in the 27455839Sasmodaimost ordinary way, to print or display an announcement including an 27555839Sasmodaiappropriate copyright notice and a notice that there is no warranty (or 27655839Sasmodaielse, saying that you provide a warranty) and that users may 27755839Sasmodairedistribute the program under these conditions, and telling the user 27855839Sasmodaihow to view a copy of this License. (Exception: if the Program itself 27955839Sasmodaiis interactive but does not normally print such an announcement, your 28055839Sasmodaiwork based on the Program is not required to print an announcement.) 28155839Sasmodai@end enumerate 28255839Sasmodai 28355839SasmodaiThese requirements apply to the modified work as a whole. If 28455839Sasmodaiidentifiable sections of that work are not derived from the Program, and 28555839Sasmodaican be reasonably considered independent and separate works in 28655839Sasmodaithemselves, then this License, and its terms, do not apply to those 28755839Sasmodaisections when you distribute them as separate works. But when you 28855839Sasmodaidistribute the same sections as part of a whole which is a work based on 28955839Sasmodaithe Program, the distribution of the whole must be on the terms of this 29055839SasmodaiLicense, whose permissions for other licensees extend to the entire 29155839Sasmodaiwhole, and thus to each and every part regardless of who wrote it. 29255839Sasmodai 29355839SasmodaiThus, it is not the intent of this section to claim rights or contest 29455839Sasmodaiyour rights to work written entirely by you; rather, the intent is to 29555839Sasmodaiexercise the right to control the distribution of derivative or 29655839Sasmodaicollective works based on the Program. 29755839Sasmodai 29855839SasmodaiIn addition, mere aggregation of another work not based on the Program 29955839Sasmodaiwith the Program (or with a work based on the Program) on a volume of a 30055839Sasmodaistorage or distribution medium does not bring the other work under the 30155839Sasmodaiscope of this License. 30255839Sasmodai 30355839Sasmodai@item 30455839SasmodaiYou may copy and distribute the Program (or a work based on it, under 30555839SasmodaiSection@w{ }2) in object code or executable form under the terms of 30655839SasmodaiSections 1 and 2 above provided that you also do one of the following: 30755839Sasmodai 30855839Sasmodai@enumerate a 30955839Sasmodai@item 31055839SasmodaiAccompany it with the complete corresponding machine-readable source 31155839Sasmodaicode, which must be distributed under the terms of Sections 1 and 2 31255839Sasmodaiabove on a medium customarily used for software interchange; or, 31355839Sasmodai 31455839Sasmodai@item 31555839SasmodaiAccompany it with a written offer, valid for at least three years, to 31655839Sasmodaigive any third party, for a charge no more than your cost of physically 31755839Sasmodaiperforming source distribution, a complete machine-readable copy of the 31855839Sasmodaicorresponding source code, to be distributed under the terms of Sections 31955839Sasmodai1 and 2 above on a medium customarily used for software interchange; or, 32055839Sasmodai 32155839Sasmodai@item 32255839SasmodaiAccompany it with the information you received as to the offer to 32355839Sasmodaidistribute corresponding source code. (This alternative is allowed only 32455839Sasmodaifor noncommercial distribution and only if you received the program in 32555839Sasmodaiobject code or executable form with such an offer, in accord with 32655839SasmodaiSubsection b above.) 32755839Sasmodai@end enumerate 32855839Sasmodai 32955839SasmodaiThe source code for a work means the preferred form of the work for 33055839Sasmodaimaking modifications to it. For an executable work, complete source 33155839Sasmodaicode means all the source code for all modules it contains, plus any 33255839Sasmodaiassociated interface definition files, plus the scripts used to control 33355839Sasmodaicompilation and installation of the executable. However, as a special 33455839Sasmodaiexception, the source code distributed need not include anything that is 33555839Sasmodainormally distributed (in either source or binary form) with the major 33655839Sasmodaicomponents (compiler, kernel, and so on) of the operating system on 33755839Sasmodaiwhich the executable runs, unless that component itself accompanies the 33855839Sasmodaiexecutable. 33955839Sasmodai 34055839SasmodaiIf distribution of executable or object code is made by offering access 34155839Sasmodaito copy from a designated place, then offering equivalent access to copy 34255839Sasmodaithe source code from the same place counts as distribution of the source 34355839Sasmodaicode, even though third parties are not compelled to copy the source 34455839Sasmodaialong with the object code. 34555839Sasmodai 34655839Sasmodai@item 34755839SasmodaiYou may not copy, modify, sublicense, or distribute the Program except 34855839Sasmodaias expressly provided under this License. Any attempt otherwise to 34955839Sasmodaicopy, modify, sublicense or distribute the Program is void, and will 35055839Sasmodaiautomatically terminate your rights under this License. However, 35155839Sasmodaiparties who have received copies, or rights, from you under this License 35255839Sasmodaiwill not have their licenses terminated so long as such parties remain 35355839Sasmodaiin full compliance. 35455839Sasmodai 35555839Sasmodai@item 35655839SasmodaiYou are not required to accept this License, since you have not signed 35755839Sasmodaiit. However, nothing else grants you permission to modify or distribute 35855839Sasmodaithe Program or its derivative works. These actions are prohibited by 35955839Sasmodailaw if you do not accept this License. Therefore, by modifying or 36055839Sasmodaidistributing the Program (or any work based on the Program), you 36155839Sasmodaiindicate your acceptance of this License to do so, and all its terms and 36255839Sasmodaiconditions for copying, distributing or modifying the Program or works 36355839Sasmodaibased on it. 36455839Sasmodai 36555839Sasmodai@item 36655839SasmodaiEach time you redistribute the Program (or any work based on the 36755839SasmodaiProgram), the recipient automatically receives a license from the 36855839Sasmodaioriginal licensor to copy, distribute or modify the Program subject to 36955839Sasmodaithese terms and conditions. You may not impose any further restrictions 37055839Sasmodaion the recipients' exercise of the rights granted herein. You are not 37155839Sasmodairesponsible for enforcing compliance by third parties to this License. 37255839Sasmodai 37355839Sasmodai@item 37455839SasmodaiIf, as a consequence of a court judgment or allegation of patent 37555839Sasmodaiinfringement or for any other reason (not limited to patent issues), 37655839Sasmodaiconditions are imposed on you (whether by court order, agreement or 37755839Sasmodaiotherwise) that contradict the conditions of this License, they do not 37855839Sasmodaiexcuse you from the conditions of this License. If you cannot 37955839Sasmodaidistribute so as to satisfy simultaneously your obligations under this 38055839SasmodaiLicense and any other pertinent obligations, then as a consequence you 38155839Sasmodaimay not distribute the Program at all. For example, if a patent license 38255839Sasmodaiwould not permit royalty-free redistribution of the Program by all those 38355839Sasmodaiwho receive copies directly or indirectly through you, then the only way 38455839Sasmodaiyou could satisfy both it and this License would be to refrain entirely 38555839Sasmodaifrom distribution of the Program. 38655839Sasmodai 38755839SasmodaiIf any portion of this section is held invalid or unenforceable under 38855839Sasmodaiany particular circumstance, the balance of the section is intended to 38955839Sasmodaiapply and the section as a whole is intended to apply in other 39055839Sasmodaicircumstances. 39155839Sasmodai 39255839SasmodaiIt is not the purpose of this section to induce you to infringe any 39355839Sasmodaipatents or other property right claims or to contest validity of any 39455839Sasmodaisuch claims; this section has the sole purpose of protecting the 39555839Sasmodaiintegrity of the free software distribution system, which is implemented 39655839Sasmodaiby public license practices. Many people have made generous 39755839Sasmodaicontributions to the wide range of software distributed through that 39855839Sasmodaisystem in reliance on consistent application of that system; it is up to 39955839Sasmodaithe author/donor to decide if he or she is willing to distribute 40055839Sasmodaisoftware through any other system and a licensee cannot impose that 40155839Sasmodaichoice. 40255839Sasmodai 40355839SasmodaiThis section is intended to make thoroughly clear what is believed to be 40455839Sasmodaia consequence of the rest of this License. 40555839Sasmodai 40655839Sasmodai@item 40755839SasmodaiIf the distribution and/or use of the Program is restricted in certain 40855839Sasmodaicountries either by patents or by copyrighted interfaces, the original 40955839Sasmodaicopyright holder who places the Program under this License may add an 41055839Sasmodaiexplicit geographical distribution limitation excluding those countries, 41155839Sasmodaiso that distribution is permitted only in or among countries not thus 41255839Sasmodaiexcluded. In such case, this License incorporates the limitation as if 41355839Sasmodaiwritten in the body of this License. 41455839Sasmodai 41555839Sasmodai@item 41655839SasmodaiThe Free Software Foundation may publish revised and/or new versions of 41755839Sasmodaithe General Public License from time to time. Such new versions will be 41855839Sasmodaisimilar in spirit to the present version, but may differ in detail to 41955839Sasmodaiaddress new problems or concerns. 42055839Sasmodai 42155839SasmodaiEach version is given a distinguishing version number. If the Program 42255839Sasmodaispecifies a version number of this License which applies to it and ``any 42355839Sasmodailater version'', you have the option of following the terms and 42455839Sasmodaiconditions either of that version or of any later version published by 42555839Sasmodaithe Free Software Foundation. If the Program does not specify a version 42655839Sasmodainumber of this License, you may choose any version ever published by the 42755839SasmodaiFree Software Foundation. 42855839Sasmodai 42955839Sasmodai@item 43055839SasmodaiIf you wish to incorporate parts of the Program into other free programs 43155839Sasmodaiwhose distribution conditions are different, write to the author to ask 43255839Sasmodaifor permission. For software which is copyrighted by the Free Software 43355839SasmodaiFoundation, write to the Free Software Foundation; we sometimes make 43455839Sasmodaiexceptions for this. Our decision will be guided by the two goals of 43555839Sasmodaipreserving the free status of all derivatives of our free software and 43655839Sasmodaiof promoting the sharing and reuse of software generally. 43755839Sasmodai 43855839Sasmodai@iftex 43955839Sasmodai@heading NO WARRANTY 44055839Sasmodai@end iftex 44155839Sasmodai@ifinfo 44255839Sasmodai@center NO WARRANTY 44355839Sasmodai@end ifinfo 44455839Sasmodai 44555839Sasmodai@item 44655839SasmodaiBECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR 44755839SasmodaiTHE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN 44855839SasmodaiOTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 44955839SasmodaiPROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER 45055839SasmodaiEXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 45155839SasmodaiWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. 45255839SasmodaiTHE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH 45355839SasmodaiYOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 45455839SasmodaiNECESSARY SERVICING, REPAIR OR CORRECTION. 45555839Sasmodai 45655839Sasmodai@item 45755839SasmodaiIN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 45855839SasmodaiWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 45955839SasmodaiREDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 46055839SasmodaiDAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL 46155839SasmodaiDAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM 46255839Sasmodai(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED 46355839SasmodaiINACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF 46455839SasmodaiTHE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR 46555839SasmodaiOTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 46655839Sasmodai@end enumerate 46755839Sasmodai 46855839Sasmodai@iftex 46955839Sasmodai@heading END OF TERMS AND CONDITIONS 47055839Sasmodai@end iftex 47155839Sasmodai@ifinfo 47255839Sasmodai@center END OF TERMS AND CONDITIONS 47355839Sasmodai@end ifinfo 47455839Sasmodai 47555839Sasmodai 47655839Sasmodai@page 47755839Sasmodai@unnumberedsec How to Apply These Terms to Your New Programs 47855839Sasmodai 47955839SasmodaiIf you develop a new program, and you want it to be of the greatest 48055839Sasmodaipossible use to the public, the best way to achieve this is to make it 48155839Sasmodaifree software which everyone can redistribute and change under these 48255839Sasmodaiterms. 48355839Sasmodai 48455839SasmodaiTo do so, attach the following notices to the program. It is safest to 48555839Sasmodaiattach them to the start of each source file to most effectively convey 48655839Sasmodaithe exclusion of warranty; and each file should have at least the 48755839Sasmodai``copyright'' line and a pointer to where the full notice is found. 48855839Sasmodai 48955839Sasmodai@smallexample 49055839Sasmodai@var{one line to give the program's name and an idea of what it does.} 49155839SasmodaiCopyright (C) 19@var{yy} @var{name of author} 49255839Sasmodai 49355839SasmodaiThis program is free software; you can redistribute it and/or modify it 49455839Sasmodaiunder the terms of the GNU General Public License as published by the 49555839SasmodaiFree Software Foundation; either version 2 of the License, or (at your 49655839Sasmodaioption) any later version. 49755839Sasmodai 49855839SasmodaiThis program is distributed in the hope that it will be useful, but 49955839SasmodaiWITHOUT ANY WARRANTY; without even the implied warranty of 50055839SasmodaiMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU 50155839SasmodaiGeneral Public License for more details. 50255839Sasmodai 50355839SasmodaiYou should have received a copy of the GNU General Public License along 50455839Sasmodaiwith this program; if not, write to the Free Software Foundation, Inc., 50555839Sasmodai59 Temple Place, Suite 330, Boston, MA 02111, USA. 50655839Sasmodai@end smallexample 50755839Sasmodai 50855839SasmodaiAlso add information on how to contact you by electronic and paper mail. 50955839Sasmodai 51055839SasmodaiIf the program is interactive, make it output a short notice like this 51155839Sasmodaiwhen it starts in an interactive mode: 51255839Sasmodai 51355839Sasmodai@smallexample 51455839SasmodaiGnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} 51555839SasmodaiGnomovision comes with ABSOLUTELY NO WARRANTY; for details type 51655839Sasmodai`show w'. This is free software, and you are welcome to redistribute it 51755839Sasmodaiunder certain conditions; type `show c' for details. 51855839Sasmodai@end smallexample 51955839Sasmodai 52055839SasmodaiThe hypothetical commands @samp{show w} and @samp{show c} should show 52155839Sasmodaithe appropriate parts of the General Public License. Of course, the 52255839Sasmodaicommands you use may be called something other than @samp{show w} and 52355839Sasmodai@samp{show c}; they could even be mouse-clicks or menu items---whatever 52455839Sasmodaisuits your program. 52555839Sasmodai 52655839SasmodaiYou should also get your employer (if you work as a programmer) or your 52755839Sasmodaischool, if any, to sign a ``copyright disclaimer'' for the program, if 52855839Sasmodainecessary. Here is a sample; alter the names: 52955839Sasmodai 53055839Sasmodai@smallexample 53155839Sasmodai@group 53255839SasmodaiYoyodyne, Inc., hereby disclaims all copyright 53355839Sasmodaiinterest in the program `Gnomovision' 53455839Sasmodai(which makes passes at compilers) written 53555839Sasmodaiby James Hacker. 53655839Sasmodai 53755839Sasmodai@var{signature of Ty Coon}, 1 April 1989 53855839SasmodaiTy Coon, President of Vice 53955839Sasmodai@end group 54055839Sasmodai@end smallexample 54155839Sasmodai 54255839SasmodaiThis General Public License does not permit incorporating your program 54355839Sasmodaiinto proprietary programs. If your program is a subroutine library, you 54455839Sasmodaimay consider it more useful to permit linking proprietary applications 54555839Sasmodaiwith the library. If this is what you want to do, use the GNU Library 54655839SasmodaiGeneral Public License instead of this License. 54755839Sasmodai 54855839Sasmodai 54955839Sasmodai 55055839Sasmodai@node Introduction, Invoking groff, Copying, Top 55155839Sasmodai@chapter Introduction 55255839Sasmodai@cindex introduction 55355839Sasmodai 55455839SasmodaiGNU @code{troff} (or @code{groff}) is a system for typesetting 55555839Sasmodaidocuments. @code{troff} is very flexible and has been in existence (and 55655839Sasmodaiuse) for about 3@w{ }decades. It is quite widespread and firmly 55755839Sasmodaientrenched in the @sc{Unix} community. 55855839Sasmodai 55955839Sasmodai 56055839Sasmodai 56155839Sasmodai@menu 56255839Sasmodai* What Is groff?:: 56355839Sasmodai* History:: 56455839Sasmodai* groff Capabilities:: 56555839Sasmodai* Macro Packages:: 56655839Sasmodai* Preprocessors:: 56755839Sasmodai* Postprocessors:: 56855839Sasmodai* Credits:: 56955839Sasmodai@end menu 57055839Sasmodai 57155839Sasmodai@node What Is groff?, History, Introduction, Introduction 57255839Sasmodai@section What Is @code{groff}? 57355839Sasmodai@cindex what is @code{groff}? 57455839Sasmodai@cindex @code{groff} -- what is it? 57555839Sasmodai 57655839Sasmodai 57755839Sasmodai@code{groff} is of an older generation of document preparation systems, 57855839Sasmodaiwhich operate more like compilers than the more recent interactive 57955839SasmodaiWYSIWYG @footnote{What You See Is What You Get} systems. @code{groff} 58055839Sasmodaiand its contemporary counterpart, @TeX{}, both work using a @dfn{batch} 58155839Sasmodaiparadigm: The input (or @dfn{source}) files are normal text files with 58255839Sasmodaiembedded formatting commands. These files can then be processed by 58355839Sasmodai@code{groff} to produce a typeset document on a variety of devices. 58455839Sasmodai 58555839SasmodaiLikewise, @code{groff} should not be confused with a @dfn{word 58655839Sasmodaiprocessor}, since that term connotes an integrated system which includes 58755839Sasmodaian editor and a text formatter. Also, many word processors follow the 58855839SasmodaiWYSIWYG paradigm which was discussed earlier. 58955839Sasmodai 59055839SasmodaiAlthough WYSIWYG systems may be easier to use, they have a number of 59155839Sasmodaidisadvantages compared to @code{troff}: 59255839Sasmodai 59355839Sasmodai@itemize @bullet{} 59455839Sasmodai@item 59555839SasmodaiThey must be used on a bitmapped display to do any operations on your 59655839Sasmodaidocument. 59755839Sasmodai@item 59855839SasmodaiMost of the WYSIWYG systems are either non-free or are not very 59955839Sasmodaiportable. 60055839Sasmodai@item 60155839Sasmodai@code{troff} is firmly entrenched in all @sc{Unix} systems. 60255839Sasmodai@item 60355839SasmodaiIt is difficult to have a wide range of capabilities available within 60455839Sasmodaithe confines of a GUI/window system. 60555839Sasmodai@item 60655839SasmodaiIt is more difficult to make global changes to a document. 60755839Sasmodai@end itemize 60855839Sasmodai 60955839Sasmodai@quotation 61055839Sasmodai``GUIs normally make it simple to accomplish simple actions and 61155839Sasmodaiimpossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 61255839Sasmodai@code{comp.unix.wizards}) 61355839Sasmodai@end quotation 61455839Sasmodai 61555839Sasmodai 61655839Sasmodai 61755839Sasmodai@node History, groff Capabilities, What Is groff?, Introduction 61855839Sasmodai@section History 61955839Sasmodai@cindex history 62055839Sasmodai 62155839Sasmodai@code{troff} can trace its origins back to a formatting program called 62255839Sasmodai@code{runoff} which ran on MIT's CTSS system. This name came from the 62355839Sasmodaicommon phrase of the time ``I'll run off a document.'' 62455839Sasmodai 62555839SasmodaiThe first version of @sc{Unix} was developed on a PDP-7 which was 62655839Sasmodaisitting around Bell Labs. In 1971 the developers wanted to get a PDP-11 62755839Sasmodaifor further work on the operating system. In order to justify the cost 62855839Sasmodaifor this system, they proposed that they would implement a document 62955839Sasmodaiformatting system for the AT&T patents division. This first formatting 63055839Sasmodaiprogram was a reimplementation of @code{runoff}. In accordance with 63155839Sasmodai@sc{Unix}'s penchant for abreviations, it was named @code{roff} (an 63255839Sasmodaiabreviation of @code{runoff}). 63355839Sasmodai 63455839SasmodaiWhen they needed a more flexible language, a new version of @code{roff} 63555839Sasmodaicalled @code{nroff} (Newer @code{roff}) was written. It had a much more 63655839Sasmodaicomplicated syntax, but provided the basis for all future versions. 63755839SasmodaiWhen they got a Graphic Systems CAT Phototypesetter, J.@w{ }F.@w{ 63855839Sasmodai}Ossanna wrote a version of @code{nroff} which would drive it. It was 63955839Sasmodaidubbed @code{troff} for typesetter @code{roff}, although many people 64055839Sasmodaihave speculated that it actually means Times @code{roff} because of 64155839Sasmodai@code{troff}'s use of the Times font family by default. As such, the 64255839Sasmodainame @code{troff} is pronounced t-roff rather than trough. 64355839Sasmodai 64455839SasmodaiWith @code{troff} came @code{nroff} (they were actually the same program 64555839Sasmodaiexcept for some @samp{#ifdefs}), which was for producing output for line 64655839Sasmodaiprinters and ascii terminals. It understood everything @code{troff} 64755839Sasmodaidid, and ignored the commands which were not aplicable (i.e.@: font 64855839Sasmodaichanges). 64955839Sasmodai 65055839SasmodaiSince there are several things which cannot be done easily in 65155839Sasmodai@code{troff}, work on several preprocessors began. These programs would 65255839Sasmodaitransform certain parts of a document into @code{troff}, which made a 65355839Sasmodaivery natural use of pipes in @sc{Unix}. 65455839Sasmodai 65555839SasmodaiThe @code{eqn} preprocessor allowed mathematical formul@ae{} to be 65655839Sasmodaispecified in a much simpler and more intuitive manner. @code{tbl} is a 65755839Sasmodaipreprocessor for formatting tables. The @code{refer} preprocessor (and 65855839Sasmodaithe similar program, @code{bib}) processes citations in a document 65955839Sasmodaiaccording to a bibliographic database. 66055839Sasmodai 66155839SasmodaiUnfortunately, Ossanna's @code{troff} was written in PDP-11 assembly 66255839Sasmodailanguage and produced output specifically for the CAT phototypesetter. 66355839SasmodaiHe rewrote it in C, although it was now 7000@w{ }lines of uncommented 66455839Sasmodaicode and still dependent on the CAT. As the CAT became less common, and 66555839Sasmodaiwas no longer supported by the manufacturer, the need to make it support 66655839Sasmodaiother devices became a priority. However, before this could be done, he 66755839Sasmodaiwas killed in an auto accident. 66855839Sasmodai 66955839Sasmodai@pindex ditroff 67055839SasmodaiSo, Brian Kernighan took on the task of rewriting @code{troff}. The 67155839Sasmodainewly rewritten version produced a device independent code which was 67255839Sasmodaivery easy for postprocessors to read and translate to the appropriate 67355839Sasmodaiprinter codes. Also, this new version of @code{troff} (called 67455839Sasmodai@code{ditroff}) had several extentions, which included drawing 67555839Sasmodaifunctions. 67655839Sasmodai 67755839SasmodaiDue to the additional abilities of the new version of @code{troff}, 67855839Sasmodaiseveral new preprocessors appeared. The @code{pic} preprocessor 67955839Sasmodaiprovides a wide range of drawing functions. Likewise the @code{ideal} 68055839Sasmodaipreprocessor did the same, although via a much different paradigm. The 68155839Sasmodai@code{grap} preprocessor took specifications for graphs, but, unlike 68255839Sasmodaiother preprocessors, produced @code{pic} code. 68355839Sasmodai 68455839SasmodaiJames Clark began work on a GNU implementation of @code{ditroff} in 68555839Sasmodaiearly@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released 68655839SasmodaiJune@w{ }1990. @code{groff} included 68755839Sasmodai 68855839Sasmodai@itemize @bullet{} 68955839Sasmodai@item 69055839SasmodaiA replacement for @code{ditroff} with many extentions. 69155839Sasmodai@item 69255839SasmodaiThe @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 69355839Sasmodai@item 69455839SasmodaiPostprocessors for ascii devices, PostScript, @TeX{} DVI, and X@w{ 69555839Sasmodai}windows. GNU @code{troff} also eliminated the need for a separate 69655839Sasmodai@code{nroff} program with a postprocessor which would produce ascii 69755839Sasmodaioutput. 69855839Sasmodai@item 69955839SasmodaiA version of the @code{-me} macros and an implementation of the 70055839Sasmodai@code{-man} macros. 70155839Sasmodai@end itemize 70255839Sasmodai 70355839SasmodaiAlso, a front-end was included which could construct the, sometimes 70455839Sasmodaipainfully long, pipelines required for all the post- and preprocessors. 70555839Sasmodai 70655839SasmodaiDevelopment of GNU @code{troff} progressed rapidly, and saw the 70755839Sasmodaiadditions of a replacement for @code{refer}, an implementation of the 70855839Sasmodai@code{-ms} and @code{-mm} macros, and a program to deduce how to format 70955839Sasmodaia document (@code{grog}). 71055839Sasmodai 71155839SasmodaiIt was declared a stable (i.e.@: non beta) package with the release of 71255839Sasmodaiversion@w{ }1.04 around November@w{ }1991. 71355839Sasmodai 71455839Sasmodai 71555839Sasmodai 71655839Sasmodai@node groff Capabilities, Macro Packages, History, Introduction 71755839Sasmodai@section @code{groff} Capabilities 71855839Sasmodai@cindex @code{groff} capabilities 71955839Sasmodai@cindex capabilities of @code{groff} 72055839Sasmodai 72155839SasmodaiSo what exactly is @code{groff} capable of doing? @code{groff} provides 72255839Sasmodaia wide range of low-level text formatting operations. Using these, you 72355839Sasmodaican perform a wide range of formatting tasks, such as footnotes, table 72455839Sasmodaiof contents, multiple columns, etc. 72555839Sasmodai 72655839Sasmodai@itemize @bullet{} 72755839Sasmodai@item 72855839SasmodaiText filling, adjusting, and centering 72955839Sasmodai@item 73055839SasmodaiHyphenation 73155839Sasmodai@item 73255839SasmodaiPage control 73355839Sasmodai@item 73455839SasmodaiFont and character size control 73555839Sasmodai@item 73655839SasmodaiVertical spacing (i.e.@: double spacing) 73755839Sasmodai@item 73855839SasmodaiLine length and indenting 73955839Sasmodai@item 74055839SasmodaiMacros, strings, diversions, and traps 74155839Sasmodai@item 74255839SasmodaiNumber registers 74355839Sasmodai@item 74455839SasmodaiTabs, leaders, and fields 74555839Sasmodai@item 74655839SasmodaiInput and output conventions and character translation 74755839Sasmodai@item 74855839SasmodaiOverstrike, bracket, line drawing, and zero-width functions 74955839Sasmodai@item 75055839SasmodaiLocal horizontal and vertical motions and the width function 75155839Sasmodai@item 75255839SasmodaiThree-part titles 75355839Sasmodai@item 75455839SasmodaiOutput line numbering 75555839Sasmodai@item 75655839SasmodaiConditional acceptance of input 75755839Sasmodai@item 75855839SasmodaiEnvironment switching 75955839Sasmodai@item 76055839SasmodaiInsertions from the standard input 76155839Sasmodai@item 76255839SasmodaiInput/output file switching 76355839Sasmodai@item 76455839SasmodaiOutput and error messages 76555839Sasmodai@end itemize 76655839Sasmodai 76755839Sasmodai 76855839Sasmodai@node Macro Packages, Preprocessors, groff Capabilities, Introduction 76955839Sasmodai@section Macro Packages 77055839Sasmodai@cindex macro packages 77155839Sasmodai 77255839SasmodaiSince @code{groff} provides such low level facilities, it can be quite 77355839Sasmodaidifficult to use by itself. However, @code{groff} provides a 77455839Sasmodai@dfn{macro} facility which allows you to specify how certain routine 77555839Sasmodaioperations (e.g.@w{ }starting paragraphs, printing headers and footers, 77655839Sasmodaietc.)@: should be done. These macros can be collected together into a 77755839Sasmodai@dfn{macro package}. There are a number of macro packages available; 77855839Sasmodaithe most common (and the ones described in this manual) are @code{-man}, 77955839Sasmodai@code{-me}, @code{-ms}, and @code{-mm}. 78055839Sasmodai 78155839Sasmodai 78255839Sasmodai@node Preprocessors, Postprocessors, Macro Packages, Introduction 78355839Sasmodai@section Preprocessors 78455839Sasmodai@cindex preprocessors 78555839Sasmodai 78655839SasmodaiAlthough @code{groff} provides most functions needed to format a 78755839Sasmodaidocument, some operations would be unwieldy (i.e.@: drawing pictures). 78855839SasmodaiTherefore, programs called preprocessors were written which understand 78955839Sasmodaitheir own language and produce the necessary groff operations. These 79055839Sasmodaipreprocessors are able to differentiate their own input from the rest of 79155839Sasmodaithe document via markers. 79255839Sasmodai 79355839SasmodaiTo use a preprocessor, @sc{Unix} pipes are used to feed the output from 79455839Sasmodaithe preprocessor into @code{groff}. Any number of preprocessors may be 79555839Sasmodaiused on a given document; in this case, the preprocessors are linked 79655839Sasmodaitogether into one pipeline. However, in @code{groff}, the user does not 79755839Sasmodaineed to construct the pipe, but only tell @code{groff} what 79855839Sasmodaipreprocessors to use. 79955839Sasmodai 80055839Sasmodai@code{groff} currently has preprocessors for producing tables 80155839Sasmodai(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 80255839Sasmodai(@code{pic}), and for processing bibliographies (@code{refer}). An 80355839Sasmodaiassociated program which is useful when dealing with preprocessors is 80455839Sasmodai@code{soelim}. 80555839Sasmodai 80655839SasmodaiThere are other preprocessors in existence, but there are, 80755839Sasmodaiunfortunately, no free implementations available. They are for drawing 80855839Sasmodaipictures (@code{ideal} and @code{gremlin}), for drawing graphs 80955839Sasmodai(@code{grap}), and chemical structures (@code{chem}). 81055839Sasmodai 81155839Sasmodai 81255839Sasmodai@node Postprocessors, Credits, Preprocessors, Introduction 81355839Sasmodai@section Postprocessors 81455839Sasmodai@cindex postprocessors 81555839Sasmodai 81655839Sasmodai@code{groff} actually produces device independent code which may be fed 81755839Sasmodaiinto a postprocessor which will produce output for a particular device. 81855839SasmodaiCurrently, @code{groff} has postprocessors for PostScript, ascii 81955839Sasmodaiterminals, X@w{ }windows (for previewing), @TeX{} DVI format, and HTML. 82055839Sasmodai 82155839Sasmodai 82255839Sasmodai@node Credits, , Postprocessors, Introduction 82355839Sasmodai@section Credits 82455839Sasmodai@cindex credits 82555839Sasmodai 82655839Sasmodai 82755839SasmodaiLarge portions of this manual were taken from existing documents, most 82855839Sasmodainotably, the manual pages for the @code{groff} package by James Clark, 82955839Sasmodaiand Eric Allman's papers on the @code{-me} macro package. 83055839Sasmodai 83155839Sasmodai 83255839Sasmodai 83355839Sasmodai@node Invoking groff, Tutorial for Macro Users, Introduction, Top 83455839Sasmodai@chapter Invoking @code{groff} 83555839Sasmodai@cindex invoking @code{groff} 83655839Sasmodai@cindex @code{groff} invocation 83755839Sasmodai 83855839Sasmodai 83955839Sasmodai@pindex groff 84055839Sasmodai@pindex gtroff 84155839SasmodaiThis section focuses on how to invoke the @code{groff} front end. This 84255839Sasmodaifront end takes care of the details of constructing the pipeline among 84355839Sasmodaithe preprocessors, @code{gtroff} and the postprocessor. 84455839Sasmodai 84555839SasmodaiIt has become a tradition that GNU programs get the prefix @dfn{g} to 84655839Sasmodaidistinguish it from its original counterparts provided by the host 84755839Sasmodai(@pxref{Environment}, for more details). Thus, for example, @code{geqn} 84855839Sasmodaiis GNU @code{eqn}. On operating systems like Linux or the Hurd, which 84955839Sasmodaidon't contain proprietary software, this prefix is omitted since GNU 85055839Sasmodai@code{troff} is the only used incarnation of @code{troff}. Exception: 85155839Sasmodai@code{groff} is never replaced by `roff'. 85255839Sasmodai 85355839Sasmodai 85455839Sasmodai@menu 85555839Sasmodai* Options:: 85655839Sasmodai* Environment:: 85755839Sasmodai* Invocation Examples:: 85855839Sasmodai@end menu 85955839Sasmodai 86055839Sasmodai@node Options, Environment, Invoking groff, Invoking groff 86155839Sasmodai@section Options 86255839Sasmodai@cindex options 86355839Sasmodai 86455839Sasmodai 86555839Sasmodai@pindex groff 86655839Sasmodai@pindex gtroff 86755839Sasmodai@pindex gpic 86855839Sasmodai@pindex geqn 86955839Sasmodai@pindex gtbl 87055839Sasmodai@pindex grefer 87155839Sasmodai@pindex gsoelim 87255839Sasmodai@code{groff} is a front-end to the groff document formatting system. 87355839SasmodaiNormally it runs the @code{gtroff} program and a postprocessor 87455839Sasmodaiappropriate for the selected device. The default device is @samp{ps}. 87555839SasmodaiIt can optionally preprocess with any of @code{gpic}, @code{geqn}, 87655839Sasmodai@code{gtbl}, @code{grefer}, or @code{gsoelim}. 87755839Sasmodai 87855839SasmodaiThis section only documents options to the @code{groff} front end. Many 87955839Sasmodaiof the arguments to @code{groff} are passed on to @code{gtroff}, 88055839Sasmodaitherefore those are also included. Arguments to pre- or postprocessors 88155839Sasmodaican be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 88255839Sasmodaigtbl}, @ref{Invoking grefer}, @ref{Invoking gsoelim}, @ref{Invoking 88355839Sasmodaigrotty}, @ref{Invoking grops}, @ref{Invoking grohtml}, @ref{Invoking 88455839Sasmodaigrodvi}, and @ref{Invoking gxditview} 88555839Sasmodai 88655839SasmodaiThe command line format for @code{groff} is: 88755839Sasmodai 88855839Sasmodai@example 88955839Sasmodaigroff [ -abehilpstvzCENRSVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 89055839Sasmodai [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 89155839Sasmodai [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 89255839Sasmodai [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] 89355839Sasmodai [ @var{files}@dots{} ] 89455839Sasmodai@end example 89555839Sasmodai 89655839SasmodaiThe command line format for @code{gtroff} is as follows. As you can 89755839Sasmodaisee, many of the options to @code{groff} are actually passed on to 89855839Sasmodai@code{gtroff}. 89955839Sasmodai 90055839Sasmodai@example 90155839Sasmodaigtroff [ -abivzCER ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 90255839Sasmodai [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 90355839Sasmodai [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 90455839Sasmodai [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 90555839Sasmodai@end example 90655839Sasmodai 90755839SasmodaiOptions without an argument can be grouped behind a single @samp{-}. A 90855839Sasmodaifilename of @samp{-} denotes the standard input. 90955839Sasmodai 91055839Sasmodai@pindex grog 91155839SasmodaiThe @code{grog} command can be used to guess the correct @code{groff} 91255839Sasmodaicommand to use to format a file. 91355839Sasmodai 91455839Sasmodai@table @samp 91555839Sasmodai@item -h 91655839SasmodaiPrint a help message. 91755839Sasmodai@item -e 91855839SasmodaiPreprocess with @code{geqn}. 91955839Sasmodai@item -t 92055839SasmodaiPreprocess with @code{gtbl}. 92155839Sasmodai@item -p 92255839SasmodaiPreprocess with @code{gpic}. 92355839Sasmodai@item -s 92455839SasmodaiPreprocess with @code{gsoelim}. 92555839Sasmodai@item -R 92655839SasmodaiPreprocess with @code{grefer}. No mechanism is provided for passing 92755839Sasmodaiarguments to @code{grefer} because most @code{grefer} options have 92855839Sasmodaiequivalent commands which can be included in the file. @xref{grefer}, 92955839Sasmodaifor more details. 93055839Sasmodai 93155839Sasmodai@pindex troffrc 93255839SasmodaiNote that @code{gtroff} also accepts a @samp{-R} option, which is not 93355839Sasmodaiaccessible via @code{groff}. This option prevents the loading of the 93455839Sasmodai@file{troffrc} file. 93555839Sasmodai@item -v 93655839SasmodaiMake programs run by @code{groff} print out their version number. 93755839Sasmodai@item -V 93855839SasmodaiPrint the pipeline on stdout instead of executing it. 93955839Sasmodai@item -z 94055839SasmodaiSuppress output from @code{gtroff}. Only error messages will be printed. 94155839Sasmodai@item -Z 94255839SasmodaiDo not postprocess the output of @code{gtroff}. Normally @code{groff} 94355839Sasmodaiwill automatically run the appropriate postprocessor. 94455839Sasmodai@item -P@var{arg} 94555839SasmodaiPass @var{arg} to the postprocessor. Each argument should be passed 94655839Sasmodaiwith a separate @samp{-P} option. Note that groff does not prepend 94755839Sasmodai@samp{-} to @var{arg} before passing it to the postprocessor. 94855839Sasmodai@item -l 94955839SasmodaiSend the output to a printer. The command used for this is specified by 95055839Sasmodaithe print command in the device description file. 95155839Sasmodai@item -L@var{arg} 95255839SasmodaiPass @var{arg} to the spooler. Each argument should be passed with a 95355839Sasmodaiseparate @samp{-L} option. Note that @code{groff} does not prepend a 95455839Sasmodai@samp{-} to @var{arg} before passing it to the postprocessor. 95555839Sasmodai@item -T@var{dev} 95655839SasmodaiPrepare output for device @var{dev}. The default device is @samp{ps}. 95755839SasmodaiThe following are the output devices currently available: 95855839Sasmodai@table @samp 95955839Sasmodai@item ps 96055839SasmodaiFor PostScript printers and previewers. 96155839Sasmodai@item dvi 96255839SasmodaiFor TeX dvi format. 96355839Sasmodai@item X75 96455839SasmodaiFor a 75 dpi X11 previewer. 96555839Sasmodai@item X100 96655839SasmodaiFor a 100dpi X11 previewer. 96755839Sasmodai@item ascii 96855839SasmodaiFor typewriter-like devices. 96955839Sasmodai@item latin1 97055839SasmodaiFor typewriter-like devices using the ISO Latin-1 character set. 97155839Sasmodai@item lj4 97255839SasmodaiFor an HP LaserJet4-compatible (or other PCL5-compatible) printer. 97355839Sasmodai@item html 97455839SasmodaiTo produce HTML output. 97555839Sasmodai@end table 97655839Sasmodai 97755839SasmodaiThe postprocessor to be used for a device is specified by the 97855839Sasmodai@code{postpro} command in the device description file. (@xref{Font 97955839SasmodaiFiles}, for more info.) This can be overridden with the @samp{-X} 98055839Sasmodaioption. 98155839Sasmodai@item -X 98255839SasmodaiPreview with @code{gxditview} instead of using the usual postprocessor. 98355839SasmodaiThis is unlikely to produce good results except with @samp{-Tps}. 98455839Sasmodai@item -N 98555839SasmodaiDon't allow newlines with @code{eqn} delimiters. This is the same as 98655839Sasmodaithe @samp{-N} option in @code{geqn}. 98755839Sasmodai@item -S 98855839SasmodaiSafer mode. Pass the @samp{-S} option to @code{gpic} and use the 98955839Sasmodai@samp{-msafer} macros with @code{gtroff}. 99055839Sasmodai@item -a 99155839SasmodaiGenerate an ASCII approximation of the typeset output. 99255839Sasmodai@item -b 99355839SasmodaiPrint a backtrace with each warning or error message. This backtrace 99455839Sasmodaishould help track down the cause of the error. The line numbers given 99555839Sasmodaiin the backtrace may not always be correct: @code{troff}'s idea of line 99655839Sasmodainumbers gets confused by @code{as} or @code{am} requests. 99755839Sasmodai@item -i 99855839SasmodaiRead the standard input after all the named input files have been 99955839Sasmodaiprocessed. 100055839Sasmodai@item -w@var{name} 100155839SasmodaiEnable warning @var{name}. Available warnings are described in 100255839Sasmodai@ref{Debugging}. Multiple @samp{-w} options are allowed. 100355839Sasmodai@item -W@var{name} 100455839SasmodaiInhibit warning @var{name}. Multiple @samp{-W} options are allowed. 100555839Sasmodai@item -E 100655839SasmodaiInhibit all error messages. 100755839Sasmodai@item -C 100855839SasmodaiEnable compatibility mode. 100955839Sasmodai@item -d@var{cs} 101055839Sasmodai@itemx -d@var{name}=s 101155839SasmodaiDefine @var{c} or @var{name} to be a string @var{s}; @var{c} must be a 101255839Sasmodaione-letter @var{name}. 101355839Sasmodai@item -f@var{fam} 101455839SasmodaiUse @var{fam} as the default font family. 101555839Sasmodai@item -m@var{name} 101655839SasmodaiRead in the file @file{tmac.@var{name}}. Normally this will be searched 101755839Sasmodaifor in @code{groff}'s lib directory. 101855839Sasmodai@item -n@var{num} 101955839SasmodaiNumber the first page @var{num}. 102055839Sasmodai@item -o@var{list} 102155839SasmodaiOutput only pages in @var{list}, which is a comma-separated list of page 102255839Sasmodairanges; @var{n} means print page @var{n}, @samp{@var{m}-@var{n}} means 102355839Sasmodaiprint every page between @var{m} and @var{n}, @samp{-@var{n}} means 102455839Sasmodaiprint every page up to @var{n}, @samp{@var{n}-} means print every page 102555839Sasmodaifrom @var{n}. @code{troff} will exit after printing the last page in 102655839Sasmodaithe list. 102755839Sasmodai@item -r@var{cn} 102855839Sasmodai@itemx -r@var{name}=@var{n} 102955839SasmodaiSet number register @var{c} or @var{name} to @var{n}; @var{c} must be a 103055839Sasmodaione-letter @var{name}; @var{n} can be any troff numeric expression. 103155839Sasmodai@item -F@var{dir} 103255839SasmodaiSearch @var{dir} for subdirectories dev@var{name} (@var{name} is the 103355839Sasmodainame of the device) for the @file{DESC} file and font files before the 103455839Sasmodainormal directory. 103555839Sasmodai@item -M@var{dir} 103655839SasmodaiSearch directory @var{dir} for macro files before the normal directory. 103755839Sasmodai@end table 103855839Sasmodai 103955839Sasmodai 104055839Sasmodai 104155839Sasmodai@node Environment, Invocation Examples, Options, Invoking groff 104255839Sasmodai@section Environment 104355839Sasmodai@cindex environment 104455839Sasmodai 104555839Sasmodai 104655839SasmodaiThere are also several environment variables which can modify groff's 104755839Sasmodaibehavior. 104855839Sasmodai 104955839Sasmodai@table @code 105055839Sasmodai@item GROFF_COMMAND_PREFIX 105155839SasmodaiIf this is set to @var{X}, then @code{groff} will run 105255839Sasmodai@var{X}@code{troff} instead of @code{gtroff}. This also applies to 105355839Sasmodai@code{tbl}, @code{pic}, @code{eqn}, @code{refer}, and @code{soelim}. It 105455839Sasmodaidoes not apply to @code{grops}, @code{grodvi}, @code{grotty}, 105555839Sasmodai@code{grohtml}, @code{grolj4}, and @code{gxditview}. 105655839Sasmodai@item GROFF_TMAC_PATH 105755839SasmodaiA colon separated list of directories in which to search for macro 105855839Sasmodaifiles. 105955839Sasmodai@item GROFF_TYPESETTER 106055839SasmodaiDefault device. 106155839Sasmodai@item GROFF_FONT_PATH 106255839SasmodaiA colon separated list of directories in which to search for the 106355839Sasmodai@code{dev}@var{name} directory. 106455839Sasmodai@item PATH 106555839SasmodaiThe search path for commands executed by groff. 106655839Sasmodai@item GROFF_TMPDIR 106755839SasmodaiThe directory in which temporary files will be created. If this is not 106855839Sasmodaiset and @code{TMPDIR} is set, temporary files will be created in that 106955839Sasmodaidirectory. Otherwise temporary files will be created in @code{/tmp}. 107055839SasmodaiThe @code{grops} and @code{grefer} commands can create temporary files. 107155839Sasmodai@end table 107255839Sasmodai 107355839Sasmodai 107455839Sasmodai@node Invocation Examples, , Environment, Invoking groff 107555839Sasmodai@section Invocation Examples 107655839Sasmodai@cindex invocation examples 107755839Sasmodai@cindex examples of invocation 107855839Sasmodai 107955839Sasmodai 108055839SasmodaiThis section will list several common uses of @code{groff} and the 108155839Sasmodaicommand line which will accomplish it. 108255839Sasmodai 108355839Sasmodai@example 108455839Sasmodaigroff file 108555839Sasmodaigroff -X -me file 108655839Sasmodaigroff -mm -rD1 -z file 108755839Sasmodaigroff -tps -me file | lpr -Plw2 108855839Sasmodai... any more?? ... 108955839Sasmodai@end example 109055839Sasmodai 109155839Sasmodai@subsection @code{grog} 109255839Sasmodai 109355839Sasmodai@code{grog} reads files and guesses which of the @code{groff} 109455839Sasmodaipreprocessors and/or macro packages are are required for formatting 109555839Sasmodaithem, and prints the @code{groff} command including those options on the 109655839Sasmodaistandard output. The options generated are one of @samp{-e}, 109755839Sasmodai@samp{-man}, @samp{-me}, @samp{-mm}, @samp{-ms}, @samp{-p}, @samp{-s}, 109855839Sasmodaiand @samp{-t}. 109955839Sasmodai 110055839SasmodaiA filename of @samp{-} is taken to refer to the standard input. If no 110155839Sasmodaifiles are specified the standard input will be read. Any specified 110255839Sasmodaioptions will be included in the printed command. No space is allowed 110355839Sasmodaibetween options and their arguments. For example, 110455839Sasmodai 110555839Sasmodai@example 110655839Sasmodaigrog -Tdvi paper.ms 110755839Sasmodai@end example 110855839Sasmodai 110955839Sasmodaiwill guess the approriate command to print @file{paper.ms} and then run 111055839Sasmodaiit after adding the @samp{-Tdvi} option. 111155839Sasmodai 111255839Sasmodai 111355839Sasmodai@node Tutorial for Macro Users, -man, Invoking groff, Top 111455839Sasmodai@chapter Tutorial for Macro Users 111555839Sasmodai@cindex tutorial for macro users 111655839Sasmodai@cindex macro tutorial for users 111755839Sasmodai@cindex user's tutorial for macros 111855839Sasmodai@cindex user's macro tutorial 111955839Sasmodai 112055839SasmodaiMost users tend to use a macro package to format their papers. This 112155839Sasmodaimeans that the whole breadth of @code{groff} is not neccessary for most 112255839Sasmodaipeople. This chapter covers the material needed to efficiently use a 112355839Sasmodaimacro package. 112455839Sasmodai 112555839Sasmodai 112655839Sasmodai@menu 112755839Sasmodai* Basics:: 112855839Sasmodai* Common Features:: 112955839Sasmodai@end menu 113055839Sasmodai 113155839Sasmodai@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 113255839Sasmodai@section Basics 113355839Sasmodai@cindex basics 113455839Sasmodai 113555839Sasmodai 113655839SasmodaiThis section covers some of the basic concepts you will need to 113755839Sasmodaiunderstand to use a macro package.@footnote{This section is derived from 113855839Sasmodai@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman} 113955839SasmodaiReferences are made throughout to more detailed information, if desired. 114055839Sasmodai 114155839Sasmodai@code{groff} reads an input file prepared by the user and outputs a 114255839Sasmodaiformatted paper suitable for publication or framing. The input consists 114355839Sasmodaiof text, or words to be printed, and embedded commands (@dfn{requests} 114455839Sasmodaiand @dfn{escapes}), which tell @code{groff} how to format the printed 114555839Sasmodaicopy. For more detail on this @pxref{Embedded Commands}. 114655839Sasmodai 114755839SasmodaiThe word @dfn{argument} is used in this manual to mean a word or number 114855839Sasmodaiwhich appears on the same line as a request which modifies the meaning 114955839Sasmodaiof that request. For example, the request 115055839Sasmodai 115155839Sasmodai@example 115255839Sasmodai.sp 115355839Sasmodai@end example 115455839Sasmodai 115555839Sasmodai@noindent 115655839Sasmodaispaces one line, but 115755839Sasmodai 115855839Sasmodai@example 115955839Sasmodai.sp 4 116055839Sasmodai@end example 116155839Sasmodai 116255839Sasmodai@noindent 116355839Sasmodaispaces four lines. The number@w{ }4 is an argument to the @code{sp} 116455839Sasmodairequest which says to space four lines instead of one. Arguments are 116555839Sasmodaiseparated from the request and from each other by spaces. More details 116655839Sasmodaion this can be found in @ref{Request Arguments}. 116755839Sasmodai 116855839SasmodaiThe primary function of @code{groff} is to collect words from input 116955839Sasmodailines, fill output lines with those words, justify the right hand margin 117055839Sasmodaiby inserting extra spaces in the line, and output the result. For 117155839Sasmodaiexample, the input: 117255839Sasmodai 117355839Sasmodai@example 117455839SasmodaiNow is the time 117555839Sasmodaifor all good men 117655839Sasmodaito come to the aid 117755839Sasmodaiof their party. 117855839SasmodaiFour score and seven 117955839Sasmodaiyears ago,... 118055839Sasmodai@end example 118155839Sasmodai 118255839Sasmodai@noindent 118355839Sasmodaiwill be read, packed onto output lines, and justified to produce: 118455839Sasmodai 118555839Sasmodai@quotation 118655839SasmodaiNow is the time for all good men to come to the aid of their party. 118755839SasmodaiFour score and seven years ago,... 118855839Sasmodai@end quotation 118955839Sasmodai 119055839Sasmodai@cindex break 119155839Sasmodai@cindex line break 119255839SasmodaiSometimes you may want to start a new output line even though the line 119355839Sasmodaiyou are on is not yet full; for example, at the end of a paragraph. To 119455839Sasmodaido this you can cause a @dfn{break}, which starts a new output line. 119555839SasmodaiSome requests cause a break automatically, as do blank input lines and 119655839Sasmodaiinput lines beginning with a space. 119755839Sasmodai 119855839SasmodaiNot all input lines are text to be formatted. Some of the input lines 119955839Sasmodaiare requests which describe how to format the text. Requests always 120055839Sasmodaihave a period or an apostrophe (@samp{'}) as the first character of the 120155839Sasmodaiinput line. 120255839Sasmodai 120355839SasmodaiThe text formatter also does more complex things, such as automatically 120455839Sasmodainumbering pages, skipping over page boundaries putting footnotes in the 120555839Sasmodaicorrect place, and so forth. 120655839Sasmodai 120755839SasmodaiHere a few hints for preparing text for input to @code{groff}. First, 120855839Sasmodaikeep the input lines short. Short input lines are easier to edit, and 120955839Sasmodai@code{groff} will pack words onto longer lines for you anyhow. In 121055839Sasmodaikeeping with this, it is helpful to begin a new line after every period, 121155839Sasmodaicomma, or phrase, since common corrections are to add or delete 121255839Sasmodaisentences or phrases. Secondly, do not hyphenate words at the end of 121355839Sasmodailines -- @code{groff} is smart enough to hyphenate words for you as 121455839Sasmodaineeded, but is not smart enough to take hyphens out and join a word back 121555839Sasmodaitogether. Also, words such as ``mother-in-law'' should not be broken 121655839Sasmodaiover a line, since then you will get a space where not wanted, such as 121755839Sasmodai``mother- in-law''. 121855839Sasmodai 121955839Sasmodai@findex ls 122055839Sasmodai@cindex double spacing 122155839Sasmodai@cindex spacing 122255839SasmodaiGroff will double space output text automatically if you use the request 122355839Sasmodai@samp{.ls 2}. You can revert to single spaced mode by typing @samp{.ls 122455839Sasmodai1}. 122555839Sasmodai 122655839SasmodaiA number of requests allow you to change the way the printed copy looks, 122755839Sasmodaisometimes called the @dfn{layout} of the output page. Most of these 122855839Sasmodairequests adjust the placing of @dfn{white space} (blank lines or 122955839Sasmodaispaces). 123055839Sasmodai 123155839Sasmodai@findex bp 123255839Sasmodai@cindex new page 123355839SasmodaiThe @samp{.bp} request starts a new page. 123455839Sasmodai 123555839Sasmodai@findex sp 123655839Sasmodai@cindex blank lines 123755839Sasmodai@cindex empty lines 123855839SasmodaiThe request @samp{.sp @var{N}} leaves @var{N} lines of blank space. 123955839Sasmodai@var{N} can be omitted (meaning skip a single line) or can be of the 124055839Sasmodaiform @var{N}i (for @var{N} inches) or @var{N}c (for @var{N} 124155839Sasmodaicentimeters). For example, the input: 124255839Sasmodai 124355839Sasmodai@example 124455839Sasmodai.sp 1.5i 124555839SasmodaiMy thoughts on the subject 124655839Sasmodai.sp 124755839Sasmodai@end example 124855839Sasmodai 124955839Sasmodai@noindent 125055839Sasmodaileaves one and a half inches of space, followed by the line ``My 125155839Sasmodaithoughts on the subject'', followed by a single blank line. 125255839Sasmodai 125355839Sasmodai@findex ce 125455839Sasmodai@cindex centering lines 125555839SasmodaiText lines can be centered by using the @samp{.ce} request. The line 125655839Sasmodaiafter @samp{.ce} is centered (horizontally) on the page. To center more 125755839Sasmodaithan one line, use @samp{.ce @var{N}} (where @var{N} is the number of 125855839Sasmodailines to center), followed by the @var{N} lines. If you want to center 125955839Sasmodaimany lines but don't want to count them, type: 126055839Sasmodai 126155839Sasmodai@example 126255839Sasmodai.ce 1000 126355839Sasmodailines to center 126455839Sasmodai.ce 0 126555839Sasmodai@end example 126655839Sasmodai 126755839Sasmodai@noindent 126855839SasmodaiThe @samp{.ce 0} request tells @code{groff} to center zero more lines, 126955839Sasmodaiin other words, stop centering. 127055839Sasmodai 127155839Sasmodai@findex br 127255839Sasmodai@cindex line break 127355839Sasmodai@cindex break 127455839SasmodaiAll of these requests cause a break; that is, they always start a new 127555839Sasmodailine. If you want to start a new line without performing any other 127655839Sasmodaiaction, use @samp{.br}. 127755839Sasmodai 127855839Sasmodai 127955839Sasmodai@node Common Features, , Basics, Tutorial for Macro Users 128055839Sasmodai@section Common Features 128155839Sasmodai@cindex common features 128255839Sasmodai@cindex features, common 128355839Sasmodai 128455839Sasmodai 128555839SasmodaiGroff provides very low level operations for formatting a document. 128655839SasmodaiThere are many common routine operations which are done in all documents. 128755839SasmodaiThese common operations are written into @dfn{macros} and collected into a 128855839Sasmodai@dfn{macro package}. 128955839Sasmodai 129055839SasmodaiAll macro packages provide certain common capabilities which fall 129155839Sasmodaiinto the following categories. 129255839Sasmodai 129355839Sasmodai@subsection Paragraphs 129455839Sasmodai@cindex paragraphs 129555839Sasmodai 129655839SasmodaiOne of the most common and most used capability is starting a 129755839Sasmodaiparagraph. There are a number of different types of paragraphs, 129855839Sasmodaiany of which can be initiated with macros supplied by the macro 129955839Sasmodaipackage. Normally paragraphs start with a blank line and the first 130055839Sasmodailine indented, like the text in this manual. There are also block 130155839Sasmodaistyle paragraphs, which omit the indentation: 130255839Sasmodai 130355839Sasmodai@example 130455839SasmodaiSome men look at constitutions with sanctimonious 130555839Sasmodaireverence, and deem them like the ark of the covenant, too 130655839Sasmodaisacred to be touched. 130755839Sasmodai@end example 130855839Sasmodai 130955839SasmodaiAnd there are also indented paragraphs which begin with a tag or label 131055839Sasmodaiat the margin and the remaining text indented. 131155839Sasmodai 131255839Sasmodai@example 131355839Sasmodaione This is the first paragraph. Notice how the first 131455839Sasmodai line of the resulting paragraph lines up with the 131555839Sasmodai other lines in the paragraph. 131655839Sasmodailonglabel 131755839Sasmodai This paragraph had a long label. The first 131855839Sasmodai character of text on the first line will not line up 131955839Sasmodai with the text on second and subsequent lines, 132055839Sasmodai although they will line up with each other. 132155839Sasmodai@end example 132255839Sasmodai 132355839SasmodaiA variation of this is a bulleted list.... 132455839Sasmodai 132555839Sasmodai@subsection Sections and Chapters 132655839Sasmodai 132755839SasmodaiMost macro packages supply some form of section headers. 132855839SasmodaiThe simplest kind is simply the heading on a line by itself in bold 132955839Sasmodaitype. Others supply automatically numbered section heading or 133055839Sasmodaidifferent heading styles at different levels. 133155839SasmodaiSome, more sophisticated, macro packages supply macros for starting 133255839Sasmodaichapters and appendicies. 133355839Sasmodai 133455839Sasmodai@subsection Headers and Footers 133555839Sasmodai 133655839SasmodaiEvery macro packages gives you some way to manipulate the headers and 133755839Sasmodaifooters (or @dfn{titles} on each page. Some packages will allow you 133855839Sasmodaito have different ones on the even and odd pages (for material 133955839Sasmodaiprinted in a book form). 134055839SasmodaiThe titles are called three-part titles, that is, there is a 134155839Sasmodaileft-justified part, a centered part, and a right-justified part. 134255839SasmodaiAn automatically generated page number may be put in any of these 134355839Sasmodaifields with the @samp{%} character. 134455839Sasmodai 134555839Sasmodai@subsection Page Layout 134655839Sasmodai 134755839SasmodaiMost macro packages let you specify top and bottom margins and other 134855839Sasmodaidetails about the appearance of the printed pages. 134955839Sasmodai 135055839Sasmodai@subsection Displays 135155839Sasmodai@cindex displays 135255839Sasmodai 135355839SasmodaiDisplays are sections of text to be set off from the body 135455839Sasmodaiof the paper. Major quotes, tables, and figures are types of 135555839Sasmodaidisplays, as are all the examples used in this document. 135655839Sasmodai 135755839Sasmodai@cindex quotes, major 135855839Sasmodai@cindex major quotes 135955839SasmodaiMajor quotes are quotes which are several lines long, 136055839Sasmodaiand hence are set in from the rest of the text without 136155839Sasmodaiquote marks around them. 136255839Sasmodai 136355839Sasmodai@cindex list 136455839SasmodaiA list is an indented, single spaced, unfilled display. Lists should 136555839Sasmodaibe used when the material to be printed 136655839Sasmodaishould not be filled and justified like normal text, such 136755839Sasmodaias columns of figures or the examples used in this paper. 136855839Sasmodai 136955839Sasmodai@cindex keep 137055839SasmodaiA keep is a display of lines which are kept on a single page if 137155839Sasmodaipossible. An example of where you would use a 137255839Sasmodaikeep might be a diagram. Keeps differ from lists in that 137355839Sasmodailists may be broken over a page boundary whereas keeps will 137455839Sasmodainot. 137555839Sasmodai 137655839Sasmodai@cindex keep, floating 137755839Sasmodai@cindex floating keep 137855839SasmodaiFloating keeps move relative to the text. Hence, they 137955839Sasmodaiare good for things which will be referred to by name, such 138055839Sasmodaias ``See figure 3''. A floating keep will appear at the bottom of the 138155839Sasmodaicurrent page if it will fit; otherwise, it will 138255839Sasmodaiappear at the top of the next page. Meanwhile, the surrounding text 138355839Sasmodaiwill `flow' around the keep, thus leaving now blank areas. 138455839Sasmodai 138555839Sasmodai@subsection Footnotes and annotations 138655839Sasmodai@cindex footnotes 138755839Sasmodai@cindex annotations 138855839Sasmodai 138955839SasmodaiThere are a number of requests to save text for later 139055839Sasmodaiprinting. Footnotes are printed at the bottom of the current 139155839Sasmodaipage. Delayed text is intended to be a variant form of foot- 139255839Sasmodainote; the text is printed only when explicitly called for, 139355839Sasmodaisuch as at the end of each chapter. 139455839Sasmodai 139555839SasmodaiDelayed text is very similar to a footnote except that 139655839Sasmodaiit is printed when called for explicitly. This allows a 139755839Sasmodailist of references to appear (for example) at the end of 139855839Sasmodaieach chapter, as is the convention in some disciplines. 139955839Sasmodai 140055839SasmodaiMost macro packages which supply this functionality also supply a 140155839Sasmodaimeans of automatically numbering either type of annotation. 140255839Sasmodai 140355839Sasmodai@subsection Table of Contents 140455839Sasmodai 140555839SasmodaiTables of contents are a type of 140655839Sasmodaidelayed text having a tag (usually the page number) attached 140755839Sasmodaito each entry after a row of dots. The table accumulates 140855839Sasmodaithroughought the paper until printed, usually after the paper has 140955839Sasmodaiended. Many macro packages will provide the abilitly to have several 141055839Sasmodaitables of contents (i.e. one standard one, one for tables, &c.) 141155839Sasmodai 141255839Sasmodai@subsection Indexes 141355839Sasmodai 141455839SasmodaiWhile some macro packages will use the term @dfn{index}, none 141555839Sasmodaiactually provide that functionality. The facilities they call 141655839Sasmodaiindexes are actually more appropriate for tables of contents. 141755839Sasmodai 141855839Sasmodai@subsection Paper formats 141955839Sasmodai 142055839SasmodaiSome macro packages provide stock formats for various kinds of 142155839Sasmodaidocuments. Many of them provide a common format for the title and 142255839Sasmodaiopening pages of a technical paper. The -mm macros in particular 142355839Sasmodaiprovide formats for letters and memorandums. 142455839Sasmodai 142555839Sasmodai@subsection Multiple Columns 142655839Sasmodai 142755839SasmodaiSome macro packages (except -man) provide the ability to have two or 142855839Sasmodaimore columns on a page. 142955839Sasmodai 143055839Sasmodai@subsection Font and Size changes 143155839Sasmodai 143255839SasmodaiThe builtin font and size functions are not always intuitive, so all 143355839Sasmodaimacro packages provide macros to make these operations simpler. 143455839Sasmodai 143555839Sasmodai@subsection Predefined Strings 143655839Sasmodai 143755839SasmodaiMost macro packages provide various predefined strings for a variety 143855839Sasmodaiof uses, examples are sub- and super-scripts, printable dates, quotes 143955839Sasmodaiand various special characters. 144055839Sasmodai 144155839Sasmodai@subsection Preprocessor Support 144255839Sasmodai 144355839SasmodaiAll macro packages provide support for the various preprocessors. 144455839Sasmodai 144555839Sasmodai@subsection Configuration and Customization 144655839Sasmodai 144755839SasmodaiSome macro packages provide means of customizing many of details of 144855839Sasmodaihow the package behaves. This ranges from setting the default type 144955839Sasmodaisize to changing the appearance of section headers. 145055839Sasmodai 145155839Sasmodai 145255839Sasmodai@node -man, -ms, Tutorial for Macro Users, Top 145355839Sasmodai@chapter -man 145455839Sasmodai@cindex @code{-man} 145555839Sasmodai 145655839Sasmodai 145755839Sasmodai 145855839Sasmodai@node -ms, -me, -man, Top 145955839Sasmodai@chapter -ms 146055839Sasmodai@cindex @code{-ms} 146155839Sasmodai 146255839Sasmodai 146355839Sasmodai 146455839Sasmodai@node -me, -mm, -ms, Top 146555839Sasmodai@chapter -me 146655839Sasmodai@cindex @code{-me} 146755839Sasmodai 146855839Sasmodai 146955839Sasmodai 147055839Sasmodai@node -mm, Programming Tutorial, -me, Top 147155839Sasmodai@chapter -mm 147255839Sasmodai@cindex @code{-mm} 147355839Sasmodai 147455839Sasmodai 147555839Sasmodai 147655839Sasmodai@node Programming Tutorial, geqn, -mm, Top 147755839Sasmodai@chapter Programming Tutorial 147855839Sasmodai@cindex programming tutorial 147955839Sasmodai@cindex tutorial for programming 148055839Sasmodai 148155839SasmodaiThis chapter covers @strong{all} of the facilities of groff. 148255839SasmodaiIf you are intending to use a macro package, you probably do not want 148355839Sasmodaito read this chapter. 148455839Sasmodai 148555839Sasmodai 148655839Sasmodai@menu 148755839Sasmodai* Text:: 148855839Sasmodai* Input Conventions:: 148955839Sasmodai* Measurements:: 149055839Sasmodai* Expressions:: 149155839Sasmodai* Identifiers:: 149255839Sasmodai* Embedded Commands:: 149355839Sasmodai* Registers:: 149455839Sasmodai* Manipulating Filling and Adjusting:: 149555839Sasmodai* Manipulating Hyphenation:: 149655839Sasmodai* Manipulating Spacing:: 149755839Sasmodai* Tabs and Fields:: 149855839Sasmodai* Character Translations:: 149955839Sasmodai* Line Layout:: 150055839Sasmodai* Page Layout:: 150155839Sasmodai* Page Control:: 150255839Sasmodai* Fonts:: 150355839Sasmodai* Sizes:: 150455839Sasmodai* Strings:: 150555839Sasmodai* Conditionals and Loops:: 150655839Sasmodai* Writing Macros:: 150755839Sasmodai* Page Motions:: 150855839Sasmodai* Drawing Functions:: 150955839Sasmodai* Traps:: 151055839Sasmodai* Diversions:: 151155839Sasmodai* Environments:: 151255839Sasmodai* I/O:: 151355839Sasmodai* Postprocessor Access:: 151455839Sasmodai* Miscellany:: 151555839Sasmodai* Debugging:: 151655839Sasmodai* Implementation Differences:: 151755839Sasmodai* Summary:: 151855839Sasmodai@end menu 151955839Sasmodai 152055839Sasmodai@node Text, Input Conventions, Programming Tutorial, Programming Tutorial 152155839Sasmodai@section Text 152255839Sasmodai@cindex text 152355839Sasmodai 152455839Sasmodai@code{groff} input files contain text with control commands 152555839Sasmodaiinterspersed throughout. But, even without control codes, 152655839Sasmodai@code{groff} will still do several things with your text: 152755839Sasmodaifilling and adjusting, 152855839Sasmodaiadding additional space after sentences, 152955839Sasmodaihyphenating 153055839Sasmodaiand 153155839Sasmodaiinserting implicit line breaks. 153255839Sasmodai 153355839Sasmodai 153455839Sasmodai@menu 153555839Sasmodai* Filling and Adjusting:: 153655839Sasmodai* Hyphenation:: 153755839Sasmodai* Sentences:: 153855839Sasmodai* Tab Stops:: 153955839Sasmodai* Implicit Line Breaks:: 154055839Sasmodai@end menu 154155839Sasmodai 154255839Sasmodai@node Filling and Adjusting, Hyphenation, Text, Text 154355839Sasmodai@subsection Filling and Adjusting 154455839Sasmodai@cindex filling and adjusting 154555839Sasmodai@cindex adjusting and filling 154655839Sasmodai 154755839Sasmodai 154855839SasmodaiWhen troff reads in text it collects words from input and fits as many 154955839Sasmodaiof them together on one output line as it can. This is known as 155055839Sasmodai@dfn{filling}. 155155839Sasmodai 155255839SasmodaiOnce troff has a @dfn{filled} line it will try to @dfn{adjust} it. 155355839Sasmodaiwhich means it will widen the spacing between words until 155455839Sasmodaithe text reaches the right margin (in the default adjustment mode). 155555839SasmodaiExtra spaces between words are preserved, but 155655839Sasmodaispaces at the end of lines are ignored. 155755839SasmodaiSpaces at the front of a line will cause a @dfn{break} 155855839Sasmodai(breaks will be explained in @ref{Implicit Line Breaks}) 155955839Sasmodai 156055839Sasmodai@c distribute these through the text 156155839Sasmodai@xref{Manipulating Filling and Adjusting} 156255839Sasmodai 156355839Sasmodai@node Hyphenation, Sentences, Filling and Adjusting, Text 156455839Sasmodai@subsection Hyphenation 156555839Sasmodai@cindex hyphenation 156655839Sasmodai 156755839Sasmodai 156855839SasmodaiSince the odds of finding a set of words, for every output line, 156955839Sasmodaiwhich will fit nicely on a 157055839Sasmodailine without inserting excessive amounts of space between words 157155839Sasmodaiis not great, 157255839Sasmodaitroff will hyphenate words so that lines can be justified 157355839Sasmodaiwithout there being too much space between words. 157455839SasmodaiIt uses an internal hyphenation algorithm, to indicate which words can 157555839Sasmodaibe hyphenated and how to do so. 157655839SasmodaiWhen a word is hyphenated the first part of the word will be added 157755839Sasmodaito the current filled line being output (with an attached hyphen), 157855839Sasmodaiand the other portion will be added to the next line to be filled. 157955839Sasmodai 158055839Sasmodai@c distribute these through the text 158155839Sasmodai@xref{Manipulating Hyphenation} 158255839Sasmodai 158355839Sasmodai@node Sentences, Tab Stops, Hyphenation, Text 158455839Sasmodai@subsection Sentences 158555839Sasmodai@cindex sentences 158655839Sasmodai 158755839Sasmodai 158855839SasmodaiAlthough it is often debated, 158955839Sasmodaisome typesetting rules say there should be different amounts of space 159055839Sasmodaiafter various puctuation marks. 159155839SasmodaiFor example, a period at the end of a sentence 159255839Sasmodaishould have twice as much space following it 159355839Sasmodaias would a comma or a period as part of an abbreviation. 159455839Sasmodai 159555839Sasmodai@cindex sentence spaces 159655839Sasmodai@cindex spaces between sentences 159755839SasmodaiTroff does this by flagging certain characters (normally 159855839Sasmodai@samp{!}, @samp{?} and @samp{.}) 159955839Sasmodaias @dfn{end of sentence} characters. 160055839SasmodaiWhen troff encounters one of these characters at the end of a line it 160155839Sasmodaiwill append two @dfn{sentence spaces} in the formatted output. 160255839Sasmodai(thus, one of the conventions mentioned in @ref{Input Conventions}). 160355839Sasmodai 160455839Sasmodai@c also describe how characters like ) are treated here -jjc 160555839Sasmodai@c gotta do some research on this -trent 160655839Sasmodai 160755839Sasmodai 160855839Sasmodai 160955839Sasmodai@node Tab Stops, Implicit Line Breaks, Sentences, Text 161055839Sasmodai@subsection Tab Stops 161155839Sasmodai@cindex tab stops 161255839Sasmodai@cindex stops, tabulator 161355839Sasmodai 161455839Sasmodai 161555839SasmodaiGroff translates tabs in the input into movements to the next tab 161655839Sasmodaistop. These tab stops are initially located every half inch across 161755839Sasmodaithe page. 161855839SasmodaiUsing this you can make simple tables. However, this can often be 161955839Sasmodaideceptive as the appearance (and width) of your text on a terminal and 162055839Sasmodaithe results from groff can vary greatly. 162155839Sasmodai 162255839SasmodaiAlso, a possible sticking point is that lines beginning with tab 162355839Sasmodaicharacters will still be filled, again producing unexpected results. 162455839SasmodaiFor example, the following input 162555839Sasmodai 162655839Sasmodai@example 162755839Sasmodai 1 2 3 162855839Sasmodai 4 5 162955839Sasmodai@end example 163055839Sasmodai 163155839Sasmodai@noindent 163255839Sasmodaiwill produce 163355839Sasmodai 163455839Sasmodai@example 163555839Sasmodai 1 2 3 4 5 163655839Sasmodai@end example 163755839Sasmodai 163855839Sasmodai@c Tab stops are with respect to the input line. -jjc 163955839Sasmodai@c did that last section address that?? -trent 164055839Sasmodai 164155839Sasmodai 164255839Sasmodai 164355839Sasmodai@c distribute these through the text 164455839Sasmodai@xref{Tabs and Fields} 164555839Sasmodai 164655839Sasmodai@node Implicit Line Breaks, , Tab Stops, Text 164755839Sasmodai@subsection Implicit Line Breaks 164855839Sasmodai@cindex implicit line breaks 164955839Sasmodai@cindex implicit breaks of lines 165055839Sasmodai@cindex line, implicit breaks 165155839Sasmodai@cindex break 165255839Sasmodai@cindex break, implicit 165355839Sasmodai@cindex line break 165455839Sasmodai 165555839SasmodaiAn important concept in troff is the @dfn{break}. When a @dfn{break} 165655839Sasmodaioccurs, troff will output the partially filled line (unadjusted), 165755839Sasmodaiand resume collecting and filling text on the next output line. 165855839Sasmodai 165955839Sasmodai@cindex blank line 166055839Sasmodai@cindex empty line 166155839Sasmodai@cindex line, blank 166255839SasmodaiThere are several ways to cause a break in troff. 166355839SasmodaiA blank line will not only cause a break, but it will also cause a 166455839Sasmodaione line vertical space (effectively a blank line) to be output. 166555839Sasmodai 166655839SasmodaiA line which begins with a space will cause a break and the space 166755839Sasmodaiwill be output at the beginning of the next line. 166855839SasmodaiNote that this space isn't adjusted, even in fill mode. 166955839Sasmodai 167055839SasmodaiThe end of file will also cause a break (otherwise the last line of 167155839Sasmodaiyour document may vanish!) 167255839Sasmodai 167355839SasmodaiCertain @dfn{requests} also cause breaks, implicitly or explicity. 167455839SasmodaiThis will be discussed later. 167555839Sasmodai 167655839Sasmodai@c distribute these through the text 167755839Sasmodai@xref{Manipulating Filling and Adjusting} 167855839Sasmodai 167955839Sasmodai@node Input Conventions, Measurements, Text, Programming Tutorial 168055839Sasmodai@section Input Conventions 168155839Sasmodai@cindex input conventions 168255839Sasmodai@cindex conventions for input 168355839Sasmodai 168455839Sasmodai 168555839SasmodaiSince groff does filling automatically, it is traditional in groff not 168655839Sasmodaito try and type things in as nicely formatted paragraphs. These are 168755839Sasmodaisome conventions commonly used when typing groff text: 168855839Sasmodai 168955839Sasmodai@itemize @bullet{} 169055839Sasmodai@item 169155839SasmodaiBreak lines after punctuation, particularily at the ends of 169255839Sasmodaisentences, and in other logical places. Keep separate phrases on 169355839Sasmodailines by themselves, as entire phrases are often added or deleted 169455839Sasmodaiwhen editing. 169555839Sasmodai@item 169655839SasmodaiTry to keep lines less than 40-60 characters, 169755839Sasmodaito allow space for inserting more text. 169855839Sasmodai@item 169955839SasmodaiDo not try to do any formatting in a WYSIWYG manner (i.e. don't 170055839Sasmodaitry and use spaces to get proper indentation). 170155839Sasmodai@end itemize 170255839Sasmodai 170355839Sasmodai 170455839Sasmodai@node Measurements, Expressions, Input Conventions, Programming Tutorial 170555839Sasmodai@section Measurements 170655839Sasmodai@cindex measurements 170755839Sasmodai 170855839Sasmodai 170955839Sasmodai@cindex units of measurement 171055839Sasmodai@cindex basic units 171155839Sasmodai@cindex machine units 171255839SasmodaiTroff (like any other programs) requires numeric parameters to 171355839Sasmodaispecify various measurements. Most numeric parameters 171455839Sasmodai@footnote{those that specify vertical or horizontal motion or a type 171555839Sasmodaisize} may have a measurement unit attached. 171655839SasmodaiThese units are specified as a single 171755839Sasmodaicharacter which immediately follows the number or expression. 171855839SasmodaiEach of these units are understood, by troff, to be a multiple of its 171955839Sasmodai@dfn{basic unit}. So, whenever a different measurement unit is 172055839Sasmodaispecified troff converts this into its basic units. 172155839SasmodaiThis basic unit, represented by a @samp{u} is a 172255839Sasmodaidevice dependent measurement which is quite small, ranging from 172355839Sasmodai1/75th to 1/72000th of an inch. 172455839Sasmodai 172555839SasmodaiSome of the measurement units are compleatly independent of any of 172655839Sasmodaithe current settings (e.g. type size) of groff. 172755839Sasmodai 172855839Sasmodai@table @samp 172955839Sasmodai@item i 173055839Sasmodai@cindex inch 173155839SasmodaiInches. An antiquated measurement unit still in use in certain 173255839Sasmodaibackwards countries. 173355839Sasmodai@item c 173455839Sasmodai@cindex centimeter 173555839SasmodaiCentimeters. 173655839Sasmodai@item p 173755839Sasmodai@cindex points 173855839SasmodaiPoints. This is a typesetter's measurement used for measure type size. 173955839SasmodaiIt is 72 points to an inch. 174055839Sasmodai@item P 174155839Sasmodai@cindex pica 174255839SasmodaiPica. Another typesetting measurement. 6 Picas to an inch. 174355839Sasmodai@item s 174455839Sasmodai@item z 174555839Sasmodai@end table 174655839Sasmodai 174755839SasmodaiThe other measurements understood by troff are dependent on settings 174855839Sasmodaicurrently in effect in troff. These are very useful for specifying 174955839Sasmodaimeasurements which should look proper with any size of text. 175055839Sasmodai 175155839Sasmodai@table @samp 175255839Sasmodai@item m 175355839Sasmodai@cindex em 175455839SasmodaiEms. This unit is equal to the current font size in points. 175555839SasmodaiSo called because it is @emph{approximately} the width of the letter 175655839Sasmodai@samp{m} in the current font. 175755839Sasmodai@item n 175855839Sasmodai@cindex en 175955839SasmodaiEns. This is half of an em. 176055839Sasmodai@item v 176155839Sasmodai@cindex vertical space 176255839Sasmodai@cindex space, vertical 176355839SasmodaiVertical space. This is equivalent to the current line spacing. 176455839Sasmodai@xref{Sizes}, for more information about this. 176555839Sasmodai@item M 176655839Sasmodai100ths of an em. 176755839Sasmodai@end table 176855839Sasmodai 176955839Sasmodai@c distribute these through the text 177055839Sasmodai@xref{Fractional Type Sizes} 177155839Sasmodai 177255839Sasmodai@menu 177355839Sasmodai* Default Units:: 177455839Sasmodai@end menu 177555839Sasmodai 177655839Sasmodai@node Default Units, , Measurements, Measurements 177755839Sasmodai@subsection Default Units 177855839Sasmodai@cindex default units 177955839Sasmodai@cindex units, default 178055839Sasmodai 178155839Sasmodai 178255839SasmodaiMany requests take a default unit. While this can be helpful at 178355839Sasmodaitimes, it can cause strange errors in some expressions. 178455839SasmodaiFor example, the line length request expects em's. 178555839SasmodaiHere are several attempts to get 3.5 inches and the results: 178655839Sasmodai 178755839Sasmodai@example 178855839Sasmodai3.5i @result{} 3.5i 178955839Sasmodai7/2 @result{} 0i 179055839Sasmodai7/2i @result{} 0i 179155839Sasmodai7i/2 @result{} .1i 179255839Sasmodai7i/2u @result{} 3.5i 179355839Sasmodai@end example 179455839Sasmodai 179555839SasmodaiAs you can see, the safest way to specify measurements is to always 179655839Sasmodaiattach a scaling indicator. 179755839Sasmodai 179855839Sasmodai@node Expressions, Identifiers, Measurements, Programming Tutorial 179955839Sasmodai@section Expressions 180055839Sasmodai@cindex expressions 180155839Sasmodai 180255839Sasmodai 180355839SasmodaiTroff has most of operators common to other languages: 180455839Sasmodai 180555839Sasmodai@itemize @bullet 180655839Sasmodai@item 180755839SasmodaiArithmetic: +, -, /, *, % 180855839Sasmodai@item 180955839SasmodaiComparison: <, >, >=, <=, =, == (the last two are the same) 181055839Sasmodai@item 181155839SasmodaiLogical: &, : 181255839Sasmodai@item 181355839SasmodaiUnary operators: -, +, ! (if/while only??) 181455839Sasmodai@item 181555839SasmodaiMaximum and minimum: >?, <? 181655839Sasmodai@item 181755839SasmodaiScaling: (@var{c};@var{e}) 181855839SasmodaiEvaluate @var{e} using @var{c} as the default scaling indicator. 181955839SasmodaiIf @var{c} is missing, ignore scaling indicators in the 182055839Sasmodaievaluation of @var{e}. 182155839Sasmodai@end itemize 182255839Sasmodai 182355839SasmodaiParenthesis may be used as in any other language. 182455839SasmodaiHowever, in groff they are necessary to ensure order of evaluation. 182555839SasmodaiGroff has no operator precedence, 182655839Sasmodaiexpressions are evaluated left to right. 182755839SasmodaiThis means that @samp{3+5*4} is evaluated as if it were parenthesized 182855839Sasmodailike @samp{(3+5)*4}, not as @samp{3+(5*4)}, like you may expect. 182955839Sasmodai 183055839SasmodaiFor many requests which cause a motion on the page, the unary 183155839Sasmodaioperators work differently. 183255839SasmodaiThe @samp{+} and @samp{-} operators indicate a motion relative to the 183355839Sasmodaicurrent position (down or up, respectively). The @samp{|} operator 183455839Sasmodaiindicates an absolute position on the page or input line. (????) 183555839Sasmodai@code{+} and @code{-} are also treated differently by @code{nr} (?) 183655839Sasmodai 183755839SasmodaiDue to the way arguments are parsed, spaces are not allowed in 183855839Sasmodaiexpressions, unless the entire expression is surrounded by parenthesis. 183955839Sasmodai 184055839Sasmodai@c distribute these through the text 184155839Sasmodai@xref{Request Arguments} 184255839Sasmodai@c distribute these through the text 184355839Sasmodai@xref{Conditionals and Loops} 184455839Sasmodai 184555839Sasmodai@node Identifiers, Embedded Commands, Expressions, Programming Tutorial 184655839Sasmodai@section Identifiers 184755839Sasmodai@cindex identifiers 184855839Sasmodai 184955839SasmodaiLike any other language troff, has rules for properly formed 185055839Sasmodaiidentifiers. 185155839SasmodaiIn troff an identifier can be made up of most any printable 185255839Sasmodaicharacter. 185355839SasmodaiThe only exception is characters which are interpreted by troff 185455839Sasmodai(backslash, square bracket and ?). So, for example, any of the following 185555839Sasmodaiare valid. 185655839Sasmodai 185755839Sasmodai@example 185855839Sasmodaibr 185955839SasmodaiPP 186055839Sasmodai(l 186155839Sasmodaiend-list 186255839Sasmodai@@_ 186355839Sasmodai@end example 186455839Sasmodai 186555839SasmodaiYou can test whether an identifier is valid in groff with the 186655839Sasmodai@code{\A} escape. It expands to 1 or 0 according whether its argument 186755839Sasmodai(given in quotes) is or is not acceptable as the name of a string, 186855839Sasmodaimacro, diversion, number register, environment or font. It will return 186955839Sasmodai0 if no argument is given. This is useful if you want to lookup user 187055839Sasmodaiinput in some sort of associative table. 187155839Sasmodai 187255839SasmodaiIdentifiers in groff can be any length, but, in some contexts, 187355839Sasmodaigroff needs to told 187455839Sasmodaiwhere identifiers end and text begins (and in different ways 187555839Sasmodaidepending on their length) 187655839Sasmodai 187755839Sasmodai@itemize @bullet{} 187855839Sasmodai@item 187955839SasmodaiSingle character 188055839Sasmodai@item 188155839SasmodaiTwo characters 188255839SasmodaiMust be prefixed with @samp{(} in some situations. 188355839Sasmodai@item 188455839SasmodaiArbitrary length (groff only) 188555839SasmodaiMust be bracketed with @samp{[}, @samp{]} in some situations. 188655839SasmodaiAny length identifier can be put in brackets. 188755839Sasmodai@end itemize 188855839Sasmodai 188955839SasmodaiUnlike many other programming languages, undefined identifiers are 189055839Sasmodaisilently ignored or expanded to nothing. 189155839Sasmodai 189255839Sasmodai 189355839Sasmodai@c distribute these through the text 189455839Sasmodai@xref{Interpolating Registers} 189555839Sasmodai@c distribute these through the text 189655839Sasmodai@xref{Strings} 189755839Sasmodai 189855839Sasmodai@node Embedded Commands, Registers, Identifiers, Programming Tutorial 189955839Sasmodai@section Embedded Commands 190055839Sasmodai@cindex embedded commands 190155839Sasmodai@cindex commands, embedded 190255839Sasmodai 190355839Sasmodai 190455839SasmodaiWith most documents you need more funtionality beyond filling, 190555839Sasmodaiadjusting and implicit line breaking. 190655839SasmodaiIn order to gain further functionality, groff allows commands to be 190755839Sasmodaiembeded into your text, in two ways. 190855839Sasmodai 190955839SasmodaiThe first is a @dfn{request} which takes up an entire line, and does 191055839Sasmodaisome large scale operation (e.g. break lines, start new pages). 191155839Sasmodai 191255839SasmodaiThe other is an @dfn{escape} which can be embedded anywhere 191355839Sasmodaiin your text, or even as an argument to a request. (Not always?) 191455839SasmodaiEscapes generally do more minor operations like sub- and super- 191555839Sasmodaiscripts, print a symbol, &c. 191655839Sasmodai 191755839Sasmodai 191855839Sasmodai 191955839Sasmodai@menu 192055839Sasmodai* Requests:: 192155839Sasmodai* Macros:: 192255839Sasmodai* Escapes:: 192355839Sasmodai@end menu 192455839Sasmodai 192555839Sasmodai@node Requests, Macros, Embedded Commands, Embedded Commands 192655839Sasmodai@subsection Requests 192755839Sasmodai@cindex requests 192855839Sasmodai 192955839Sasmodai 193055839Sasmodai@cindex control character 193155839Sasmodai@cindex character, control 193255839SasmodaiA request line begins with a control character, 193355839Sasmodaiwhich is either a single quote (@samp{'}) or a period (@samp{.}). 193455839SasmodaiThese can be changed @pxref{Character Translations}, for details. 193555839SasmodaiAfter this there may be optional tabs or spaces followed by an 193655839Sasmodaiidentifier which is the name of the request. 193755839SasmodaiThis may be followed by any number of space separated arguments. 193855839Sasmodai 193955839Sasmodai@findex \& 194055839SasmodaiIf you want to begin a line with a control character without it being 194155839Sasmodaiinterpreted, precede it with a @code{\&}. This represents a zero 194255839Sasmodaiwidth space, which means it will not affect you output. 194355839Sasmodai 194455839SasmodaiIn most cases you will use the period as a control character. 194555839SasmodaiSeveral requests will cause a break, using the single quote control 194655839Sasmodaicharacter will prevent this. 194755839Sasmodai 194855839Sasmodai 194955839Sasmodai@menu 195055839Sasmodai* Request Arguments:: 195155839Sasmodai@end menu 195255839Sasmodai 195355839Sasmodai@node Request Arguments, , Requests, Requests 195455839Sasmodai@subsubsection Request Arguments 195555839Sasmodai@cindex request arguments 195655839Sasmodai@cindex arguments to requests 195755839Sasmodai 195855839Sasmodai 195955839SasmodaiArgument to requests (and macros) are processed much like the shell: 196055839SasmodaiThe line is split into arguments according to spaces. 196155839SasmodaiAn argument which is intended to contain spaces can either be enclosed 196255839Sasmodaiin quotes (single or double), or have the spaces @dfn{escaped} with 196355839Sasmodaibackslashes. 196455839Sasmodai 196555839SasmodaiSo, for example: 196655839Sasmodai 196755839Sasmodai@example 196855839Sasmodai.uh The Mouse Problem 196955839Sasmodai.uh "The Mouse Problem" 197055839Sasmodai.uh The\ Mouse\ Problem 197155839Sasmodai@end example 197255839Sasmodai 197355839SasmodaiThe first line is the @code{.uh} macro being called with 3 arguments, 197455839Sasmodai@samp{The}, @samp{Mouse}, and @samp{Problem}. 197555839SasmodaiThe latter two have the same effect or calling the @code{.uh} macro 197655839Sasmodaiwith one argument @samp{The Mouse Problem}. 197755839Sasmodai 197855839SasmodaiNote, however, that the @code{.ds} request works differently. 197955839Sasmodai 198055839Sasmodai@c distribute these through the text 198155839Sasmodai@xref{Strings} 198255839Sasmodai 198355839Sasmodai@node Macros, Escapes, Requests, Embedded Commands 198455839Sasmodai@subsection Macros 198555839Sasmodai@cindex macros 198655839Sasmodai 198755839Sasmodai 198855839SasmodaiTroff has a @dfn{macro} facility for defining a series of lines which 198955839Sasmodaican be invoked by name. 199055839SasmodaiThey are called in the same manner as requests 199155839Sasmodaiand arguments may be passed in the same manner. 199255839Sasmodai 199355839Sasmodai 199455839Sasmodai@c distribute these through the text 199555839Sasmodai@xref{Writing Macros} 199655839Sasmodai@c distribute these through the text 199755839Sasmodai@xref{Request Arguments} 199855839Sasmodai 199955839Sasmodai@node Escapes, , Macros, Embedded Commands 200055839Sasmodai@subsection Escapes 200155839Sasmodai@cindex escapes 200255839Sasmodai 200355839Sasmodai 200455839Sasmodai@findex \e 200555839Sasmodai@findex \\ 200655839SasmodaiEscapes may occur anywhere in the input to groff. 200755839SasmodaiThey begin with a backslash and are followed by a single character 200855839Sasmodaiwhich indicates the function to be performed. 200955839SasmodaiIf you want to have a backslash appear in your document, you should 201055839Sasmodaiuse the escape sequence @code{\e}. Merely escaping the backslash 201155839Sasmodaiwith another backslash will work in @emph{some} curcumstances. 201255839Sasmodai 201355839SasmodaiMany escapes have no parameters, those that do, do so in one of two 201455839Sasmodaiways. For escapes which require an identifier there must be a way for 201555839Sasmodaigroff to tell where the identifier ends and the text begins. 201655839SasmodaiIt assumes that the next single character is the identifier, but if 201755839Sasmodaithat character is an open parenthesis, it takes the next two 201855839Sasmodaicharacters as the identifier; and if the next character is an open 201955839Sasmodaibracket, all characters until a close bracket are taken as the 202055839Sasmodaiidentifier. Note that in the second case there is no closing 202155839Sasmodaiparenthesis. For example: 202255839Sasmodai 202355839Sasmodai@example 202455839Sasmodai\fB 202555839Sasmodai\n(XX 202655839Sasmodai\*[TeX] 202755839Sasmodai@end example 202855839Sasmodai 202955839SasmodaiOther escapes may require several arguments and/or some special 203055839Sasmodaiformat. In these cases the @dfn{argument} is enclosed in single 203155839Sasmodaiquotes (not required??) and the enclosing text is decoded according 203255839Sasmodaito what that escape expects. 203355839Sasmodai 203455839Sasmodai@example 203555839Sasmodai\l'1.5i\(bu' 203655839Sasmodai@end example 203755839Sasmodai 203855839Sasmodai@findex \\ 203955839Sasmodai@findex \e 204055839Sasmodai@findex \E 204155839SasmodaiIf you want to have a backslash appear in your output, you can use several 204255839Sasmodaiescapes: @code{\\}, @code{\e} or @code{\E}. 204355839SasmodaiThese are very similar, and only differ with respect to being used in 204455839Sasmodaimacros or diversions (@xref{Copy-in Mode}, and @ref{Diversions}, for 204555839Sasmodaimore information) 204655839Sasmodai 204755839Sasmodai 204855839Sasmodai 204955839Sasmodai@c distribute these through the text 205055839Sasmodai@xref{Identifiers} 205155839Sasmodai 205255839Sasmodai@menu 205355839Sasmodai* Comments:: 205455839Sasmodai@end menu 205555839Sasmodai 205655839Sasmodai@node Comments, , Escapes, Escapes 205755839Sasmodai@subsubsection Comments 205855839Sasmodai@cindex comments 205955839Sasmodai 206055839Sasmodai 206155839Sasmodai@findex \" 206255839SasmodaiProbably one of the most@footnote{Unfortunately, this is a lie. But 206355839Sasmodaihopefully future troff hackers will believe it :-)} 206455839Sasmodaicommon forms of escapes is the comment. 206555839SasmodaiThey begin with the @code{\"} escape and end at the end of the input 206655839Sasmodailine. 206755839Sasmodai 206855839SasmodaiThis may sound simple, but it can be tricky to keep the comments from 206955839Sasmodaiinterfering with the apperarance of your final outupt. 207055839Sasmodai 207155839SasmodaiIf the escape is to the right of some text or a request, that portion 207255839Sasmodaiof the line will be ignored, but the space leading up to it will be 207355839Sasmodainoticed by groff. This only affects the @code{.ds} request (any 207455839Sasmodaiothers?). 207555839Sasmodai 207655839SasmodaiOne possibly irritating idiosyncracy is that you mustn't use tabs to 207755839Sasmodailine up your comments. 207855839SasmodaiTabs are not treated as white space between request and macro 207955839Sasmodaiarguments. 208055839Sasmodai 208155839SasmodaiIf you have a comment on a line by itself, it will be treated as a 208255839Sasmodaiblank line, because after eliminating the comment, that is all that 208355839Sasmodairemains. So, it is common to start the line with @code{.\"} which 208455839Sasmodaiwill cause the line to be treated as an undefined request. 208555839Sasmodai 208655839SasmodaiAnother commenting scheme seen sometimes is three consecutive single 208755839Sasmodaiquotes (@code{'''}) at the begining of a line. This works, but groff 208855839Sasmodaiwill give a warning about an undefined macro, which is harmless, but 208955839Sasmodaiirritating. 209055839Sasmodai 209155839Sasmodai@findex \# 209255839SasmodaiNow to avoid all this groff has a new comment mechanism using the 209355839Sasmodai@code{\#} escape. This escape works the same as @code{\"} except 209455839Sasmodaithat the newline is also ignored. 209555839Sasmodai 209655839Sasmodai@findex ig 209755839SasmodaiFor large blocks of text, the @code{ig} request may be useful. 209855839Sasmodai@c distribute these through the text 209955839Sasmodai@xref{Strings} 210055839Sasmodai 210155839Sasmodai@node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial 210255839Sasmodai@section Registers 210355839Sasmodai@cindex registers 210455839Sasmodai 210555839Sasmodai 210655839SasmodaiRegisters are groff's numeric variables. groff has a number of 210755839Sasmodaibuiltin registers, supplying anything from the date to details of 210855839Sasmodaiformatting parameters. 210955839Sasmodai 211055839Sasmodai@c distribute these through the text 211155839Sasmodai@xref{Identifiers} 211255839Sasmodai 211355839Sasmodai@menu 211455839Sasmodai* Setting Registers:: 211555839Sasmodai* Interpolating Registers:: 211655839Sasmodai* Auto-increment:: 211755839Sasmodai* Assigning Formats:: 211855839Sasmodai* Builtin Registers:: 211955839Sasmodai@end menu 212055839Sasmodai 212155839Sasmodai@node Setting Registers, Interpolating Registers, Registers, Registers 212255839Sasmodai@subsection Setting Registers 212355839Sasmodai@cindex setting registers 212455839Sasmodai@cindex registers, setting 212555839Sasmodai 212655839Sasmodai 212755839Sasmodai@findex nr 212855839Sasmodai@findex \R 212955839SasmodaiRegisters are defined/set via the @code{nr} 213055839Sasmodairequest or the @code{\R} escape, for example, the following two lines 213155839Sasmodaiare equivalent: 213255839Sasmodai 213355839Sasmodai@example 213455839Sasmodai.nr a 1 213555839Sasmodai\R'a 1' 213655839Sasmodai@end example 213755839Sasmodai 213855839Sasmodai@findex rr 213955839SasmodaiThe @code{rr} request will 214055839Sasmodairemove the register specified by the argument. 214155839Sasmodai 214255839Sasmodai@findex rnn 214355839SasmodaiThe @code{rnn} request will rename a number register. 214455839SasmodaiThe format is @samp{.rnn @var{x} @var{y}}, which will 214555839Sasmodairename number register @var{x} to @var{y}. 214655839Sasmodai 214755839Sasmodai@findex aln 214855839SasmodaiAliases can be created for a number register. The format is 214955839Sasmodai@samp{.aln @var{xx} @var{yy}}, which will create an alias @var{xx} for 215055839Sasmodainumber register object named @var{yy}. The new name and the old name 215155839Sasmodaiwill be exactly equivalent. If @var{yy} is undefined, a warning of 215255839Sasmodaitype @samp{reg} will be generated, and the request will be ignored. 215355839Sasmodai@xref{Debugging}, for information about warnings. 215455839Sasmodai 215555839Sasmodai 215655839Sasmodai@node Interpolating Registers, Auto-increment, Setting Registers, Registers 215755839Sasmodai@subsection Interpolating Registers 215855839Sasmodai@cindex interpolating registers 215955839Sasmodai@cindex registers, interpolating 216055839Sasmodai 216155839Sasmodai 216255839Sasmodai@findex \n 216355839SasmodaiNumeric registers are @dfn{interpolated} via the @code{\n} escape. 216455839Sasmodai@c the following is wrong. Should I say any more than the above?? 216555839Sasmodai@c This means that the value of the number register in expanded in-place 216655839Sasmodai@c on the input line before any other actions, i.e. before requests and 216755839Sasmodai@c escapes are interpreted. 216855839Sasmodai 216955839Sasmodai@example 217055839Sasmodai.nr as \na+\na 217155839Sasmodai\n(as 217255839Sasmodai@end example 217355839Sasmodai 217455839Sasmodai 217555839Sasmodai@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 217655839Sasmodai@subsection Auto-increment 217755839Sasmodai@cindex auto-increment 217855839Sasmodai@cindex increment, automatic 217955839Sasmodai 218055839SasmodaiNumber registers can also be auto incremented/decremented. You can 218155839Sasmodaispecify the increment/decrement factor with third argument to the 218255839Sasmodai@code{nr} request. The default value is 0. For example: 218355839Sasmodai 218455839Sasmodai@example 218555839Sasmodai.nr a 0 1 218655839Sasmodai.nr xx 0 5 218755839Sasmodai\n+a, \n+a, \n+a, \n+a, \n+a 218855839Sasmodai.br 218955839Sasmodai\n+(xx, \n+(xx, \n+(xx, \n+(xx, \n+(xx 219055839Sasmodai@end example 219155839Sasmodai 219255839SasmodaiProduces: 219355839Sasmodai 219455839Sasmodai@example 219555839Sasmodai1, 2, 3, 4, 5 219655839Sasmodai5, 10, 15, 20, 25 219755839Sasmodai@end example 219855839Sasmodai 219955839SasmodaiIf you want to change the increment factor without changing the value 220055839Sasmodaiof a register, the following can be used. 220155839Sasmodai 220255839Sasmodai@example 220355839Sasmodai.nr a \na 10 220455839Sasmodai@end example 220555839Sasmodai 220655839Sasmodai 220755839Sasmodai@node Assigning Formats, Builtin Registers, Auto-increment, Registers 220855839Sasmodai@subsection Assigning Formats 220955839Sasmodai@cindex assigning formats 221055839Sasmodai@cindex formats, assigning 221155839Sasmodai 221255839Sasmodai 221355839Sasmodai@findex af 221455839SasmodaiWhen a register is used in the text of an input file 221555839Sasmodai(as opposed to part of an expression) 221655839Sasmodaiit is textually replaced (or interpolated) with a representation of 221755839Sasmodaithat number. 221855839SasmodaiThis output format can be changed to a variety of formats 221955839Sasmodai(numbers, roman numerals, etc) 222055839SasmodaiThis is done using the @code{af} request. 222155839SasmodaiThe first argument to @code{af} is the name of the number register to 222255839Sasmodaibe changed, 222355839Sasmodaiand the second argument is the output format. 222455839SasmodaiThe following output formats are available: 222555839Sasmodai 222655839Sasmodai@table @samp 222755839Sasmodai@item 1 222855839SasmodaiThis is the default format, decimal numbers: 222955839Sasmodai1, 2, 3, @dots{} 223055839Sasmodai@item 001 223155839SasmodaiDecimal numbers with as many leading zeros as specified. 223255839SasmodaiSo, @samp{001} would result in 001, 002, 003, @dots{} 223355839Sasmodai@item I 223455839Sasmodai@cindex roman numerals 223555839Sasmodai@cindex numerals, roman 223655839SasmodaiUpper-case roman numerals: 223755839Sasmodai0, I, II, III, IV, @dots{} 223855839Sasmodai@item i 223955839SasmodaiLower-case roman numerals: 224055839Sasmodai0, i, ii, iii, iv, @dots{} 224155839Sasmodai@item A 224255839SasmodaiUpper-case letters: 224355839SasmodaiA, B, C, @dots{}, Z, AA, AB, @dots{} 224455839Sasmodai@item a 224555839SasmodaiLower-case letters: 224655839Sasmodaia, b, c, @dots{}, z, aa, ab, @dots{} 224755839Sasmodai@end table 224855839Sasmodai 224955839SasmodaiThe following example will produce @samp{10, X, j, 010}. 225055839Sasmodai 225155839Sasmodai@example 225255839Sasmodai.nr a 10 225355839Sasmodai.af a 1 \" the default format 225455839Sasmodai\na, 225555839Sasmodai.af a I 225655839Sasmodai\na, 225755839Sasmodai.af a a 225855839Sasmodai\na, 225955839Sasmodai.af a 001 226055839Sasmodai\na 226155839Sasmodai@end example 226255839Sasmodai 226355839Sasmodai@findex \g 226455839SasmodaiThe @code{\g} escape returns the current format of the specified 226555839Sasmodairegister. For example, @samp{\ga} after the following example would 226655839Sasmodaiproduce @samp{001}. 226755839Sasmodai 226855839Sasmodai 226955839Sasmodai 227055839Sasmodai@node Builtin Registers, , Assigning Formats, Registers 227155839Sasmodai@subsection Builtin Registers 227255839Sasmodai@cindex builtin registers 227355839Sasmodai@cindex registers, builtin 227455839Sasmodai 227555839Sasmodai 227655839SasmodaiThe following are some builtin registers, which are not listed 227755839Sasmodaielsewhere in this manual. Any registers which begin with a @samp{.} 227855839Sasmodaiare read-only. A compleat listing of all builtin registers can be 227955839Sasmodaifound in @ref{Register Index}. 228055839Sasmodai 228155839Sasmodai@table @code 228255839Sasmodai@item .H 228355839Sasmodai@vindex .H 228455839SasmodaiHorizontal resolution in basic units. 228555839Sasmodai@item .V 228655839Sasmodai@vindex .V 228755839SasmodaiVertical resolution in basic units. 228855839Sasmodai@item dw 228955839Sasmodai@vindex dw 229055839SasmodaiDay of the week (1-7). 229155839Sasmodai@item dy 229255839Sasmodai@vindex dy 229355839SasmodaiDay of the year (1-31). 229455839Sasmodai@item mo 229555839Sasmodai@vindex mo 229655839SasmodaiCurrent month (1-12). 229755839Sasmodai@item yr 229855839Sasmodai@vindex yr 229955839SasmodaiLast two digits of the current year (see you in 7 years :-) 230055839Sasmodai@item .c 230155839Sasmodai@vindex .c 230255839Sasmodai@itemx c. 230355839Sasmodai@vindex c. 230455839SasmodaiThe current @emph{input} line number. 230555839Sasmodai@item ln 230655839Sasmodai@vindex ln 230755839SasmodaiThe current @emph{output} line number. 230855839Sasmodai@item .x 230955839Sasmodai@vindex .x 231055839SasmodaiThe major version number. For example, if the version number is 1.03 231155839Sasmodaithen @code{.x} will contain 1. 231255839Sasmodai@item .y 231355839Sasmodai@vindex .y 231455839SasmodaiThe minor version number. For example, if the version number is 1.03 231555839Sasmodaithen @code{.y} will contain 03. 231655839Sasmodai@item .g 231755839Sasmodai@vindex .g 231855839SasmodaiAlways 1. 231955839SasmodaiMacros should use this to determine whether they are running 232055839Sasmodaiunder GNU troff. 232155839Sasmodai@item .A 232255839Sasmodai@vindex .A 232355839SasmodaiIf the current output device is ascii, this is set to 1, 232455839Sasmodaizero otherwise. 232555839Sasmodai@item .P 232655839Sasmodai@vindex .P 232755839SasmodaiThis register indicates whether the current page is actualy being 232855839Sasmodaiprinted, i.e. if the @samp{-o} option is being used to only print 232955839Sasmodaiselected pages. 233055839Sasmodai@xref{Options}, for more information. 233155839Sasmodai@end table 233255839Sasmodai 233355839Sasmodai@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial 233455839Sasmodai@section Manipulating Filling and Adjusting 233555839Sasmodai@cindex manipulating filling and adjusting 233655839Sasmodai@cindex filling and adjusting, manipulating 233755839Sasmodai@cindex adjusting and filling, manipulating 233855839Sasmodai 233955839Sasmodai 234055839Sasmodai@findex br 234155839Sasmodai@cindex break 234255839Sasmodai@cindex line break 234355839SasmodaiSeveral ways of causing @dfn{breaks} were given in 234455839Sasmodai@ref{Implicit Line Breaks}. 234555839SasmodaiThe @code{br} request will likewise cause a break. 234655839SasmodaiSeveral other requests will also cause breaks, implicitly. 234755839SasmodaiThey are 234855839Sasmodai@code{bp}, 234955839Sasmodai@code{ce}, 235055839Sasmodai@code{fi}, 235155839Sasmodai@code{fl}, 235255839Sasmodai@code{in}, 235355839Sasmodai@code{nf}, 235455839Sasmodai@code{sp} and 235555839Sasmodai@code{ti}. 235655839Sasmodai 235755839Sasmodai@findex nf 235855839Sasmodai@findex fi 235955839Sasmodai@vindex .u 236055839SasmodaiInitially, groff will fill and ajust text to both margins. 236155839SasmodaiFilling can be disabled via the @code{nf} request 236255839Sasmodaiand re-enabled with the @code{fi} request. 236355839SasmodaiThese implicitly disable and re-enable adjusting. 236455839SasmodaiBoth of these will cause break in text currently being filled. 236555839SasmodaiThe number register @code{.u} is equal to 1 in fill mode and 0 in 236655839Sasmodaino-fill mode. 236755839Sasmodai 236855839Sasmodai@findex ad 236955839Sasmodai@findex na 237055839Sasmodai@vindex .j 237155839SasmodaiAdjusting can be disabled with the @code{ad} request and re-enabled 237255839Sasmodaiwith the @code{na} request. 237355839SasmodaiThe @code{ad} request takes a single argument to indicate how to 237455839Sasmodaiadjust text. 237555839SasmodaiThe current adjustment mode is available in the number register 237655839Sasmodai@code{.j}. 237755839Sasmodai 237855839Sasmodai@table @samp 237955839Sasmodai@item l 238055839Sasmodai@cindex ragged-right 238155839SasmodaiAdjust text to the left margin. This produces what is traditionally 238255839Sasmodaicalled ragged-right text. 238355839Sasmodai@item r 238455839SasmodaiAdjust text to the right margin. 238555839Sasmodai@item c 238655839SasmodaiCenter filled text. 238755839Sasmodai@item b 238855839Sasmodai@itemx n 238955839SasmodaiJustify to both margins. This is groff's default. 239055839Sasmodai@end table 239155839Sasmodai 239255839SasmodaiWith no argument to @code{ad}, troff will adjust lines the same way 239355839Sasmodaiit was the last time it was filling. For example: 239455839Sasmodai 239555839Sasmodai@example 239655839Sasmodaitext 239755839Sasmodai.ad r 239855839Sasmodaitext 239955839Sasmodai.ad c 240055839Sasmodaitext 240155839Sasmodai.na 240255839Sasmodaitext 240355839Sasmodai.ad \" back to centering 240455839Sasmodaitext 240555839Sasmodai@end example 240655839Sasmodai 240755839Sasmodai@findex \p 240855839SasmodaiThe escape @code{\p} will cause a break and cause the remaining text 240955839Sasmodaito be adjusted. 241055839Sasmodai 241155839Sasmodai@findex ss 241255839SasmodaiThe @code{ss} request allows you to change the minimum size of a 241355839Sasmodaispace between filled words. 241455839SasmodaiThis request takes it's units as one twelfth of the 241555839Sasmodaispacewidth parameter for the current font. Initially both the word 241655839Sasmodaispace size and the sentence space size are 12. 241755839Sasmodai 241855839SasmodaiWhen two arguments are given to the @code{ss} request, the second argument 241955839Sasmodaigives the sentence space size. If the second argument is not given, the 242055839Sasmodaisentence space size will be the same as the word space size. 242155839SasmodaiThe sentence space size 242255839Sasmodaiis used in two circumstances: if the end of a sentence occurs at the end 242355839Sasmodaiof a line in fill mode, then both an inter-word space and a sentence 242455839Sasmodaispace will be added; if two spaces follow the end of a sentence in the 242555839Sasmodaimiddle of a line, then the second space will be a sentence space. Note 242655839Sasmodaithat the behaviour of @sc{Unix} troff will be exactly that exhibited by GNU 242755839Sasmodaitroff if a second argument is never given to the @code{ss} request. In GNU 242855839Sasmodaitroff, as in @sc{Unix} troff, you should always follow a sentence with either 242955839Sasmodaia newline or two spaces. 243055839Sasmodai 243155839Sasmodai@vindex .ss 243255839Sasmodai@vindex .sss 243355839SasmodaiThe number registers @code{.ss} and @code{.sss} are 243455839Sasmodaithe values of the parameters set by the first and second 243555839Sasmodaiarguments of the @code{ss} request. 243655839Sasmodai 243755839Sasmodai@findex ce 243855839SasmodaiThe @code{ce} request will center text. 243955839SasmodaiWhile the @samp{ad c} request will also center text, it has the side 244055839Sasmodaieffect of filling the text. The @code{.ce} request will not fill the 244155839Sasmodaitext it affects. 244255839SasmodaiThis request causes a break. 244355839Sasmodai 244455839SasmodaiWith no arguments, @code{ce} will fill the next line of text. 244555839SasmodaiThe single argument @code{ce} takes is a number indicating the 244655839Sasmodainumber of lines to be centered. With no argument centering is 244755839Sasmodaidisabled. 244855839Sasmodai 244955839SasmodaiA common idiom is to turn on centering for a large number of lines, 245055839Sasmodaiand then turn off centering when you are done with the centered text. 245155839SasmodaiThis is useful for any request which takes a number of lines as an 245255839Sasmodaiargument. 245355839Sasmodai 245455839Sasmodai@example 245555839Sasmodai.ce 1000 245655839Sasmodaireplace this 245755839Sasmodaiwith 245855839Sasmodaisomething 245955839Sasmodaimore interesting 246055839Sasmodai@dots{} 246155839Sasmodai.ce 0 246255839Sasmodai@end example 246355839Sasmodai 246455839Sasmodai@vindex .ce 246555839SasmodaiThe @code{.ce} number register contains the number of lines remaining 246655839Sasmodaito be centered, as set by the @code{ce} request. 246755839Sasmodai 246855839Sasmodai 246955839Sasmodai@findex rj 247055839Sasmodai@vindex .rj 247155839SasmodaiA similar request is @code{rj} request which will justify unfilled 247255839Sasmodaitext to the right margin. Its arguments are identical to the 247355839Sasmodai@code{ce} request. 247455839SasmodaiThe @code{.rj} number register is 247555839Sasmodaithe number of lines to be right-justified as set by the @code{rj} 247655839Sasmodairequest. 247755839Sasmodai 247855839Sasmodai 247955839Sasmodai 248055839Sasmodai@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial 248155839Sasmodai@section Manipulating Hyphenation 248255839Sasmodai@cindex manipulating hyphenation 248355839Sasmodai@cindex hyphenation, manipulating 248455839Sasmodai 248555839Sasmodai 248655839SasmodaiAs discussed in @ref{Hyphenation}, groff will hyphenate words. 248755839SasmodaiThere are a number of ways to modify the how hyphenation is done. 248855839Sasmodai 248955839Sasmodai@findex nh 249055839Sasmodai@findex hy 249155839Sasmodai@vindex .hy 249255839SasmodaiThis hyphenation can be turned off with the @code{nh} request, and 249355839Sasmodaiturned back on with the @code{hy} request. However, troff's 249455839Sasmodaihyphenation facilities are far more flexible than this. The @code{hy} 249555839Sasmodairequest can be used to tell troff to restrict hypenation to certain 249655839Sasmodaicases. The request takes a single numeric argument. 249755839SasmodaiThe current hyphenation restrictions can be found in the number 249855839Sasmodairegister @code{.hy} 249955839Sasmodai 250055839Sasmodai@table @samp 250155839Sasmodai@item 1 250255839SasmodaiThe default argument, which 250355839Sasmodaiindicates to hyphenate without restrictions. 250455839Sasmodai@item 2 250555839SasmodaiDo not hyphenate the last word on a page or column. 250655839Sasmodai@item 4 250755839SasmodaiDo not hyphenate the last two characters of a word. 250855839Sasmodai@item 8 250955839SasmodaiDo not hyphenate the first two characters of a word. 251055839Sasmodai@end table 251155839Sasmodai 251255839Sasmodai@findex hlm 251355839Sasmodai@vindex .hlc 251455839Sasmodai@vindex .hlm 251555839SasmodaiThe @code{hlm} request will 251655839Sasmodaiset the maximum number of consecutive hyphenated lines to the value 251755839Sasmodaigiven as the first argument. 251855839SasmodaiIf this number is 251955839Sasmodainegative, there is no maximum. The default value is -1. 252055839SasmodaiThis value is 252155839Sasmodaiassociated with the current environment. Only lines output from an 252255839Sasmodaienvironment count towards the maximum associated with that environment. 252355839SasmodaiHyphens resulting from @code{\%} are counted; explicit hyphens are not. 252455839SasmodaiThe current setting of this is available in the @code{.hlm} request. 252555839SasmodaiAlso the number of immediately preceding consecutive hyphenated lines 252655839Sasmodaiare available in the number register @code{.hlc}. 252755839Sasmodai 252855839Sasmodai@findex hw 252955839SasmodaiThe @code{hw} request allows you to specify how a specific word is 253055839Sasmodaito be hyphenated. It takes only one argument which is the word with 253155839Sasmodaihyphens at the hyphenation points. For example: 253255839Sasmodai@samp{.hw in-sa-lub-rious}. 253355839Sasmodai@c In old versions of troff there was a 253455839Sasmodai@c limited amount of space to store such information, fortunately, 253555839Sasmodai@c with groff, this is no longer a restriction. 253655839Sasmodai 253755839Sasmodai@findex \% 253855839Sasmodai@cindex hyphenation character 253955839Sasmodai@cindex character, hyphenation 254055839SasmodaiYou can also tell troff how to hyphenate words on the fly with the 254155839Sasmodaiuse of the @code{\%} escape, also known as the @dfn{hyphenation 254255839Sasmodaicharacter}. Preceding a word with this character will prevent it 254355839Sasmodaifrom being hyphenated, putting it in a word will indicate to troff 254455839Sasmodaithat the word may be hyphenated at that point. Note that this 254555839Sasmodaimechanism will only affect one word, if you want to change the 254655839Sasmodaihyphenation of a word for the entire document, use the @code{hw} 254755839Sasmodairequest. 254855839Sasmodai 254955839Sasmodai@findex hc 255055839SasmodaiThe @code{hc} request allows you to change the hyphenation character. 255155839SasmodaiThe character specified as an argument will then work the same as the 255255839Sasmodai@code{\%} escape, and, thus, no longer appear in the output. Without 255355839Sasmodaian argument it will return the hyphenation character to @code{\%}. 255455839Sasmodai 255555839Sasmodai@findex hpf 255655839SasmodaiTo further customize hyphenation the @code{hpf} request will read in 255755839Sasmodaia file of hyphenation patterns. 255855839SasmodaiThis file will be searched for in the 255955839Sasmodaisame way that @file{tmac.@var{name}} is searched for when the 256055839Sasmodai@samp{-m@var{name}} option is specified. 256155839Sasmodai 256255839SasmodaiIt should have the same format as the argument to the 256355839Sasmodai\patterns primitive in @TeX{}; the letters appearing in this file are 256455839Sasmodaiinterpreted as hyphenation codes. 256555839SasmodaiA @samp{%} character in the patterns file 256655839Sasmodaiintroduces a comment that continues to the end of the line. 256755839Sasmodai 256855839Sasmodai@findex hla 256955839Sasmodai@findex hpf 257055839Sasmodai@pindex troffrc 257155839SasmodaiThe set of 257255839Sasmodaihyphenation patterns is associated with the current language set by the 257355839Sasmodai@code{hla} request. The @code{hpf} request is usually invoked by the 257455839Sasmodai@file{troffrc} file. 257555839Sasmodai 257655839Sasmodai@findex hcode 257755839Sasmodai@code{.hcode @var{c1 code1 c2 code2...}} 257855839SasmodaiSet the hyphenation code of character @var{c1} to code1 and that of 257955839Sasmodai@var{c2} to @var{code2}. 258055839SasmodaiA hyphenation code must be a single input character (not a 258155839Sasmodaispecial character) other than a digit or a space. Initially each 258255839Sasmodailower-case letter has a hyphenation code, which is itself, and each 258355839Sasmodaiupper-case letter has a hyphenation code which is the lower case 258455839Sasmodaiversion of itself. 258555839Sasmodai 258655839Sasmodai@findex hym 258755839Sasmodai@vindex .hym 258855839SasmodaiThe @code{hym} request will set the hyphenation margin to the value 258955839Sasmodaigiven as the first argument: when the current adjustment mode is not 259055839Sasmodai@samp{b}, the line will not be hyphenated if the line is no more than 259155839Sasmodaithat amount short. 259255839SasmodaiThe default hyphenation margin is 0. The default scaling 259355839Sasmodaiindicator for this request is m. The hyphenation margin is associated 259455839Sasmodaiwith the current environment. The current hyphenation margin is 259555839Sasmodaiavailable in the @code{.hym} register. 259655839Sasmodai 259755839Sasmodai@findex hys 259855839Sasmodai@vindex .hys 259955839SasmodaiThe @code{hys} request set the hyphenation space to the value given as 260055839Sasmodaithe first argument: when the current adjustment mode is b, don't 260155839Sasmodaihyphenate the line if the line can be justified by adding no more than 260255839Sasmodaithat amount of extra space to each word space. The default 260355839Sasmodaihyphenation space is 0. The default scaling indicator for this 260455839Sasmodairequest is m. The hyphenation space is associated with the current 260555839Sasmodaienvironment. The current hyphenation space is available in the 260655839Sasmodai@code{.hys} register. 260755839Sasmodai 260855839Sasmodai@findex shc 260955839SasmodaiThe @code{shc} request will set the soft hyphen character to the 261055839Sasmodaiargument given as an argument. If the argument is omitted, the soft 261155839Sasmodaihyphen character will be set to the default @code{\(hy}. The soft 261255839Sasmodaihyphen character is the character which will be inserted when a word 261355839Sasmodaiis hyphenated at a line break. If the soft hyphen character does not 261455839Sasmodaiexist in the font of the character immediately preceding a potential 261555839Sasmodaibreak point, then the line will not be broken at that point. Neither 261655839Sasmodaidefinitions (specified with the @code{char} request) nor translations 261755839Sasmodai(specified with the @code{tr} request) are considered when finding the soft 261855839Sasmodaihyphen character. 261955839Sasmodai 262055839Sasmodai@findex hla 262155839Sasmodai@vindex .hla 262255839Sasmodai@pindex troffrc 262355839SasmodaiThe @code{hla} request will set the current hyphenation language to 262455839Sasmodaithat given by the first argument. Hyphenation exceptions specified 262555839Sasmodaiwith the @code{hw} request and hyphenation patterns specified with the 262655839Sasmodai@code{hpf} request are both associated with the current hyphenation 262755839Sasmodailanguage. The @code{hla} request is usually invoked by the 262855839Sasmodai@file{troffrc} file. The current hyphenation language is available 262955839Sasmodaiin the number register @code{.hla}. 263055839Sasmodai 263155839Sasmodai 263255839Sasmodai 263355839Sasmodai@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial 263455839Sasmodai@section Manipulating Spacing 263555839Sasmodai@cindex manipulating spacing 263655839Sasmodai@cindex spacing, manipulating 263755839Sasmodai 263855839Sasmodai 263955839Sasmodai@findex sp 264055839SasmodaiThe @code{sp} request will cause troff to space downwards the 264155839Sasmodaidistance specified as the first argument. With no argument it will 264255839Sasmodaiadvance 1 line. 264355839SasmodaiA negative argument will cause troff to move up the page the 264455839Sasmodaispecified distance. 264555839SasmodaiIf the argument is preceded by a @samp{|} troff will move that 264655839Sasmodaidistance from the top of the page. 264755839Sasmodai 264855839Sasmodai@findex ls 264955839Sasmodai@vindex .L 265055839SasmodaiOften you may want your output to be double or triple spaced. 265155839SasmodaiThe @code{ls} request will cause troff to output @var{n}-1 blank 265255839Sasmodailines after each line of text, where @var{n} is the argument given to 265355839Sasmodaithe @code{ls} request. With no argument troff will go back to single 265455839Sasmodaispacing. The number register @code{.L} contains the current line 265555839Sasmodaispacing setting. 265655839Sasmodai 265755839Sasmodai@findex \x 265855839Sasmodai@vindex .a 265955839SasmodaiSometimes, extra vertical spacing is only needed occasionaly, 266055839Sasmodaii.e. to allow space for a tall construct (like an equation). 266155839SasmodaiThe @code{\x} escape will do this. 266255839SasmodaiThe escape is given a numerical argument (like @samp{\x'3p'}). 266355839SasmodaiIf this number is positive extra vertical space will be inserted 266455839Sasmodaibelow the current line. A negative number will add space above. 266555839SasmodaiIf this escape is used multiple times on the same line, the maximum 266655839Sasmodaivalues are used. 266755839SasmodaiThe @code{.a} number register contains the most recent 266855839Sasmodaiextra vertical @strong{emph} line space. 266955839Sasmodai 267055839Sasmodai@example 267155839Sasmodai... example of inline equation ... 267255839Sasmodai@end example 267355839Sasmodai 267455839Sasmodai@findex ns 267555839Sasmodai@findex rs 267655839Sasmodai@cindex no-space mode 267755839Sasmodai@cindex mode, no-space 267855839SasmodaiSpacing (via either @code{sp} or via blank lines) can be disabled 267955839Sasmodaiwith the @code{ns} request. This will enable @dfn{no-space mode}. 268055839SasmodaiThis mode will end when actual text is output or the @code{rs} 268155839Sasmodairequest is encountered. No-space mode will also prevent requests to 268255839Sasmodaiadvance to the next page unless they are accompanied by a page number 268355839Sasmodai(@pxref{Page Control}, for more information.) 268455839Sasmodai 268555839Sasmodai 268655839Sasmodai@node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial 268755839Sasmodai@section Tabs and Fields 268855839Sasmodai@cindex tabs and fields 268955839Sasmodai@cindex fields and tabs 269055839Sasmodai 269155839Sasmodai 269255839Sasmodai@findex \t 269355839SasmodaiTab stops are much like those on a typewriter: a tab character (or the 269455839Sasmodai@code{\t} escape) on input will cause horizontal motion to the next 269555839Sasmodaitab stop. 269655839Sasmodai 269755839Sasmodai@findex ta 269855839SasmodaiTab stops can be changed with the @code{ta} request. 269955839SasmodaiThis request takes a series of numbers as arguments which indicate 270055839Sasmodaiwhere each tab stop is to be (overriding any previous settings). 270155839SasmodaiThese can be specified absolutely, 270255839Sasmodaii.e. as the distance from the left margin. 270355839SasmodaiFor example, the following wil set tab stops every one inch. 270455839Sasmodai 270555839Sasmodai@example 270655839Sasmodai.ta 1i 2i 3i 4i 5i 6i 270755839Sasmodai@end example 270855839Sasmodai 270955839SasmodaiTab stops can also be specified relatively (using a leading @samp{+}) 271055839Sasmodaiwhich means that the specified tab stop will be set that distance 271155839Sasmodaifrom the previous tab stop. For example the following is equivalent 271255839Sasmodaito the previous example. 271355839Sasmodai 271455839Sasmodai@example 271555839Sasmodai.ta 1i +1i +1i +1i +1i +1i 271655839Sasmodai@end example 271755839Sasmodai 271855839SasmodaiAfter the specified tab stops repeat values may be set for tabs beyond 271955839Sasmodaithe last one specified. This is most commonly used to specify tabs 272055839Sasmodaiset at equal intervals. The compleat syntax for setting tabs is 272155839Sasmodai@code{ta @var{n1} @var{n2} @dots{} @var{nn} T @var{r1} @var{r2} 272255839Sasmodai@dots{} @var{rn}} This will set tabs at positions @var{n1}, @var{n2}, 272355839Sasmodai@dots{}, @var{nn} and then set tabs at @var{nn}+@var{r1}, 272455839Sasmodai@var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} and then at 272555839Sasmodai@var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, @dots{}, 272655839Sasmodai@var{nn}+@var{rn}+@var{rn}, and so on. For example the following is, 272755839Sasmodaiyet again, the same as the previous examples. 272855839Sasmodai 272955839Sasmodai@example 273055839Sasmodai.ta T 1i 273155839Sasmodai@end example 273255839Sasmodai 273355839SasmodaiThe material in each tab column may be justified to the right or left 273455839Sasmodaior centered in the column. This is specified by appending an 273555839Sasmodai@samp{R}, @samp{L} or @samp{C} to the number specifying that tab stop. 273655839SasmodaiThe default justification is @samp{L}. 273755839Sasmodai 273855839Sasmodai@example 273955839Sasmodai.ta 1i 2iC 2iR 274055839Sasmodai@end example 274155839Sasmodai 274255839Sasmodai@vindex .tabs 274355839SasmodaiThe number register @code{.tabs} contains 274455839Sasmodaia string representation of the current tab settings suitable for use as 274555839Sasmodaian argument to the @code{ta} request. 274655839Sasmodai 274755839Sasmodai@findex tc 274855839SasmodaiNormally troff will fill the space to the next tab stop with spaces. 274955839SasmodaiIn some cases you may wish to change this. The @code{tc} request 275055839Sasmodaiwill do this. With no argument troff will revert to using spaces. 275155839Sasmodai 275255839Sasmodai@subsection Leaders 275355839Sasmodai@cindex leaders 275455839Sasmodai 275555839Sasmodai@findex lc 275655839SasmodaiSometimes you may wish to use the @code{tc} request to fill a tab 275755839Sasmodaistop with a given character, but also, you want to use normal tab 275855839Sasmodaistops on the rest of the line. For this groff provides an alternate 275955839Sasmodaitab mechanism, called @dfn{leaders} which will do just that. 276055839SasmodaiThey are used exclusively to produce a repeated run of characters to 276155839Sasmodaithe next tab stop. 276255839Sasmodai 276355839SasmodaiYou can declare what character will be repeated with the @code{lc} 276455839Sasmodairequest. If you do not give it an argument, the leaders will act the 276555839Sasmodaisame as tabs. 276655839Sasmodai 276755839Sasmodai@findex \a 276855839SasmodaiThe difference is that a leader is invoked by using the @code{\a} 276955839Sasmodaiescape. 277055839Sasmodai 277155839Sasmodai@cindex table of contents 277255839Sasmodai@cindex contents, table of 277355839SasmodaiSo for a table of contents you may want to have tab stops defined so 277455839Sasmodaithat the section number is one tab stop, the title is the second with 277555839Sasmodaithe remaining space being filled with a line of dots and then the 277655839Sasmodaipage number slightly separated from the dots. 277755839Sasmodai 277855839Sasmodai@example 277955839Sasmodai.lc . 278055839Sasmodai.ta .5iR 5i +.25i 278155839Sasmodai1.1\tFoo\a\t12 278255839Sasmodai@end example 278355839Sasmodai 278455839Sasmodai@subsection Fields 278555839Sasmodai@cindex fields 278655839Sasmodai 278755839Sasmodai@findex fc 278855839SasmodaiFields are a more general way of laying out tabular data. 278955839Sasmodai@code{fc} 279055839Sasmodai 279155839Sasmodai@node Character Translations, Line Layout, Tabs and Fields, Programming Tutorial 279255839Sasmodai@section Character Translations 279355839Sasmodai@cindex character translations 279455839Sasmodai@cindex translations of characters 279555839Sasmodai 279655839Sasmodai 279755839Sasmodai@findex cc 279855839Sasmodai@findex c2 279955839SasmodaiThe control character (@samp{.}) and the no-break control character 280055839Sasmodai(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 280155839Sasmodairespectively. 280255839SasmodaiThe single argument is the new character to be used, with no argument 280355839Sasmodaithe normal control character is restored. 280455839Sasmodai 280555839Sasmodai@findex ec 280655839Sasmodai@findex eo 280755839SasmodaiThe @code{eo} request will compleatly disable the escape mechanism. 280855839SasmodaiThe @code{ec} request can be used to change the escape character from 280955839Sasmodaithe default @samp{\} to what is specified as an argument. 281055839Sasmodai 281155839Sasmodai@findex tr 281255839SasmodaiThe @code{tr} request will translate characters. 281355839Sasmodai 281455839Sasmodai@findex trnt 281555839Sasmodai@findex \! 281655839Sasmodai@code{trnt} 281755839SasmodaiThis is the same as the @code{tr} request except that the 281855839Sasmodaitranslations do not 281955839Sasmodaiapply to text that is transparently throughput into a diversion with 282055839Sasmodai@code{\!}. @xref{Diversions}, for more information. 282155839SasmodaiFor example, 282255839Sasmodai 282355839Sasmodai@example 282455839Sasmodai.tr ab 282555839Sasmodai.di x 282655839Sasmodai\!.tm a 282755839Sasmodai.di 282855839Sasmodai.x 282955839Sasmodai@end example 283055839Sasmodai 283155839Sasmodaiwill print @samp{b}; if @code{trnt} is used instead of @code{tr} it 283255839Sasmodaiwill print @samp{a}. 283355839Sasmodai 283455839Sasmodai 283555839Sasmodai@node Line Layout, Page Layout, Character Translations, Programming Tutorial 283655839Sasmodai@section Line Layout 283755839Sasmodai@cindex line layout 283855839Sasmodai@cindex layout, line 283955839Sasmodai 284055839Sasmodai 284155839Sasmodai@cindex dimensions, line 284255839Sasmodai@cindex line dimensions 284355839SasmodaiThe following drawing shows the dimensions which troff uses for 284455839Sasmodaiplacing a line of output onto the page. They are labeled with the 284555839Sasmodairequest which manipulates that dimension. 284655839Sasmodai 284755839Sasmodai@example 284855839Sasmodai@group 284955839Sasmodai | -->| in |<-- | 285055839Sasmodai -->| po |<-----------ll------------>| 285155839Sasmodai +----+----+----------------------+----+ 285255839Sasmodai | : : : | 285355839Sasmodai +----+----+----------------------+----+ 285455839Sasmodai@end group 285555839Sasmodai@end example 285655839Sasmodai 285755839SasmodaiThese dimensions are: 285855839Sasmodai 285955839Sasmodai@ftable @code 286055839Sasmodai@item po 286155839Sasmodai@vindex .o 286255839Sasmodai@dfn{Page offset}--This is the leftmost postition of text on the final 286355839Sasmodaioutput. This can be adjusted with the @code{po} request, and the 286455839Sasmodaicurrent setting can be found in the builtin number register @code{.o} 286555839SasmodaiNote, that this request does not cause a break, so changing the page 286655839Sasmodaioffset in the middle of text being filled may not do what you expect. 286755839Sasmodai@item in 286855839Sasmodai@vindex .i 286955839Sasmodai@dfn{Indentation}--This is the distance from the left margin where text 287055839Sasmodaiwill be printed. This can be adjusted with the @code{in} request, and 287155839Sasmodaithe current setting can be found in the builtin number register. 287255839Sasmodai@code{.i} 287355839SasmodaiThis request causes a break. 287455839Sasmodai 287555839Sasmodai@findex ti 287655839Sasmodai@findex .in 287755839SasmodaiThere is also the request @code{ti} which will cause one output line 287855839Sasmodaito be indented, after which the indentation returns to 0. 287955839SasmodaiThis request causes a break. 288055839SasmodaiThe number register @code{.in} is the indent that applies to the 288155839Sasmodaicurrent output line. 288255839Sasmodai@item ll 288355839Sasmodai@findex .l 288455839Sasmodai@findex .ll 288555839Sasmodai@dfn{Line length}--This is the distance from the left margin to right 288655839Sasmodaimargin. This can be adjusted with the @code{.ll} request, and the 288755839Sasmodaicurrent setting can be found in the builtin number register @code{.l} 288855839SasmodaiNote, as the figure implies, line length is not affected by the current 288955839Sasmodaiindentation. 289055839SasmodaiThe number register @code{.ll} is 289155839Sasmodaithe line length that applies to the current output line. 289255839Sasmodai@end ftable 289355839Sasmodai 289455839Sasmodai@example 289555839Sasmodai.in +.5i 289655839Sasmodai.ll -.5i 289755839SasmodaiA bunch of really boring text which should 289855839Sasmodaibe indented from both margins. 289955839Sasmodaireplace me with a better (and more) example! 290055839Sasmodai.in -.5i 290155839Sasmodai.ll +.5i 290255839Sasmodai@end example 290355839Sasmodai 290455839Sasmodai 290555839Sasmodai@node Page Layout, Page Control, Line Layout, Programming Tutorial 290655839Sasmodai@section Page Layout 290755839Sasmodai@cindex page layout 290855839Sasmodai@cindex layout, page 290955839Sasmodai 291055839Sasmodai 291155839SasmodaiTroff provides some very primitive operations for controlling page 291255839Sasmodailayout. 291355839Sasmodai 291455839Sasmodai@findex pl 291555839Sasmodai@vindex .p 291655839SasmodaiTroff lets you specify the @dfn{page length} via the @code{pl} request. 291755839SasmodaiThis is the length of the physical output page. 291855839SasmodaiThe current setting can 291955839Sasmodaibe found in the builtin number register @code{.p}. Note that this only 292055839Sasmodaispecifies the size of the page, not the not the top and bottom margins. 292155839SasmodaiThose are not done by groff directly, @xref{Traps}, for further 292255839Sasmodaiinformation on how to do this. 292355839Sasmodai 292455839Sasmodai@cindex headers 292555839Sasmodai@cindex footers 292655839Sasmodai@cindex titles 292755839SasmodaiTroff provides several operations which help in setting up top and 292855839Sasmodaibottom titles (or headers and footers) 292955839Sasmodai 293055839Sasmodai@findex tl 293155839SasmodaiThe @code{tl} request will print a @dfn{title line}, which consists 293255839Sasmodaiof three parts: a left justified portion, a centered portion and a 293355839Sasmodairight justified portion. The argument to @code{tl} is specified as 293455839Sasmodai@code{'@var{left}'@var{center}'@var{right}'} 293555839SasmodaiThe @samp{%} character is replaced with the current page number. 293655839Sasmodai 293755839Sasmodai@findex lt 293855839Sasmodai@vindex .lt 293955839SasmodaiThe title line is printed using its own line length, which is 294055839Sasmodaispecified with the @code{lt} request. The current setting of this is 294155839Sasmodaiavailable in the @code{.lt} number register. 294255839Sasmodai 294355839Sasmodai@findex pn 294455839SasmodaiThe @code{pn} request will change the page number of the @emph{next} 294555839Sasmodaipage. The only argument is the page number. 294655839Sasmodai 294755839Sasmodai@vindex % 294855839Sasmodai@vindex .pn 294955839SasmodaiThe current page number is stored in the number register @code{%}. 295055839SasmodaiThe number register @code{.pn} contains the 295155839Sasmodainumber of the next page: 295255839Sasmodaieither the value set by a @code{pn} request, or 295355839Sasmodaithe number of the current page plus 1. 295455839Sasmodai 295555839Sasmodai@findex pc 295655839SasmodaiThe @code{pc} request will change the page number character (used by 295755839Sasmodaithe @code{tl} request) to a different character. With no argument, 295855839Sasmodaithis mechanism is disabled. 295955839Sasmodai 296055839Sasmodai 296155839Sasmodai@c distribute these through the text 296255839Sasmodai@xref{Traps} 296355839Sasmodai 296455839Sasmodai@node Page Control, Fonts, Page Layout, Programming Tutorial 296555839Sasmodai@section Page Control 296655839Sasmodai@cindex page control 296755839Sasmodai@cindex control, page 296855839Sasmodai 296955839Sasmodai 297055839Sasmodai@findex bp 297155839SasmodaiTo stop processing the current page, and move to the next page, you 297255839Sasmodaican invoke the @code{bp} request. This request will also cause a 297355839Sasmodaibreak. This request can also take an argument of what the next page 297455839Sasmodaishould be numbered. 297555839SasmodaiThe only difference 297655839Sasmodaibetween @code{bp} and @code{pn} is that @code{pn} does not cause a 297755839Sasmodaibreak or actually eject a page. 297855839Sasmodai 297955839Sasmodai@example 298055839Sasmodai.de newpage 298155839Sasmodai'bp 298255839Sasmodai'sp .5i 298355839Sasmodai.tl 'left top'center top'right top' 298455839Sasmodai'sp .3i 298555839Sasmodai.. 298655839Sasmodai@end example 298755839Sasmodai 298855839Sasmodai@cindex orphan 298955839Sasmodai@findex ne 299055839SasmodaiOften you may want to make sure that you have a certain amount of 299155839Sasmodaispace before a new page occurs. This is most useful to make sure 299255839Sasmodaithat there is not a single @dfn{orphan} line left at the bottom of a 299355839Sasmodaipage. The @code{ne} request will ensure that there is a certain 299455839Sasmodaidistance, specified by the first argument, before the next page is 299555839Sasmodaitriggered (@pxref{Traps}, for further information). 299655839SasmodaiThe default unit for @code{ne} is v's and the default argument 299755839Sasmodaiis 1v. 299855839Sasmodai 299955839SasmodaiFor example, to make sure that no fewer than 2 lines get orphaned, 300055839Sasmodaiyou can do the following before each paragraph. 300155839Sasmodai 300255839Sasmodai@example 300355839Sasmodai.ne 2 300455839Sasmodai.ti +5n 300555839Sasmodaitext 300655839Sasmodai@end example 300755839Sasmodai 300855839Sasmodai@findex sv 300955839Sasmodai@findex os 301055839SasmodaiThe @code{sv} is similar to the @code{ne} request, it reserves the 301155839Sasmodaispecified amount of vertical space. If the desired amount of space 301255839Sasmodaiexists before the next trap (bottom page boundary), the space will be 301355839Sasmodaioutput immediately. If there is not enough space, it is stored for 301455839Sasmodailater output via the @code{os} request. 301555839SasmodaiThe default argument is 1v and the default units are v's. 301655839Sasmodai 301755839Sasmodai 301855839Sasmodai@node Fonts, Sizes, Page Control, Programming Tutorial 301955839Sasmodai@section Fonts 302055839Sasmodai@cindex fonts 302155839Sasmodai 302255839Sasmodai 302355839Sasmodai@findex ft 302455839Sasmodai@findex \f 302555839SasmodaiGroff gives you the ability to switch fonts at any point in your 302655839Sasmodaitext. There are two ways to do this, via the @code{ft} request and 302755839Sasmodaithe @code{\f} escape. 302855839Sasmodai 302955839SasmodaiFonts are generaly specified as uppercase strings, which are usually 303055839Sasmodai1 to 4 characters representing an abreviation of acronym of the font 303155839Sasmodainame. 303255839Sasmodai 303355839SasmodaiThe basic set of fonts are R, I, B, and BI. These are Times Roman, 303455839SasmodaiItalic, Bold, and Bold Italic. There is also at least one symbol 303555839Sasmodaifont which contains various special symbols (greek, mathematics). 303655839SasmodaiThese latter fonts cannot be used directly, but should be used via an 303755839Sasmodaiescape. 303855839Sasmodai 303955839Sasmodai 304055839Sasmodai@menu 304155839Sasmodai* Changing Fonts:: 304255839Sasmodai* Font Families:: 304355839Sasmodai* Font Positions:: 304455839Sasmodai* Using Symbols:: 304555839Sasmodai* Artificial Fonts:: 304655839Sasmodai* Ligatures and Kerning:: 304755839Sasmodai@end menu 304855839Sasmodai 304955839Sasmodai@node Changing Fonts, Font Families, Fonts, Fonts 305055839Sasmodai@subsection Changing Fonts 305155839Sasmodai@cindex changing fonts 305255839Sasmodai@cindex fonts, changing 305355839Sasmodai 305455839Sasmodai 305555839Sasmodai@findex ft 305655839SasmodaiYou can change fonts with both the @code{ft} request. 305755839SasmodaiWith no arguments it 305855839Sasmodaiwill switch to the previous font (also known as P). 305955839Sasmodai 306055839Sasmodai@example 306155839Sasmodaieggs, bacon, 306255839Sasmodai.ft B 306355839Sasmodaispam 306455839Sasmodai.ft 306555839Sasmodaiand sausage. 306655839Sasmodai@end example 306755839Sasmodai 306855839Sasmodai@findex \f 306955839SasmodaiThe @code{\f} escape is useful for changing fonts in the middle of words 307055839Sasmodai 307155839Sasmodai@example 307255839Sasmodaieggs, bacon, \fBspam\fP and sausage. 307355839Sasmodai@end example 307455839Sasmodai 307555839SasmodaiBoth of the above examples will produce the same output. 307655839Sasmodai 307755839SasmodaiSometimes when putting letters of different fonts, you need more or 307855839Sasmodailess space at such boundaries. There are two escapes to help with 307955839Sasmodaithis. 308055839Sasmodai 308155839Sasmodai@findex \/ 308255839SasmodaiThe @code{\/} escape 308355839Sasmodaiincreases the width of the preceding character so that the spacing 308455839Sasmodaibetween that character and the following character will be correct if 308555839Sasmodaithe following character is a roman character. For example, if an italic 308655839Sasmodaif is immediately followed by a roman right parenthesis, then in many 308755839Sasmodaifonts the top right portion of the f will overlap the top left of the 308855839Sasmodairight parenthesis. 308955839SasmodaiIt is a good idea to use this escape sequence 309055839Sasmodaiwhenever an italic character is immediately followed by a roman 309155839Sasmodaicharacter without any intervening space. 309255839Sasmodai 309355839Sasmodai@c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids this problem. 309455839Sasmodai 309555839Sasmodai@findex \, 309655839SasmodaiThe @code{\,} escape 309755839Sasmodaimodifies the spacing of the following character so that the spacing 309855839Sasmodaibetween that character and the preceding character will correct if the 309955839Sasmodaipreceding character is a roman character. 310055839SasmodaiIt is a good idea 310155839Sasmodaito use this escape sequence whenever a roman character is immediately 310255839Sasmodaifollowed by an italic character without any intervening space. 310355839Sasmodai 310455839Sasmodai@c For example, inserting \, between the parenthesis and the f changes (f to (f. 310555839Sasmodai 310655839Sasmodai@findex ftr 310755839SasmodaiThe @code{ftr} request will translate fonts, it is called as 310855839Sasmodai@samp{.ftr @var{F G}}, which 310955839SasmodaiTranslate font @var{F} to @var{G}. 311055839SasmodaiWhenever a font named @var{F} is referred to in @code{\f} 311155839Sasmodaiescape sequence, 311255839Sasmodaior in the @code{ft}, @var{ul}, @var{bd}, @var{cs}, @var{tkf}, 311355839Sasmodai@var{special}, @var{fspecial}, @var{fp}, 311455839Sasmodaior @var{sty} requests, font @var{G} will be used. If @var{G} is 311555839Sasmodaimissing, or equal to @var{F} then font @var{F} will not be translated. 311655839Sasmodai 311755839Sasmodai 311855839Sasmodai@node Font Families, Font Positions, Changing Fonts, Fonts 311955839Sasmodai@subsection Font Families 312055839Sasmodai@cindex font families 312155839Sasmodai@cindex families, font 312255839Sasmodai 312355839Sasmodai 312455839SasmodaiDue to the variety of fonts available, groff has added the concept of 312555839Sasmodaifont families. Each of these families has four styles (R, I, B and BI), 312655839Sasmodai 312755839SasmodaiThe fonts are specified as the concatenation of the font family and 312855839Sasmodaistyle. Specifying a font without the family part will cause groff to 312955839Sasmodaiuse that style of the current family. 313055839SasmodaiBy default, groff uses the Times family. 313155839Sasmodai 313255839SasmodaiThis way, you can just use the basic four fonts and select a 313355839Sasmodaidifferent font family on the command line. 313455839Sasmodai 313555839Sasmodai@findex fam 313655839Sasmodai@vindex .fam 313755839SasmodaiYou can also switch font families with the @code{fam} request 313855839SasmodaiThe current font family is available in the number register 313955839Sasmodai@code{.fam}. 314055839SasmodaiThis is a string-valued register. 314155839Sasmodai 314255839Sasmodai@example 314355839Sasmodaispam, 314455839Sasmodai.fam H 314555839Sasmodaispam, 314655839Sasmodai.ft B 314755839Sasmodaispam, 314855839Sasmodai.fam T 314955839Sasmodaispam, 315055839Sasmodai.ft AR 315155839Sasmodaibaked beans, 315255839Sasmodai.ft R 315355839Sasmodaiand spam. 315455839Sasmodai@end example 315555839Sasmodai 315655839Sasmodai 315755839Sasmodai 315855839Sasmodai@node Font Positions, Using Symbols, Font Families, Fonts 315955839Sasmodai@subsection Font Positions 316055839Sasmodai@cindex font positions 316155839Sasmodai@cindex positions, font 316255839Sasmodai 316355839Sasmodai 316455839SasmodaiFor the sake of old phototypesetters and compatability with old 316555839Sasmodaiversions of troff, groff has the concept of font 316655839Sasmodai@dfn{positions}, on which various fonts are mounted. 316755839SasmodaiThe last one or two are reserved for the symbol font(s). 316855839Sasmodai 316955839Sasmodai@findex fp 317055839SasmodaiNew fonts can be mounted with the @code{fp} request. 317155839SasmodaiThese numeric positions can then be referred to with font changing commands. 317255839SasmodaiWhen groff starts it is using font number one. 317355839Sasmodai 317455839Sasmodai@example 317555839Sasmodai.fp 1 H 317655839Sasmodai.fp 2 HI 317755839Sasmodai.fp 3 HB 317855839Sasmodaiwink, wink, 317955839Sasmodai.ft 2 318055839Sasmodainudge, nudge, 318155839Sasmodai.ft 318255839Sasmodai.ft 3 318355839Sasmodaisay no more! 318455839Sasmodai.ft 318555839Sasmodai@end example 318655839Sasmodai 318755839Sasmodai(note that after these font changes have taken place the original 318855839Sasmodaifont is restored.) 318955839Sasmodai 319055839Sasmodai@vindex .f 319155839SasmodaiThe current font in use, as a font position. 319255839SasmodaiThis can be useful to remember the current font, for later recall. 319355839Sasmodai 319455839Sasmodai@example 319555839Sasmodai.nr save-font \n(.f 319655839Sasmodai... lots 'o text ... 319755839Sasmodai.ft \n[save-font] 319855839Sasmodai@end example 319955839Sasmodai 320055839Sasmodai@vindex .fp 320155839SasmodaiThe number of the next free font position is available in the number 320255839Sasmodairegister @code{.fp}. This is useful when mounting a new font, like so: 320355839Sasmodai 320455839Sasmodai@example 320555839Sasmodai.fp \n[.fp] NEATOFONT 320655839Sasmodai@end example 320755839Sasmodai 320855839Sasmodai@pindex DESC 320955839SasmodaiFonts not listed in the @file{DESC} file are automatically mounted on 321055839Sasmodaithe next available font position when they are referenced. 321155839SasmodaiIf a font is to be 321255839Sasmodaimountfed explicitly with the @code{fp} request on an unused font position, it 321355839Sasmodaishould be mounted on the first unused font position, which can be found 321455839Sasmodaiin the @code{.fp} register; although troff does not enforce this strictly, 321555839Sasmodaiit will not allow a font to be mounted at a position whose number is 321655839Sasmodaimuch greater than that of any currently used position. 321755839Sasmodai 321855839SasmodaiThe @code{fp} request has an optional third argument. 321955839SasmodaiThis argument gives the 322055839Sasmodaiexternal name of the font, which is used for finding the font 322155839Sasmodaidescription file. The second argument gives the internal name of the 322255839Sasmodaifont which is used to refer to the font in troff after it has been 322355839Sasmodaimounted. If there is no third argument then the internal name will be 322455839Sasmodaiused as the external name. This feature allows you to use fonts with 322555839Sasmodailong names in compatibility mode. 322655839Sasmodai 322755839Sasmodai 322855839Sasmodai 322955839Sasmodai@node Using Symbols, Artificial Fonts, Font Positions, Fonts 323055839Sasmodai@subsection Using Symbols 323155839Sasmodai@cindex using symbols 323255839Sasmodai@cindex symbols, using 323355839Sasmodai 323455839Sasmodai 323555839Sasmodai@findex \( 323655839Sasmodai@findex \[ 323755839SasmodaiSymbols can be inserted by using a special escape sequence. 323855839SasmodaiThis escape is simply the escape character (a backslash) followed by 323955839Sasmodaian identifier. The symbol identifiers have to be two or more 324055839Sasmodaicharacters, since single characters conflict with all the other 324155839Sasmodaiescapes. The identifier can be either preceded by a parenthesis if 324255839Sasmodaiit is two character, or surrounded by square brackets. 324355839SasmodaiSo, the symbol for pi can be produced either by @code{\(*p} or 324455839Sasmodai@code{\[*p]}. 324555839Sasmodai 324655839Sasmodai@example 324755839Sasmodaiarea = \(*p\fIr\fP\u2\d 324855839Sasmodai@end example 324955839Sasmodai 325055839Sasmodai@findex \C 325155839SasmodaiThe escape @code{\C'@var{xxx}'} will typeset character named 325255839Sasmodai@var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}. 325355839SasmodaiBut @code{\C} has the advantage that it is compatible with recent 325455839Sasmodaiversions of ditroff and is available in compatibility mode. 325555839Sasmodai 325655839Sasmodai@findex \N 325755839SasmodaiThe escape @code{\N'@var{n}'} will typeset the character with code 325855839Sasmodai@var{n} in the current font. @var{n} can be any integer. Most devices only 325955839Sasmodaihave characters with codes between 0 and 255. If the current font 326055839Sasmodaidoes not contain a character with that code, special fonts will not be 326155839Sasmodaisearched. The @code{\N} escape sequence can be conveniently used on 326255839Sasmodaiconjunction with the @code{char} request: 326355839Sasmodai 326455839Sasmodai@example 326555839Sasmodai.char \[phone] \f(ZD\N'37' 326655839Sasmodai@end example 326755839Sasmodai 326855839SasmodaiThe code of each character is given in the fourth column in the font 326955839Sasmodaidescription file after the charset command. It is possible to include 327055839Sasmodaiunnamed characters in the font description file by using a name of 327155839Sasmodai@samp{---}; the @code{\N} escape sequence is the only way to use these. 327255839Sasmodai 327355839Sasmodai@findex cflags 327455839SasmodaiEach character has certain properties associated with it. 327555839SasmodaiThese properties can be modified with the @code{cflags} request. 327655839SasmodaiThe first argument is the the sum of the desired flags and the 327755839Sasmodairemaining arguments are the characters to have those properties. 327855839Sasmodai@table @code 327955839Sasmodai@item 1 328055839Sasmodaithe character ends sentences (initially characters @samp{.?!} have this 328155839Sasmodaiproperty); 328255839Sasmodai@item 2 328355839Sasmodailines can be broken before the character (initially no characters have 328455839Sasmodaithis property); 328555839Sasmodai@item 4 328655839Sasmodailines can be broken after the character (initially characters 328755839Sasmodai@samp{-\(hy\(em} have this property); 328855839Sasmodai@item 8 328955839Sasmodaithe character overlaps horizontally (initially characters 329055839Sasmodai@samp{\(ul\(rn\(ru} have this property); 329155839Sasmodai@item 16 329255839Sasmodaithe character overlaps vertically (initially character @samp{\(br} has 329355839Sasmodaithis property); 329455839Sasmodai@item 32 329555839Sasmodaian end of sentence character followed by any number of characters with 329655839Sasmodaithis property will be treated as the end of a sentence if followed by a 329755839Sasmodainewline or two spaces; in other words the character is transparent for 329855839Sasmodaithe purposes of end of sentence recognition; this is the same as having 329955839Sasmodaia zero space factor in @TeX{} (initially characters 330055839Sasmodai@samp{"')]*\(dg\(rq} have this property). 330155839Sasmodai@end table 330255839Sasmodai 330355839Sasmodai@findex char 330455839SasmodaiYou can create new characters with the @code{char} request. It is 330555839Sasmodaicalled as @samp{.char @var{c} @var{string}} Define character @var{c} 330655839Sasmodaito be @var{string}. Every time character @var{c} needs to be printed, 330755839Sasmodai@var{string} will be processed in a temporary environment and the 330855839Sasmodairesult will be wrapped up into a single object. Compatibility mode 330955839Sasmodaiwill be turned off and the escape character will be set to \ while 331055839Sasmodai@var{string} is being processed. Any emboldening, constant spacing or 331155839Sasmodaitrack kerning will be applied to this object rather than to individual 331255839Sasmodaicharacters in @var{string}. A character defined by this request can 331355839Sasmodaibe used just like a normal character provided by the output device. 331455839SasmodaiIn particular other characters can be translated to it with the 331555839Sasmodai@code{tr} request; it can be made the leader character by the 331655839Sasmodai@code{lc} request; repeated patterns can be drawn with the character 331755839Sasmodaiusing the @code{\l} and @code{\L} escape sequences; words containing 331855839Sasmodaithe character can be hyphenated correctly, if the @code{hcode} request 331955839Sasmodaiis used to give the character a hyphenation code. There is a special 332055839Sasmodaianti-recursion feature: use of character within the character's 332155839Sasmodaidefinition will be handled like normal characters not defined with 332255839Sasmodai@code{char}. 332355839Sasmodai 332455839Sasmodai@findex rchar 332555839SasmodaiA character definition can be removed with the @code{rchar} request. Its 332655839Sasmodaiarguments are the characters to be removed. This undoes the effect of 332755839Sasmodaia @code{char} request. 332855839Sasmodai 332955839Sasmodai@c distribute these through the text 333055839Sasmodai@xref{Special Characters} 333155839Sasmodai 333255839Sasmodai@node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts 333355839Sasmodai@subsection Artificial Fonts 333455839Sasmodai@cindex artificial fonts 333555839Sasmodai@cindex fonts, artificial 333655839Sasmodai 333755839Sasmodai 333855839SasmodaiThere are a number of requests for artificially creating fonts. 333955839SasmodaiThese are largely vestigal remains from the days when output devices 334055839Sasmodaidid not have a wide variety of fonts, and when nroff and troff were 334155839Sasmodaiseparate programs. 334255839SasmodaiThese are no longer necessary in GNU Troff. 334355839Sasmodai 334455839Sasmodai@findex ul 334555839SasmodaiThe @code{ul} request will print subsequent lines in italics on a 334655839Sasmodaidevice capable of it, or underline the text on an ascii output device. 334755839SasmodaiThe single argument is the number of lines to be ``underlined,'' 334855839Sasmodaiwith no argument, the next line will be underlined. 334955839Sasmodai 335055839Sasmodai@findex cu 335155839SasmodaiThe @code{cu} request is similar to @code{ul} ... 335255839Sasmodai 335355839Sasmodai@findex uf 335455839SasmodaiThe @code{uf} request will set the underline font used by @code{ul} 335555839Sasmodaiand @code{cu}. 335655839Sasmodai 335755839Sasmodai@findex bd 335855839SasmodaiThe @code{bd} request artificially creates a bold font by printing 335955839Sasmodaieach character twice, slightly offset. 336055839SasmodaiThe first argument specifies the font to embolden, and the second is 336155839Sasmodaithe number of basic units, minus one, by which the two characters 336255839Sasmodaiwill be offset. If the second argument is missing, emboldening will 336355839Sasmodaibe turned off. 336455839Sasmodai 336555839Sasmodai 336655839Sasmodai@node Ligatures and Kerning, , Artificial Fonts, Fonts 336755839Sasmodai@subsection Ligatures and Kerning 336855839Sasmodai@cindex ligatures and kerning 336955839Sasmodai@cindex kerning and ligatures 337055839Sasmodai 337155839Sasmodai 337255839Sasmodai@findex lg 337355839Sasmodai@vindex .lg 337455839Sasmodai@code{lg} 337555839Sasmodai@code{.lg} 337655839SasmodaiThe current ligature mode. 337755839Sasmodai 337855839SasmodaiWhat is kerning?? 337955839Sasmodai 338055839SasmodaiIf the font description file contains pairwise kerning information, 338155839Sasmodaicharacters from that font will be kerned. Kerning between two 338255839Sasmodaicharacters can be inhibited by placing a @code{\&} between them. 338355839Sasmodai 338455839Sasmodai@findex kern 338555839Sasmodai@vindex .kern 338655839Sasmodai@code{kern} 338755839SasmodaiIf n is non-zero or missing, enable pairwise kerning, otherwise disable 338855839Sasmodaiit. 338955839Sasmodai@code{.kern} 339055839Sasmodai1 if pairwise kerning is enabled, 0 otherwise. 339155839Sasmodai 339255839Sasmodai@findex tkf 339355839Sasmodai.tkf f s1 n1 s2 n2 339455839SasmodaiEnable track kerning for font f. When the current font is f the width 339555839Sasmodaiof every character will be increased by an amount between n1 and n2; 339655839Sasmodaiwhen the current point size is less than or equal to s1 the width will 339755839Sasmodaibe increased by n1; when it is greater than or equal to s2 the width 339855839Sasmodaiwill be increased by n2; when the point size is greater than or equal to 339955839Sasmodais1 and less than or equal to s2 the increase in width is a linear 340055839Sasmodaifunction of the point size. 340155839Sasmodai 340255839Sasmodai 340355839Sasmodai@node Sizes, Strings, Fonts, Programming Tutorial 340455839Sasmodai@section Sizes 340555839Sasmodai@cindex sizes 340655839Sasmodai 340755839Sasmodai 340855839Sasmodai@cindex baseline 340955839SasmodaiGroff uses two dimensions with each line of text, type size and 341055839Sasmodaivertical spacing. The type size is the height from the text 341155839Sasmodai@dfn{baseline} to the top of the tallest character (decenders may drop 341255839Sasmodaibelow this baseline). Vertical spacing is the amount of space groff 341355839Sasmodaiallows for a line of text, normally, this is about 20% larger than the 341455839Sasmodaicurrent type size. Ratios smaller than this can result in 341555839Sasmodaihard-to-read text, larger that this, it will spread your text out more 341655839Sasmodaivertically (useful for term papers). By default, troff uses 10 point 341755839Sasmodaitype on 12 point spacing. 341855839Sasmodai 341955839Sasmodai@cindex leading 342055839SasmodaiThe difference between type size and vertical spacing is known, by 342155839Sasmodaitypesetters, as @dfn{leading}. 342255839Sasmodai 342355839Sasmodai 342455839Sasmodai@menu 342555839Sasmodai* Changing Type Sizes:: 342655839Sasmodai* Fractional Type Sizes:: 342755839Sasmodai@end menu 342855839Sasmodai 342955839Sasmodai@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 343055839Sasmodai@subsection Changing Type Sizes 343155839Sasmodai@cindex changing type sizes 343255839Sasmodai@cindex type sizes, changing 343355839Sasmodai 343455839Sasmodai 343555839Sasmodai@findex ps 343655839Sasmodai@findex vs 343755839Sasmodai@findex \s 343855839Sasmodai@vindex .s 343955839Sasmodai@vindex .v 344055839SasmodaiUsing the @code{ps} request and the @code{\s} escape you can change 344155839Sasmodaithe type size. The @code{vs} request will change the vertical 344255839Sasmodaispacing. The default unit for the @code{ps} and @code{vs} requests are 344355839Sasmodaipoints. 344455839SasmodaiThe number registers @code{.s} and @code{.v} contain the current 344555839Sasmodaitype size and vertical spacing. 344655839Sasmodai 344755839SasmodaiThese requests take parameters in units of points. You can specify 344855839Sasmodaisizes as an absolute size, or as a relative change from the current 344955839Sasmodaisize. The size 0 means go back to the previous size. With no 345055839Sasmodaiargument it will revert to the previous size. 345155839Sasmodai 345255839Sasmodai@example 345355839Sasmodaisnap, snap, 345455839Sasmodai.ps +2 345555839Sasmodaigrin, grin, 345655839Sasmodai.ps +2 345755839Sasmodaiwink, wink, \s+2nudge, nudge,\s+8 say no more! 345855839Sasmodai.ps 10 345955839Sasmodai@end example 346055839Sasmodai 346155839SasmodaiThe @code{\s} escape may be called in a variety of ways. 346255839SasmodaiMuch like other escapes there must be a way to determine where the 346355839Sasmodaiargument ends and the text begins. 346455839SasmodaiAny of the following forms are valid: 346555839Sasmodai@code{\s@var{n}}, 346655839Sasmodai@code{\s+@var{n}}, 346755839Sasmodai@code{\s-@var{n}}, 346855839Sasmodai@code{\s(@var{nn}}, 346955839Sasmodai@code{\s+(@var{nn}}, 347055839Sasmodai@code{\s-(@var{nn}}, 347155839Sasmodai@code{\s[+@var{nnn}]}, 347255839Sasmodai@code{\s[-@var{nnn}]}, 347355839Sasmodai@code{\s+[@var{nnn}]}, 347455839Sasmodai@code{\s-[@var{nnn}]}. 347555839Sasmodai 347655839SasmodaiSome devices may only have certain permissible sizes, in which case 347755839Sasmodaigroff will round to the nearest permissible size. 347855839Sasmodai 347955839Sasmodai@example 348055839Sasmodai... .sz macro example?? ... 348155839Sasmodai@end example 348255839Sasmodai 348355839Sasmodai@node Fractional Type Sizes, , Changing Type Sizes, Sizes 348455839Sasmodai@subsection Fractional Type Sizes 348555839Sasmodai@cindex fractional type sizes 348655839Sasmodai@cindex type sizes, fractional 348755839Sasmodai 348855839Sasmodai 348955839SasmodaiA @dfn{scaled point} is equal to 1/@var{sizescale} points, where 349055839Sasmodai@var{sizescale} is specified in the @file{DESC} file (1 by default.) 349155839SasmodaiThere is a new scale indicator @samp{z} which has the effect of 349255839Sasmodaimultiplying by @var{sizescale}. Requests and escape sequences in 349355839Sasmodaitroff interpret arguments that represent a pointsize as being in units 349455839Sasmodaiof scaled points, but they evaluate each such argument using a default 349555839Sasmodaiscale indicator of @samp{z}. Arguments treated in this way are the 349655839Sasmodaiargument to the @code{ps} request, the third argument to the @code{cs} 349755839Sasmodairequest, the second and fourth arguments to the @code{tkf} request, 349855839Sasmodaithe argument to the @code{\H} escape sequence, and those variants of 349955839Sasmodaithe @code{\s} escape sequence that take a numeric expression as their 350055839Sasmodaiargument. 350155839Sasmodai 350255839SasmodaiFor example, suppose @var{sizescale} is 1000; then a scaled point will be 350355839Sasmodaiequivalent to a millipoint; the request @samp{.ps 10.25} is equivalent to 350455839Sasmodai@samp{.ps 10.25z} and so sets the pointsize to 10250 scaled points, which is 350555839Sasmodaiequal to 10.25 points. 350655839Sasmodai 350755839SasmodaiThe number register @code{\n(.s} returns the pointsize in points as 350855839Sasmodaidecimal fraction. There is also a new number register @code{\n[.ps]} 350955839Sasmodaithat returns the pointsize in scaled points. 351055839Sasmodai 351155839SasmodaiIt would make no sense to use the @samp{z} scale indicator in a 351255839Sasmodainumeric expression whose default scale indicator was neither @samp{u} 351355839Sasmodainor @samp{z}, and so troff disallows this. Similarily it would make 351455839Sasmodaino sense to use a scaling indicator other than @samp{z} or @samp{u} in a 351555839Sasmodainumeric expression whose default scale indicator was @samp{z}, and so 351655839Sasmodaitroff disallows this as well. 351755839Sasmodai 351855839SasmodaiThere is also new scale indicator @samp{s} which multiplies by the 351955839Sasmodainumber of units in a scaled point. So, for example, @samp{\n[.ps]s} 352055839Sasmodaiis equal to 1m. Be sure not to confuse the @samp{s} and @samp{z} 352155839Sasmodaiscale indicators. 352255839Sasmodai 352355839Sasmodai@code{\s'+@var{n}'} 352455839Sasmodai@code{\s'-@var{n}'} 352555839Sasmodai@code{\s+'@var{n}'} 352655839Sasmodai@code{\s-'@var{n}'} 352755839SasmodaiSet the point size to @var{n} scaled points; @var{n} is a numeric 352855839Sasmodaiexpression with a default scale indicator of @samp{z}. 352955839Sasmodai 353055839Sasmodai@code{\n[.ps]} 353155839SasmodaiThe current pointsize in scaled points. 353255839Sasmodai 353355839Sasmodai@code{\n[.psr]} 353455839SasmodaiThe last-requested pointsize in scaled points. 353555839Sasmodai 353655839Sasmodai@code{\n[.sr]} 353755839SasmodaiThe last requested pointsize in points as a decimal fraction. This is a 353855839Sasmodaistring-valued register. 353955839Sasmodai 354055839Sasmodai 354155839Sasmodai@c distribute these through the text 354255839Sasmodai@xref{Font Files} 354355839Sasmodai 354455839Sasmodai@node Strings, Conditionals and Loops, Sizes, Programming Tutorial 354555839Sasmodai@section Strings 354655839Sasmodai@cindex strings 354755839Sasmodai 354855839Sasmodai 354955839Sasmodai@findex ds 355055839SasmodaiGroff has string variables, which are entirely for user convenience 355155839Sasmodai(i.e. there are no builtin strings) They are defined via the 355255839Sasmodai@code{ds} request. 355355839Sasmodai 355455839Sasmodai@example 355555839Sasmodai.ds UX \s-1UNIX\s0\u\s-3tm\s0\d 355655839Sasmodai@end example 355755839Sasmodai 355855839Sasmodai@findex \* 355955839SasmodaiThe are interpolated, or expanded in-place, via the @code{\*} escape: 356055839Sasmodai 356155839Sasmodai@example 356255839SasmodaiThe \*(UX Operating System 356355839Sasmodai@end example 356455839Sasmodai 356555839SasmodaiWill produce: 356655839Sasmodai 356755839Sasmodai@example 356855839SasmodaiThe UNIXtm Operating System 356955839Sasmodai@end example 357055839Sasmodai 357155839SasmodaiIf the string named by the @code{\*} does not exist, the escape will 357255839Sasmodaibe replaced by nothing. 357355839Sasmodai 357455839Sasmodai@cindex comments, with @code{ds} 357555839SasmodaiNOTE: Unlike other requests the third argument takes up the entire 357655839Sasmodailine including trailing spaces. This means that comments on a line 357755839Sasmodaiwith such a request can introduce unwanted space into a string. 357855839Sasmodai 357955839Sasmodai@example 358055839Sasmodai.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" trademark of you-know-who 358155839Sasmodai@end example 358255839Sasmodai 358355839SasmodaiInstead you should either put the comment on another line or 358455839Sasmodaihave the comment escape adjacent with the end of the string. 358555839Sasmodai 358655839Sasmodai@example 358755839Sasmodai.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" trademark of you-know-who 358855839Sasmodai@end example 358955839Sasmodai 359055839SasmodaiIf you need leading space you can start the string with a double 359155839Sasmodaiquote. No trailing quote is needed, in fact any trailing quote is 359255839Sasmodaiincluded in your string. 359355839Sasmodai 359455839Sasmodai@cindex canibalism 359555839Sasmodai@example 359655839Sasmodai.ds sign " Yours in a white wine sauce, 359755839Sasmodai@end example 359855839Sasmodai 359955839Sasmodai@findex as 360055839Sasmodai@cindex appending to strings 360155839Sasmodai@cindex strings, appending 360255839SasmodaiYou can also append onto a string with the @code{as} request. 360355839SasmodaiIt works the same as the @code{ds} request except that it appends the 360455839Sasmodaisecond argument onto the string named by the first argument. 360555839Sasmodai 360655839Sasmodai@example 360755839Sasmodai.as sign " with shallots, onions and garlic, 360855839Sasmodai@end example 360955839Sasmodai 361055839Sasmodai@findex \@key{ret} 361155839SasmodaiStrings are not limited to a sigle line of text. A string can span 361255839Sasmodaiseveral lines by escaping the newlines with a backslash. The 361355839Sasmodairesulting string will be stored @emph{without} the newlines. 361455839Sasmodai 361555839Sasmodai@example 361655839Sasmodai.ds foo lots and lots \ 361755839Sasmodaiof text are on these \ 361855839Sasmodainext several lines 361955839Sasmodai@end example 362055839Sasmodai 362155839Sasmodai@findex rn 362255839Sasmodai@code{rn} 362355839Sasmodai 362455839Sasmodai@findex rm 362555839Sasmodai@code{rm} 362655839Sasmodai 362755839Sasmodai@findex als 362855839Sasmodai@code{als} 362955839Sasmodai 363055839Sasmodai@findex chop 363155839Sasmodai@code{chop} 363255839Sasmodai 363355839Sasmodai@c distribute these through the text 363455839Sasmodai@xref{Identifiers} 363555839Sasmodai@c distribute these through the text 363655839Sasmodai@xref{Comments} 363755839Sasmodai 363855839Sasmodai@node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial 363955839Sasmodai@section Conditionals and Loops 364055839Sasmodai@cindex conditionals and loops 364155839Sasmodai@cindex loops and conditionals 364255839Sasmodai 364355839Sasmodai 364455839Sasmodai@findex if 364555839Sasmodai@findex while 364655839SasmodaiIn @code{if} and @code{while} requests, there are several more operators 364755839Sasmodaiavailable: 364855839Sasmodai 364955839Sasmodai@table @code 365055839Sasmodai@item e 365155839Sasmodai@itemx o 365255839SasmodaiTrue if the current page is even or odd numbered (respectively) 365355839Sasmodai@item n 365455839Sasmodai@itemx t 365555839SasmodaiTrue if the document is being processed by 365655839Sasmodainroff (or an ascii device) or troff. 365755839Sasmodai@item '@var{xxx}'@var{yyy}' 365855839SasmodaiTrue if the string @var{xxx} is equal to the string @var{yyy}. 365955839SasmodaiOther characters can be used in place of the single quotes. 366055839Sasmodai(Which?) 366155839SasmodaiThe strings are `formatted' before being compared. (?) 366255839Sasmodai@item r@var{xxx} 366355839SasmodaiTrue if there is a number register named @var{xxx}. 366455839Sasmodai@item d@var{xxx} 366555839SasmodaiTrue if there is a string, macro, diversion, or request named @var{xxx}. 366655839Sasmodai@item c@var{ch} 366755839SasmodaiTrue if there is a character @var{ch} available; @var{ch} is 366855839Sasmodaieither an ASCII character or a special character @code{\(@var{ch}} or 366955839Sasmodai@code{\[@var{ch}]}; the condition will also be true if @var{ch} has been 367055839Sasmodaidefined by the @code{char} request. 367155839Sasmodai@end table 367255839Sasmodai 367355839Sasmodai 367455839Sasmodai@menu 367555839Sasmodai* if-else:: 367655839Sasmodai* while:: 367755839Sasmodai@end menu 367855839Sasmodai 367955839Sasmodai@node if-else, while, Conditionals and Loops, Conditionals and Loops 368055839Sasmodai@subsection if-else 368155839Sasmodai@cindex if-else 368255839Sasmodai 368355839Sasmodai 368455839SasmodaiTroff has if-then-else constructs like other languages, although 368555839Sasmodaithe formatting can be painful. 368655839Sasmodai 368755839Sasmodai@findex if 368855839SasmodaiThe @code{if} request is troff's if statement, it is called as 368955839Sasmodai@samp{.if @var{expr} @var{anything}}, where @var{expr} is the 369055839Sasmodaiexpression to be evaluated, 369155839Sasmodaiand @var{anything} (the remainder of the line) 369255839Sasmodaiwhich will be executed if 369355839Sasmodaithe @var{expr} evaluates to non-zero (true). 369455839Sasmodai@var{anything} will be interpreted as though it was on a line by 369555839Sasmodaiitself. 369655839Sasmodai@xref{Expressions}, for more info. 369755839Sasmodai 369855839SasmodaiHere are some examples: 369955839Sasmodai 370055839Sasmodai@example 370155839Sasmodai.if t .ls 2 \" double spacing in troff 370255839Sasmodai.if 0 .ab how'd this happen?? 370355839Sasmodai@end example 370455839Sasmodai 370555839Sasmodai@findex ie 370655839Sasmodai@findex el 370755839SasmodaiAn if-then-else is written using two requests @code{ie} and @code{el} 370855839Sasmodaithe first request is the if part and the latter is the else part. 370955839Sasmodai 371055839Sasmodai@example 371155839Sasmodai.ie 371255839Sasmodai.el 371355839Sasmodai@end example 371455839Sasmodai 371555839Sasmodai@findex \@{ 371655839Sasmodai@findex \@} 371755839SasmodaiIn many cases you will want more than one request to be executed as a 371855839Sasmodairesult of any of these requests, this can be done using the \@{ and 371955839Sasmodai\@} escapes. 372055839SasmodaiThe following example shows the possible ways to use these escapes. 372155839Sasmodai 372255839Sasmodai@example 372355839Sasmodai.ie t \@{\ 372455839Sasmodai. ds lq `` 372555839Sasmodai. ds rq '' 372655839Sasmodai.\@} 372755839Sasmodai.el \ 372855839Sasmodai.\@{\ 372955839Sasmodai. ds lq " 373055839Sasmodai. ds rq "\@} 373155839Sasmodai.ds qq " 373255839Sasmodai@end example 373355839Sasmodai 373455839Sasmodai 373555839Sasmodai@c distribute these through the text 373655839Sasmodai@xref{Expressions} 373755839Sasmodai 373855839Sasmodai@node while, , if-else, Conditionals and Loops 373955839Sasmodai@subsection while 374055839Sasmodai@cindex while 374155839Sasmodai 374255839Sasmodai 374355839Sasmodai@findex while 374455839SasmodaiGroff provides a looping construct using the @code{while} request, 374555839Sasmodaiwhich is used much like the @code{if} (and related) requests. 374655839SasmodaiThe first argument is an expression which will be evaluated. 374755839SasmodaiThe @code{while} request will interpret the remainder of the line 374855839Sasmodaiuntil the expression evaluates to 0 or false. 374955839Sasmodai 375055839Sasmodai@example 375155839Sasmodai.nr a 0 1 375255839Sasmodai.while (\na<9) \&\n+a, 375355839Sasmodai\&\n+a 375455839Sasmodai@end example 375555839Sasmodai 375655839SasmodaiThe preceding example produces: 375755839Sasmodai 375855839Sasmodai@example 375955839Sasmodai1, 2, 3, 4, 5, 6, 7, 8, 9, 10 376055839Sasmodai@end example 376155839Sasmodai 376255839Sasmodai@findex break 376355839Sasmodai@findex continue 376455839SasmodaiThe @code{break} request will 376555839Sasmodai@dfn{break} out of a while loop. 376655839SasmodaiBe sure not to confuse this with the @code{.br} request. 376755839SasmodaiThe @code{continue} request will 376855839Sasmodaifinish the current iteration of a while loop. 376955839Sasmodai 377055839Sasmodai@c distribute these through the text 377155839Sasmodai@xref{Expressions} 377255839Sasmodai 377355839Sasmodai@node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial 377455839Sasmodai@section Writing Macros 377555839Sasmodai@cindex writing macros 377655839Sasmodai@cindex macros, writing 377755839Sasmodai 377855839Sasmodai 377955839Sasmodai@findex de 378055839SasmodaiA macro is a collection of text and embedded commands which can be 378155839Sasmodaiinvoked multiple times. Macros are used for defining common operations. 378255839SasmodaiMacros are defined using the @code{de} request. This request takes 378355839Sasmodaia name for the macro as the first argument. Subsequent lines are 378455839Sasmodaicopied into an internal buffer until the line @code{..} is 378555839Sasmodaiencountered. The optional second argument to @code{de} can change 378655839Sasmodaithis ending token. 378755839Sasmodai 378855839SasmodaiFor example, suppose at the beginning of each paragraph, you want 378955839Sasmodaicause a break, move down a partial line and indent the first line. 379055839SasmodaiSuch a macro could be defined as follows: 379155839Sasmodai 379255839Sasmodai@example 379355839Sasmodai.de P 379455839Sasmodai.br 379555839Sasmodai.sp .8v 379655839Sasmodai.. 379755839Sasmodai@end example 379855839Sasmodai 379955839Sasmodai@findex am 380055839SasmodaiThe @code{am} request works similarily to @code{de} except it appends 380155839Sasmodaionto the macro named by the first argument. So, if we decide we want 380255839Sasmodaiour previously @code{P} macro to actually do indented instead of 380355839Sasmodaiblock paragraphs we can add the necessary code to our existing macro. 380455839Sasmodai 380555839Sasmodai@example 380655839Sasmodai.am P 380755839Sasmodai.ti +5n 380855839Sasmodai.. 380955839Sasmodai@end example 381055839Sasmodai 381155839Sasmodai@findex als 381255839Sasmodai@cindex aliases, macro 381355839Sasmodai@cindex macro aliases 381455839SasmodaiMacros can be aliased with the @code{als} request. 381555839Sasmodai 381655839Sasmodai@findex rn 381755839Sasmodai@code{rn} 381855839Sasmodai 381955839Sasmodai@findex rm 382055839Sasmodai@code{rm} 382155839Sasmodai 382255839Sasmodai@findex chop 382355839Sasmodai@code{chop} 382455839Sasmodai 382555839Sasmodai 382655839Sasmodai@menu 382755839Sasmodai* Copy-in Mode:: 382855839Sasmodai* Parameters:: 382955839Sasmodai@end menu 383055839Sasmodai 383155839Sasmodai@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 383255839Sasmodai@subsection Copy-in Mode 383355839Sasmodai@cindex copy-in mode 383455839Sasmodai@cindex mode, copy-in 383555839Sasmodai 383655839Sasmodai 383755839Sasmodai@findex \n 383855839Sasmodai@findex \$ 383955839Sasmodai@findex \* 384055839Sasmodai@findex \\ 384155839Sasmodai@findex \@key{RET} 384255839SasmodaiWhen troff reads in the test for a macro or diversion it copies the 384355839Sasmodaitext (including request lines) into an internal buffer, except for 384455839Sasmodaiescapes. Escapes will be converted into an internal form, except for 384555839Sasmodai@code{\n}, @code{\$}, @code{\*}, @code{\\} and @code{\@key{RET}} which 384655839Sasmodaiare evaluated and inserted into the text where the escape was located. 384755839SasmodaiThis is known as @dfn{copy-in} mode. 384855839Sasmodai 384955839SasmodaiWhat this means is that you can specify when these escapes are to be 385055839Sasmodaievaluated (copy-in time or time of use) by insulating the escapes 385155839Sasmodaiwith an extra backslash. 385255839Sasmodai 385355839SasmodaiFor example, the following will result in the numbers 20 and 10 being 385455839Sasmodaiprinted. 385555839Sasmodai 385655839Sasmodai@example 385755839Sasmodai.nr x 20 385855839Sasmodai.de y 385955839Sasmodai.nr x 10 386055839Sasmodai\&\nx 386155839Sasmodai\&\\nx 386255839Sasmodai.. 386355839Sasmodai.y 386455839Sasmodai@end example 386555839Sasmodai 386655839Sasmodai 386755839Sasmodai 386855839Sasmodai@node Parameters, , Copy-in Mode, Writing Macros 386955839Sasmodai@subsection Parameters 387055839Sasmodai@cindex parameters 387155839Sasmodai 387255839Sasmodai 387355839Sasmodai@findex \$ 387455839Sasmodai@vindex .$ 387555839SasmodaiThe arguments to a macro can be examined using a variety of escapes. 387655839SasmodaiThe number of arguments is available in the @code{.$} number register. 387755839SasmodaiAny individual argument can be retrieved with one of the following 387855839Sasmodaiescapes: 387955839Sasmodai 388055839SasmodaiThe escapes @code{\$@var{n}}, @code{\$(@var{nn}} 388155839Sasmodaiand @code{\$[@var{nnn}]} 388255839Sasmodaiwill result in the @var{n}th, @var{nn}th or @var{nnn}th 388355839Sasmodaiargument. Macros can have a unlimited number of arguments. 388455839SasmodaiNote that due to copy-in mode, you will want to have two backslashes 388555839Sasmodaion these in actual use, since you do not want them interpolated until 388655839Sasmodaithe macro is actually invoked. 388755839Sasmodai 388855839Sasmodai@findex shift 388955839SasmodaiThe request @code{shift} will shift the arguments 1 position, or as 389055839Sasmodaimany positions as specified by the first argument. 389155839SasmodaiAfter executing this request, argument 389255839Sasmodai@var{i} will become argument @var{i}-@var{n}; arguments 1 to @var{n} 389355839Sasmodaiwill no longer be available. 389455839SasmodaiShifting by negative amounts is currently undefined. 389555839Sasmodai 389655839Sasmodai@findex \$* 389755839Sasmodai@findex \$@@ 389855839SasmodaiIn some cases you will want to just use all of the arguments at once. 389955839SasmodaiFor example if you pass the arguments along to another macro. 390055839SasmodaiThe @code{\$*} escape is 390155839Sasmodaithe concatenation of all the arguments separated by spaces. 390255839SasmodaiA similar escape is @code{\$@@}, 390355839Sasmodaiwhich is 390455839Sasmodaithe concatenation of all the arguments with each surrounded 390555839Sasmodaiby double quotes, and separated by spaces. 390655839Sasmodai 390755839Sasmodai@findex \$0 390855839Sasmodai@findex als 390955839SasmodaiThe @code{\$0} escape is 391055839Sasmodaithe name by which the current macro was invoked. The @code{als} 391155839Sasmodairequest can make a macro have more than one name. 391255839Sasmodai 391355839Sasmodai@example 391455839Sasmodai.de vl 391555839Sasmodai.ie \\n(.$=1 .ds Vl Pre-Release Version 391655839Sasmodai.el .ds Vl Version \\$3, \\$4. 391755839Sasmodai.. 391855839Sasmodai@end example 391955839Sasmodai 392055839SasmodaiThis would be called as 392155839Sasmodai 392255839Sasmodai@example 392355839Sasmodai.vl $Id: groff.texinfo,v 1.5 1999/12/09 09:42:29 wlemb Exp $ 392455839Sasmodai@end example 392555839Sasmodai 392655839Sasmodai 392755839Sasmodai@c distribute these through the text 392855839Sasmodai@xref{Request Arguments} 392955839Sasmodai 393055839Sasmodai@node Page Motions, Drawing Functions, Writing Macros, Programming Tutorial 393155839Sasmodai@section Page Motions 393255839Sasmodai@cindex page motions 393355839Sasmodai@cindex motions, page 393455839Sasmodai 393555839Sasmodai 393655839Sasmodai@findex sp 393755839SasmodaiMotions up and down the page can be done with the @code{sp} request. 393855839SasmodaiHowever, this causes a break so that the actual effect is to move to 393955839Sasmodaithe left margin and then to the specified location. 394055839Sasmodai 394155839Sasmodai@findex mk 394255839Sasmodai@findex rt 394355839SasmodaiThe request @code{mk} can be used to mark a location on a page, for 394455839Sasmodaimovement to later. This request takes a register name as an 394555839Sasmodaiargument in which to store the current page location, with no 394655839Sasmodaiargument it will store the location in an internal register. 394755839SasmodaiThe results of this can be used later by the @code{rt} or the 394855839Sasmodai@code{sp} request. The @code{rt} request will return 394955839Sasmodai@strong{upwards} to the location given in the register name given as 395055839Sasmodaian argument, with no argument it will return to the location marked 395155839Sasmodaiwith the @code{mk} request 395255839Sasmodai 395355839Sasmodai@example 395455839Sasmodai... dual column example ... 395555839Sasmodai@end example 395655839Sasmodai 395755839SasmodaiThere are escapes which will give you much finer control of movements 395855839Sasmodaiabout the page. 395955839Sasmodai 396055839Sasmodai@findex \v 396155839SasmodaiThe @code{\v'@var{e}'} will let you do arbitrary vertical motion from 396255839Sasmodaithe current location on the page. The argument @var{e} specifies the 396355839Sasmodaidistance to move, positive is downwards and negative upwards. The 396455839Sasmodaidefault unit for this escape is vertical spaces, @code{v}'s. Beware, 396555839Sasmodaihowever, that troff will leave text processing to continue wherever 396655839Sasmodaithe motion ends, so if you don't want to interfere with text 396755839Sasmodaiprocessing, make sure your motions are balanced. 396855839Sasmodai 396955839SasmodaiThere are some special case escapes for vertical motion. 397055839Sasmodai 397155839Sasmodai@ftable @code 397255839Sasmodai@item \r 397355839Sasmodaimove upwards 1v. 397455839Sasmodai@item \u 397555839Sasmodaimove upwards .5v. 397655839Sasmodai@item \d 397755839Sasmodaimove down .5v. 397855839Sasmodai@end ftable 397955839Sasmodai 398055839Sasmodai@findex \h 398155839SasmodaiHorizontal motions can be done via the @code{\h'@var{e}'} escape. 398255839SasmodaiThe expression @var{e} indicates how far to move: positive is 398355839Sasmodairightwards and negative leftwards. 398455839Sasmodai 398555839SasmodaiThere are a number of special case escapes for horizontal motion: 398655839Sasmodai 398755839Sasmodai@ftable @code 398855839Sasmodai@item \@key{SP} 398955839SasmodaiAn unbreakable and unpadable (i.e. not expanded during filling) space. 399055839Sasmodai(Note: it is a backslash followed by a space.) 399155839Sasmodai@item \~ 399255839SasmodaiThis produces an unbreakable space that stretches like a normal 399355839Sasmodaiinterword space when a line is adjusted. 399455839Sasmodai@item \| 399555839Sasmodaia 1/6th em space. 399655839Sasmodai@item \^ 399755839Sasmodaia 1/12th em space. 399855839Sasmodai@item \0 399955839Sasmodaia space the size of a digit. 400055839Sasmodai@item \& 400155839SasmodaiA zero width space. 400255839Sasmodai@item \) 400355839SasmodaiLike @code{\&} except that it behaves like a character declared with 400455839Sasmodaithe @code{cflags} request to be transparent for the purposes of end 400555839Sasmodaiof sentence recognition. 400655839Sasmodai@end ftable 400755839Sasmodai 400855839Sasmodai@example 400955839Sasmodai... tex logo example ... 401055839Sasmodai@end example 401155839Sasmodai 401255839Sasmodai@findex \w 401355839Sasmodai@cindex width escape 401455839Sasmodai@cindex escape, width 401555839SasmodaiOften you will want to do horizontal movement based on the width of 401655839Sasmodaisome arbitrary text (e.g. given as an argument to a macro). 401755839SasmodaiFor that, there is the escape @code{\w'@var{text}'} which will 401855839Sasmodaiinterpolate to the width of the given @var{text} in basic units. 401955839Sasmodai 402055839Sasmodai@example 402155839Sasmodai... strlen example ... 402255839Sasmodai@end example 402355839Sasmodai 402455839SasmodaiFont changes may occur in @var{text} and not affect current settings. 402555839Sasmodai 402655839SasmodaiAlso after use, @code{\w} sets several registers: 402755839Sasmodai 402855839Sasmodai@table @code 402955839Sasmodai@item st 403055839Sasmodai@vindex st 403155839Sasmodai@itemx sb 403255839Sasmodai@vindex sb 403355839SasmodaiThe highest and lowest point, respectively, in @var{text}. 403455839Sasmodai@item rst 403555839Sasmodai@vindex rst 403655839Sasmodai@itemx rsb 403755839Sasmodai@vindex rsb 403855839SasmodaiLike the @code{st} and @code{sb} registers, but takes account of the 403955839Sasmodaiheights and depths of characters. 404055839Sasmodai@item ct 404155839Sasmodai@vindex ct 404255839Sasmodaiis set according to what kinds of characters occur in @var{text}. 404355839Sasmodai@table @asis 404455839Sasmodai@item 0 404555839Sasmodaiall short characters, no decenders or tall characters. 404655839Sasmodai@item 1 404755839Sasmodaidecender 404855839Sasmodai@item 2 404955839Sasmodaitall character 405055839Sasmodai@item 3 405155839Sasmodaiboth a decender and a tall character 405255839Sasmodai@end table 405355839Sasmodai@item ssc 405455839Sasmodai@vindex ssc 405555839SasmodaiThe amount of horizontal space (possibly negative) that should be 405655839Sasmodaiadded to the last character before a subscript. 405755839Sasmodai@item skw 405855839Sasmodai@vindex skw 405955839SasmodaiHow far to right of the center of the last character in the @code{\w} 406055839Sasmodaiargument, the center of an accent from a roman font should be 406155839Sasmodaiplaced over that character. 406255839Sasmodai@end table 406355839Sasmodai 406455839Sasmodai@findex \k 406555839Sasmodai@vindex .k 406655839Sasmodai@code{\k} 406755839Sasmodai@code{.k} 406855839Sasmodai 406955839Sasmodai@node Drawing Functions, Traps, Page Motions, Programming Tutorial 407055839Sasmodai@section Drawing Functions 407155839Sasmodai@cindex drawing functions 407255839Sasmodai@cindex functions for drawing 407355839Sasmodai 407455839Sasmodai 407555839SasmodaiGroff provides a number of ways to draw lines, and other figures on 407655839Sasmodaithe page. Used in combination with the page motion commands 407755839Sasmodai(@pxref{Page Motions}, for more info) you can draw a wide variety of 407855839Sasmodaifigures. However, for complex drawings these operations can be quite 407955839Sasmodaicumbersome, and it may be wise to use the pic preprocessor. 408055839Sasmodai@xref{gpic}, for more information. 408155839Sasmodai 408255839SasmodaiAll drawing is done via escapes. 408355839Sasmodai 408455839Sasmodai@findex \l 408555839SasmodaiThe @code{\l} will draw a line rightwards from the current location. 408655839SasmodaiThe full syntax for this escape is @samp{\l'@var{l}@var{c}'}, where 408755839Sasmodai@var{l} is the length of the line to be drawn, starting at the 408855839Sasmodaicurrent location, positive numbers will draw to the right, and 408955839Sasmodainegative will draw towards the left. This can also be specified 409055839Sasmodaiabsolutely (i.e. with a leading |) which will draw back to the 409155839Sasmodaibegining of the line. 409255839Sasmodai 409355839SasmodaiThe optional second parameter @var{c} is a character to draw the line 409455839Sasmodaiwith. If this second argument is not specified, troff will use the 409555839Sasmodaiunderscore character. 409655839Sasmodai 409755839SasmodaiIf you need to separate the two arguments (to prevent troff from 409855839Sasmodaiinterpreting a drawing character as a scaling indicator), you can 409955839Sasmodaiseparate them with @code{\&}. 410055839Sasmodai 410155839SasmodaiAnd now, for a useful example: 410255839Sasmodai 410355839Sasmodai@example 410455839Sasmodai.de box 410555839Sasmodai\(br\\$*\(br\l'|0\(rn'\l'|0\(ul' 410655839Sasmodai.. 410755839Sasmodai@end example 410855839Sasmodai 410955839SasmodaiNote that this works by outputing a box rule (a vertical line), then 411055839Sasmodaithe text given as an argument and then another box rule. 411155839SasmodaiThen the line drawing escapes both draw from the current location to 411255839Sasmodaithe beginning of the @emph{input} line. 411355839Sasmodai 411455839Sasmodai@findex \L 411555839SasmodaiVertical lines are drawn using the @code{\L} escape. It's parameters 411655839Sasmodaiare specified the same as the @code{\l} escape. If the length is 411755839Sasmodaipositive, the movement will be downwards, and upwards for negative. 411855839SasmodaiThe default character is the box rule character. 411955839SasmodaiAs with the vertical motion escapes, text processing will blindly 412055839Sasmodaicontinue where the line ends. 412155839Sasmodai 412255839Sasmodai@example 412355839Sasmodai...box macro... 412455839Sasmodai@end example 412555839Sasmodai 412655839Sasmodai@findex \D 412755839SasmodaiMore flexible drawing functions are available via the @code{\D} 412855839Sasmodaiescape. While the previous escapes will work on an ascii device, 412955839Sasmodaithese escapes will not. 413055839Sasmodai 413155839Sasmodai@table @code 413255839Sasmodai@item \D'l @var{x} @var{y}' 413355839SasmodaiDraw a line from the current location to the relative point specified 413455839Sasmodaiby @var{x}, @var{y}. 413555839Sasmodai 413655839Sasmodai@example 413755839Sasmodai...revised box macro... 413855839Sasmodai@end example 413955839Sasmodai 414055839Sasmodai@item \D'c @var{d}' 414155839SasmodaiDraw a circle with a diameter of @var{d} with the leftmost point at 414255839Sasmodaithe current position. 414355839Sasmodai@item \D'C @var{d}' 414455839SasmodaiDraw a solid circle with the same parameters as an outlined circle. 414555839Sasmodai@item \D'e @var{dx} @var{dy}' 414655839SasmodaiDraw an ellipse with a horizontal diameter of @var{dx} and a vertical 414755839Sasmodaidiameter of @var{dy} with the leftmost point at the current position. 414855839Sasmodai@item \D'E @var{dx} @var{dy}' 414955839SasmodaiDraw a solid elipse with the same parameters as an outlined elipse. 415055839Sasmodai@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 415155839SasmodaiDraw an arc clockwise from the current location through the two 415255839Sasmodaispecified locations. 415355839Sasmodai@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 415455839SasmodaiDraw a spline from the current location to 415555839Sasmodai@var{dx1}, @var{dy1} and then to @var{dx2}, @var{dy2}, and so on. 415655839Sasmodai@item \D'f @var{n}' 415755839SasmodaiSet the shade of gray to be used for filling solid objects to @var{n}; 415855839Sasmodai@var{n} must be an integer between 0 and 1000, where 0 corresponds 415955839Sasmodaisolid white and 1000 to solid black, and values in between correspond 416055839Sasmodaito intermediate shades of gray. This applies only to solid circles, 416155839Sasmodaisolid ellipses and solid polygons. By default, a level of 1000 will 416255839Sasmodaibe used. 416355839Sasmodai@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 416455839SasmodaiDraw a polygon from the current location to @var{dx1}, @var{dy1} 416555839Sasmodaiand then to @var{dx2}, @var{dy2} and so on. When the specified data 416655839Sasmodaipoints are exhausted, a line is drawn back to the starting point. 416755839Sasmodai 416855839Sasmodai@example 416955839Sasmodai... box example (yes, again)... 417055839Sasmodai@end example 417155839Sasmodai 417255839Sasmodai@itemx \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...' 417355839SasmodaiDraw a solid polygon with the same parameters as an outlined polygon. 417455839Sasmodai 417555839Sasmodai@example 417655839Sasmodai... shaded box example ... 417755839Sasmodai@end example 417855839Sasmodai 417955839Sasmodai@item \D't @var{n}' 418055839SasmodaiSet the current line thickness to @var{n} machine units. 418155839SasmodaiA value of zero selects the smallest available line thickness. 418255839Sasmodai 418355839Sasmodai@end table 418455839Sasmodai 418555839SasmodaiCurrent position 418655839Sasmodai 418755839Sasmodai@findex \b 418855839Sasmodai@cindex pile, character 418955839Sasmodai@cindex character pile 419055839SasmodaiThe @code{\b} escape will @dfn{pile} a sequence of characters 419155839Sasmodaivertically, and center it vertically on the current line. 419255839SasmodaiThis can be used to build large brackets and braces. 419355839Sasmodai 419455839Sasmodai@example 419555839Sasmodai\b'\(lt\(bv\(lk\(bv\(lb' 419655839Sasmodai@end example 419755839Sasmodai 419855839Sasmodai 419955839Sasmodai 420055839Sasmodai 420155839Sasmodai@node Traps, Diversions, Drawing Functions, Programming Tutorial 420255839Sasmodai@section Traps 420355839Sasmodai@cindex traps 420455839Sasmodai 420555839Sasmodai 420655839SasmodaiTraps are locations, which, when reached, will call a specified macro. 420755839SasmodaiThese traps can occur at a given location on the page, at a given 420855839Sasmodailocation in the current diversion, after a certain number of input 420955839Sasmodailines or at the end of input. 421055839Sasmodai 421155839Sasmodai@findex ch 421255839SasmodaiAny of these traps can be changed after they have been set with the 421355839Sasmodai@code{ch} request. The first arguemnt is the name of the trap or 421455839Sasmodaimacro, and the second is the new value for that trap. 421555839Sasmodai 421655839Sasmodai 421755839Sasmodai@menu 421855839Sasmodai* Page Location Traps:: 421955839Sasmodai* Diversion Traps:: 422055839Sasmodai* Input Line Traps:: 422155839Sasmodai* End-of-input Traps:: 422255839Sasmodai@end menu 422355839Sasmodai 422455839Sasmodai@node Page Location Traps, Diversion Traps, Traps, Traps 422555839Sasmodai@subsection Page Location Traps 422655839Sasmodai@cindex page location traps 422755839Sasmodai@cindex traps, page location 422855839Sasmodai 422955839Sasmodai 423055839SasmodaiPage location traps are frequently used for page headers and 423155839Sasmodaifooters. The following is a simple example of this. 423255839Sasmodai 423355839Sasmodai@example 423455839Sasmodai.de hd \" Page header 423555839Sasmodai'sp .5i 423655839Sasmodai.tl 'Title''date' 423755839Sasmodai'sp .3i 423855839Sasmodai.. 423955839Sasmodai.de fo \" Page footer 424055839Sasmodai'sp 1v 424155839Sasmodai.tl ''%'' 424255839Sasmodai'bp 424355839Sasmodai.. 424455839Sasmodai.wh 0 hd \" top of the page 424555839Sasmodai.wh -1i fo \" one inch from bottom 424655839Sasmodai@end example 424755839Sasmodai 424855839Sasmodai@vindex .t 424955839SasmodaiThe number register @code{.t} is the distance to the next trap. 425055839Sasmodai 425155839Sasmodai@findex ch 425255839SasmodaiThe location of a trap can be changed later on with the @code{ch} 425355839Sasmodairequest. 425455839SasmodaiThe first argument is the name of the macro to be invoked at the trap 425555839Sasmodaiand the second argument is the new location for the trap. 425655839SasmodaiThis is useful when you are building up footnotes in a diversion, and 425755839Sasmodaiyou need to allow more space at the bottom of the page for them. 425855839Sasmodai 425955839Sasmodai@example 426055839Sasmodai... (simplified) footnote example ... 426155839Sasmodai@end example 426255839Sasmodai 426355839Sasmodai@findex vpt 426455839Sasmodai@findex wh 426555839Sasmodai@findex dt 426655839Sasmodai@vindex .vpt 426755839SasmodaiThe @code{vpt} request will enable vertical position traps if the argment is 426855839Sasmodainon-zero, disable them otherwise. Vertical position traps are traps 426955839Sasmodaiset by the @code{wh} or @code{dt} requests. Traps set by the 427055839Sasmodai@code{it} request are not vertical position traps. The parameter that 427155839Sasmodaicontrols whether vertical position traps are enabled is global. 427255839SasmodaiInitially vertical position traps are enabled. The current setting of 427355839Sasmodaithis is available in the number register @code{.vpt}. 427455839Sasmodai 427555839Sasmodai@vindex .trunc 427655839Sasmodai@findex ne 427755839SasmodaiThe number register @code{.trunc} contains 427855839Sasmodaithe amount of vertical space truncated by the most recently 427955839Sasmodaisprung vertical position trap, or, if the trap was sprung by a 428055839Sasmodai@code{ne} request, minus the amount of vertical motion produced by 428155839Sasmodaithe @code{ne} request. In other words, at the point a trap is 428255839Sasmodaisprung, it represents the difference of what the vertical position 428355839Sasmodaiwould have been but for the trap, and what the vertical position 428455839Sasmodaiactually is. 428555839Sasmodai 428655839Sasmodai@vindex .ne 428755839SasmodaiThe number register @code{.ne} contains 428855839Sasmodaithe amount of space that was needed in the last @code{ne} request that caused 428955839Sasmodaia trap to be sprung. Useful in conjunction with the @code{.trunc} 429055839Sasmodairegister. @xref{Page Control}, for more information. 429155839Sasmodai 429255839Sasmodai 429355839Sasmodai 429455839Sasmodai@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 429555839Sasmodai@subsection Diversion Traps 429655839Sasmodai@cindex diversion traps 429755839Sasmodai@cindex traps, diversion 429855839Sasmodai 429955839Sasmodai 430055839Sasmodai@findex dt 430155839Sasmodai@vindex .t 430255839SasmodaiTraps can also be set @emph{within} a diversion using the @code{dt} 430355839Sasmodairequest. Like @code{wh} the first argument is the location of the 430455839Sasmodaitrap and the second argument is the name of the macro to be invoked. 430555839SasmodaiThe number register @code{.t} will still work within diversions. 430655839Sasmodai@xref{Diversions}, for more information. 430755839Sasmodai 430855839Sasmodai@node Input Line Traps, End-of-input Traps, Diversion Traps, Traps 430955839Sasmodai@subsection Input Line Traps 431055839Sasmodai@cindex input line traps 431155839Sasmodai@cindex traps, input line 431255839Sasmodai 431355839Sasmodai 431455839Sasmodai@findex it 431555839SasmodaiThe @code{it} request will set an input line trap. The format for 431655839Sasmodaicalling this is @samp{.it @var{n} @var{name}}, where @var{n} is the 431755839Sasmodainumber of lines of input which may be read before @dfn{springing} the 431855839Sasmodaitrap, @var{name} is the macro to be invoked. Request lines are not 431955839Sasmodaicounted as input lines. 432055839Sasmodai 432155839SasmodaiFor example, one possible use is to have a macro which will print the 432255839Sasmodainext @var{n} lines in a bold font. 432355839Sasmodai 432455839Sasmodai@example 432555839Sasmodai.de B 432655839Sasmodai.it B-end \\$1 432755839Sasmodai.ft B 432855839Sasmodai.. 432955839Sasmodai.de B-end 433055839Sasmodai.ft R 433155839Sasmodai.. 433255839Sasmodai@end example 433355839Sasmodai 433455839Sasmodai@node End-of-input Traps, , Input Line Traps, Traps 433555839Sasmodai@subsection End-of-input Traps 433655839Sasmodai@cindex end-of-input traps 433755839Sasmodai@cindex traps, end-of-input 433855839Sasmodai 433955839Sasmodai 434055839Sasmodai@findex em 434155839SasmodaiThe @code{em} request will set a trap at the end of input. 434255839SasmodaiThe macro specified as an arguement will be executed after the last 434355839Sasmodailine of the input file has been processed. 434455839Sasmodai 434555839SasmodaiFor example, if your document had to have a section at the bottom of 434655839Sasmodaithe last page for someone to approve you document, you could set it 434755839Sasmodaiup with @code{em}. 434855839Sasmodai 434955839Sasmodai@example 435055839Sasmodai.de approval 435155839Sasmodai.ne 5v 435255839Sasmodai.sp |(\\n(.t-6v) 435355839Sasmodai.in +4i 435455839Sasmodai.lc _ 435555839Sasmodai.br 435655839SasmodaiApproved:\t\a 435755839Sasmodai.sp 435855839SasmodaiDate:\t\t\a 435955839Sasmodai.. 436055839Sasmodai.em approval 436155839Sasmodai@end example 436255839Sasmodai 436355839Sasmodai 436455839Sasmodai@node Diversions, Environments, Traps, Programming Tutorial 436555839Sasmodai@section Diversions 436655839Sasmodai@cindex diversions 436755839Sasmodai 436855839Sasmodai 436955839SasmodaiIn Troff you can divert text into a named storage area, due to the 437055839Sasmodaisimilarity to defining macros it is sometimes said to be stored in a 437155839Sasmodaimacro. This is used for saving text for output at a later time, 437255839Sasmodaiwhich is useful for keeping blocks of text on the same page, 437355839Sasmodaifootnotes, tables of contents and indexes. 437455839Sasmodai 437555839Sasmodai@findex di 437655839Sasmodai@findex da 437755839SasmodaiDiversion is initiated by the @code{di} request, like the @code{de} 437855839Sasmodairequest it takes an argument of a macro name to divert subsequent 437955839Sasmodaitext to into. The @code{da} macro will append to an existing diversion. 438055839Sasmodai 438155839Sasmodai@example 438255839Sasmodai... end-note example ... 438355839Sasmodai@end example 438455839Sasmodai 438555839Sasmodai@vindex .z 438655839Sasmodai@vindex .d 438755839Sasmodai@vindex nl 438855839Sasmodai@vindex .h 438955839SasmodaiDiversions may be nested. 439055839SasmodaiThe number register @code{.z} contains the name of the current diversion. 439155839SasmodaiThe number register @code{.d} contains the current vertical place in 439255839Sasmodaithe diversion. If not in a diversion it is the same as the register 439355839Sasmodai@code{nl}. 439455839Sasmodai@code{.h} 439555839Sasmodai 439655839Sasmodai@vindex dn 439755839Sasmodai@vindex dl 439855839SasmodaiAfter compleating a diversion, the builtin number registers @code{dn} 439955839Sasmodaiand @code{dl} contain the vertical and horizontal size of the diversion. 440055839Sasmodai 440155839Sasmodai@example 440255839Sasmodai.\" Center text both horizontally & vertically 440355839Sasmodai.de (c 440455839Sasmodai.br 440555839Sasmodai.nf 440655839Sasmodai.di @@c 440755839Sasmodai.. 440855839Sasmodai.de )c 440955839Sasmodai.br 441055839Sasmodai.di 441155839Sasmodai.nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v) 441255839Sasmodai.sp \\n(@@su 441355839Sasmodai.ce 1000 441455839Sasmodai.nf 441555839Sasmodai.@c 441655839Sasmodai.br 441755839Sasmodai.ce 0 441855839Sasmodai.sp \\n(@@su 441955839Sasmodai.br 442055839Sasmodai.fi 442155839Sasmodai.rr @@s 442255839Sasmodai.. 442355839Sasmodai@end example 442455839Sasmodai 442555839Sasmodai@findex \! 442655839SasmodaiRequests, macros and escapes are interpreted when read into a 442755839Sasmodaidiversion. 442855839SasmodaiThere are two ways to prevent this, either way will take the given 442955839Sasmodaitext and @dfn{transparently} embed it into the diversion. 443055839SasmodaiThe first method is to prefix the line with @code{\!}. This will 443155839Sasmodaicause the entire line to be transparently inserted into the diversion. 443255839SasmodaiThis is useful for macros you do not want invoked until the diverted 443355839Sasmodaitext is actually output. 443455839Sasmodai 443555839Sasmodai@c anything is read in copy mode. (what about \! ??) 443655839Sasmodai 443755839Sasmodai@findex \? 443855839SasmodaiThe other way is to surround the text by the @code{\?} escape, i.e. 443955839Sasmodai@samp{\?@var{anything}\?}. 444055839Sasmodai@var{anything} may not contain 444155839Sasmodainewlines; use @code{\!} if you want to embed newlines in a diversion. The 444255839Sasmodaiescape sequence @code{\?} is also recognised in copy mode and turned into a 444355839Sasmodaisingle internal code; it is this code that terminates anything. Thus 444455839Sasmodaithe followin example will print 4. 444555839Sasmodai 444655839Sasmodai@example 444755839Sasmodai.nr x 1 444855839Sasmodai.nf 444955839Sasmodai.di d 445055839Sasmodai\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 445155839Sasmodai.di 445255839Sasmodai.nr x 2 445355839Sasmodai.di e 445455839Sasmodai.d 445555839Sasmodai.di 445655839Sasmodai.nr x 3 445755839Sasmodai.di f 445855839Sasmodai.e 445955839Sasmodai.di 446055839Sasmodai.nr x 4 446155839Sasmodai.f 446255839Sasmodai@end example 446355839Sasmodai 446455839Sasmodai@findex rn 446555839Sasmodai@code{rn} 446655839Sasmodai 446755839Sasmodai@findex rm 446855839Sasmodai@code{rm} 446955839Sasmodai 447055839Sasmodai@findex als 447155839Sasmodai@code{als} 447255839Sasmodai 447355839Sasmodai@findex chop 447455839Sasmodai@code{chop} 447555839Sasmodai 447655839Sasmodai@findex asciify 447755839Sasmodai@code{asciify} 447855839SasmodaiThis request only exists in order to make it possible to make certain 447955839Sasmodaigross hacks work with GNU troff. It @dfn{unformats} the diversion 448055839Sasmodaispecified as an argument in 448155839Sasmodaisuch a way that ASCII characters that were formatted and diverted 448255839Sasmodaiwill be treated like ordinary input characters when the diversion is 448355839Sasmodaireread. For example, the following will set register @code{n} to 1. 448455839Sasmodai 448555839Sasmodai@example 448655839Sasmodai.tr @@. 448755839Sasmodai.di x 448855839Sasmodai@@nr\ n\ 1 448955839Sasmodai.br 449055839Sasmodai.di 449155839Sasmodai.tr @@@@ 449255839Sasmodai.asciify x 449355839Sasmodai.x 449455839Sasmodai@end example 449555839Sasmodai 449655839Sasmodai 449755839Sasmodai@c distribute these through the text 449855839Sasmodai@xref{Copy-in Mode} 449955839Sasmodai 450055839Sasmodai@node Environments, I/O, Diversions, Programming Tutorial 450155839Sasmodai@section Environments 450255839Sasmodai@cindex environments 450355839Sasmodai 450455839Sasmodai 450555839SasmodaiOften you will need to print some text in a certain format regardless 450655839Sasmodaiof what may be in effect at the time, for example, in a trap invoked 450755839Sasmodaimacro to print headers and footers. 450855839SasmodaiTo solve this groff has @dfn{environments} in which text is processed. 450955839SasmodaiAn environment contains most of the parameters that control 451055839Sasmodaitext processing. You can switch amongst these environments, by 451155839Sasmodaidefault groff processes text in environment 0. 451255839SasmodaiThe following is the information kept in an environment. 451355839Sasmodai 451455839Sasmodai@itemize @bullet{} 451555839Sasmodai@item 451655839SasmodaiType size 451755839Sasmodai@item 451855839SasmodaiFont (family and style) 451955839Sasmodai@item 452055839SasmodaiPage parameters 452155839Sasmodai@item 452255839SasmodaiFill/adjust mode 452355839Sasmodai@item 452455839SasmodaiTab stops 452555839Sasmodai@item 452655839SasmodaiPartially collected lines 452755839Sasmodai@end itemize 452855839Sasmodai 452955839SasmodaiThese environments may be given arbitrary names 453055839Sasmodai(@pxref{Identifiers}, for more info.) 453155839SasmodaiOld versions of troff only had environments named 0, 1 and 2. 453255839Sasmodai 453355839Sasmodai@findex ev 453455839Sasmodai@vindex .ev 453555839SasmodaiThe @code{ev} request will switch among these environments. 453655839SasmodaiThe single argument is the name of the environment to switch to, with 453755839Sasmodaino argument groff will switch back to the previous enviroment. 453855839SasmodaiThere is no limit on the number of named environments; 453955839Sasmodaithey will be created the first time that they are referenced. 454055839SasmodaiThe @code{.ev} number register contains 454155839Sasmodaithe name or number of the current environment. This is a string-valued 454255839Sasmodairegister. 454355839Sasmodai 454455839Sasmodai@example 454555839Sasmodai... page break macro, revised ... 454655839Sasmodai@end example 454755839Sasmodai 454855839Sasmodai@example 454955839Sasmodai.ev footnote-env 455055839Sasmodai.fam N 455155839Sasmodai.ps 6 455255839Sasmodai.vs 8 455355839Sasmodai.ll -.5i 455455839Sasmodai.ev 455555839Sasmodai... 455655839Sasmodai.ev footnote-env 455755839Sasmodai\(dg Note the large, friendly letters. 455855839Sasmodai.ev 455955839Sasmodai@end example 456055839Sasmodai 456155839Sasmodai 456255839Sasmodai 456355839Sasmodai 456455839Sasmodai@node I/O, Postprocessor Access, Environments, Programming Tutorial 456555839Sasmodai@section I/O 456655839Sasmodai@cindex i/o 456755839Sasmodai 456855839Sasmodai 456955839Sasmodai@findex so 457055839SasmodaiThe @code{so} request will read in the file given as an argument and 457155839Sasmodaiinclude it in place of the @code{so} request. This is quite useful 457255839Sasmodaifor large documents, i.e. keeping each chapter in a separate file. 457355839Sasmodai@xref{gsoelim}, for more information. 457455839Sasmodai 457555839Sasmodai@findex mso 457655839SasmodaiThe @code{mso} request is 457755839Sasmodaithe same as the @code{so} request except that file is searched for in 457855839Sasmodaithe same way that @file{tmac.@var{name}} is searched for when the 457955839Sasmodai@samp{-m@var{name}} option is specified. 458055839Sasmodai 458155839Sasmodai@findex cf 458255839Sasmodai@findex trf 458355839SasmodaiThe @code{cf} and @code{trf} requests are to include a file. 458455839SasmodaiIt will transparently output the contents of file filename. Each 458555839Sasmodailine is output 458655839Sasmodaias it would be were it preceded by @code{\!}; however, the lines are not 458755839Sasmodaisubject to copy-mode interpretation. If the file does not end with a 458855839Sasmodainewline, then a newline will be added. For example, you can define a 458955839Sasmodaimacro @code{x} containing the contents of file @file{f}, using 459055839Sasmodai 459155839Sasmodai@example 459255839Sasmodai.di x 459355839Sasmodai.trf f 459455839Sasmodai.di 459555839Sasmodai@end example 459655839Sasmodai 459755839Sasmodai.cf filename 459855839SasmodaiWhen used in a diversion, this will embed in the diversion an object 459955839Sasmodaiwhich, when reread, will cause the contents of filename to be 460055839Sasmodaitransparently copied through to the output. In @sc{Unix} troff, the contents 460155839Sasmodaiof filename is immediately copied through to the output regardless of 460255839Sasmodaiwhether there is a current diversion; this behaviour is so anomalous 460355839Sasmodaithat it must be considered a bug. 460455839Sasmodai 460555839Sasmodai 460655839SasmodaiWith @code{trf}, unlike @code{cf}, the file cannot contain characters 460755839Sasmodaisuch as NUL that are not legal troff input characters. 460855839Sasmodai 460955839Sasmodai@findex nx 461055839SasmodaiThe @code{nx} request will force groff to continue processing of the 461155839Sasmodaifile specified as an argument. 461255839Sasmodai 461355839Sasmodai@findex rd 461455839SasmodaiThe @code{rd} request will read from standard input, and include what 461555839Sasmodaiis read as though it were part of the input file. Text is read until 461655839Sasmodaia blank line is encountered. 461755839Sasmodai 461855839Sasmodai@cindex form letters 461955839Sasmodai@cindex letters, form 462055839SasmodaiUsing these two requests you can set up form letters. 462155839SasmodaiThe form letter template is constructed like this: 462255839Sasmodai 462355839Sasmodai@example 462455839Sasmodai.ce 462555839Sasmodai\*(td 462655839Sasmodai.sp 2 462755839Sasmodai.nf 462855839Sasmodai.rd 462955839Sasmodai.sp 463055839Sasmodai.rd 463155839Sasmodai.fi 463255839SasmodaiBody of letter. 463355839Sasmodai.bp 463455839Sasmodai.nx repeat.let 463555839Sasmodai@end example 463655839Sasmodai 463755839Sasmodai@findex ex 463855839SasmodaiWhen this is run, the following file should be redirected in. 463955839SasmodaiNote that requests included in this file are executed as though they 464055839Sasmodaiwere part of the form letter. The last block of input is the 464155839Sasmodai@code{ex} requests which tells groff to stop processing. If this was 464255839Sasmodainot there, groff would not know when to stop. 464355839Sasmodai 464455839Sasmodai@cindex Beagle Brothers 464555839Sasmodai@example 464655839SasmodaiTrent A. Fisher 464755839Sasmodai708 NW 19th Av., #202 464855839SasmodaiPortland, OR 97209 464955839Sasmodai 465055839SasmodaiDear Trent, 465155839Sasmodai 465255839SasmodaiLen Adollar 465355839Sasmodai4315 Sierra Vista 465455839SasmodaiSan Diego, CA 92103 465555839Sasmodai 465655839SasmodaiDear Mr. Adollar, 465755839Sasmodai 465855839Sasmodai.ex 465955839Sasmodai@end example 466055839Sasmodai 466155839Sasmodai@findex pi 466255839Sasmodai@code{pi} 466355839Sasmodai 466455839Sasmodai@findex sy 466555839SasmodaiThe @code{sy} request will allow arbitrary system commands to be 466655839Sasmodaiexecuted from within a groff document. The output is not saved 466755839Sasmodaianyplace, so it is up to you to do so. 466855839Sasmodai 466955839SasmodaiFor example, the following example will introduce the current time 467055839Sasmodaiinto your document: 467155839Sasmodai 467255839Sasmodai@cindex time 467355839Sasmodai@pindex perl 467455839Sasmodai@example 467555839Sasmodai.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 467655839Sasmodai (localtime(time))[2,1,0]' > /tmp/x\n[$$] 467755839Sasmodai.so /tmp/x\n[$$] 467855839Sasmodai.sy rm /tmp/x\n[$$] 467955839Sasmodai\nH:\nM:\nS 468055839Sasmodai@end example 468155839Sasmodai 468255839SasmodaiNote that this works by having the perl script (run by @code{sy}) 468355839Sasmodaiprint out the @code{nr} requests which will set the number registers 468455839Sasmodai@samp{H}, @samp{M} and @samp{S}, and then reads those commands in 468555839Sasmodaiwith the @code{so} request. 468655839Sasmodai 468755839Sasmodai@vindex systat 468855839SasmodaiThe @code{systat} number register contains 468955839SasmodaiThe return value of the @code{system()} function executed by the last 469055839Sasmodai@code{sy} request. 469155839Sasmodai 469255839Sasmodai@findex open 469355839SasmodaiThe @code{open} request will open 469455839Sasmodaia file (specified as the second argument) for writing and associate 469555839Sasmodaithe stream (specified as the first argument) with it. 469655839Sasmodai 469755839Sasmodai@findex opena 469855839SasmodaiThe @code{opena} is 469955839Sasmodailike open, but if filename exists, append to it instead of truncating 470055839Sasmodaiit. 470155839Sasmodai 470255839Sasmodai@findex write 470355839Sasmodai@findex ds 470455839Sasmodai@cindex copy-in mode 470555839Sasmodai@cindex mode, copy-in 470655839SasmodaiThe @code{write} request will write to the file associated with the 470755839Sasmodaistream specified by the first argument. The stream must previously 470855839Sasmodaihave been the subject of an open request. The remainder of the line 470955839Sasmodaiin interpreted as the @code{ds} request reads its second argument: a 471055839Sasmodaileading @code{"} will be stripped, and it will be read in copy-in mode. 471155839Sasmodai 471255839Sasmodai@findex close 471355839SasmodaiThe @code{close} request will 471455839Sasmodaiclose the stream specified by the first argument; stream will no 471555839Sasmodailonger be an acceptable argument to the @code{write} request. 471655839Sasmodai 471755839Sasmodai@example 471855839Sasmodai... example of open write &c... 471955839Sasmodai@end example 472055839Sasmodai 472155839Sasmodai@findex \v 472255839SasmodaiThe @code{\V} escape will 472355839Sasmodaiinterpolate the contents of the specified environment variable, as returned 472455839Sasmodaiby getenv(3). 472555839SasmodaiThe argument to @code{\V} is specified as an identifier, i.e. 472655839Sasmodai@samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. 472755839Sasmodai@code{\V} is interpreted in copy-in mode. 472855839Sasmodai 472955839Sasmodai 473055839Sasmodai@node Postprocessor Access, Miscellany, I/O, Programming Tutorial 473155839Sasmodai@section Postprocessor Access 473255839Sasmodai@cindex postprocessor access 473355839Sasmodai@cindex access of postprocessor 473455839Sasmodai 473555839Sasmodai 473655839SasmodaiThere are two escapes which will allow you to give information 473755839Sasmodaidirectly to the postprocessor. This is particularly useful for 473855839Sasmodaiembedding PostScript into your final document. 473955839Sasmodai 474055839Sasmodai@findex \X 474155839SasmodaiThe @code{\X} escape will embed its argument into the gtroff output 474255839Sasmodaipreceded with @samp{x X}. 474355839Sasmodai 474455839Sasmodai@findex \Y 474555839SasmodaiThe @code{\Y} escape is called with an identifier (i.e. 474655839Sasmodai@code{\Y@var{x}}, 474755839Sasmodai@code{\Y(@var{xx}} or 474855839Sasmodai@code{\Y[@var{xxx}]}). 474955839SasmodaiThis is approximately equivalent to @samp{\X'\*[@var{xxx}]'}. 475055839SasmodaiHowever the contents 475155839Sasmodaiof the string or macro @var{xxx} are not interpreted; also it is 475255839Sasmodaipermitted for 475355839Sasmodai@var{xxx} to have been defined as a macro and thus contain newlines 475455839Sasmodai(it is not permitted for the argument to @code{\X} to contain newlines). 475555839SasmodaiThe inclusion of 475655839Sasmodainewlines requires an extetension to the @sc{Unix} troff output format, and will 475755839Sasmodaiconfuse drivers that do not know about this extension. 475855839Sasmodai 475955839Sasmodai 476055839Sasmodai@c distribute these through the text 476155839Sasmodai@xref{Devices} 476255839Sasmodai 476355839Sasmodai@node Miscellany, Debugging, Postprocessor Access, Programming Tutorial 476455839Sasmodai@section Miscellany 476555839Sasmodai@cindex miscellany 476655839Sasmodai 476755839Sasmodai 476855839SasmodaiThis section contains parts of troff which cannot (yet) be 476955839Sasmodaicategorized elsewhere in this manual. 477055839Sasmodai 477155839Sasmodai@findex nm 477255839SasmodaiLine numbers can be printed in the left margin 477355839Sasmodaiusing the @code{nm} request. 477455839SasmodaiThe first argument is the line number of the @emph{next} output line, 477555839Sasmodaithis defaults to 1. 477655839SasmodaiThe second argument indicates on which lines numbers will be printed, 477755839Sasmodaii.e. 5 means put line numbers on every 5 lines, this defaults to 1. 477855839SasmodaiThe third argument is the space to be left between the number and 477955839Sasmodaiyour text, this defaults to 1. 478055839SasmodaiThe fourth argument is the indentation of the line numbers. 478155839SasmodaiWithout arguments, line numbers are turned off. 478255839Sasmodai 478355839Sasmodai@findex nn 478455839SasmodaiThe @code{nn} request will temporarily turn off line numbering. 478555839SasmodaiThe first argument is the number of lines not to be numbered, 478655839Sasmodaithis defaults to 1. (does this disable incrementing or display?) 478755839Sasmodai 478855839Sasmodai@example 478955839Sasmodai... line numbering example ... 479055839Sasmodai@end example 479155839Sasmodai 479255839Sasmodai@findex mc 479355839Sasmodaimargin characters can be automatically printed to the right of your 479455839Sasmodaitext with the @code{mc} request. 479555839SasmodaiThe first argument is the character to be printed and the second 479655839Sasmodaiargument is the distance away from your text. 479755839SasmodaiWith no arguments the margin characters are turned off. 479855839SasmodaiIf this occurs before a break, no margin character will be printed. 479955839Sasmodai 480055839SasmodaiThis is quite useful for indicating text that has changed, and, in 480155839Sasmodaifact, there are programs available for doing this (they are called 480255839Sasmodai@code{nrchbar} and @code{changebar} and can be found in any 480355839Sasmodai@samp{comp.sources.unix} archive. 480455839Sasmodai 480555839Sasmodai@example 480655839Sasmodai... margin char example ... 480755839Sasmodai@end example 480855839Sasmodai 480955839Sasmodai@findex lf 481055839Sasmodai@pindex soelim 481155839SasmodaiThe @code{lf} primary reason for existence is to make debugging 481255839Sasmodaidocuments which are split into many files, which are then put 481355839Sasmodaitogether with @code{soelim} and other preprocessors. 481455839SasmodaiThe first argument is the name of the file and the second argument is 481555839Sasmodaithe input line number in that file. 481655839SasmodaiThis way troff can produce error messages which are intelligible to 481755839Sasmodaithe user. 481855839Sasmodai 481955839Sasmodai@example 482055839Sasmodai... example of soelim'ed doc ... 482155839Sasmodai@end example 482255839Sasmodai 482355839Sasmodai@node Debugging, Implementation Differences, Miscellany, Programming Tutorial 482455839Sasmodai@section Debugging 482555839Sasmodai@cindex debugging 482655839Sasmodai 482755839Sasmodai 482855839SasmodaiTroff is not easy to debug, but there are some useful features and 482955839Sasmodaistrategies for debugging. 483055839Sasmodai 483155839Sasmodai@itemize @bullet{} 483255839Sasmodai@item 483355839Sasmodai@findex tm 483455839SasmodaiThe @code{tm} request will send output to stderr, this is very useful for 483555839Sasmodaiprinting debugging output. 483655839Sasmodai@item 483755839SasmodaiWhen doing something involved it is useful to leave the debugging 483855839Sasmodaistatements in the code and have them turned on by a command line 483955839Sasmodaiflag. 484055839Sasmodai 484155839Sasmodai@example 484255839Sasmodai.if \n(DB .tm debugging output 484355839Sasmodai@end example 484455839Sasmodai 484555839SasmodaiThen you can activate these statements with: 484655839Sasmodai 484755839Sasmodai@example 484855839Sasmodaigroff -rDB=1 file 484955839Sasmodai@end example 485055839Sasmodai 485155839Sasmodai@item 485255839Sasmodai@findex ab 485355839SasmodaiThe @code{ab} request is similar to the @code{tm} request, 485455839Sasmodaiexcept that it will cause groff to stop processing. 485555839SasmodaiWith no argument it will print @samp{User Abort}. 485655839Sasmodai@item 485755839Sasmodai@findex ex 485855839SasmodaiThe @code{ex} request will also cause groff to stop processing. 485955839Sasmodai@item 486055839SasmodaiIf you know you are going to get many errors and no useful output, 486155839Sasmodaiyou can tell groff to suppress formatted output with the @samp{-z} 486255839Sasmodaiflag. 486355839Sasmodai@item 486455839Sasmodai@findex pm 486555839SasmodaiThe @code{pm} request will dump out the entire symbol table. 486655839Sasmodai@item 486755839Sasmodai@findex pnr 486855839SasmodaiThe @code{pnr} request will print the names and contents of all 486955839Sasmodaicurrently defined number registers on stderr. 487055839Sasmodai@item 487155839Sasmodai@findex ptr 487255839SasmodaiThe @code{ptr} request will 487355839Sasmodaiprint the names and positions of all traps (not including input line 487455839Sasmodaitraps and diversion traps) on stderr. Empty slots in the page trap list 487555839Sasmodaiare printed as well, because they can affect the priority of 487655839Sasmodaisubsequently planted traps. 487755839Sasmodai@item 487855839Sasmodai@findex fl 487955839SasmodaiThe @code{fl} request instructs groff to flush its output immediately. 488055839SasmodaiThe intention is that this be used when using troff interactively. 488155839SasmodaiThere is little other use for it. 488255839Sasmodai@item 488355839Sasmodai@findex backtrace 488455839SasmodaiThe @code{backtrace} request will 488555839Sasmodaiprint a backtrace of the input stack on stderr. 488655839Sasmodai@item 488755839SasmodaiGroff has command line options for printing out more warnings 488855839Sasmodai(@samp{-w}) and for printing backtraces (@samp{-b}) when a warning or 488955839Sasmodaian error occurs. The most verbose level of warnings is @samp{-ww}. 489055839Sasmodai@item 489155839Sasmodai@findex warn 489255839Sasmodai@vindex .warn 489355839SasmodaiThe @code{warn} request controls the level of warnings checked for. 489455839SasmodaiThe one argument is the sum of the numbers associated with each 489555839Sasmodaiwarning that is to be enabled; all other warnings will be disabled. 489655839SasmodaiThe number associated with each warning is listed below. 489755839SasmodaiFor example, @code{.warn 0} will disable all warnings, and 489855839Sasmodai@code{.warn 1} will disable 489955839Sasmodaiall warnings except that about missing characters. If an argument 490055839Sasmodaiis not given, all warnings will be enabled. 490155839SasmodaiThe number register @code{.warn} contains the current warning level. 490255839Sasmodai@end itemize 490355839Sasmodai 490455839Sasmodai@subsection Warnings 490555839Sasmodai@cindex warnings 490655839Sasmodai 490755839SasmodaiThe warnings that can be given by troff are divided into the 490855839Sasmodaifollowing categories. The name associated with each warning is used 490955839Sasmodaiby the @samp{-w} and @samp{-W} options; the number is used by the 491055839Sasmodai@code{warn} request, and by the @code{.warn} register. 491155839Sasmodai 491255839Sasmodai@table @samp 491355839Sasmodai@item char 491455839Sasmodai@itemx 1 491555839SasmodaiNon-existent characters. This is enabled by default. 491655839Sasmodai@item number 491755839Sasmodai@itemx 2 491855839SasmodaiInvalid numeric expressions. This is enabled by default. 491955839Sasmodai@item break 492055839Sasmodai@itemx 4 492155839SasmodaiIn fill mode, lines which could not be broken so that 492255839Sasmodaitheir length was less than the line length. This is 492355839Sasmodaienabled by default. 492455839Sasmodai@item delim 492555839Sasmodai@itemx 8 492655839SasmodaiMissing or mismatched closing delimiters. 492755839Sasmodai@item el 492855839Sasmodai@itemx 16 492955839SasmodaiUse of the @code{el} request with no matching @code{ie} request. 493055839Sasmodai@xref{if-else}, for more information. 493155839Sasmodai@item scale 493255839Sasmodai@itemx 32 493355839SasmodaiMeaningless scaling indicators. 493455839Sasmodai@item range 493555839Sasmodai@itemx 64 493655839SasmodaiOut of range arguments. 493755839Sasmodai@item syntax 493855839Sasmodai@itemx 128 493955839SasmodaiDubious syntax in numeric expressions. 494055839Sasmodai@item di 494155839Sasmodai@itemx 256 494255839Sasmodai@findex di 494355839Sasmodai@findex da 494455839SasmodaiUse of @code{di} or @code{da} without an argument when there is no 494555839Sasmodaicurrent diversion. 494655839Sasmodai@item mac 494755839Sasmodai@itemx 512 494855839SasmodaiUse of undefined strings, macros and diversions. 494955839SasmodaiWhen an undefined string, macro or diversion is used, 495055839Sasmodaithat string is automatically defined as empty. So, 495155839Sasmodaiin most cases, at most one warning will be given for 495255839Sasmodaieach name. 495355839Sasmodai@item reg 495455839Sasmodai@itemx 1024 495555839SasmodaiUse of undefined number registers. When an undefined 495655839Sasmodainumber register is used, that register is 495755839Sasmodaiautomatically defined to have a value of 0. a 495855839Sasmodaidefinition is automatically made with a value of 0. 495955839SasmodaiSo, in most cases, at most one warning will be given 496055839Sasmodaifor use of a particular name. 496155839Sasmodai@item tab 496255839Sasmodai@itemx 2048 496355839SasmodaiUse of a tab character where a number was expected. 496455839Sasmodai@item right-brace 496555839Sasmodai@itemx 4096 496655839Sasmodai@findex \@} 496755839SasmodaiUse of @code{\@}} where a number was expected. 496855839Sasmodai@item missing 496955839Sasmodai@itemx 8192 497055839SasmodaiRequests that are missing non-optional arguments. 497155839Sasmodai@item input 497255839Sasmodai@itemx 16384 497355839SasmodaiIllegal input characters. 497455839Sasmodai@item escape 497555839Sasmodai@itemx 32768 497655839SasmodaiUnrecognized escape sequences. When an unrecognized 497755839Sasmodaiescape sequence is encountered, the escape character 497855839Sasmodaiis ignored. 497955839Sasmodai@item space 498055839Sasmodai@itemx 65536 498155839SasmodaiMissing space between a request or macro and its 498255839Sasmodaiargument. This warning will be given when an 498355839Sasmodaiundefined name longer than two characters is 498455839Sasmodaiencountered, and the first two characters of the name 498555839Sasmodaimake a defined name. The request or macro will not 498655839Sasmodaibe invoked. When this warning is given, no macro is 498755839Sasmodaiautomatically defined. This is enabled by default. 498855839SasmodaiThis warning will never occur in compatibility mode. 498955839Sasmodai@item font 499055839Sasmodai@itemx 131072 499155839SasmodaiNon-existent fonts. This is enabled by default. 499255839Sasmodai@item all 499355839SasmodaiAll warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 499455839Sasmodaiintended that this covers 499555839Sasmodaiall warnings that are useful with traditional macro packages. 499655839Sasmodai@item w 499755839SasmodaiAll warnings. 499855839Sasmodai@end table 499955839Sasmodai 500055839Sasmodai 500155839Sasmodai@node Implementation Differences, Summary, Debugging, Programming Tutorial 500255839Sasmodai@section Implementation Differences 500355839Sasmodai@cindex implementation differences 500455839Sasmodai@cindex differences in implementation 500555839Sasmodai 500655839Sasmodai 500755839SasmodaiGNU troff has a number of features which cause incompatibilites with 500855839Sasmodaidocuments written with old versions of troff. 500955839Sasmodai 501055839SasmodaiLong names cause some incompatibilities. @sc{Unix} troff will interpret 501155839Sasmodai 501255839Sasmodai@example 501355839Sasmodai.dsabcd 501455839Sasmodai@end example 501555839Sasmodai 501655839Sasmodai@findex \* 501755839Sasmodai@findex \n 501855839Sasmodai@findex cp 501955839Sasmodai@vindex .C 502055839Sasmodaias defining a string @samp{ab} with contents @samp{cd}. 502155839SasmodaiNormally, GNU troff will interpret this as a call of a macro named 502255839Sasmodai@code{dsabcd}. Also @sc{Unix} troff will interpret @code{\*[} or 502355839Sasmodai@code{\n[} as references to a string or number register called 502455839Sasmodai@samp{[}. In GNU troff, however, this will normally be interpreted as the 502555839Sasmodaistart of a long name. In compatibility mode GNU troff will interpret 502655839Sasmodaithese things in the traditional way. In compatibility mode, however, 502755839Sasmodailong names are not recognised. Compatibility mode can be turned on with 502855839Sasmodaithe @samp{-C} command line option, and turned on or off with the 502955839Sasmodai@code{cp} request. 503055839SasmodaiThe number register @code{.C} is 1 if compatibility mode is on, 0 otherwise. 503155839Sasmodai 503255839Sasmodai@findex \A 503355839SasmodaiGNU troff does not allow the use of the escape sequences 503455839Sasmodai@samp{\| \^ \& \@} \@{ \@key{SP} \' \` \- \_ \! \% \c} in names of 503555839Sasmodaistrings, macros, 503655839Sasmodaidiversions, number registers, fonts or environments; @sc{Unix} troff does. 503755839SasmodaiThe @code{\A} escape sequence may be helpful in avoiding use of these escape 503855839Sasmodaisequences in names. 503955839Sasmodai 504055839Sasmodai@cindex fractional point sizes 504155839Sasmodai@cindex point sizes, fractional 504255839Sasmodai@findex ps 504355839SasmodaiFractional pointsizes cause one noteworthy incompatibility. In @sc{Unix} 504455839Sasmodaitroff the @code{ps} request ignores scale indicators and so 504555839Sasmodai 504655839Sasmodai@example 504755839Sasmodai.ps 10u 504855839Sasmodai@end example 504955839Sasmodai 505055839Sasmodaiwill set the pointsize to 10 points, whereas in GNU troff it will set 505155839Sasmodaithe pointsize to 10 scaled points. 505255839Sasmodai@xref{Fractional Type Sizes}, for more information. 505355839Sasmodai 505455839Sasmodai@findex bd 505555839Sasmodai@findex cs 505655839Sasmodai@findex tkf 505755839Sasmodai@findex tr 505855839Sasmodai@findex fp 505955839SasmodaiIn GNU troff there is a fundamental difference between unformatted, 506055839Sasmodaiinput characters, and formatted, output characters. Everything that 506155839Sasmodaiaffects how an output character will be output is stored with the 506255839Sasmodaicharacter; once an output character has been constructed it is 506355839Sasmodaiunaffected by any subsequent requests that are executed, including 506455839Sasmodai@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} 506555839Sasmodairequests. Normally output characters are constructed 506655839Sasmodaifrom input characters at the moment immediately before the character is 506755839Sasmodaiadded to the current output line. Macros, diversions and strings are 506855839Sasmodaiall, in fact, the same type of object; they contain lists of input 506955839Sasmodaicharacters and output characters in any combination. An output 507055839Sasmodaicharacter does not behave like an input character for the purposes of 507155839Sasmodaimacro processing; it does not inherit any of the special properties that 507255839Sasmodaithe input character from which it was constructed might have had. For 507355839Sasmodaiexample, 507455839Sasmodai 507555839Sasmodai@example 507655839Sasmodai.di x 507755839Sasmodai\\\\ 507855839Sasmodai.br 507955839Sasmodai.di 508055839Sasmodai.x 508155839Sasmodai@end example 508255839Sasmodai 508355839Sasmodai@findex \e 508455839Sasmodai@findex \! 508555839Sasmodai@findex \? 508655839Sasmodaiwill print @samp{\\} in GNU troff; each pair of input backslashes is 508755839Sasmodaiturned into one 508855839Sasmodaioutput backslash and the resulting output backslashes are not 508955839Sasmodaiinterpreted as escape 509055839Sasmodaicharacters when they are reread. @sc{Unix} troff would interpret them as 509155839Sasmodaiescape characters when they were reread and would end up printing one 509255839Sasmodai@samp{\}. 509355839SasmodaiThe correct way to obtain a printable backslash is to use the 509455839Sasmodai@code{\e} escape 509555839Sasmodaisequence: this will always print a single instance of the current escape 509655839Sasmodaicharacter, regardless of whether or not it is used in a diversion; it 509755839Sasmodaiwill also work in both GNU troff and @sc{Unix} troff. If you wish for some 509855839Sasmodaireason to store in a diversion an escape sequence that will be 509955839Sasmodaiinterpreted when the diversion is reread, you can either use the 510055839Sasmodaitraditional @code{\!} transparent output facility, or, if this is unsuitable, 510155839Sasmodaithe new @code{\?} escape sequence. @xref{Diversions}, for more information. 510255839Sasmodai 510355839Sasmodai 510455839Sasmodai@node Summary, , Implementation Differences, Programming Tutorial 510555839Sasmodai@section Summary 510655839Sasmodai@cindex summary 510755839Sasmodai 510855839Sasmodai 510955839Sasmodai@node geqn, gtbl, Programming Tutorial, Top 511055839Sasmodai@chapter @code{geqn} 511155839Sasmodai@cindex @code{eqn} 511255839Sasmodai@cindex @code{geqn} 511355839Sasmodai 511455839Sasmodai 511555839Sasmodai@menu 511655839Sasmodai* Invoking geqn:: 511755839Sasmodai@end menu 511855839Sasmodai 511955839Sasmodai@node Invoking geqn, , geqn, geqn 512055839Sasmodai@section Invoking @code{geqn} 512155839Sasmodai@cindex invoking @code{geqn} 512255839Sasmodai@cindex @code{geqn}, invoking 512355839Sasmodai 512455839Sasmodai 512555839Sasmodai 512655839Sasmodai@node gtbl, gpic, geqn, Top 512755839Sasmodai@chapter @code{gtbl} 512855839Sasmodai@cindex @code{tbl} 512955839Sasmodai@cindex @code{gtbl} 513055839Sasmodai 513155839Sasmodai 513255839Sasmodai@menu 513355839Sasmodai* Invoking gtbl:: 513455839Sasmodai@end menu 513555839Sasmodai 513655839Sasmodai@node Invoking gtbl, , gtbl, gtbl 513755839Sasmodai@section Invoking @code{gtbl} 513855839Sasmodai@cindex invoking @code{gtbl} 513955839Sasmodai@cindex @code{gtbl}, invoking 514055839Sasmodai 514155839Sasmodai 514255839Sasmodai@node gpic, grap, gtbl, Top 514355839Sasmodai@chapter @code{gpic} 514455839Sasmodai@cindex @code{pic} 514555839Sasmodai@cindex @code{gpic} 514655839Sasmodai 514755839Sasmodai 514855839Sasmodai@menu 514955839Sasmodai* Invoking gpic:: 515055839Sasmodai@end menu 515155839Sasmodai 515255839Sasmodai@node Invoking gpic, , gpic, gpic 515355839Sasmodai@section Invoking @code{gpic} 515455839Sasmodai@cindex invoking @code{gpic} 515555839Sasmodai@cindex @code{gpic}, invoking 515655839Sasmodai 515755839Sasmodai 515855839Sasmodai 515955839Sasmodai@node grap, grefer, gpic, Top 516055839Sasmodai@chapter @code{grap} 516155839Sasmodai@cindex @code{grap} 516255839Sasmodai 516355839Sasmodai 516455839Sasmodai 516555839Sasmodai@node grefer, gsoelim, grap, Top 516655839Sasmodai@chapter @code{grefer} 516755839Sasmodai@cindex @code{refer} 516855839Sasmodai@cindex @code{grefer} 516955839Sasmodai 517055839Sasmodai 517155839Sasmodai@menu 517255839Sasmodai* Invoking grefer:: 517355839Sasmodai@end menu 517455839Sasmodai 517555839Sasmodai@node Invoking grefer, , grefer, grefer 517655839Sasmodai@section Invoking @code{grefer} 517755839Sasmodai@cindex invoking @code{grefer} 517855839Sasmodai@cindex @code{grefer}, invoking 517955839Sasmodai 518055839Sasmodai 518155839Sasmodai 518255839Sasmodai@node gsoelim, Devices, grefer, Top 518355839Sasmodai@chapter @code{gsoelim} 518455839Sasmodai@cindex @code{soelim} 518555839Sasmodai@cindex @code{gsoelim} 518655839Sasmodai 518755839Sasmodai 518855839Sasmodai@menu 518955839Sasmodai* Invoking gsoelim:: 519055839Sasmodai@end menu 519155839Sasmodai 519255839Sasmodai@node Invoking gsoelim, , gsoelim, gsoelim 519355839Sasmodai@section Invoking @code{gsoelim} 519455839Sasmodai@cindex invoking @code{gsoelim} 519555839Sasmodai@cindex @code{gsoelim}, invoking 519655839Sasmodai 519755839Sasmodai 519855839Sasmodai 519955839Sasmodai@node Devices, File formats, gsoelim, Top 520055839Sasmodai@chapter Devices 520155839Sasmodai@cindex devices 520255839Sasmodai 520355839Sasmodai 520455839Sasmodai 520555839Sasmodai@menu 520655839Sasmodai* Special Characters:: 520755839Sasmodai* grotty:: 520855839Sasmodai* grops:: 520955839Sasmodai* grodvi:: 521055839Sasmodai* grolj4:: 521155839Sasmodai* grohtml:: 521255839Sasmodai* gxditview:: 521355839Sasmodai@end menu 521455839Sasmodai 521555839Sasmodai@node Special Characters, grotty, Devices, Devices 521655839Sasmodai@section Special Characters 521755839Sasmodai@cindex special characters 521855839Sasmodai@cindex characters, special 521955839Sasmodai 522055839Sasmodai 522155839Sasmodai@c distribute these through the text 522255839Sasmodai@xref{Font Files} 522355839Sasmodai 522455839Sasmodai@node grotty, grops, Special Characters, Devices 522555839Sasmodai@section @code{grotty} 522655839Sasmodai@cindex @code{grotty} 522755839Sasmodai 522855839Sasmodai 522955839Sasmodai 523055839Sasmodai@menu 523155839Sasmodai* Invoking grotty:: 523255839Sasmodai@end menu 523355839Sasmodai 523455839Sasmodai@node Invoking grotty, , grotty, grotty 523555839Sasmodai@subsection Invoking @code{grotty} 523655839Sasmodai@cindex invoking @code{grotty} 523755839Sasmodai@cindex @code{grotty}, invoking 523855839Sasmodai 523955839Sasmodai 524055839Sasmodai 524155839Sasmodai@node grops, grodvi, grotty, Devices 524255839Sasmodai@section @code{grops} 524355839Sasmodai@cindex @code{grops} 524455839Sasmodai 524555839Sasmodai 524655839Sasmodai 524755839Sasmodai@menu 524855839Sasmodai* Invoking grops:: 524955839Sasmodai* Embedding PostScript:: 525055839Sasmodai@end menu 525155839Sasmodai 525255839Sasmodai@node Invoking grops, Embedding PostScript, grops, grops 525355839Sasmodai@subsection Invoking @code{grops} 525455839Sasmodai@cindex invoking @code{grops} 525555839Sasmodai@cindex @code{grops}, invoking 525655839Sasmodai 525755839Sasmodai 525855839Sasmodai 525955839Sasmodai@node Embedding PostScript, , Invoking grops, grops 526055839Sasmodai@subsection Embedding PostScript 526155839Sasmodai@cindex embedding postscript 526255839Sasmodai@cindex postscript, embedding 526355839Sasmodai 526455839Sasmodai 526555839Sasmodai 526655839Sasmodai@node grodvi, grolj4, grops, Devices 526755839Sasmodai@section @code{grodvi} 526855839Sasmodai@cindex @code{grodvi} 526955839Sasmodai 527055839Sasmodai 527155839Sasmodai 527255839Sasmodai@menu 527355839Sasmodai* Invoking grodvi:: 527455839Sasmodai@end menu 527555839Sasmodai 527655839Sasmodai@node Invoking grodvi, , grodvi, grodvi 527755839Sasmodai@subsection Invoking @code{grodvi} 527855839Sasmodai@cindex invoking @code{grodvi} 527955839Sasmodai@cindex @code{grodvi}, invoking 528055839Sasmodai 528155839Sasmodai 528255839Sasmodai 528355839Sasmodai@node grolj4, grohtml, grodvi, Devices 528455839Sasmodai@section @code{grolj4} 528555839Sasmodai@cindex @code{grolj4} 528655839Sasmodai 528755839Sasmodai 528855839Sasmodai 528955839Sasmodai@menu 529055839Sasmodai* Invoking grolj4:: 529155839Sasmodai@end menu 529255839Sasmodai 529355839Sasmodai@node Invoking grolj4, , grolj4, grolj4 529455839Sasmodai@subsection Invoking @code{grolj4} 529555839Sasmodai@cindex invoking @code{grolj4} 529655839Sasmodai@cindex @code{grolj4}, invoking 529755839Sasmodai 529855839Sasmodai 529955839Sasmodai 530055839Sasmodai@node grohtml, gxditview, grolj4, Devices 530155839Sasmodai@section @code{grohtml} 530255839Sasmodai@cindex @code{grohtml} 530355839Sasmodai 530455839Sasmodai 530555839Sasmodai 530655839Sasmodai@menu 530755839Sasmodai* Invoking grohtml:: 530855839Sasmodai@end menu 530955839Sasmodai 531055839Sasmodai@node Invoking grohtml, , grohtml, grohtml 531155839Sasmodai@subsection Invoking @code{grohtml} 531255839Sasmodai@cindex invoking @code{grohtml} 531355839Sasmodai@cindex @code{grohtml}, invoking 531455839Sasmodai 531555839Sasmodai 531655839Sasmodai 531755839Sasmodai@node gxditview, , grohtml, Devices 531855839Sasmodai@section @code{gxditview} 531955839Sasmodai@cindex @code{gxditview} 532055839Sasmodai 532155839Sasmodai 532255839Sasmodai 532355839Sasmodai@menu 532455839Sasmodai* Invoking gxditview:: 532555839Sasmodai@end menu 532655839Sasmodai 532755839Sasmodai@node Invoking gxditview, , gxditview, gxditview 532855839Sasmodai@subsection Invoking @code{gxditview} 532955839Sasmodai@cindex invoking @code{gxditview} 533055839Sasmodai@cindex @code{gxditview}, invoking 533155839Sasmodai 533255839Sasmodai 533355839Sasmodai 533455839Sasmodai@node File formats, Installation, Devices, Top 533555839Sasmodai@chapter File formats 533655839Sasmodai@cindex file formats 533755839Sasmodai@cindex formats, file 533855839Sasmodai 533955839Sasmodai 534055839Sasmodai 534155839Sasmodai@menu 534255839Sasmodai* gtroff Output:: 534355839Sasmodai* Font Files:: 534455839Sasmodai@end menu 534555839Sasmodai 534655839Sasmodai@node gtroff Output, Font Files, File formats, File formats 534755839Sasmodai@section @code{gtroff} Output 534855839Sasmodai@cindex @code{gtroff} output 534955839Sasmodai@cindex output, @code{gtroff} 535055839Sasmodai 535155839Sasmodai 535255839SasmodaiThis section describes the format output by GNU troff. The output 535355839Sasmodaiformat used by GNU troff is very similar to that used by @sc{Unix} 535455839Sasmodaidevice-independent troff. 535555839Sasmodai 535655839SasmodaiThe output format is ascii based, as opposed to a binary format (like 535755839Sasmodai@TeX{} dvi). 535855839SasmodaiThe output format is 8 bit clean, thus single characters can have the 535955839Sasmodaieighth bit set, as can the names of fonts and special characters. 536055839Sasmodai 536155839SasmodaiThe output format consists of single command characters with attached 536255839Sasmodaiparameters which are separated from subsequent text by whitespace, or 536355839Sasmodaia newline. 536455839Sasmodai 536555839SasmodaiThe names of characters and fonts an be of arbitrary length; drivers 536655839Sasmodaishould not assume that they will be only two characters long (as 536755839Sasmodaidevice-independent troff did). 536855839Sasmodai 536955839SasmodaiWhen a character is to be printed, that character will always be in the 537055839Sasmodaicurrent font. 537155839SasmodaiUnlike device-independent troff, it is not necessary for 537255839Sasmodaidrivers to search special fonts to find a character. 537355839Sasmodai 537455839Sasmodai@table @code 537555839Sasmodai@item H@var{n} 537655839Sasmodai@item V@var{n} 537755839Sasmodai@item h@var{n} 537855839Sasmodai@item v@var{n} 537955839Sasmodai@item c@var{n} 538055839Sasmodai@item C@var{n} 538155839Sasmodai@item @var{nn}@var{c} 538255839Sasmodai@item t@var{xxx} 538355839Sasmodai@var{xxx} is any sequence of characters terminated by a space or a 538455839Sasmodainewline; the first character should be printed at the current 538555839Sasmodaiposition, the the current horizontal position should be increased by 538655839Sasmodaithe width of the first character, and so on for each character. 538755839SasmodaiThe width of the character is that given in the font file, 538855839Sasmodaiappropriately scaled for the current point size, 538955839Sasmodaiand rounded so that it is a multiple of the horizontal resolution. 539055839SasmodaiSpecial characters cannot be printed using this command. 539155839Sasmodai 539255839SasmodaiThis command is only allowed if the @samp{tcommand} line is present 539355839Sasmodaiin the @file{DESC} file. 539455839Sasmodai@item u@var{n} @var{xxx} 539555839Sasmodai@pindex DESC 539655839SasmodaiThis is same as the @code{t} command except that after printing each 539755839Sasmodaicharacter, the current horizontal position is increased by the sum of 539855839Sasmodaithe width of that character and @code{n}. 539955839Sasmodai 540055839SasmodaiThis command is only allowed if the @samp{tcommand} line is present 540155839Sasmodaiin the @file{DESC} file. 540255839Sasmodai@item n@var{a}@var{b} 540355839Sasmodai@item p@var{n} 540455839Sasmodai@item s@var{n} 540555839SasmodaiThe argument to the s command is in scaled points (units of points/n, 540655839Sasmodaiwhere n is the argument to the sizescale command in the DESC file.) 540755839Sasmodai@item f@var{n} 540855839Sasmodai@item x @dots{} \n 540955839SasmodaiDevice control. 541055839Sasmodai@item D@var{c} @var{x}@dots{}\n 541155839Sasmodai@end table 541255839Sasmodai 541355839Sasmodai@subsection Device Control 541455839Sasmodai 541555839SasmodaiThe @code{x} command is normally followed by a letter or word 541655839Sasmodaiindicating the function to perform, followed by white space separated 541755839Sasmodaiarguments. 541855839Sasmodai 541955839SasmodaiThe first argument can be abreviated to the first letter. 542055839Sasmodai 542155839Sasmodai@table @code 542255839Sasmodai@item x init 542355839Sasmodai@item x T 542455839Sasmodai@item x res @var{n} @var{h} @var{v} 542555839Sasmodai@item x H 542655839SasmodaiThe argument to the x Height command is also in scaled points. 542755839Sasmodai@end table 542855839Sasmodai 542955839SasmodaiThe first three output commands are guaranteed to be: 543055839Sasmodai 543155839Sasmodai@example 543255839Sasmodaix T device 543355839Sasmodaix res n h v 543455839Sasmodaix init 543555839Sasmodai@end example 543655839Sasmodai 543755839SasmodaiFor example, the input @samp{crunchy \fH\s+2frog\s0\fP!?} will produce: 543855839Sasmodai 543955839Sasmodai@example 544055839Sasmodai... sample output here ... 544155839Sasmodai@end example 544255839Sasmodai 544355839Sasmodai@subsection Drawing Functions 544455839Sasmodai 544555839SasmodaiThe D drawing command has been extended. These extensions will only be 544655839Sasmodaiused by GNU pic if the -x option is given. 544755839Sasmodai 544855839Sasmodai@table @code 544955839Sasmodai... 545055839Sasmodai@item Df n\n 545155839SasmodaiSet the shade of gray to be used for filling solid objects to n; n must 545255839Sasmodaibe an integer between 0 and 1000, where 0 corresponds solid white and 545355839Sasmodai1000 to solid black, and values in between correspond to intermediate 545455839Sasmodaishades of gray. This applies only to solid circles, solid ellipses and 545555839Sasmodaisolid polygons. By default, a level of 1000 will be used. Whatever 545655839Sasmodaicolor a solid object has, it should completely obscure everything 545755839Sasmodaibeneath it. A value greater than 1000 or less than 0 can also be used: 545855839Sasmodaithis means fill with the shade of gray that is currently being used for 545955839Sasmodailines and text. Normally this will be black, but some drivers may 546055839Sasmodaiprovide a way of changing this. 546155839Sasmodai@item DC d\n 546255839SasmodaiDraw a solid circle with a diameter of d with the leftmost point at the 546355839Sasmodaicurrent position. 546455839Sasmodai@item DE dx dy\n 546555839SasmodaiDraw a solid ellipse with a horizontal diameter of dx and a vertical 546655839Sasmodaidiameter of dy with the leftmost point at the current position. 546755839Sasmodai@item Dp $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub 546855839Sasmodain$\n 546955839SasmodaiDraw a polygon with, for $i = 1 ,..., n+1$, the i-th vertex at the 547055839Sasmodaicurrent position $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$. At 547155839Sasmodaithe moment, GNU pic only uses this command to generate triangles and 547255839Sasmodairectangles. 547355839Sasmodai@item DP $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub 547455839Sasmodain$\n 547555839SasmodaiLike Dp but draw a solid rather than outlined polygon. 547655839Sasmodai@item Dt n\n 547755839SasmodaiSet the current line thickness to n machine units. Traditionally @sc{Unix} 547855839Sasmodaitroff drivers use a line thickness proportional to the current point 547955839Sasmodaisize; drivers should continue to do this if no Dt command has been 548055839Sasmodaigiven, or if a Dt command has been given with a negative value of n. A 548155839Sasmodaizero value of n selects the smallest available line thickness. 548255839Sasmodai@end table 548355839Sasmodai 548455839SasmodaiA difficulty arises in how the current position should be changed after 548555839Sasmodaithe execution of these commands. This is not of great importance since 548655839Sasmodaithe code generated by GNU pic does not depend on this. Given a drawing 548755839Sasmodaicommand of the form 548855839Sasmodai 548955839Sasmodai\D'c $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$' 549055839Sasmodai 549155839Sasmodaiwhere c is not one of c, e, l, a or ~, @sc{Unix} troff will treat each of the 549255839Sasmodai$x sub i$ as a horizontal quantity, and each of the $y sub i$ as a 549355839Sasmodaivertical quantity and will assume that the width of the drawn object is 549455839Sasmodai$sum from i=1 to n x sub i$, and that the height is $sum from i=1 to n y 549555839Sasmodaisub i$. (The assumption about the height can be seen by examining the 549655839Sasmodaist and sb registers after using such a D command in a \w escape 549755839Sasmodaisequence.) This rule also holds for all the original drawing commands 549855839Sasmodaiwith the exception of De. For the sake of compatibility GNU troff also 549955839Sasmodaifollows this rule, even though it produces an ugly result in the case of 550055839Sasmodaithe Df, Dt, and, to a lesser extent, DE commands. Thus after executing 550155839Sasmodaia D command of the form 550255839Sasmodai 550355839SasmodaiDc $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\n 550455839Sasmodai 550555839Sasmodaithe current position should be increased by $( sum from i=1 to n x sub i 550655839Sasmodai, sum from i=1 to n y sub i )$. 550755839Sasmodai 550855839Sasmodai@subsection Line Continuation 550955839Sasmodai 551055839SasmodaiThere is a continuation convention which permits the argument to the x X 551155839Sasmodaicommand to contain newlines: when outputting the argument to the x X 551255839Sasmodaicommand, GNU troff will follow each newline in the argument with a + 551355839Sasmodaicharacter (as usual, it will terminate the entire argument with a 551455839Sasmodainewline); thus if the line after the line containing the x X command 551555839Sasmodaistarts with +, then the newline ending the line containing the x X 551655839Sasmodaicommand should be treated as part of the argument to the x X command, 551755839Sasmodaithe + should be ignored, and the part of the line following the + should 551855839Sasmodaibe treated like the part of the line following the x X command. 551955839Sasmodai 552055839Sasmodai 552155839Sasmodai 552255839Sasmodai 552355839Sasmodai@node Font Files, , gtroff Output, File formats 552455839Sasmodai@section Font Files 552555839Sasmodai@cindex font files 552655839Sasmodai@cindex files, font 552755839Sasmodai 552855839Sasmodai 552955839SasmodaiThe groff font format is roughly a superset of the ditroff font 553055839Sasmodaiformat. Unlike the ditroff font format, there is no associated binary 553155839Sasmodaiformat. The font files for device name are stored in a directory 553255839Sasmodai@file{dev@var{name}}. There are two types of file: a device 553355839Sasmodaidescription file called @file{DESC} and for each font @samp{F} a font 553455839Sasmodaifile called @file{F}. These are text files; there is no associated 553555839Sasmodaibinary format. 553655839Sasmodai 553755839Sasmodai@subsection @file{DESC} file format 553855839Sasmodai@pindex DESC 553955839Sasmodai 554055839SasmodaiThe @file{DESC} file can contain the following types of line: 554155839Sasmodai 554255839Sasmodai@table @code 554355839Sasmodai@item res @var{n} 554455839SasmodaiThere are @var{n} machine units per inch. 554555839Sasmodai@item hor @var{n} 554655839SasmodaiThe horizontal resolution is @var{n} machine units. 554755839Sasmodai@item vert @var{n} 554855839SasmodaiThe vertical resolution is @var{n} machine units. 554955839Sasmodai@item sizescale @var{n} 555055839SasmodaiThe scale factor for pointsizes. By default this has a value of 1. One 555155839Sasmodaiscaled point is equal to one point/@var{n}. The arguments to the 555255839Sasmodai@code{unitwidth} and @code{sizes} commands are given in scaled points. 555355839Sasmodai@xref{Fractional Type Sizes}, for more information. 555455839Sasmodai@item unitwidth @var{n} 555555839SasmodaiQuantities in the font files are given in machine units for fonts whose 555655839Sasmodaipoint size is @var{n} scaled points. 555755839Sasmodai@item tcommand 555855839SasmodaiThis means that the postprocessor can handle the @code{t} and 555955839Sasmodai@code{u} output commands. 556055839Sasmodai@item sizes @var{s1} @var{s2}@dots{}@var{sn} 0 556155839SasmodaiThis means that the device has fonts at @var{s1}, @var{s2}, 556255839Sasmodai@dots{}@var{sn} scaled points. The list of sizes must be terminated 556355839Sasmodaiby a 0. Each @var{si} can also be a range of 556455839Sasmodaisizes @var{m}-@var{n}. The list can extend over more than one line. 556555839Sasmodai@item styles @var{S1 S2@dots{}Sm} 556655839SasmodaiThe first @var{m} font positions will be associated with styles 556755839Sasmodai@var{S1}@dots{}@var{Sm}. 556855839Sasmodai@item fonts @var{n} @var{F1 F2 F3@dots{}Fn} 556955839SasmodaiFonts @var{F1@dots{}Fn} will be mounted in the font positions 557055839Sasmodai@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} 557155839Sasmodaiis the number of styles. This command may extend over more than one 557255839Sasmodailine. A font name of 0 will cause no font to be mounted on the 557355839Sasmodaicorresponding font position. 557455839Sasmodai@item family @var{fam} 557555839SasmodaiThe default font family is @var{fam}. 557655839Sasmodai@item charset 557755839SasmodaiThis line and everything following in the file are ignored. It is 557855839Sasmodaiallowed for the sake of backwards compatibility. 557955839Sasmodai@end table 558055839Sasmodai 558155839SasmodaiThe @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines 558255839Sasmodaiare compulsory. Other commands are ignored by troff but may be used 558355839Sasmodaiby postprocessors to store arbitrary information about the device in 558455839Sasmodaithe @file{DESC} file. 558555839Sasmodai 558655839Sasmodai 558755839Sasmodai@subsection Font file format 558855839Sasmodai 558955839SasmodaiA font file has two sections. The first section is a sequence of lines 559055839Sasmodaieach containing a sequence of blank delimited words; the first word in 559155839Sasmodaithe line is a key, and subsequent words give a value for that key. 559255839Sasmodai 559355839Sasmodai@table @code 559455839Sasmodai@item name @var{F} 559555839SasmodaiThe name of the font is @var{F}. 559655839Sasmodai@item spacewidth @var{n} 559755839SasmodaiThe normal width of a space is @var{n}. 559855839Sasmodai@item slant @var{n} 559955839SasmodaiThe characters of the font have a slant of @var{n} degrees. 560055839Sasmodai(Positive means forward.) 560155839Sasmodai@item ligatures @var{lig1} @var{lig2}@dots{}@var{lign} [0] 560255839SasmodaiCharacters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 560355839Sasmodaipossible ligatures are ff, fi, fl and ffl. For backwards 560455839Sasmodaicompatibiliy, the list of ligatures may be terminated with a 0. The 560555839Sasmodailist of ligatures may not extend over more than one line. 560655839Sasmodai@item special 560755839SasmodaiThe font is special; this means that when a character is requested that 560855839Sasmodaiis not present in the current font, it will be searched for in any 560955839Sasmodaispecial fonts that are mounted. 561055839Sasmodai@end table 561155839Sasmodai 561255839SasmodaiOther commands are ignored by troff but may be used by postprocessors to 561355839Sasmodaistore arbitrary information about the font in the font file. 561455839Sasmodai 561555839SasmodaiThe first section can contain comments which start with the # character 561655839Sasmodaiand extend to the end of a line. 561755839Sasmodai 561855839SasmodaiThe second section contains one or two subsections. It must contain a 561955839Sasmodai@code{charset} subsection and it may also contain a @code{kernpairs} 562055839Sasmodaisubsection. These subsections can appear in any order. Each 562155839Sasmodaisubsection starts with a word on a line by itself. 562255839Sasmodai 562355839SasmodaiThe word @code{charset} starts the @code{charset} subsection. The 562455839Sasmodai@code{charset} line is followed by a sequence of lines. Each line 562555839Sasmodaigives information for one character. A line comprises a number of 562655839Sasmodaifields separated by blanks or tabs. The format is 562755839Sasmodai 562855839Sasmodai@display 562955839Sasmodai@var{name} @var{metrics} @var{type} @var{code} @var{comment} 563055839Sasmodai@end display 563155839Sasmodai 563255839Sasmodai@var{name} identifies the character: if @var{name} is a single 563355839Sasmodaicharacter @var{c} then it corresponds to the groff input character 563455839Sasmodai@var{c}; if it is of the form @samp{\@var{c}} where @var{c} is a 563555839Sasmodaisingle character, then it corresponds to the groff input character 563655839Sasmodai@samp{\@var{c}}; otherwise it corresponds to the groff input character 563755839Sasmodai@samp{\[@var{name}]} (if it is exactly two characters @var{xx} it can 563855839Sasmodaibe entered as @samp{\(@var{xx}}.) Groff supports eight bit characters; 563955839Sasmodaihowever some utilities has difficulties with eight bit characters. 564055839SasmodaiFor this reason, there is a convention that the @var{name} 564155839Sasmodai@samp{char@var{n}} is equivalent to the single character whose code is 564255839Sasmodai@var{n}. For example, @samp{char163} would be equivalent to the 564355839Sasmodaicharacter with @var{code} 163 which is the pounds sterling sign in ISO 564455839SasmodaiLatin-1 character set. The name @samp{---} is special and indicates 564555839Sasmodaithat the character is unnamed; such characters can only be used by 564655839Sasmodaimeans of the @code{\N} escape sequence in troff. 564755839Sasmodai 564855839SasmodaiThe @var{type} field gives the character type: 564955839Sasmodai 565055839Sasmodai@table @code 565155839Sasmodai@item 1 565255839Sasmodaimeans the character has an descender, for example, p; 565355839Sasmodai@item 2 565455839Sasmodaimeans the character has an ascender, for example, b; 565555839Sasmodai@item 3 565655839Sasmodaimeans the character has both an ascender and a descender, for example, 565755839Sasmodai@samp{(}. 565855839Sasmodai@end table 565955839Sasmodai 566055839SasmodaiThe @var{code} field gives the code which the postprocessor uses to 566155839Sasmodaiprint the character. The character can also be input to groff using 566255839Sasmodaithis code by means of the @code{\N} escape sequence. The code can be any 566355839Sasmodaiinteger. If it starts with a 0 it will be interpreted as octal; if it 566455839Sasmodaistarts with 0x or 0X it will be intepreted as hexdecimal. 566555839Sasmodai 566655839SasmodaiAnything on the line after the @var{code} field will be ignored. 566755839Sasmodai 566855839SasmodaiThe @var{metrics} field has the form: 566955839Sasmodai 567055839Sasmodai@smallexample 567155839Sasmodai@var{width[,height[,depth[,italic_correction[,left_italic_correction[,subscript_correction]]]]]} 567255839Sasmodai@end smallexample 567355839Sasmodai 567455839SasmodaiThere must not be any spaces between these subfields. Missing 567555839Sasmodaisubfields are assumed to be 0. The subfields are all decimal 567655839Sasmodaiintegers. Since there is no associated binary format, these values 567755839Sasmodaiare not required to fit into a variable of type @samp{char} as they 567855839Sasmodaiare in ditroff. The @var{width} subfields gives the width of the 567955839Sasmodaicharacter. The @var{height} subfield gives the height of the 568055839Sasmodaicharacter (upwards is positive); if a character does not extend above 568155839Sasmodaithe baseline, it should be given a zero height, rather than a negative 568255839Sasmodaiheight. The @var{depth} subfield gives the depth of the character, 568355839Sasmodaithat is, the distance below the lowest point below the baseline to 568455839Sasmodaiwhich the character extends (downwards is positive); if a character 568555839Sasmodaidoes not extend below above the baseline, it should be given a zero 568655839Sasmodaidepth, rather than a negative depth. The @var{italic_correction} 568755839Sasmodaisubfield gives the amount of space that should be added after the 568855839Sasmodaicharacter when it is immediately to be followed by a character from a 568955839Sasmodairoman font. The @var{left_italic_correction} subfield gives the 569055839Sasmodaiamount of space that should be added before the character when it is 569155839Sasmodaiimmediately to be preceded by a character from a roman font. The 569255839Sasmodai@var{subscript_correction} gives the amount of space that should be 569355839Sasmodaiadded after a character before adding a subscript. This should be less 569455839Sasmodaithan the italic correction. 569555839Sasmodai 569655839SasmodaiA line in the @code{charset} section can also have the format 569755839Sasmodai 569855839Sasmodai@example 569955839Sasmodai@var{name} " 570055839Sasmodai@end example 570155839Sasmodai 570255839SasmodaiThis indicates that @var{name} is just another name for the character 570355839Sasmodaimentioned in the preceding line. 570455839Sasmodai 570555839SasmodaiThe word @code{kernpairs} starts the kernpairs section. This contains a 570655839Sasmodaisequence of lines of the form: 570755839Sasmodai 570855839Sasmodai@display 570955839Sasmodai@var{c1 c2 n} 571055839Sasmodai@end display 571155839Sasmodai 571255839SasmodaiThis means that when character @var{c1} appears next to character 571355839Sasmodai@var{c2} the space between them should be increased by @var{n}. Most 571455839Sasmodaientries in kernpairs section will have a negative value for @var{n}. 571555839Sasmodai 571655839Sasmodai 571755839Sasmodai 571855839Sasmodai@node Installation, Request Index, File formats, Top 571955839Sasmodai@chapter Installation 572055839Sasmodai@cindex installation 572155839Sasmodai 572255839Sasmodai 572355839Sasmodai 572455839Sasmodai@node Request Index, Register Index, Installation, Top 572555839Sasmodai@chapter Request Index 572655839Sasmodai 572755839Sasmodai@printindex fn 572855839Sasmodai 572955839Sasmodai 573055839Sasmodai@node Register Index, String Index, Request Index, Top 573155839Sasmodai@chapter Register Index 573255839Sasmodai 573355839Sasmodai@printindex vr 573455839Sasmodai 573555839Sasmodai 573655839Sasmodai@node String Index, Macro Index, Register Index, Top 573755839Sasmodai@chapter String Index 573855839Sasmodai 573955839Sasmodai 574055839Sasmodai 574155839Sasmodai@node Macro Index, Program Index, String Index, Top 574255839Sasmodai@chapter Macro Index 574355839Sasmodai 574455839Sasmodai 574555839Sasmodai 574655839Sasmodai@node Program Index, Concept Index, Macro Index, Top 574755839Sasmodai@chapter Program Index 574855839Sasmodai 574955839Sasmodai@printindex pg 575055839Sasmodai 575155839Sasmodai 575255839Sasmodai 575355839Sasmodai@node Concept Index, , Program Index, Top 575455839Sasmodai@chapter Concept Index 575555839Sasmodai 575655839Sasmodai@printindex cp 575755839Sasmodai 575855839Sasmodai 575955839Sasmodai 576055839Sasmodai@summarycontents 576155839Sasmodai@contents 576255839Sasmodai@bye 5763