groff.texinfo revision 104862
155839Sasmodai\input texinfo @c -*-texinfo-*- 269626Sru 369626Sru@c 475584Sru@c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug 575584Sru@c in texinfo regarding expansion of user-defined macros. 669626Sru@c 7104862Sru@c You need texinfo 4.2 or newer to format this document! 8104862Sru@c 969626Sru 1055839Sasmodai@c %**start of header (This is for running Texinfo on a region.) 11104862Sru@setfilename groff 1255839Sasmodai@settitle The GNU Troff Manual 1355839Sasmodai@setchapternewpage odd 1455839Sasmodai@footnotestyle separate 1555839Sasmodai@c %**end of header (This is for running Texinfo on a region.) 1655839Sasmodai 1755839Sasmodai 18104862Sru@smallbook 19104862Sru 20104862Sru@finalout 21104862Sru 22104862Sru 23104862Sru@copying 24104862SruThis manual documents GNU @code{troff} version 1.18. 25104862Sru 26104862SruCopyright @copyright{} 1994-2000, 2001, 2002 Free Software Foundation, Inc. 27104862Sru 28104862Sru@quotation 29104862SruPermission is granted to copy, distribute and/or modify this document 30104862Sruunder the terms of the GNU Free Documentation License, Version 1.1 or 31104862Sruany later version published by the Free Software Foundation; with no 32104862SruInvariant Sections, with the Front-Cover texts being `A GNU Manual,'' 33104862Sruand with the Back-Cover Texts as in (a) below. A copy of the 34104862Srulicense is included in the section entitled `GNU Free Documentation 35104862SruLicense.'' 36104862Sru 37104862Sru(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 38104862Sruthis GNU Manual, like GNU software. Copies published by the Free 39104862SruSoftware Foundation raise funds for GNU development.'' 40104862Sru@end quotation 41104862Sru@end copying 42104862Sru 43104862Sru 4469626Sru@c We use the following indices: 4569626Sru@c 4669626Sru@c cindex: concepts 4775584Sru@c rqindex: requests 4875584Sru@c esindex: escapes 4969626Sru@c vindex: registers 5069626Sru@c kindex: commands in font files 5169626Sru@c pindex: programs and files 5269626Sru@c tindex: environment variables 5375584Sru@c maindex: macros 5475584Sru@c stindex: strings 5569626Sru@c opindex: operators 5669626Sru@c 5769626Sru@c tindex and cindex are merged. 5869626Sru 5975584Sru@defcodeindex rq 6075584Sru@defcodeindex es 6169626Sru@defcodeindex ma 6275584Sru@defcodeindex st 6369626Sru@defcodeindex op 6469626Sru@syncodeindex tp cp 6569626Sru 6669626Sru 6775584Sru@c to avoid uppercasing in @deffn while converting to info, we define 6875584Sru@c our special @Var{} 6975584Sru@c 7075584Sru@c due to a (not officially documented) `feature' in makeinfo 4.0, 7175584Sru@c macros are not expanded in @deffn (but the macro definition is 7275584Sru@c properly removed), so we have to define @Var{} directly in TeX also 7375584Sru 7475584Sru@macro Var{arg} 7575584Sru\arg\ 7669626Sru@end macro 7775584Sru@tex 7875584Sru\gdef\Var#1{\var{#1}} 7975584Sru@end tex 8069626Sru 8175584Sru 82104862Sru@c To assure correct HTML translation, some ugly hacks are necessary. 83104862Sru@c While processing a @def... request, the HTML translator looks at the 84104862Sru@c next line to decide whether it should start indentation or not. If 85104862Sru@c it is something starting with @def... (e.g. @deffnx), it doesn't. 86104862Sru@c So we must assure during macro expansion that a @def... is seen. 87104862Sru@c 88104862Sru@c The following macros have to be used: 89104862Sru@c 90104862Sru@c One item: 91104862Sru@c 92104862Sru@c @Def... 93104862Sru@c 94104862Sru@c Two items: 95104862Sru@c 96104862Sru@c @Def...List 97104862Sru@c @Def...ListEnd 98104862Sru@c 99104862Sru@c More than two: 100104862Sru@c 101104862Sru@c @Def...List 102104862Sru@c @Def...Item 103104862Sru@c @Def...Item 104104862Sru@c ... 105104862Sru@c @Def...ListEnd 106104862Sru@c 107104862Sru@c The definition block must end with 108104862Sru@c 109104862Sru@c @endDef... 110104862Sru@c 111104862Sru@c The above is valid for texinfo 4.0f. 112104862Sru 113104862Sru 114104862Sru@c a dummy macro to assure the `@def...' 115104862Sru 116104862Sru@macro defdummy 117104862Sru@end macro 118104862Sru 119104862Sru 12075584Sru@c definition of requests 12175584Sru 12275584Sru@macro Defreq{name, arg} 123104862Sru@deffn Request @t{.\name\} \arg\ 12475584Sru@rqindex \name\ 125104862Sru@end macro 126104862Sru 127104862Sru@macro DefreqList{name, arg} 12875584Sru@deffn Request @t{.\name\} \arg\ 129104862Sru@defdummy 130104862Sru@rqindex \name\ 13175584Sru@end macro 13275584Sru 133104862Sru@macro DefreqItem{name, arg} 134104862Sru@deffnx Request @t{.\name\} \arg\ 135104862Sru@defdummy 13675584Sru@rqindex \name\ 137104862Sru@end macro 138104862Sru 139104862Sru@macro DefreqListEnd{name, arg} 14075584Sru@deffnx Request @t{.\name\} \arg\ 141104862Sru@rqindex \name\ 14275584Sru@end macro 14375584Sru 14475584Sru@macro endDefreq 14569626Sru@end deffn 14669626Sru@end macro 14769626Sru 14875584Sru 14975584Sru@c definition of escapes 15075584Sru 15175584Sru@macro Defesc{name, delimI, arg, delimII} 152104862Sru@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 15375584Sru@esindex \name\ 154104862Sru@end macro 155104862Sru 156104862Sru@macro DefescList{name, delimI, arg, delimII} 15775584Sru@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 158104862Sru@defdummy 159104862Sru@esindex \name\ 16069626Sru@end macro 16169626Sru 162104862Sru@macro DefescItem{name, delimI, arg, delimII} 163104862Sru@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 164104862Sru@defdummy 16575584Sru@esindex \name\ 166104862Sru@end macro 167104862Sru 168104862Sru@macro DefescListEnd{name, delimI, arg, delimII} 16975584Sru@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 170104862Sru@esindex \name\ 17169626Sru@end macro 17269626Sru 17375584Sru@macro endDefesc 17475584Sru@end deffn 17575584Sru@end macro 17675584Sru 17775584Sru 17875584Sru@c definition of registers 17975584Sru 18075584Sru@macro Defreg{name} 181104862Sru@deffn Register @t{\\n[\name\]} 18275584Sru@vindex \name\ 183104862Sru@end macro 184104862Sru 185104862Sru@macro DefregList{name} 18675584Sru@deffn Register @t{\\n[\name\]} 187104862Sru@defdummy 188104862Sru@vindex \name\ 18975584Sru@end macro 19075584Sru 191104862Sru@macro DefregItem{name} 192104862Sru@deffnx Register @t{\\n[\name\]} 193104862Sru@defdummy 19475584Sru@vindex \name\ 195104862Sru@end macro 196104862Sru 197104862Sru@macro DefregListEnd{name} 19875584Sru@deffnx Register @t{\\n[\name\]} 199104862Sru@vindex \name\ 20075584Sru@end macro 20175584Sru 20275584Sru@macro endDefreg 20375584Sru@end deffn 20475584Sru@end macro 20575584Sru 20675584Sru 207104862Sru@c definition of registers specific to macro packages, preprocessors, etc. 208104862Sru 209104862Sru@macro Defmpreg{name, package} 210104862Sru@deffn Register @t{\\n[\name\]} 211104862Sru@vindex \name\ @r{[}\package\@r{]} 212104862Sru@end macro 213104862Sru 214104862Sru@macro DefmpregList{name, package} 215104862Sru@deffn Register @t{\\n[\name\]} 216104862Sru@defdummy 217104862Sru@vindex \name\ @r{[}\package\@r{]} 218104862Sru@end macro 219104862Sru 220104862Sru@macro DefmpregItem{name, package} 221104862Sru@deffnx Register @t{\\n[\name\]} 222104862Sru@defdummy 223104862Sru@vindex \name\ @r{[}\package\@r{]} 224104862Sru@end macro 225104862Sru 226104862Sru@macro DefmpregListEnd{name, package} 227104862Sru@deffnx Register @t{\\n[\name\]} 228104862Sru@vindex \name\ @r{[}\package\@r{]} 229104862Sru@end macro 230104862Sru 231104862Sru@macro endDefmpreg 232104862Sru@end deffn 233104862Sru@end macro 234104862Sru 235104862Sru 23675584Sru@c definition of macros 23775584Sru 238104862Sru@macro Defmac{name, arg, package} 23975584Sru@defmac @t{.\name\} \arg\ 240104862Sru@maindex \name\ @r{[}\package\@r{]} 24169626Sru@end macro 24269626Sru 243104862Sru@macro DefmacList{name, arg, package} 244104862Sru@defmac @t{.\name\} \arg\ 245104862Sru@defdummy 246104862Sru@maindex \name\ @r{[}\package\@r{]} 247104862Sru@end macro 248104862Sru 249104862Sru@macro DefmacItem{name, arg, package} 25075584Sru@defmacx @t{.\name\} \arg\ 251104862Sru@defdummy 252104862Sru@maindex \name\ @r{[}\package\@r{]} 25375584Sru@end macro 25475584Sru 255104862Sru@macro DefmacListEnd{name, arg, package} 256104862Sru@defmacx @t{.\name\} \arg\ 257104862Sru@maindex \name\ @r{[}\package\@r{]} 258104862Sru@end macro 259104862Sru 26075584Sru@macro endDefmac 26169626Sru@end defmac 26269626Sru@end macro 26369626Sru 26475584Sru 26575584Sru@c definition of strings 26675584Sru 267104862Sru@macro Defstr{name, package} 268104862Sru@deffn String @t{\\*[\name\]} 269104862Sru@stindex \name\ @r{[}\package\@r{]} 27069626Sru@end macro 27169626Sru 272104862Sru@macro DefstrList{name, package} 273104862Sru@deffn String @t{\\*[\name\]} 274104862Sru@defdummy 275104862Sru@stindex \name\ @r{[}\package\@r{]} 27669626Sru@end macro 27769626Sru 278104862Sru@macro DefstrItem{name, package} 279104862Sru@deffnx String @t{\\*[\name\]} 280104862Sru@defdummy 281104862Sru@stindex \name\ @r{[}\package\@r{]} 282104862Sru@end macro 283104862Sru 284104862Sru@macro DefstrListEnd{name, package} 285104862Sru@deffnx String @t{\\*[\name\]} 286104862Sru@stindex \name\ @r{[}\package\@r{]} 287104862Sru@end macro 288104862Sru 28975584Sru@macro endDefstr 29075584Sru@end deffn 29175584Sru@end macro 29269626Sru 29375584Sru 29475584Sru@c our example macro 29575584Sru 29675584Sru@macro Example 29775584Sru@example 29875584Sru@group 29975584Sru@end macro 30075584Sru 30175584Sru@macro endExample 30275584Sru@end group 30375584Sru@end example 30475584Sru@end macro 30575584Sru 30675584Sru 307104862Sru@c <text> 308104862Sru 309104862Sru@tex 310104862Sru\gdef\angles#1{\angleleft{}\r{#1}\angleright{}} 311104862Sru@end tex 312104862Sru 313104862Sru@macro angles{text} 314104862Sru<\text\> 315104862Sru@end macro 316104862Sru 317104862Sru 318104862Sru@c a <= sign 319104862Sru 320104862Sru@tex 321104862Sru\gdef\LE{\le} 322104862Sru@end tex 323104862Sru 324104862Sru@macro LE 325104862Sru<= 326104862Sru@end macro 327104862Sru 328104862Sru 329104862Sru@c due to a bug in texinfo 4.2, the spacing of `<' is bad in @item 330104862Sru 331104862Sru@tex 332104862Sru\gdef\LT{\string<} 333104862Sru@end tex 334104862Sru 335104862Sru@macro LT 336104862Sru< 337104862Sru@end macro 338104862Sru 339104862Sru 34075584Sru@c We need special parentheses and brackets: 34175584Sru@c 34275584Sru@c . Real parentheses in @deffn produce an error while compiling with 34375584Sru@c TeX 34475584Sru@c . Real brackets use the wrong font in @deffn, overriding @t{}. 34575584Sru@c 346104862Sru@c Since macros aren't expanded in @deffn during -E, the following 347104862Sru@c definitions are for non-TeX only. 348104862Sru@c 34975584Sru@c This is true for texinfo 4.0. 35075584Sru 35175584Sru@macro lparen 35275584Sru( 35375584Sru@end macro 35475584Sru@macro rparen 35575584Sru) 35675584Sru@end macro 35775584Sru@macro lbrack 35875584Sru[ 35975584Sru@end macro 36075584Sru@macro rbrack 36175584Sru] 36275584Sru@end macro 36375584Sru 36475584Sru 365104862Sru@tex 366104862Sru\gdef\gobblefirst#1#2{#2} 367104862Sru\gdef\putwordAppendix{\gobblefirst} 368104862Sru@end tex 36975584Sru 370104862Sru 37175584Sru@c Note: We say `Roman numerals' but `roman font'. 37275584Sru 37375584Sru 37455839Sasmodai@dircategory Miscellaneous 37555839Sasmodai@direntry 376104862Sru* Groff: (groff). The GNU troff document formatting system. 37755839Sasmodai@end direntry 37855839Sasmodai 37955839Sasmodai 38055839Sasmodai@titlepage 38155839Sasmodai@title groff 38269626Sru@subtitle The GNU implementation of @code{troff} 383104862Sru@subtitle Edition 1.18 384104862Sru@subtitle Spring 2002 38555839Sasmodai@author by Trent A.@w{ }Fisher 386104862Sru@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 38755839Sasmodai 38855839Sasmodai@page 38955839Sasmodai@vskip 0pt plus 1filll 390104862Sru@insertcopying 39155839Sasmodai@end titlepage 39255839Sasmodai 39355839Sasmodai 394104862Sru@contents 39555839Sasmodai 39655839Sasmodai@ifinfo 397104862Sru@node Top, Introduction, (dir), (dir) 398104862Sru@top GNU troff 39955839Sasmodai 400104862Sru@insertcopying 40155839Sasmodai@end ifinfo 40255839Sasmodai 403104862Sru@ifhtml 404104862Sru@node Top, Introduction, (dir), (dir) 405104862Sru@top GNU troff 406104862Sru 407104862Sru@insertcopying 408104862Sru@end ifhtml 409104862Sru 41055839Sasmodai@menu 41175584Sru* Introduction:: 41275584Sru* Invoking groff:: 41375584Sru* Tutorial for Macro Users:: 41475584Sru* Macro Packages:: 41575584Sru* gtroff Reference:: 41675584Sru* Preprocessors:: 41775584Sru* Output Devices:: 41875584Sru* File formats:: 41975584Sru* Installation:: 420104862Sru* Copying This Manual:: 42175584Sru* Request Index:: 42275584Sru* Escape Index:: 42375584Sru* Operator Index:: 42475584Sru* Register Index:: 42575584Sru* Macro Index:: 42675584Sru* String Index:: 42775584Sru* Glyph Name Index:: 42875584Sru* Font File Keyword Index:: 42975584Sru* Program and File Index:: 43075584Sru* Concept Index:: 43155839Sasmodai@end menu 43255839Sasmodai 43355839Sasmodai 43455839Sasmodai 43569626Sru@c ===================================================================== 43669626Sru@c ===================================================================== 43769626Sru 438104862Sru@node Introduction, Invoking groff, Top, Top 43955839Sasmodai@chapter Introduction 44055839Sasmodai@cindex introduction 44155839Sasmodai 44255839SasmodaiGNU @code{troff} (or @code{groff}) is a system for typesetting 44355839Sasmodaidocuments. @code{troff} is very flexible and has been in existence (and 44455839Sasmodaiuse) for about 3@w{ }decades. It is quite widespread and firmly 44569626Sruentrenched in the @acronym{UNIX} community. 44655839Sasmodai 44755839Sasmodai@menu 44875584Sru* What Is groff?:: 44975584Sru* History:: 45075584Sru* groff Capabilities:: 45175584Sru* Macro Package Intro:: 45275584Sru* Preprocessor Intro:: 45375584Sru* Output device intro:: 45475584Sru* Credits:: 45555839Sasmodai@end menu 45655839Sasmodai 45769626Sru 45869626Sru@c ===================================================================== 45969626Sru 46055839Sasmodai@node What Is groff?, History, Introduction, Introduction 46155839Sasmodai@section What Is @code{groff}? 46255839Sasmodai@cindex what is @code{groff}? 46355839Sasmodai@cindex @code{groff} -- what is it? 46455839Sasmodai 46569626Sru@code{groff} belongs to an older generation of document preparation 46669626Srusystems, which operate more like compilers than the more recent 46769626Sruinteractive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 46869626Srusystems. @code{groff} and its contemporary counterpart, @TeX{}, both 46969626Sruwork using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 47069626Srunormal text files with embedded formatting commands. These files can 47169626Sruthen be processed by @code{groff} to produce a typeset document on a 47269626Sruvariety of devices. 47355839Sasmodai 47455839SasmodaiLikewise, @code{groff} should not be confused with a @dfn{word 47575584Sruprocessor}, since that term connotes an integrated system that includes 47655839Sasmodaian editor and a text formatter. Also, many word processors follow the 47775584Sru@acronym{WYSIWYG} paradigm discussed earlier. 47855839Sasmodai 47969626SruAlthough @acronym{WYSIWYG} systems may be easier to use, they have a 48069626Srunumber of disadvantages compared to @code{troff}: 48155839Sasmodai 48269626Sru@itemize @bullet 48355839Sasmodai@item 48475584SruThey must be used on a graphics display to work on a document. 48569626Sru 48655839Sasmodai@item 48769626SruMost of the @acronym{WYSIWYG} systems are either non-free or are not 48869626Sruvery portable. 48969626Sru 49055839Sasmodai@item 49169626Sru@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 49269626Sru 49355839Sasmodai@item 49455839SasmodaiIt is difficult to have a wide range of capabilities available within 49555839Sasmodaithe confines of a GUI/window system. 49669626Sru 49755839Sasmodai@item 49855839SasmodaiIt is more difficult to make global changes to a document. 49955839Sasmodai@end itemize 50055839Sasmodai 50155839Sasmodai@quotation 50255839Sasmodai``GUIs normally make it simple to accomplish simple actions and 50355839Sasmodaiimpossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 50455839Sasmodai@code{comp.unix.wizards}) 50555839Sasmodai@end quotation 50655839Sasmodai 50755839Sasmodai 50869626Sru@c ===================================================================== 50955839Sasmodai 51055839Sasmodai@node History, groff Capabilities, What Is groff?, Introduction 51155839Sasmodai@section History 51255839Sasmodai@cindex history 51355839Sasmodai 514104862Sru@cindex @code{runoff}, the program 515104862Sru@cindex @code{rf}, the program 51655839Sasmodai@code{troff} can trace its origins back to a formatting program called 51769626Sru@code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS 51869626Sruoperating system in the mid-sixties. This name came from the common 51969626Sruphrase of the time ``I'll run off a document.'' Bob Morris ported it to 52069626Sruthe 635 architecture and called the program @code{roff} (an abbreviation 52175584Sruof @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 52275584Sru(before having @acronym{UNIX}), and at the same time (1969), Doug 52369626SruMcIllroy rewrote an extended and simplified version of @code{roff} in 52469626Sruthe @acronym{BCPL} programming language. 52555839Sasmodai 526104862Sru@cindex @code{roff}, the program 52775584SruThe first version of @acronym{UNIX} was developed on a @w{PDP-7} which 52875584Sruwas sitting around Bell Labs. In 1971 the developers wanted to get a 52975584Sru@w{PDP-11} for further work on the operating system. In order to 53075584Srujustify the cost for this system, they proposed that they would 531104862Sruimplement a document formatting system for the @acronym{AT&T} patents 532104862Srudivision. This first formatting program was a reimplementation of 533104862SruMcIllroy's @code{roff}, written by J.@w{ }F.@w{ }Ossanna. 53455839Sasmodai 535104862Sru@cindex @code{nroff}, the program 53655839SasmodaiWhen they needed a more flexible language, a new version of @code{roff} 53769626Srucalled @code{nroff} (``Newer @code{roff}'') was written. It had a much 53869626Srumore complicated syntax, but provided the basis for all future versions. 53969626SruWhen they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 54075584Sruversion of @code{nroff} that would drive it. It was dubbed 54169626Sru@code{troff}, for ``typesetter @code{roff}'', although many people have 54269626Sruspeculated that it actually means ``Times @code{roff}'' because of the 54369626Sruuse of the Times font family in @code{troff} by default. As such, the 54469626Sruname @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 54555839Sasmodai 54655839SasmodaiWith @code{troff} came @code{nroff} (they were actually the same program 54769626Sruexcept for some @samp{#ifdef}s), which was for producing output for line 54869626Sruprinters and character terminals. It understood everything @code{troff} 54969626Srudid, and ignored the commands which were not applicable (e.g.@: font 55055839Sasmodaichanges). 55155839Sasmodai 55255839SasmodaiSince there are several things which cannot be done easily in 55355839Sasmodai@code{troff}, work on several preprocessors began. These programs would 55455839Sasmodaitransform certain parts of a document into @code{troff}, which made a 55569626Sruvery natural use of pipes in @acronym{UNIX}. 55655839Sasmodai 55755839SasmodaiThe @code{eqn} preprocessor allowed mathematical formul@ae{} to be 55855839Sasmodaispecified in a much simpler and more intuitive manner. @code{tbl} is a 55955839Sasmodaipreprocessor for formatting tables. The @code{refer} preprocessor (and 56055839Sasmodaithe similar program, @code{bib}) processes citations in a document 56155839Sasmodaiaccording to a bibliographic database. 56255839Sasmodai 56375584SruUnfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 56455839Sasmodailanguage and produced output specifically for the CAT phototypesetter. 56555839SasmodaiHe rewrote it in C, although it was now 7000@w{ }lines of uncommented 56655839Sasmodaicode and still dependent on the CAT. As the CAT became less common, and 56755839Sasmodaiwas no longer supported by the manufacturer, the need to make it support 56869626Sruother devices became a priority. However, before this could be done, 569104862SruOssanna was killed in a car accident. 57055839Sasmodai 57155839Sasmodai@pindex ditroff 572104862Sru@cindex @code{ditroff}, the program 57355839SasmodaiSo, Brian Kernighan took on the task of rewriting @code{troff}. The 574104862Srunewly rewritten version produced device independent code which was 57555839Sasmodaivery easy for postprocessors to read and translate to the appropriate 57655839Sasmodaiprinter codes. Also, this new version of @code{troff} (called 57769626Sru@code{ditroff} for ``device independent @code{troff}'') had several 57869626Sruextensions, which included drawing functions. 57955839Sasmodai 58055839SasmodaiDue to the additional abilities of the new version of @code{troff}, 58155839Sasmodaiseveral new preprocessors appeared. The @code{pic} preprocessor 58255839Sasmodaiprovides a wide range of drawing functions. Likewise the @code{ideal} 58355839Sasmodaipreprocessor did the same, although via a much different paradigm. The 58455839Sasmodai@code{grap} preprocessor took specifications for graphs, but, unlike 58555839Sasmodaiother preprocessors, produced @code{pic} code. 58655839Sasmodai 58755839SasmodaiJames Clark began work on a GNU implementation of @code{ditroff} in 58855839Sasmodaiearly@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released 58969626SruJune@w{ }1990. @code{groff} included: 59055839Sasmodai 59169626Sru@itemize @bullet 59255839Sasmodai@item 59369626SruA replacement for @code{ditroff} with many extensions. 59469626Sru 59555839Sasmodai@item 59655839SasmodaiThe @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 59769626Sru 59855839Sasmodai@item 59975584SruPostprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 600104862SruX@w{ }Windows. GNU @code{troff} also eliminated the need for a 60169626Sruseparate @code{nroff} program with a postprocessor which would produce 60269626Sru@acronym{ASCII} output. 60369626Sru 60455839Sasmodai@item 60569626SruA version of the @file{me} macros and an implementation of the 60669626Sru@file{man} macros. 60755839Sasmodai@end itemize 60855839Sasmodai 60955839SasmodaiAlso, a front-end was included which could construct the, sometimes 61055839Sasmodaipainfully long, pipelines required for all the post- and preprocessors. 61155839Sasmodai 61255839SasmodaiDevelopment of GNU @code{troff} progressed rapidly, and saw the 61355839Sasmodaiadditions of a replacement for @code{refer}, an implementation of the 61469626Sru@file{ms} and @file{mm} macros, and a program to deduce how to format a 61569626Srudocument (@code{grog}). 61655839Sasmodai 61769626SruIt was declared a stable (i.e.@: non-beta) package with the release of 61855839Sasmodaiversion@w{ }1.04 around November@w{ }1991. 61955839Sasmodai 62069626SruBeginning in@w{ }1999, @code{groff} has new maintainers (the package was 62169626Sruan orphan for a few years). As a result, new features and programs like 62275584Sru@code{grn}, a preprocessor for gremlin images, and an output device to 62375584Sruproduce @acronym{HTML} output have been added. 62455839Sasmodai 62555839Sasmodai 62669626Sru@c ===================================================================== 62769626Sru 62869626Sru@node groff Capabilities, Macro Package Intro, History, Introduction 62955839Sasmodai@section @code{groff} Capabilities 63055839Sasmodai@cindex @code{groff} capabilities 63155839Sasmodai@cindex capabilities of @code{groff} 63255839Sasmodai 63355839SasmodaiSo what exactly is @code{groff} capable of doing? @code{groff} provides 63469626Srua wide range of low-level text formatting operations. Using these, it 63569626Sruis possible to perform a wide range of formatting tasks, such as 63669626Srufootnotes, table of contents, multiple columns, etc. Here's a list of 63769626Sruthe most important operations supported by @code{groff}: 63855839Sasmodai 63969626Sru@itemize @bullet 64055839Sasmodai@item 64169626Srutext filling, adjusting, and centering 64269626Sru 64355839Sasmodai@item 64469626Sruhyphenation 64569626Sru 64655839Sasmodai@item 64769626Srupage control 64869626Sru 64955839Sasmodai@item 650104862Srufont and glyph size control 65169626Sru 65255839Sasmodai@item 653104862Sruvertical spacing (e.g.@: double-spacing) 65469626Sru 65555839Sasmodai@item 65669626Sruline length and indenting 65769626Sru 65855839Sasmodai@item 65969626Srumacros, strings, diversions, and traps 66069626Sru 66155839Sasmodai@item 66269626Srunumber registers 66369626Sru 66455839Sasmodai@item 66569626Srutabs, leaders, and fields 66669626Sru 66755839Sasmodai@item 66869626Sruinput and output conventions and character translation 66969626Sru 67055839Sasmodai@item 67169626Sruoverstrike, bracket, line drawing, and zero-width functions 67269626Sru 67355839Sasmodai@item 67469626Srulocal horizontal and vertical motions and the width function 67569626Sru 67655839Sasmodai@item 67769626Sruthree-part titles 67869626Sru 67955839Sasmodai@item 68069626Sruoutput line numbering 68169626Sru 68255839Sasmodai@item 68369626Sruconditional acceptance of input 68469626Sru 68555839Sasmodai@item 68669626Sruenvironment switching 68769626Sru 68855839Sasmodai@item 68969626Sruinsertions from the standard input 69069626Sru 69155839Sasmodai@item 69269626Sruinput/output file switching 69369626Sru 69455839Sasmodai@item 69569626Sruoutput and error messages 69655839Sasmodai@end itemize 69755839Sasmodai 69855839Sasmodai 69969626Sru@c ===================================================================== 70069626Sru 70169626Sru@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 70255839Sasmodai@section Macro Packages 70355839Sasmodai@cindex macro packages 70455839Sasmodai 70569626SruSince @code{groff} provides such low-level facilities, it can be quite 70655839Sasmodaidifficult to use by itself. However, @code{groff} provides a 70769626Sru@dfn{macro} facility to specify how certain routine operations (e.g.@w{ 70869626Sru}starting paragraphs, printing headers and footers, etc.)@: should be 70969626Srudone. These macros can be collected together into a @dfn{macro 71069626Srupackage}. There are a number of macro packages available; the most 71169626Srucommon (and the ones described in this manual) are @file{man}, 71269626Sru@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 71355839Sasmodai 71455839Sasmodai 71569626Sru@c ===================================================================== 71669626Sru 71769626Sru@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 71855839Sasmodai@section Preprocessors 71955839Sasmodai@cindex preprocessors 72055839Sasmodai 72155839SasmodaiAlthough @code{groff} provides most functions needed to format a 72269626Srudocument, some operations would be unwieldy (e.g.@: to draw pictures). 723104862SruTherefore, programs called @dfn{preprocessors} were written which 724104862Sruunderstand their own language and produce the necessary @code{groff} 725104862Sruoperations. These preprocessors are able to differentiate their own 726104862Sruinput from the rest of the document via markers. 72755839Sasmodai 72869626SruTo use a preprocessor, @acronym{UNIX} pipes are used to feed the output 72969626Srufrom the preprocessor into @code{groff}. Any number of preprocessors 73069626Srumay be used on a given document; in this case, the preprocessors are 731104862Srulinked together into one pipeline. However, with @code{groff}, the user 73269626Srudoes not need to construct the pipe, but only tell @code{groff} what 73355839Sasmodaipreprocessors to use. 73455839Sasmodai 73555839Sasmodai@code{groff} currently has preprocessors for producing tables 73655839Sasmodai(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 73769626Sru(@code{pic} and @code{grn}), and for processing bibliographies 73869626Sru(@code{refer}). An associated program which is useful when dealing with 73969626Srupreprocessors is @code{soelim}. 74055839Sasmodai 74169626SruA free implementation of @code{grap}, a preprocessor for drawing graphs, 74269626Srucan be obtained as an extra package; @code{groff} can use @code{grap} 74369626Srualso. 74455839Sasmodai 74569626SruThere are other preprocessors in existence, but, unfortunately, no free 74669626Sruimplementations are available. Among them are preprocessors for drawing 74769626Srumathematical pictures (@code{ideal}) and chemical structures 74869626Sru(@code{chem}). 74955839Sasmodai 75069626Sru 75169626Sru@c ===================================================================== 75269626Sru 75369626Sru@node Output device intro, Credits, Preprocessor Intro, Introduction 75469626Sru@section Output Devices 75555839Sasmodai@cindex postprocessors 75669626Sru@cindex output devices 75769626Sru@cindex devices for output 75855839Sasmodai 75975584Sru@code{groff} actually produces device independent code which may be 76075584Srufed into a postprocessor to produce output for a particular device. 76175584SruCurrently, @code{groff} has postprocessors for @sc{PostScript} 76275584Srudevices, character terminals, X@w{ }Windows (for previewing), @TeX{} 76375584SruDVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use 76469626Sru@acronym{CAPSL}), and @acronym{HTML}. 76555839Sasmodai 76655839Sasmodai 76769626Sru@c ===================================================================== 76869626Sru 76969626Sru@node Credits, , Output device intro, Introduction 77055839Sasmodai@section Credits 77155839Sasmodai@cindex credits 77255839Sasmodai 77355839SasmodaiLarge portions of this manual were taken from existing documents, most 77455839Sasmodainotably, the manual pages for the @code{groff} package by James Clark, 77569626Sruand Eric Allman's papers on the @file{me} macro package. 77655839Sasmodai 77769626SruThe section on the @file{man} macro package is partly based on Susan@w{ 77869626Sru}G.@: Kleinmann's @file{groff_man} manual page written for the Debian 77969626SruGNU/Linux system. 78055839Sasmodai 781104862SruLarry Kollar contributed the section in the @file{ms} macro package. 78255839Sasmodai 78369626Sru 78475584Sru 78569626Sru@c ===================================================================== 78669626Sru@c ===================================================================== 78769626Sru 78855839Sasmodai@node Invoking groff, Tutorial for Macro Users, Introduction, Top 78955839Sasmodai@chapter Invoking @code{groff} 79055839Sasmodai@cindex invoking @code{groff} 79155839Sasmodai@cindex @code{groff} invocation 79255839Sasmodai 79355839SasmodaiThis section focuses on how to invoke the @code{groff} front end. This 79455839Sasmodaifront end takes care of the details of constructing the pipeline among 79555839Sasmodaithe preprocessors, @code{gtroff} and the postprocessor. 79655839Sasmodai 79769626SruIt has become a tradition that GNU programs get the prefix @samp{g} to 79869626Srudistinguish it from its original counterparts provided by the host (see 79969626Sru@ref{Environment}, for more details). Thus, for example, @code{geqn} is 800104862SruGNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 801104862Srudon't contain proprietary versions of @code{troff}, and on 802104862SruMS-DOS/MS-Windows, where @code{troff} and associated programs are not 803104862Sruavailable at all, this prefix is omitted since GNU @code{troff} is the 804104862Sruonly used incarnation of @code{troff}. Exception: @samp{groff} is never 805104862Srureplaced by @samp{roff}. 80655839Sasmodai 807104862SruIn this document, we consequently say @samp{gtroff} when talking about 808104862Sruthe GNU @code{troff} program. All other implementations of @code{troff} 809104862Sruare called @acronym{AT&T} @code{troff} which is the common origin of 810104862Sruall @code{troff} derivates (with more or less compatible changes). 811104862SruSimilarly, we say @samp{gpic}, @samp{geqn}, etc. 812104862Sru 81355839Sasmodai@menu 81475584Sru* Groff Options:: 81575584Sru* Environment:: 816104862Sru* Macro Directories:: 817104862Sru* Font Directories:: 81875584Sru* Invocation Examples:: 81955839Sasmodai@end menu 82055839Sasmodai 82169626Sru 82269626Sru@c ===================================================================== 82369626Sru 82469626Sru@node Groff Options, Environment, Invoking groff, Invoking groff 82555839Sasmodai@section Options 82655839Sasmodai@cindex options 82755839Sasmodai 82855839Sasmodai@pindex groff 82955839Sasmodai@pindex gtroff 83055839Sasmodai@pindex gpic 83155839Sasmodai@pindex geqn 83269626Sru@pindex ggrn 83369626Sru@pindex grap 83455839Sasmodai@pindex gtbl 83555839Sasmodai@pindex grefer 83655839Sasmodai@pindex gsoelim 83769626Sru@code{groff} normally runs the @code{gtroff} program and a postprocessor 83869626Sruappropriate for the selected device. The default device is @samp{ps} 83969626Sru(but it can be changed when @code{groff} is configured and built). It 84069626Srucan optionally preprocess with any of @code{gpic}, @code{geqn}, 84169626Sru@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 84255839Sasmodai 84355839SasmodaiThis section only documents options to the @code{groff} front end. Many 84455839Sasmodaiof the arguments to @code{groff} are passed on to @code{gtroff}, 84555839Sasmodaitherefore those are also included. Arguments to pre- or postprocessors 84655839Sasmodaican be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 84769626Srugtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 84869626Srugsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 84969626Srugrohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 85069626Srugrolbp}, and @ref{Invoking gxditview}. 85155839Sasmodai 85255839SasmodaiThe command line format for @code{groff} is: 85355839Sasmodai 85475584Sru@Example 855104862Srugroff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 85655839Sasmodai [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 85755839Sasmodai [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 85869626Sru [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 85955839Sasmodai [ @var{files}@dots{} ] 86075584Sru@endExample 86155839Sasmodai 86269626SruThe command line format for @code{gtroff} is as follows. 86355839Sasmodai 86475584Sru@Example 865104862Srugtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 86655839Sasmodai [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 86755839Sasmodai [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 86855839Sasmodai [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 86975584Sru@endExample 87055839Sasmodai 87169626Sru@noindent 87275584SruObviously, many of the options to @code{groff} are actually passed on to 87375584Sru@code{gtroff}. 87455839Sasmodai 875104862SruOptions without an argument can be grouped behind a single@w{ }@option{-}. 876104862SruA filename of@w{ }@file{-} denotes the standard input. It is possible to 87769626Sruhave whitespace between an option and its parameter. 87869626Sru 87955839SasmodaiThe @code{grog} command can be used to guess the correct @code{groff} 88069626Srucommand to format a file. 88155839Sasmodai 88269626SruHere's the description of the command-line options: 88369626Sru 88469626Sru@cindex command-line options 88555839Sasmodai@table @samp 88655839Sasmodai@item -h 88755839SasmodaiPrint a help message. 88869626Sru 88955839Sasmodai@item -e 89055839SasmodaiPreprocess with @code{geqn}. 89169626Sru 89255839Sasmodai@item -t 89355839SasmodaiPreprocess with @code{gtbl}. 89469626Sru 89569626Sru@item -g 89669626SruPreprocess with @code{ggrn}. 89769626Sru 89869626Sru@item -G 89969626SruPreprocess with @code{grap}. 90069626Sru 90155839Sasmodai@item -p 90255839SasmodaiPreprocess with @code{gpic}. 90369626Sru 90455839Sasmodai@item -s 90555839SasmodaiPreprocess with @code{gsoelim}. 90669626Sru 907104862Sru@item -c 908104862SruSuppress color output. 909104862Sru 91055839Sasmodai@item -R 91155839SasmodaiPreprocess with @code{grefer}. No mechanism is provided for passing 91255839Sasmodaiarguments to @code{grefer} because most @code{grefer} options have 91355839Sasmodaiequivalent commands which can be included in the file. @xref{grefer}, 91455839Sasmodaifor more details. 91555839Sasmodai 91655839Sasmodai@pindex troffrc 91769626Sru@pindex troffrc-end 91869626SruNote that @code{gtroff} also accepts a @option{-R} option, which is not 91955839Sasmodaiaccessible via @code{groff}. This option prevents the loading of the 92069626Sru@file{troffrc} and @file{troffrc-end} files. 92169626Sru 92255839Sasmodai@item -v 92355839SasmodaiMake programs run by @code{groff} print out their version number. 92469626Sru 92555839Sasmodai@item -V 92675584SruPrint the pipeline on @code{stdout} instead of executing it. 92769626Sru 92855839Sasmodai@item -z 92975584SruSuppress output from @code{gtroff}. Only error messages are printed. 93069626Sru 93155839Sasmodai@item -Z 93255839SasmodaiDo not postprocess the output of @code{gtroff}. Normally @code{groff} 93375584Sruautomatically runs the appropriate postprocessor. 93469626Sru 93555839Sasmodai@item -P@var{arg} 93655839SasmodaiPass @var{arg} to the postprocessor. Each argument should be passed 93769626Sruwith a separate @option{-P} option. Note that @code{groff} does not 93869626Sruprepend @samp{-} to @var{arg} before passing it to the postprocessor. 93969626Sru 94055839Sasmodai@item -l 94175584SruSend the output to a spooler for printing. The command used for this is 94275584Sruspecified by the @code{print} command in the device description file 94375584Sru(see @ref{Font Files}, for more info). If not present, @option{-l} is 94475584Sruignored. 94569626Sru 94655839Sasmodai@item -L@var{arg} 94755839SasmodaiPass @var{arg} to the spooler. Each argument should be passed with a 948104862Sruseparate @option{-L} option. Note that @code{groff} does not prepend 949104862Srua @samp{-} to @var{arg} before passing it to the postprocessor. 950104862SruIf the @code{print} keyword in the device description file is missing, 95175584Sru@option{-L} is ignored. 95269626Sru 95355839Sasmodai@item -T@var{dev} 95469626SruPrepare output for device @var{dev}. The default device is @samp{ps}, 95569626Sruunless changed when @code{groff} was configured and built. The 95669626Srufollowing are the output devices currently available: 95769626Sru 95869626Sru@table @code 95955839Sasmodai@item ps 96075584SruFor @sc{PostScript} printers and previewers. 96169626Sru 96255839Sasmodai@item dvi 96369626SruFor @TeX{} DVI format. 96469626Sru 96555839Sasmodai@item X75 96669626SruFor a 75@dmn{dpi} X11 previewer. 96769626Sru 968104862Sru@item X75-12 969104862SruFor a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 970104862Srudocument. 971104862Sru 97255839Sasmodai@item X100 97369626SruFor a 100@dmn{dpi} X11 previewer. 97469626Sru 975104862Sru@item X100-12 976104862SruFor a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 977104862Srudocument. 978104862Sru 97955839Sasmodai@item ascii 980104862Sru@cindex encoding, @acronym{ASCII} 981104862Sru@cindex @acronym{ASCII}, encoding 982104862SruFor typewriter-like devices using the (7-bit) @acronym{ASCII} 983104862Srucharacter set. 98469626Sru 98555839Sasmodai@item latin1 986104862Sru@cindex encoding, latin-1 987104862Sru@cindex latin-1, encoding 98875584SruFor typewriter-like devices that support the @w{Latin-1} (@w{ISO 98975584Sru8859-1}) character set. 99069626Sru 99169626Sru@item utf8 992104862Sru@cindex encoding, utf-8 993104862Sru@cindex utf-8, encoding 99469626SruFor typewriter-like devices which use the Unicode (@w{ISO 10646}) 99569626Srucharacter set with @w{UTF-8} encoding. 99669626Sru 99769626Sru@item cp1047 99869626Sru@cindex @acronym{EBCDIC} encoding 999104862Sru@cindex encoding, @acronym{EBCDIC} 1000104862Sru@cindex encoding, cp1047 100169626Sru@cindex cp1047 100269626Sru@cindex IBM cp1047 100369626SruFor typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 100469626Srucp1047. 100569626Sru 100655839Sasmodai@item lj4 1007104862SruFor HP LaserJet4-compatible (or other PCL5-compatible) printers. 100869626Sru 100969626Sru@item lbp 101069626SruFor Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 101169626Sruprinters). 101269626Sru 101375584Sru@pindex pre-grohtml 101475584Sru@pindex post-grohtml 1015104862Sru@cindex @code{grohtml}, the program 101655839Sasmodai@item html 101775584SruTo produce @acronym{HTML} output. Note that the @acronym{HTML} driver 101875584Sruconsists of two parts, a preprocessor (@code{pre-grohtml}) and a 101975584Srupostprocessor (@code{post-grohtml}). 102055839Sasmodai@end table 102155839Sasmodai 1022104862Sru@cindex output device name string register (@code{.T}) 1023104862Sru@cindex output device usage number register (@code{.T}) 102469626SruThe predefined @code{gtroff} string register @code{.T} contains the 102569626Srucurrent output device; the read-only number register @code{.T} is set 102669626Sruto@w{ }1 if this option is used (which is always true if @code{groff} is 102769626Sruused to call @code{gtroff}). @xref{Built-in Registers}. 102869626Sru 102955839SasmodaiThe postprocessor to be used for a device is specified by the 103055839Sasmodai@code{postpro} command in the device description file. (@xref{Font 103169626SruFiles}, for more info.) This can be overridden with the @option{-X} 103255839Sasmodaioption. 103369626Sru 103455839Sasmodai@item -X 103555839SasmodaiPreview with @code{gxditview} instead of using the usual postprocessor. 103669626SruThis is unlikely to produce good results except with @option{-Tps}. 103769626Sru 103869626SruNote that this is not the same as using @option{-TX75} or 103969626Sru@option{-TX100} to view a document with @code{gxditview}: The former 104075584Sruuses the metrics of the specified device, whereas the latter uses 104175584SruX-specific fonts and metrics. 104269626Sru 104355839Sasmodai@item -N 104455839SasmodaiDon't allow newlines with @code{eqn} delimiters. This is the same as 104569626Sruthe @option{-N} option in @code{geqn}. 104669626Sru 104755839Sasmodai@item -S 1048104862Sru@cindex @code{open} request, and safer mode 1049104862Sru@cindex @code{opena} request, and safer mode 1050104862Sru@cindex @code{pso} request, and safer mode 1051104862Sru@cindex @code{sy} request, and safer mode 1052104862Sru@cindex @code{pi} request, and safer mode 1053104862Sru@cindex safer mode 1054104862Sru@cindex mode, safer 105575584SruSafer mode. Pass the @option{-S} option to @code{gpic} and disable the 105675584Sru@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 105775584Srurequests. For security reasons, this is enabled by default. 105869626Sru 105969626Sru@item -U 1060104862Sru@cindex mode, unsafe 1061104862Sru@cindex unsafe mode 1062104862SruUnsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1063104862Sru@code{sy}, and @code{pi} requests. 106469626Sru 106555839Sasmodai@item -a 1066104862Sru@cindex @acronym{ASCII} approximation output register (@code{.A}) 106769626SruGenerate an @acronym{ASCII} approximation of the typeset output. The 106869626Sruread-only register @code{.A} is then set to@w{ }1. @xref{Built-in 106975584SruRegisters}. A typical example is 107069626Sru 107175584Sru@Example 107275584Srugroff -a -man -Tdvi troff.man | less 107375584Sru@endExample 107475584Sru 107575584Sru@noindent 107675584Sruwhich shows how lines are broken for the DVI device. Note that this 107775584Sruoption is rather useless today since graphic output devices are 107875584Sruavailable virtually everywhere. 107975584Sru 108055839Sasmodai@item -b 108155839SasmodaiPrint a backtrace with each warning or error message. This backtrace 108255839Sasmodaishould help track down the cause of the error. The line numbers given 108369626Sruin the backtrace may not always be correct: @code{gtroff} can get 108469626Sruconfused by @code{as} or @code{am} requests while counting line numbers. 108569626Sru 108655839Sasmodai@item -i 108755839SasmodaiRead the standard input after all the named input files have been 108855839Sasmodaiprocessed. 108969626Sru 109055839Sasmodai@item -w@var{name} 109155839SasmodaiEnable warning @var{name}. Available warnings are described in 109269626Sru@ref{Debugging}. Multiple @option{-w} options are allowed. 109369626Sru 109455839Sasmodai@item -W@var{name} 109569626SruInhibit warning @var{name}. Multiple @option{-W} options are allowed. 109669626Sru 109755839Sasmodai@item -E 109855839SasmodaiInhibit all error messages. 109969626Sru 110055839Sasmodai@item -C 110169626SruEnable compatibility mode. @xref{Implementation Differences}, for the 1102104862Srulist of incompatibilities between @code{groff} and @acronym{AT&T} 110369626Sru@code{troff}. 110469626Sru 1105104862Sru@item -d@var{c}@var{s} 1106104862Sru@itemx -d@var{name}=@var{s} 1107104862SruDefine @var{c} or @var{name} to be a string@w{ }@var{s}. @var{c}@w{ }must 1108104862Srube a one-letter name; @var{name} can be of arbitrary length. All string 110975584Sruassignments happen before loading any macro file (including the start-up 111075584Srufile). 111169626Sru 111255839Sasmodai@item -f@var{fam} 111375584SruUse @var{fam} as the default font family. @xref{Font Families}. 111469626Sru 111555839Sasmodai@item -m@var{name} 111675584SruRead in the file @file{@var{name}.tmac}. Normally @code{groff} searches 111775584Srufor this in its macro directories. If it isn't found, it tries 1118104862Sru@file{tmac.@var{name}} (searching in the same directories). 111969626Sru 112055839Sasmodai@item -n@var{num} 112155839SasmodaiNumber the first page @var{num}. 112269626Sru 112355839Sasmodai@item -o@var{list} 1124104862Sru@cindex print current page register (@code{.P}) 112555839SasmodaiOutput only pages in @var{list}, which is a comma-separated list of page 1126104862Sruranges; @samp{@var{n}} means print page@w{ }@var{n}, @samp{@var{m}-@var{n}} 1127104862Srumeans print every page between @var{m} and@w{ }@var{n}, @samp{-@var{n}} 1128104862Srumeans print every page up to@w{ }@var{n}, @samp{@var{n}-} means print every 1129104862Srupage beginning with@w{ }@var{n}. @code{gtroff} exits after printing the 113069626Srulast page in the list. All the ranges are inclusive on both ends. 113169626Sru 113269626SruWithin @code{gtroff}, this information can be extracted with the 113369626Sru@samp{.P} register. @xref{Built-in Registers}. 113469626Sru 113575584SruIf your document restarts page numbering at the beginning of each 113675584Sruchapter, then @code{gtroff} prints the specified page range for each 113775584Sruchapter. 113875584Sru 1139104862Sru@item -r@var{c}@var{n} 114055839Sasmodai@itemx -r@var{name}=@var{n} 1141104862SruSet number register@w{ }@var{c} or @var{name} to the value@w{ }@var{n}. 1142104862Sru@var{c}@w{ }must be a one-letter name; @var{name} can be of arbitrary 1143104862Srulength. @var{n}@w{ }can be any @code{gtroff} numeric expression. All 1144104862Sruregister assignments happen before loading any macro file (including 1145104862Sruthe start-up file). 114669626Sru 114755839Sasmodai@item -F@var{dir} 114869626SruSearch @file{@var{dir}} for subdirectories @file{dev@var{name}} 114969626Sru(@var{name} is the name of the device), for the @file{DESC} file, and 1150104862Srufor font files before looking in the standard directories (@pxref{Font 1151104862SruDirectories}). This option is passed to all pre- and postprocessors 1152104862Sruusing the @env{GROFF_FONT_PATH} environment variable. 115369626Sru 115455839Sasmodai@item -M@var{dir} 115569626SruSearch directory @file{@var{dir}} for macro files before the standard 1156104862Srudirectories (@pxref{Macro Directories}). 115769626Sru 115869626Sru@item -I@var{dir} 115969626SruThis option is as described in @ref{gsoelim}. It implies the 116069626Sru@option{-s} option. 116155839Sasmodai@end table 116255839Sasmodai 116355839Sasmodai 116469626Sru@c ===================================================================== 116555839Sasmodai 1166104862Sru@node Environment, Macro Directories, Groff Options, Invoking groff 116755839Sasmodai@section Environment 116869626Sru@cindex environment variables 116969626Sru@cindex variables in environment 117055839Sasmodai 117169626SruThere are also several environment variables (of the operating system, 117269626Srunot within @code{gtroff}) which can modify the behavior of @code{groff}. 117355839Sasmodai 117455839Sasmodai@table @code 117555839Sasmodai@item GROFF_COMMAND_PREFIX 1176104862Sru@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1177104862Sru@cindex command prefix 1178104862Sru@cindex prefix, for commands 1179104862SruIf this is set to@w{ }@var{X}, then @code{groff} runs @code{@var{X}troff} 118075584Sruinstead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 118175584Sru@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 118275584Sruapply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 118375584Sru@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 118469626Sru 1185104862SruThe default command prefix is determined during the installation process. 1186104862SruIf a non-GNU troff system is found, prefix @samp{g} is used, none 1187104862Sruotherwise. 118875584Sru 118955839Sasmodai@item GROFF_TMAC_PATH 1190104862Sru@tindex GROFF_TMAC_PATH@r{, environment variable} 119175584SruA colon-separated list of directories in which to search for macro files 1192104862Sru(before the default directories are tried). @xref{Macro Directories}. 119369626Sru 119455839Sasmodai@item GROFF_TYPESETTER 1195104862Sru@tindex GROFF_TYPESETTER@r{, environment variable} 119669626SruThe default output device. 119769626Sru 119855839Sasmodai@item GROFF_FONT_PATH 1199104862Sru@tindex GROFF_FONT_PATH@r{, environment variable} 120069626SruA colon-separated list of directories in which to search for the 120175584Sru@code{dev}@var{name} directory (before the default directories are 1202104862Srutried). @xref{Font Directories}. 120369626Sru 120475584Sru@item GROFF_BIN_PATH 1205104862Sru@tindex GROFF_BIN_PATH@r{, environment variable} 120675584SruThis search path, followed by @code{PATH}, is used for commands executed 120775584Sruby @code{groff}. 120869626Sru 120955839Sasmodai@item GROFF_TMPDIR 1210104862Sru@tindex GROFF_TMPDIR@r{, environment variable} 1211104862Sru@tindex TMPDIR@r{, environment variable} 121275584SruThe directory in which @code{groff} creates temporary files. If this is 121375584Srunot set and @env{TMPDIR} is set, temporary files are created in that 121475584Srudirectory. Otherwise temporary files are created in a system-dependent 121575584Srudefault directory (on Unix and GNU/Linux systems, this is usually 121675584Sru@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 121775584Sru@code{post-grohtml} can create temporary files in this directory. 121855839Sasmodai@end table 121955839Sasmodai 122069626SruNote that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 122169626Srurather than colons, to separate the directories in the lists described 122269626Sruabove. 122355839Sasmodai 122469626Sru 122569626Sru@c ===================================================================== 122669626Sru 1227104862Sru@node Macro Directories, Font Directories, Environment, Invoking groff 1228104862Sru@section Macro Directories 1229104862Sru@cindex macro directories 1230104862Sru@cindex directories for macros 1231104862Sru@cindex searching macros 1232104862Sru@cindex macros, searching 1233104862Sru 1234104862SruAll macro file names must be named @code{@var{name}.tmac} or 1235104862Sru@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1236104862Sruoption work. The @code{mso} request doesn't have this restriction; any 1237104862Srufile name can be used, and @code{gtroff} won't try to append or prepend 1238104862Sruthe @samp{tmac} string. 1239104862Sru 1240104862Sru@cindex tmac, directory 1241104862Sru@cindex directory, for tmac files 1242104862Sru@cindex tmac, path 1243104862Sru@cindex path, for tmac files 1244104862Sru@cindex searching macro files 1245104862Sru@cindex macro files, searching 1246104862Sru@cindex files, macro, searching 1247104862SruMacro files are kept in the @dfn{tmac directories}, all of which 1248104862Sruconstitute the @dfn{tmac path}. The elements of the search path for 1249104862Srumacro files are (in that order): 1250104862Sru 1251104862Sru@itemize @bullet 1252104862Sru@item 1253104862SruThe directories specified with @code{gtroff}'s or @code{groff}'s 1254104862Sru@option{-M} command line option. 1255104862Sru 1256104862Sru@item 1257104862Sru@tindex GROFF_TMAC_PATH@r{, environment variable} 1258104862SruThe directories given in the @env{GROFF_TMAC_PATH} environment 1259104862Sruvariable. 1260104862Sru 1261104862Sru@item 1262104862Sru@cindex safer mode 1263104862Sru@cindex mode, safer 1264104862Sru@cindex unsafe mode 1265104862Sru@cindex mode, unsafe 1266104862Sru@cindex current directory 1267104862Sru@cindex directory, current 1268104862SruThe current directory (only if in unsafe mode using the @option{-U} 1269104862Srucommand line switch). 1270104862Sru 1271104862Sru@item 1272104862Sru@cindex home directory 1273104862Sru@cindex directory, home 1274104862SruThe home directory. 1275104862Sru 1276104862Sru@item 1277104862Sru@cindex site-specific directory 1278104862Sru@cindex directory, site-specific 1279104862Sru@cindex platform-specific directory 1280104862Sru@cindex directory, platform-specific 1281104862SruA platform-dependent directory, a site-specific (platform-independent) 1282104862Srudirectory, and the main tmac directory; the default locations are 1283104862Sru 1284104862Sru@Example 1285104862Sru/usr/local/lib/groff/site-tmac 1286104862Sru/usr/local/share/groff/site-tmac 1287104862Sru/usr/local/share/groff/1.18/tmac 1288104862Sru@endExample 1289104862Sru 1290104862Sru@noindent 1291104862Sruassuming that the version of @code{groff} is 1.18, and the installation 1292104862Sruprefix was @file{/usr/local}. It is possible to fine-tune those 1293104862Srudirectories during the installation process. 1294104862Sru@end itemize 1295104862Sru 1296104862Sru 1297104862Sru@c ===================================================================== 1298104862Sru 1299104862Sru@node Font Directories, Invocation Examples, Macro Directories, Invoking groff 1300104862Sru@section Font Directories 1301104862Sru@cindex font directories 1302104862Sru@cindex directories for fonts 1303104862Sru@cindex searching fonts 1304104862Sru@cindex fonts, searching 1305104862Sru 1306104862SruBasically, there is no restriction how font files for @code{groff} are 1307104862Srunamed and how long font names are; however, to make the font family 1308104862Srumechanism work (@pxref{Font Families}), fonts within a family should 1309104862Srustart with the family name, followed by the shape. For example, the 1310104862SruTimes family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1311104862Sru@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1312104862Sru`italic', and `bold italic', respectively. Thus the final font names 1313104862Sruare @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1314104862Sru 1315104862Sru@cindex font path 1316104862Sru@cindex path, for font files 1317104862SruAll font files are kept in the @dfn{font directories} which constitute 1318104862Sruthe @dfn{font path}. The file search functions will always append the 1319104862Srudirectory @code{dev}@var{name}, where @var{name} is the name of the 1320104862Sruoutput device. Assuming, say, DVI output, and @file{/foo/bar} as a 1321104862Srufont directory, the font files for @code{grodvi} must be in 1322104862Sru@file{/foo/bar/devdvi}. 1323104862Sru 1324104862SruThe elements of the search path for font files are (in that order): 1325104862Sru 1326104862Sru@itemize @bullet 1327104862Sru@item 1328104862SruThe directories specified with @code{gtroff}'s or @code{groff}'s 1329104862Sru@option{-F} command line option. All device drivers and some 1330104862Srupreprocessors also have this option. 1331104862Sru 1332104862Sru@item 1333104862Sru@tindex GROFF_FONT_PATH@r{, environment variable} 1334104862SruThe directories given in the @env{GROFF_FONT_PATH} environment 1335104862Sruvariable. 1336104862Sru 1337104862Sru@item 1338104862Sru@cindex site-specific directory 1339104862Sru@cindex directory, site-specific 1340104862SruA site-specific directory and the main font directory; the default 1341104862Srulocations are 1342104862Sru 1343104862Sru@Example 1344104862Sru/usr/local/share/groff/site-font 1345104862Sru/usr/local/share/groff/1.18/font 1346104862Sru@endExample 1347104862Sru 1348104862Sru@noindent 1349104862Sruassuming that the version of @code{groff} is 1.18, and the installation 1350104862Sruprefix was @file{/usr/local}. It is possible to fine-tune those 1351104862Srudirectories during the installation process. 1352104862Sru@end itemize 1353104862Sru 1354104862Sru 1355104862Sru@c ===================================================================== 1356104862Sru 1357104862Sru@node Invocation Examples, , Font Directories, Invoking groff 135855839Sasmodai@section Invocation Examples 135955839Sasmodai@cindex invocation examples 136055839Sasmodai@cindex examples of invocation 136155839Sasmodai 136275584SruThis section lists several common uses of @code{groff} and the 136375584Srucorresponding command lines. 136455839Sasmodai 136575584Sru@Example 136655839Sasmodaigroff file 136775584Sru@endExample 136855839Sasmodai 136969626Sru@noindent 137069626SruThis command processes @file{file} without a macro package or a 137169626Srupreprocessor. The output device is the default, @samp{ps}, and the 137275584Sruoutput is sent to @code{stdout}. 137369626Sru 137475584Sru@Example 137569626Srugroff -t -mandoc -Tascii file | less 137675584Sru@endExample 137769626Sru 137869626Sru@noindent 137975584SruThis is basically what a call to the @code{man} program does. 138075584Sru@code{gtroff} processes the manual page @file{file} with the 138175584Sru@file{mandoc} macro file (which in turn either calls the @file{man} or 138275584Sruthe @file{mdoc} macro package), using the @code{tbl} preprocessor and 138375584Sruthe @acronym{ASCII} output device. Finally, the @code{less} pager 138475584Srudisplays the result. 138569626Sru 138675584Sru@Example 138769626Srugroff -X -m me file 138875584Sru@endExample 138969626Sru 139069626Sru@noindent 139169626SruPreview @file{file} with @code{gxditview}, using the @file{me} macro 139269626Srupackage. Since no @option{-T} option is specified, use the default 139369626Srudevice (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 139469626Sru@w{@samp{-me}}; the latter is an anachronism from the early days of 139569626Sru@acronym{UNIX}.@footnote{The same is true for the other main macro 139669626Srupackages that come with @code{groff}: @file{man}, @file{mdoc}, 139769626Sru@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 139875584Srufor example, to load @file{trace.tmac}, either @samp{-mtrace} or 139975584Sru@w{@samp{-m trace}} must be used.} 140069626Sru 140175584Sru@Example 140269626Srugroff -man -rD1 -z file 140375584Sru@endExample 140469626Sru 140569626Sru@noindent 140669626SruCheck @file{file} with the @file{man} macro package, forcing 140769626Srudouble-sided printing -- don't produce any output. 140869626Sru 140969626Sru@menu 141075584Sru* grog:: 141169626Sru@end menu 141269626Sru 141375584Sru@c --------------------------------------------------------------------- 141475584Sru 141569626Sru@node grog, , Invocation Examples, Invocation Examples 141655839Sasmodai@subsection @code{grog} 141755839Sasmodai 141869626Sru@pindex grog 141969626Sru@code{grog} reads files, guesses which of the @code{groff} preprocessors 142069626Sruand/or macro packages are required for formatting them, and prints the 142175584Sru@code{groff} command including those options on the standard output. It 142275584Srugenerates one or more of the options @option{-e}, @option{-man}, 1423104862Sru@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 142475584Sru@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 142575584Sru@option{-s}, and @option{-t}. 142655839Sasmodai 1427104862SruA special file name@w{ }@file{-} refers to the standard input. Specifying 142875584Sruno files also means to read the standard input. Any specified options 142975584Sruare included in the printed command. No space is allowed between 143075584Sruoptions and their arguments. The only options recognized are 143175584Sru@option{-C} (which is also passed on) to enable compatibility mode, and 1432104862Sru@option{-v} to print the version number and exit. 143355839Sasmodai 143475584SruFor example, 143575584Sru 143675584Sru@Example 143755839Sasmodaigrog -Tdvi paper.ms 143875584Sru@endExample 143955839Sasmodai 144069626Sru@noindent 144175584Sruguesses the appropriate command to print @file{paper.ms} and then prints 144275584Sruit to the command line after adding the @option{-Tdvi} option. For 144375584Srudirect execution, enclose the call to @code{grog} in backquotes at the 144475584Sru@acronym{UNIX} shell prompt: 144555839Sasmodai 144675584Sru@Example 144769626Sru`grog -Tdvi paper.ms` > paper.dvi 144875584Sru@endExample 144955839Sasmodai 145069626Sru@noindent 145169626SruAs seen in the example, it is still necessary to redirect the output to 145269626Srusomething meaningful (i.e.@: either a file or a pager program like 145369626Sru@code{less}). 145469626Sru 145569626Sru 145669626Sru 145769626Sru@c ===================================================================== 145869626Sru@c ===================================================================== 145969626Sru 146069626Sru@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 146155839Sasmodai@chapter Tutorial for Macro Users 146255839Sasmodai@cindex tutorial for macro users 146369626Sru@cindex macros, tutorial for users 146455839Sasmodai@cindex user's tutorial for macros 146555839Sasmodai@cindex user's macro tutorial 146655839Sasmodai 146755839SasmodaiMost users tend to use a macro package to format their papers. This 146869626Srumeans that the whole breadth of @code{groff} is not necessary for most 146955839Sasmodaipeople. This chapter covers the material needed to efficiently use a 147055839Sasmodaimacro package. 147155839Sasmodai 147255839Sasmodai@menu 147375584Sru* Basics:: 147475584Sru* Common Features:: 147555839Sasmodai@end menu 147655839Sasmodai 147769626Sru 147869626Sru@c ===================================================================== 147969626Sru 148055839Sasmodai@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 148155839Sasmodai@section Basics 148269626Sru@cindex basics of macros 148369626Sru@cindex macro basics 148455839Sasmodai 148569626SruThis section covers some of the basic concepts necessary to understand 148669626Sruhow to use a macro package.@footnote{This section is derived from 148769626Sru@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.} 148855839SasmodaiReferences are made throughout to more detailed information, if desired. 148955839Sasmodai 149069626Sru@code{gtroff} reads an input file prepared by the user and outputs a 149169626Sruformatted document suitable for publication or framing. The input 149269626Sruconsists of text, or words to be printed, and embedded commands 149369626Sru(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 149469626Sruformat the output. For more detail on this, see @ref{Embedded 149569626SruCommands}. 149655839Sasmodai 149769626SruThe word @dfn{argument} is used in this chapter to mean a word or number 149869626Sruwhich appears on the same line as a request, and which modifies the 149969626Srumeaning of that request. For example, the request 150055839Sasmodai 150175584Sru@Example 150255839Sasmodai.sp 150375584Sru@endExample 150455839Sasmodai 150555839Sasmodai@noindent 150655839Sasmodaispaces one line, but 150755839Sasmodai 150875584Sru@Example 150955839Sasmodai.sp 4 151075584Sru@endExample 151155839Sasmodai 151255839Sasmodai@noindent 151355839Sasmodaispaces four lines. The number@w{ }4 is an argument to the @code{sp} 151455839Sasmodairequest which says to space four lines instead of one. Arguments are 151575584Sruseparated from the request and from each other by spaces (@emph{no} 151675584Srutabs). More details on this can be found in @ref{Request Arguments}. 151755839Sasmodai 151869626SruThe primary function of @code{gtroff} is to collect words from input 151969626Srulines, fill output lines with those words, justify the right-hand margin 152055839Sasmodaiby inserting extra spaces in the line, and output the result. For 152155839Sasmodaiexample, the input: 152255839Sasmodai 152375584Sru@Example 152455839SasmodaiNow is the time 152555839Sasmodaifor all good men 152655839Sasmodaito come to the aid 152755839Sasmodaiof their party. 152855839SasmodaiFour score and seven 1529104862Sruyears ago, etc. 153075584Sru@endExample 153155839Sasmodai 153255839Sasmodai@noindent 153375584Sruis read, packed onto output lines, and justified to produce: 153455839Sasmodai 153555839Sasmodai@quotation 153655839SasmodaiNow is the time for all good men to come to the aid of their party. 1537104862SruFour score and seven years ago, etc. 153855839Sasmodai@end quotation 153955839Sasmodai 154055839Sasmodai@cindex break 154155839Sasmodai@cindex line break 154269626SruSometimes a new output line should be started even though the current 154369626Sruline is not yet full; for example, at the end of a paragraph. To do 154469626Sruthis it is possible to cause a @dfn{break}, which starts a new output 154575584Sruline. Some requests cause a break automatically, as normally do blank 154675584Sruinput lines and input lines beginning with a space. 154755839Sasmodai 154875584SruNot all input lines are text to be formatted. Some input lines are 154975584Srurequests which describe how to format the text. Requests always have a 155075584Sruperiod (@samp{.}) or an apostrophe (@samp{'}) as the first character of 155175584Sruthe input line. 155255839Sasmodai 155355839SasmodaiThe text formatter also does more complex things, such as automatically 155469626Srunumbering pages, skipping over page boundaries, putting footnotes in the 155555839Sasmodaicorrect place, and so forth. 155655839Sasmodai 155769626SruHere are a few hints for preparing text for input to @code{gtroff}. 155875584Sru 155975584Sru@itemize @bullet 156075584Sru@item 156169626SruFirst, keep the input lines short. Short input lines are easier to 156275584Sruedit, and @code{gtroff} packs words onto longer lines anyhow. 156355839Sasmodai 156475584Sru@item 156575584SruIn keeping with this, it is helpful to begin a new line after every 156675584Srucomma or phrase, since common corrections are to add or delete sentences 156775584Sruor phrases. 156875584Sru 156975584Sru@item 157075584SruEnd each sentence with two spaces -- or better, start each sentence on a 157175584Srunew line. @code{gtroff} recognizes characters that usually end a 157275584Srusentence, and inserts sentence space accordingly. 157375584Sru 157475584Sru@item 157575584SruDo not hyphenate words at the end of lines -- @code{gtroff} is smart 157675584Sruenough to hyphenate words as needed, but is not smart enough to take 157775584Sruhyphens out and join a word back together. Also, words such as 157875584Sru``mother-in-law'' should not be broken over a line, since then a space 157975584Srucan occur where not wanted, such as ``@w{mother- in}-law''. 158075584Sru@end itemize 158175584Sru 1582104862Sru@cindex double-spacing (@code{ls}) 158355839Sasmodai@cindex spacing 1584104862Sru@code{gtroff} double-spaces output text automatically if you use the 1585104862Srurequest @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing 1586104862Sru@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the 1587104862Sruvertical space, use the @code{pvs} request (@pxref{Changing Type 1588104862SruSizes}).} 158955839Sasmodai 159075584SruA number of requests allow to change the way the output looks, 159175584Srusometimes called the @dfn{layout} of the output page. Most of these 1592104862Srurequests adjust the placing of @dfn{whitespace} (blank lines or 159375584Sruspaces). 159455839Sasmodai 1595104862Sru@cindex new page (@code{bp}) 1596104862SruThe @code{bp} request starts a new page, causing a line break. 159755839Sasmodai 1598104862Sru@cindex blank line (@code{sp}) 1599104862Sru@cindex empty line (@code{sp}) 1600104862Sru@cindex line, empty (@code{sp}) 160169626SruThe request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank 160269626Sruspace. @var{N}@w{ }can be omitted (meaning skip a single line) or can 160369626Srube of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for 160469626Sru@var{N}@w{ }centimeters). For example, the input: 160555839Sasmodai 160675584Sru@Example 160755839Sasmodai.sp 1.5i 160855839SasmodaiMy thoughts on the subject 160955839Sasmodai.sp 161075584Sru@endExample 161155839Sasmodai 161255839Sasmodai@noindent 161355839Sasmodaileaves one and a half inches of space, followed by the line ``My 161475584Sruthoughts on the subject'', followed by a single blank line (more 161575584Srumeasurement units are available, see @ref{Measurements}). 161655839Sasmodai 1617104862Sru@cindex centering lines (@code{ce}) 1618104862Sru@cindex lines, centering (@code{ce}) 161969626SruText lines can be centered by using the @code{ce} request. The line 162069626Sruafter @code{ce} is centered (horizontally) on the page. To center more 162169626Sruthan one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 162269626Sruof lines to center), followed by the @var{N}@w{ }lines. To center many 162369626Srulines without counting them, type: 162455839Sasmodai 162575584Sru@Example 162655839Sasmodai.ce 1000 162755839Sasmodailines to center 162855839Sasmodai.ce 0 162975584Sru@endExample 163055839Sasmodai 163155839Sasmodai@noindent 163269626SruThe @w{@samp{.ce 0}} request tells @code{groff} to center zero more 163369626Srulines, in other words, stop centering. 163455839Sasmodai 1635104862Sru@cindex line break (@code{br}) 1636104862Sru@cindex break (@code{br}) 163755839SasmodaiAll of these requests cause a break; that is, they always start a new 163869626Sruline. To start a new line without performing any other action, use 163969626Sru@code{br}. 164055839Sasmodai 164155839Sasmodai 164269626Sru@c ===================================================================== 164369626Sru 164455839Sasmodai@node Common Features, , Basics, Tutorial for Macro Users 164555839Sasmodai@section Common Features 164655839Sasmodai@cindex common features 164755839Sasmodai@cindex features, common 164855839Sasmodai 164975584Sru@code{gtroff} provides very low-level operations for formatting a 165069626Srudocument. There are many common routine operations which are done in 165169626Sruall documents. These common operations are written into @dfn{macros} 165269626Sruand collected into a @dfn{macro package}. 165355839Sasmodai 165469626SruAll macro packages provide certain common capabilities which fall into 165569626Sruthe following categories. 165655839Sasmodai 165769626Sru@menu 165875584Sru* Paragraphs:: 165975584Sru* Sections and Chapters:: 166075584Sru* Headers and Footers:: 166175584Sru* Page Layout Adjustment:: 166275584Sru* Displays:: 166375584Sru* Footnotes and Annotations:: 166475584Sru* Table of Contents:: 166575584Sru* Indices:: 166675584Sru* Paper Formats:: 166775584Sru* Multiple Columns:: 166875584Sru* Font and Size Changes:: 166975584Sru* Predefined Strings:: 167075584Sru* Preprocessor Support:: 167175584Sru* Configuration and Customization:: 167269626Sru@end menu 167369626Sru 167475584Sru@c --------------------------------------------------------------------- 167575584Sru 167669626Sru@node Paragraphs, Sections and Chapters, Common Features, Common Features 167755839Sasmodai@subsection Paragraphs 167855839Sasmodai@cindex paragraphs 167955839Sasmodai 168075584SruOne of the most common and most used capability is starting a 168175584Sruparagraph. There are a number of different types of paragraphs, any 168275584Sruof which can be initiated with macros supplied by the macro package. 168375584SruNormally, paragraphs start with a blank line and the first line 168475584Sruindented, like the text in this manual. There are also block style 168575584Sruparagraphs, which omit the indentation: 168655839Sasmodai 168775584Sru@Example 168855839SasmodaiSome men look at constitutions with sanctimonious 168955839Sasmodaireverence, and deem them like the ark of the covenant, too 169055839Sasmodaisacred to be touched. 169175584Sru@endExample 169255839Sasmodai 169369626Sru@noindent 169455839SasmodaiAnd there are also indented paragraphs which begin with a tag or label 169555839Sasmodaiat the margin and the remaining text indented. 169655839Sasmodai 1697104862Sru@Example 169855839Sasmodaione This is the first paragraph. Notice how the first 169955839Sasmodai line of the resulting paragraph lines up with the 170055839Sasmodai other lines in the paragraph. 1701104862Sru@endExample 1702104862Sru@Example 170355839Sasmodailonglabel 170455839Sasmodai This paragraph had a long label. The first 170575584Sru character of text on the first line does not line up 170655839Sasmodai with the text on second and subsequent lines, 170775584Sru although they line up with each other. 1708104862Sru@endExample 170955839Sasmodai 171069626SruA variation of this is a bulleted list. 171155839Sasmodai 1712104862Sru@Example 1713104862Sru. Bulleted lists start with a bullet. It is possible 1714104862Sru to use other glyphs instead of the bullet. In nroff 1715104862Sru mode using the ASCII character set for output, a dot 1716104862Sru is used instead of a real bullet. 1717104862Sru@endExample 171869626Sru 1719104862Sru 172069626Sru@c --------------------------------------------------------------------- 172169626Sru 172269626Sru@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 172355839Sasmodai@subsection Sections and Chapters 172455839Sasmodai 172569626SruMost macro packages supply some form of section headers. The simplest 172669626Srukind is simply the heading on a line by itself in bold type. Others 172769626Srusupply automatically numbered section heading or different heading 172869626Srustyles at different levels. Some, more sophisticated, macro packages 172969626Srusupply macros for starting chapters and appendices. 173055839Sasmodai 173169626Sru@c --------------------------------------------------------------------- 173269626Sru 173369626Sru@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 173455839Sasmodai@subsection Headers and Footers 173555839Sasmodai 1736104862SruEvery macro package gives some way to manipulate the @dfn{headers} and 1737104862Sru@dfn{footers} (also called @dfn{titles}) on each page. This is text 1738104862Sruput at the top and bottom of each page, respectively, which contain 1739104862Srudata like the current page number, the current chapter title, and so 1740104862Sruon. Its appearance is not affected by the running text. Some packages 1741104862Sruallow for different ones on the even and odd pages (for material printed 1742104862Sruin a book form). 174369626Sru 1744104862SruThe titles are called @dfn{three-part titles}, that is, there is a 174569626Sruleft-justified part, a centered part, and a right-justified part. An 174669626Sruautomatically generated page number may be put in any of these fields 174769626Sruwith the @samp{%} character (see @ref{Page Layout}, for more details). 174855839Sasmodai 174969626Sru@c --------------------------------------------------------------------- 175069626Sru 175169626Sru@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 175255839Sasmodai@subsection Page Layout 175355839Sasmodai 175469626SruMost macro packages let the user specify top and bottom margins and 175569626Sruother details about the appearance of the printed pages. 175655839Sasmodai 175769626Sru@c --------------------------------------------------------------------- 175869626Sru 175969626Sru@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 176055839Sasmodai@subsection Displays 176155839Sasmodai@cindex displays 176255839Sasmodai 1763104862Sru@dfn{Displays} are sections of text to be set off from the body of 1764104862Sruthe paper. Major quotes, tables, and figures are types of displays, as 1765104862Sruare all the examples used in this document. 176655839Sasmodai 176755839Sasmodai@cindex quotes, major 176855839Sasmodai@cindex major quotes 176969626Sru@dfn{Major quotes} are quotes which are several lines long, and hence 177069626Sruare set in from the rest of the text without quote marks around them. 177155839Sasmodai 177255839Sasmodai@cindex list 1773104862SruA @dfn{list} is an indented, single-spaced, unfilled display. Lists 177469626Srushould be used when the material to be printed should not be filled and 177569626Srujustified like normal text, such as columns of figures or the examples 177669626Sruused in this paper. 177755839Sasmodai 177855839Sasmodai@cindex keep 177969626SruA @dfn{keep} is a display of lines which are kept on a single page if 178069626Srupossible. An example for a keep might be a diagram. Keeps differ from 178175584Srulists in that lists may be broken over a page boundary whereas keeps are 178275584Srunot. 178355839Sasmodai 178455839Sasmodai@cindex keep, floating 178555839Sasmodai@cindex floating keep 1786104862Sru@dfn{Floating keeps} move relative to the text. Hence, they are good for 178775584Sruthings which are referred to by name, such as ``See figure@w{ }3''. A 178875584Srufloating keep appears at the bottom of the current page if it fits; 178975584Sruotherwise, it appears at the top of the next page. Meanwhile, the 179075584Srusurrounding text `flows' around the keep, thus leaving no blank areas. 179155839Sasmodai 179269626Sru@c --------------------------------------------------------------------- 179369626Sru 179469626Sru@node Footnotes and Annotations, Table of Contents, Displays, Common Features 179569626Sru@subsection Footnotes and Annotations 179655839Sasmodai@cindex footnotes 179755839Sasmodai@cindex annotations 179855839Sasmodai 179969626SruThere are a number of requests to save text for later printing. 180055839Sasmodai 180169626Sru@dfn{Footnotes} are printed at the bottom of the current page. 180255839Sasmodai 180369626Sru@cindex delayed text 180469626Sru@dfn{Delayed text} is very similar to a footnote except that it is 180569626Sruprinted when called for explicitly. This allows a list of references to 180669626Sruappear (for example) at the end of each chapter, as is the convention in 180769626Srusome disciplines. 180855839Sasmodai 180969626SruMost macro packages which supply this functionality also supply a means 181069626Sruof automatically numbering either type of annotation. 181169626Sru 181269626Sru@c --------------------------------------------------------------------- 181369626Sru 181469626Sru@node Table of Contents, Indices, Footnotes and Annotations, Common Features 181555839Sasmodai@subsection Table of Contents 181669626Sru@cindex table of contents 181769626Sru@cindex contents, table of 181855839Sasmodai 181969626Sru@dfn{Tables of contents} are a type of delayed text having a tag 182069626Sru(usually the page number) attached to each entry after a row of dots. 182169626SruThe table accumulates throughout the paper until printed, usually after 182275584Sruthe paper has ended. Many macro packages provide the ability to have 182375584Sruseveral tables of contents (e.g.@: a standard table of contents, a list 182475584Sruof tables, etc). 182555839Sasmodai 182669626Sru@c --------------------------------------------------------------------- 182755839Sasmodai 182869626Sru@node Indices, Paper Formats, Table of Contents, Common Features 182969626Sru@subsection Indices 183069626Sru@cindex index, in macro package 183155839Sasmodai 183275584SruWhile some macro packages use the term @dfn{index}, none actually 183369626Sruprovide that functionality. The facilities they call indices are 183469626Sruactually more appropriate for tables of contents. 183555839Sasmodai 1836104862Sru@pindex makeindex 1837104862SruTo produce a real index in a document, external tools like the 1838104862Sru@code{makeindex} program are necessary. 1839104862Sru 184069626Sru@c --------------------------------------------------------------------- 184169626Sru 184269626Sru@node Paper Formats, Multiple Columns, Indices, Common Features 184369626Sru@subsection Paper Formats 184469626Sru@cindex paper formats 184569626Sru 184655839SasmodaiSome macro packages provide stock formats for various kinds of 184755839Sasmodaidocuments. Many of them provide a common format for the title and 184869626Sruopening pages of a technical paper. The @file{mm} macros in particular 184969626Sruprovide formats for letters and memoranda. 185055839Sasmodai 185169626Sru@c --------------------------------------------------------------------- 185269626Sru 185369626Sru@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 185455839Sasmodai@subsection Multiple Columns 185555839Sasmodai 185669626SruSome macro packages (but not @file{man}) provide the ability to have two 185769626Sruor more columns on a page. 185855839Sasmodai 185969626Sru@c --------------------------------------------------------------------- 186055839Sasmodai 186169626Sru@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 186269626Sru@subsection Font and Size Changes 186369626Sru 186469626SruThe built-in font and size functions are not always intuitive, so all 186555839Sasmodaimacro packages provide macros to make these operations simpler. 186655839Sasmodai 186769626Sru@c --------------------------------------------------------------------- 186869626Sru 186969626Sru@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 187055839Sasmodai@subsection Predefined Strings 187155839Sasmodai 187269626SruMost macro packages provide various predefined strings for a variety of 187369626Sruuses; examples are sub- and superscripts, printable dates, quotes and 187469626Sruvarious special characters. 187555839Sasmodai 187669626Sru@c --------------------------------------------------------------------- 187769626Sru 187869626Sru@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 187955839Sasmodai@subsection Preprocessor Support 188055839Sasmodai 1881104862SruAll macro packages provide support for various preprocessors and may 188275584Sruextend their functionality. 188355839Sasmodai 188475584SruFor example, all macro packages mark tables (which are processed with 1885104862Sru@code{gtbl}) by placing them between @code{TS} and @code{TE} macros. 1886104862SruThe @file{ms} macro package has an option, @samp{.TS@w{ }H}, that prints 188775584Srua caption at the top of a new page (when the table is too long to fit on 188875584Srua single page). 188975584Sru 189069626Sru@c --------------------------------------------------------------------- 189169626Sru 189269626Sru@node Configuration and Customization, , Preprocessor Support, Common Features 189355839Sasmodai@subsection Configuration and Customization 189455839Sasmodai 189575584SruSome macro packages provide means of customizing many of the details of 189675584Sruhow the package behaves. This ranges from setting the default type size 189775584Sruto changing the appearance of section headers. 189855839Sasmodai 189955839Sasmodai 190055839Sasmodai 190169626Sru@c ===================================================================== 190269626Sru@c ===================================================================== 190355839Sasmodai 190475584Sru@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 190569626Sru@chapter Macro Packages 190669626Sru@cindex macro packages 190769626Sru@cindex packages, macros 190855839Sasmodai 190969626SruThis chapter documents the main macro packages that come with 191069626Sru@code{groff}. 191155839Sasmodai 191269626Sru@menu 191375584Sru* man:: 191475584Sru* mdoc:: 191575584Sru* ms:: 191675584Sru* me:: 191775584Sru* mm:: 191869626Sru@end menu 191955839Sasmodai 192055839Sasmodai 192169626Sru@c ===================================================================== 192255839Sasmodai 192369626Sru@node man, mdoc, Macro Packages, Macro Packages 192469626Sru@section @file{man} 192569626Sru@cindex manual pages 1926104862Sru@cindex man pages 192775584Sru@pindex an.tmac 192875584Sru@pindex man.tmac 192975584Sru@pindex man-old.tmac 193055839Sasmodai 193169626SruThis is the most popular and probably the most important macro package 193269626Sruof @code{groff}. It is easy to use, and a vast majority of manual pages 193369626Sruare based on it. 193455839Sasmodai 193569626Sru@menu 193675584Sru* Man options:: 193775584Sru* Man usage:: 193875584Sru* Man font macros:: 193975584Sru* Miscellaneous man macros:: 194075584Sru* Predefined man strings:: 194175584Sru* Preprocessors in man pages:: 194269626Sru@end menu 194355839Sasmodai 194469626Sru@c --------------------------------------------------------------------- 194555839Sasmodai 194669626Sru@node Man options, Man usage, man, man 194769626Sru@subsection Options 194855839Sasmodai 194969626SruThe command line format for using the @file{man} macros with 195069626Sru@code{groff} is: 195169626Sru 195275584Sru@Example 1953104862Srugroff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] 1954104862Sru [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ] 195575584Sru [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ] 195675584Sru@endExample 195769626Sru 195875584Sru@noindent 195969626SruIt is possible to use @samp{-man} instead of @w{@samp{-m man}}. 196069626Sru 196169626Sru@table @code 1962104862Sru@item -rLL=@var{length} 1963104862SruSet line length to @var{length}. If not specified, the line length 1964104862Srudefaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per 1965104862Sruline) and 6.5@w{ }inch otherwise. 1966104862Sru 1967104862Sru@item -rLT=@var{length} 1968104862SruSet title length to @var{length}. If not specified, the title length 1969104862Srudefaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per 1970104862Sruline) and 6.5@w{ }inch otherwise. 1971104862Sru 197275584Sru@item -rcR=1 1973104862SruThis option (the default if a TTY output device is used) creates a 197475584Srusingle, very long page instead of multiple pages. Use @code{-rcR=0} 197575584Sruto disable it. 197675584Sru 197769626Sru@item -rC1 197869626SruIf more than one manual page is given on the command line, number the 197969626Srupages continuously, rather than starting each at@w{ }1. 198069626Sru 198169626Sru@item -rD1 198269626SruDouble-sided printing. Footers for even and odd pages are formatted 198369626Srudifferently. 198469626Sru 198569626Sru@item -rP@var{nnn} 198675584SruPage numbering starts with @var{nnn} rather than with@w{ }1. 198769626Sru 198869626Sru@item -rS@var{xx} 198969626SruUse @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base 199069626Srudocument font size instead of the default value of@w{ }10@dmn{pt}. 199169626Sru 199269626Sru@item -rX@var{nnn} 199369626SruAfter page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 199475584Sru@var{nnn}c, etc. For example, the option @option{-rX2} produces the 199569626Srufollowing page numbers: 1, 2, 2a, 2b, 2c, etc. 199669626Sru@end table 199769626Sru 199869626Sru@c --------------------------------------------------------------------- 199969626Sru 200069626Sru@node Man usage, Man font macros, Man options, man 200169626Sru@subsection Usage 200269626Sru@cindex @code{man} macros 2003104862Sru@cindex macros for manual pages [@code{man}] 200469626Sru 200569626Sru@pindex man.local 200669626SruThis section describes the available macros for manual pages. For 200769626Srufurther customization, put additional macros and requests into the file 200875584Sru@file{man.local} which is loaded immediately after the @file{man} 200975584Srupackage. 201069626Sru 2011104862Sru@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} 201275584SruSet the title of the man page to @var{title} and the section to 201369626Sru@var{section}, which must have a value between 1 and@w{ }8. The value 201475584Sruof @var{section} may also have a string appended, e.g.@: @samp{.pm}, 201575584Sruto indicate a specific subsection of the man pages. 201669626Sru 201769626SruBoth @var{title} and @var{section} are positioned at the left and right 201869626Sruin the header line (with @var{section} in parentheses immediately 201975584Sruappended to @var{title}. @var{extra1} is positioned in the middle of 202075584Sruthe footer line. @var{extra2} is positioned at the left in the footer 202175584Sruline (or at the left on even pages and at the right on odd pages if 202275584Srudouble-sided printing is active). @var{extra3} is centered in the 202375584Sruheader line. 202469626Sru 202569626SruFor @acronym{HTML} output, headers and footers are completely suppressed. 202669626Sru 202769626SruAdditionally, this macro starts a new page; the new line number is@w{ }1 202869626Sruagain (except if the @option{-rC1} option is given on the command line) 202969626Sru-- this feature is intended only for formatting multiple man pages; a 203069626Srusingle man page should contain exactly one @code{TH} macro at the 203169626Srubeginning of the file. 203275584Sru@endDefmac 203369626Sru 2034104862Sru@Defmac {SH, [@Var{heading}], man} 203575584SruSet up an unnumbered section heading sticking out to the left. Prints 203675584Sruout all the text following @code{SH} up to the end of the line (or the 203775584Srutext in the next line if there is no argument to @code{SH}) in bold 203869626Sruface, one size larger than the base document size. Additionally, the 203969626Sruleft margin for the following text is reset to its default value. 204075584Sru@endDefmac 204169626Sru 2042104862Sru@Defmac {SS, [@Var{heading}], man} 204375584SruSet up an unnumbered (sub)section heading. Prints out all the text 204475584Srufollowing @code{SS} up to the end of the line (or the text in the next 204575584Sruline if there is no argument to @code{SS}) in bold face, at the same 204675584Srusize as the base document size. Additionally, the left margin for the 204775584Srufollowing text is reset to its default value. 204875584Sru@endDefmac 204969626Sru 2050104862Sru@Defmac {TP, [@Var{nnn}], man} 205175584SruSet up an indented paragraph with label. The indentation is set to 205275584Sru@var{nnn} if that argument is supplied (the default unit is @samp{n} 205375584Sruif omitted), otherwise it is set to the default indentation value. 205469626Sru 205569626SruThe first line of text following this macro is interpreted as a string 205669626Sruto be printed flush-left, as it is appropriate for a label. It is not 205769626Sruinterpreted as part of a paragraph, so there is no attempt to fill the 205869626Srufirst line with text from the following input lines. Nevertheless, if 205969626Sruthe label is not as wide as the indentation, then the paragraph starts 206075584Sruat the same line (but indented), continuing on the following lines. 206175584SruIf the label is wider than the indentation, then the descriptive part 206275584Sruof the paragraph begins on the line following the label, entirely 206375584Sruindented. Note that neither font shape nor font size of the label is 206475584Sruset to a default value; on the other hand, the rest of the text has 206575584Srudefault font settings. 206675584Sru@endDefmac 206769626Sru 2068104862Sru@DefmacList {LP, , man} 2069104862Sru@DefmacItem {PP, , man} 2070104862Sru@DefmacListEnd {P, , man} 207175584SruThese macros are mutual aliases. Any of them causes a line break at 207275584Sruthe current position, followed by a vertical space downwards by the 207375584Sruamount specified by the @code{PD} macro. The font size and shape are 2074104862Srureset to the default value (10@dmn{pt} roman if no @option{-rS} option 2075104862Sruis given on the command line). Finally, the current left margin is 2076104862Srurestored. 207775584Sru@endDefmac 207869626Sru 2079104862Sru@Defmac {IP, [@Var{designator} [@Var{nnn}]], man} 208075584SruSet up an indented paragraph, using @var{designator} as a tag to mark 208175584Sruits beginning. The indentation is set to @var{nnn} if that argument 208275584Sruis supplied (default unit is @samp{n}), otherwise the default 208375584Sruindentation value is used. Font size and face of the paragraph (but 208475584Srunot the designator) are reset to their default values. To start an 208575584Sruindented paragraph with a particular indentation but without a 208675584Srudesignator, use @samp{""} (two double quotes) as the first argument of 208775584Sru@code{IP}. 208869626Sru 208969626SruFor example, to start a paragraph with bullets as the designator and 2090104862Sru4@w{ }en indentation, write 209169626Sru 209275584Sru@Example 209369626Sru.IP \(bu 4 209475584Sru@endExample 209575584Sru@endDefmac 209669626Sru 2097104862Sru@Defmac {HP, [@Var{nnn}], man} 2098104862Sru@cindex hanging indentation [@code{man}] 2099104862Sru@cindex @code{man} macros, hanging indentation 210075584SruSet up a paragraph with hanging left indentation. The indentation is 210169626Sruset to @var{nnn} if that argument is supplied (default unit is 210269626Sru@samp{n}), otherwise the default indentation value is used. Font size 210369626Sruand face are reset to their default values. 210475584Sru@endDefmac 210569626Sru 2106104862Sru@Defmac {RS, [@Var{nnn}], man} 2107104862Sru@cindex left margin, how to move [@code{man}] 2108104862Sru@cindex @code{man} macros, moving left margin 210975584SruMove the left margin to the right by the value @var{nnn} if specified 2110104862Sru(default unit is @samp{n}); otherwise the default indentation value 2111104862Sruis used. Calls to the @code{RS} macro can be nested. 211275584Sru@endDefmac 211369626Sru 2114104862Sru@Defmac {RE, [@Var{nnn}], man} 211575584SruMove the left margin back to level @var{nnn}; if no argument is given, 211675584Sruit moves one level back. The first level (i.e., no call to @code{RS} 211775584Sruyet) has number@w{ }1, and each call to @code{RS} increases the level 211875584Sruby@w{ }1. 211975584Sru@endDefmac 212069626Sru 2121104862Sru@cindex line breaks, with vertical space [@code{man}] 2122104862Sru@cindex @code{man} macros, line breaks with vertical space 212369626SruTo summarize, the following macros cause a line break with the insertion 212469626Sruof vertical space (which amount can be changed with the @code{PD} 212569626Srumacro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 212669626Sru@code{P}), @code{IP}, and @code{HP}. 212769626Sru 2128104862Sru@cindex line breaks, without vertical space [@code{man}] 2129104862Sru@cindex @code{man} macros, line breaks without vertical space 213069626SruThe macros @code{RS} and @code{RE} also cause a break but do not insert 213169626Sruvertical space. 213269626Sru 2133104862Sru@cindex default indentation, resetting [@code{man}] 2134104862Sru@cindex indentaion, resetting to default [@code{man}] 2135104862Sru@cindex @code{man} macros, resetting default indentation 2136104862SruFinally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}), 2137104862Sruand @code{RS} reset the indentation to its default value. 2138104862Sru 213969626Sru@c --------------------------------------------------------------------- 214069626Sru 214175584Sru@node Man font macros, Miscellaneous man macros, Man usage, man 214269626Sru@subsection Macros to set fonts 2143104862Sru@cindex font selection [@code{man}] 2144104862Sru@cindex @code{man} macros, how to set fonts 214569626Sru 214675584SruThe standard font is roman; the default text size is 10@w{ }point. 2147104862SruIf command line option @option{-rS=@var{n}} is given, use 2148104862Sru@var{n}@dmn{pt} as the default text size. 214969626Sru 2150104862Sru@Defmac {SM, [@Var{text}], man} 215175584SruSet the text on the same line or the text on the next line in a font 215275584Sruthat is one point size smaller than the default font. 215375584Sru@endDefmac 215469626Sru 2155104862Sru@Defmac {SB, [@Var{text}], man} 2156104862Sru@cindex bold face [@code{man}] 2157104862Sru@cindex @code{man} macros, bold face 2158104862SruSet the text on the same line or the text on the next line in bold face 215975584Srufont, one point size smaller than the default font. 216075584Sru@endDefmac 216169626Sru 2162104862Sru@Defmac {BI, text, man} 216375584SruSet its arguments alternately in bold face and italic. Thus, 216469626Sru 216575584Sru@Example 216669626Sru.BI this "word and" that 216775584Sru@endExample 216869626Sru 216969626Sru@noindent 217075584Sruwould set ``this'' and ``that'' in bold face, and ``word and'' in 217175584Sruitalics. 217275584Sru@endDefmac 217369626Sru 2174104862Sru@Defmac {IB, text, man} 217575584SruSet its arguments alternately in italic and bold face. 217675584Sru@endDefmac 217769626Sru 2178104862Sru@Defmac {RI, text, man} 217975584SruSet its arguments alternately in roman and italic. 218075584Sru@endDefmac 218169626Sru 2182104862Sru@Defmac {IR, text, man} 218375584SruSet its arguments alternately in italic and roman. 218475584Sru@endDefmac 218569626Sru 2186104862Sru@Defmac {BR, text, man} 218775584SruSet its arguments alternately in bold face and roman. 218875584Sru@endDefmac 218969626Sru 2190104862Sru@Defmac {RB, text, man} 219175584SruSet its arguments alternately in roman and bold face. 219275584Sru@endDefmac 219369626Sru 2194104862Sru@Defmac {B, [@Var{text}], man} 219575584SruSet @var{text} in bold face. If no text is present on the line where 219675584Sruthe macro is called, then the text of the next line appears in bold 219775584Sruface. 219875584Sru@endDefmac 219969626Sru 2200104862Sru@Defmac {I, [@Var{text}], man} 2201104862Sru@cindex italic fonts [@code{man}] 2202104862Sru@cindex @code{man} macros, italic fonts 220375584SruSet @var{text} in italic. If no text is present on the line where the 220475584Srumacro is called, then the text of the next line appears in italic. 220575584Sru@endDefmac 220669626Sru 220769626Sru@c --------------------------------------------------------------------- 220869626Sru 220975584Sru@node Miscellaneous man macros, Predefined man strings, Man font macros, man 221075584Sru@subsection Miscellaneous macros 221169626Sru 221269626Sru@pindex grohtml 2213104862Sru@cindex @code{man} macros, default indentation 2214104862Sru@cindex default indentation [@code{man}] 2215104862SruThe default indentation is 7.2@w{ }en for all output devices except for 221675584Sru@code{grohtml} which ignores indentation. 221769626Sru 2218104862Sru@Defmac {DT, , man} 2219104862Sru@cindex tab stops [@code{man}] 2220104862Sru@cindex @code{man} macros, tab stops 2221104862SruSet tabs every 0.5@w{ }inches. Since this macro is always executed 2222104862Sruduring a call to the @code{TH} macro, it makes sense to call it only if 2223104862Sruthe tab positions have been changed. 222475584Sru@endDefmac 222569626Sru 2226104862Sru@Defmac {PD, [@Var{nnn}], man} 2227104862Sru@cindex empty space before a paragraph [@code{man}] 2228104862Sru@cindex @code{man} macros, empty space before a paragraph 222975584SruAdjust the empty space before a new paragraph (or section). The 223075584Sruoptional argument gives the amount of space (default unit is 223169626Sru@samp{v}); without parameter, the value is reset to its default value 2232104862Sru(1@w{ }line for TTY devices, 0.4@dmn{v}@w{ }otherwise). 223375584Sru@endDefmac 223469626Sru 223575584SruThis affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 223675584Sruwell as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 223769626Sru 223875584Sru@c --------------------------------------------------------------------- 223975584Sru 224075584Sru@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 224175584Sru@subsection Predefined strings 224275584Sru 224369626SruThe following strings are defined: 224469626Sru 2245104862Sru@Defstr {S, man} 224669626SruSwitch back to the default font size. 224775584Sru@endDefstr 224869626Sru 2249104862Sru@Defstr {R, man} 225069626SruThe `registered' sign. 225175584Sru@endDefstr 225269626Sru 2253104862Sru@Defstr {Tm, man} 225469626SruThe `trademark' sign. 225575584Sru@endDefstr 225669626Sru 2257104862Sru@DefstrList {lq, man} 2258104862Sru@DefstrListEnd {rq, man} 2259104862Sru@cindex @code{lq} glyph, and @code{lq} string [@code{man}] 2260104862Sru@cindex @code{rq} glyph, and @code{rq} string [@code{man}] 226175584SruLeft and right quote. This is equal to @code{\(lq} and @code{\(rq}, 226275584Srurespectively. 226375584Sru@endDefstr 226469626Sru 226575584Sru@c --------------------------------------------------------------------- 226675584Sru 226775584Sru@node Preprocessors in man pages, , Predefined man strings, man 226875584Sru@subsection Preprocessors in @file{man} pages 226975584Sru 227069626Sru@cindex preprocessor, calling convention 227169626Sru@cindex calling convention of preprocessors 227269626SruIf a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 227369626Srubecome common usage to make the first line of the man page look like 227469626Sruthis: 227569626Sru 227675584Sru@Example 2277104862Sru'\" @var{word} 227875584Sru@endExample 227969626Sru 228069626Sru@pindex geqn@r{, invocation in manual pages} 228169626Sru@pindex grefer@r{, invocation in manual pages} 228269626Sru@pindex gtbl@r{, invocation in manual pages} 228369626Sru@pindex man@r{, invocation of preprocessors} 228475584Sru@noindent 228569626SruNote the single space character after the double quote. @var{word} 228669626Sruconsists of letters for the needed preprocessors: @samp{e} for 228769626Sru@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 228869626SruModern implementations of the @code{man} program read this first line 228969626Sruand automatically call the right preprocessor(s). 229069626Sru 229169626Sru 229269626Sru@c ===================================================================== 229369626Sru 229469626Sru@node mdoc, ms, man, Macro Packages 229569626Sru@section @file{mdoc} 2296104862Sru@cindex @code{mdoc} macros 229769626Sru 229869626Sru@c XXX documentation 2299104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 2300104862SruSee the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc} 2301104862Sruat the command line). 230269626Sru 230369626Sru 230469626Sru@c ===================================================================== 230569626Sru 230669626Sru@node ms, me, mdoc, Macro Packages 230769626Sru@section @file{ms} 2308104862Sru@cindex @code{ms} macros 230969626Sru 2310104862SruThe @file{-ms} 2311104862Srumacros are suitable for reports, letters, books, 2312104862Sruuser manuals, and so forth. 2313104862SruThe package provides macros for cover pages, section headings, 2314104862Sruparagraphs, lists, footnotes, pagination, 2315104862Sruand a table of contents. 231669626Sru 2317104862Sru@menu 2318104862Sru* ms Intro:: 2319104862Sru* General ms Structure:: 2320104862Sru* ms Document Control Registers:: 2321104862Sru* ms Cover Page Macros:: 2322104862Sru* ms Body Text:: 2323104862Sru* ms Page Layout:: 2324104862Sru* Differences from AT&T ms:: 2325104862Sru@end menu 232669626Sru 2327104862Sru@c --------------------------------------------------------------------- 2328104862Sru 2329104862Sru@node ms Intro, General ms Structure, ms, ms 2330104862Sru@subsection Introduction to @file{ms} 2331104862Sru 2332104862SruThe original @file{-ms} macros were included with 2333104862Sru@acronym{AT&T} @code{troff} as well as the 2334104862Sru@file{man} macros. 2335104862SruWhile the @file{man} package is intended for brief documents 2336104862Sruthat can be read on-line as well as printed, the @file{ms} 2337104862Srumacros are suitable for longer documents that are meant to be 2338104862Sruprinted rather than read on-line. 2339104862Sru 2340104862SruThe @file{ms} macro package included with @code{groff} 2341104862Sruis a complete, bottom-up re-implementation. 2342104862SruSeveral macros (specific to @acronym{AT&T} 2343104862Sruor Berkeley) are not included, while several new commands are. 2344104862Sru@xref{Differences from AT&T ms}, for more information. 2345104862Sru 2346104862Sru@c --------------------------------------------------------------------- 2347104862Sru 2348104862Sru@node General ms Structure, ms Document Control Registers, ms Intro, ms 2349104862Sru@subsection General structure of an @file{ms} document 2350104862Sru@cindex @code{ms} macros, general structure 2351104862Sru 2352104862SruThe @file{ms} macro package expects a certain amount of structure, 2353104862Srubut not as much as packages such as @file{man} or @file{mdoc}. 2354104862Sru 2355104862SruThe simplest documents can begin with a paragraph macro 2356104862Sru(such as @code{LP} or @code{PP}), 2357104862Sruand consist of text separated by paragraph macros 2358104862Sruor even blank lines. 2359104862SruLonger documents have a structure as follows: 2360104862Sru 2361104862Sru@table @strong 2362104862Sru@item Document type 2363104862SruIf you invoke the @code{RP} 2364104862Sru(report) macro on the first line of the document, 2365104862Sru@code{groff} prints the cover page information on its own page; 2366104862Sruotherwise it prints the information on the 2367104862Srufirst page with your document text immediately following. 2368104862SruOther document formats found in @acronym{AT&T} @code{troff} 2369104862Sruare specific to @acronym{AT&T} or Berkeley, and are not supported in 2370104862Sru@code{groff}. 2371104862Sru 2372104862Sru@item Format and layout 2373104862SruBy setting number registers, 2374104862Sruyou can change your document's type (font and size), 2375104862Srumargins, spacing, headers and footers, and footnotes. 2376104862Sru@xref{ms Document Control Registers}, for more details. 2377104862Sru 2378104862Sru@item Cover page 2379104862SruA cover page consists of a title, the author's name and institution, 2380104862Sruan abstract, and the date. 2381104862Sru@footnote{Actually, only the title is required.} 2382104862Sru@xref{ms Cover Page Macros}, for more details. 2383104862Sru 2384104862Sru@item Body 2385104862SruFollowing the cover page is your document. 2386104862SruYou can use the @file{ms} 2387104862Srumacros to write reports, letters, books, and so forth. 2388104862SruThe package is designed for structured documents, 2389104862Sruconsisting of paragraphs interspersed with headings 2390104862Sruand augmented by lists, footnotes, tables, and other 2391104862Srucommon constructs. 2392104862Sru@xref{ms Body Text}, for more details. 2393104862Sru 2394104862Sru@item Table of contents 2395104862SruLonger documents usually include a table of contents, 2396104862Sruwhich you can invoke by placing the 2397104862Sru@code{TC} 2398104862Srumacro at the end of your document. 2399104862SruThe @file{ms} 2400104862Srumacros have minimal indexing facilities, consisting of the 2401104862Sru@code{IX} macro, which prints an entry on standard error. 2402104862SruPrinting the table of contents at the end is necessary since 2403104862Sru@code{groff} is a single-pass text formatter, 2404104862Sruthus it cannot determine the page number of each section 2405104862Sruuntil that section has actually been set and printed. 2406104862SruSince @file{ms} output is intended for hardcopy, 2407104862Sruyou can manually relocate the pages containing 2408104862Sruthe table of contents between the cover page and the 2409104862Srubody text after printing. 2410104862Sru@end table 2411104862Sru 2412104862Sru@c --------------------------------------------------------------------- 2413104862Sru 2414104862Sru@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms 2415104862Sru@subsection Document control registers 2416104862Sru@cindex @code{ms} macros, document control registers 2417104862Sru 2418104862SruThe following is a list of document control number registers. 2419104862SruFor the sake of consistency, 2420104862Sruset registers related to margins at the beginning of your document, 2421104862Sruor just after the @code{RP} macro. 2422104862SruYou can set other registers later in your document, 2423104862Srubut you should keep them together at the beginning 2424104862Sruto make them easy to find and edit as necessary. 2425104862Sru 2426104862Sru@unnumberedsubsubsec Margin Settings 2427104862Sru 2428104862Sru@Defmpreg {PO, ms} 2429104862SruDefines the page offset (i.e.@: the left margin). 2430104862SruThere is no explicit right margin setting; the combination of 2431104862Sruthe @code{PO} and @code{LL} registers implicitly define the 2432104862Sruright margin width. 2433104862Sru 2434104862SruEffective: next page. 2435104862Sru 2436104862SruDefault value: 1@dmn{i}. 2437104862Sru@endDefmpreg 2438104862Sru 2439104862Sru@Defmpreg {LL, ms} 2440104862SruDefines the line length (i.e.@: the width of the body text). 2441104862Sru 2442104862SruEffective: next paragraph. 2443104862Sru 2444104862SruDefault: 6@dmn{i}. 2445104862Sru@endDefmpreg 2446104862Sru 2447104862Sru@Defmpreg {LT, ms} 2448104862SruDefines the title length (i.e.@: the header and footer width). 2449104862SruThis is usually the same as @code{LL}, but not necessarily. 2450104862Sru 2451104862SruEffective: next paragraph. 2452104862Sru 2453104862SruDefault: 6@dmn{i}. 2454104862Sru@endDefmpreg 2455104862Sru 2456104862Sru@Defmpreg {HM, ms} 2457104862SruDefines the header margin height at the top of the page. 2458104862Sru 2459104862SruEffective: next page. 2460104862Sru 2461104862SruDefault: 1@dmn{i}. 2462104862Sru@endDefmpreg 2463104862Sru 2464104862Sru@Defmpreg {FM, ms} 2465104862SruDefines the footer margin height at the bottom of the page. 2466104862Sru 2467104862SruEffective: next page. 2468104862Sru 2469104862SruDefault: 1@dmn{i}. 2470104862Sru@endDefmpreg 2471104862Sru 2472104862Sru@unnumberedsubsubsec Text Settings 2473104862Sru 2474104862Sru@Defmpreg {PS, ms} 2475104862SruDefines the point size of the body text. 2476104862Sru 2477104862SruEffective: next paragraph. 2478104862Sru 2479104862SruDefault: 10@dmn{p}. 2480104862Sru@endDefmpreg 2481104862Sru 2482104862Sru@Defmpreg {VS, ms} 2483104862SruDefines the space between lines (line height plus leading). 2484104862Sru 2485104862SruEffective: next paragraph. 2486104862Sru 2487104862SruDefault: 12@dmn{p}. 2488104862Sru@endDefmpreg 2489104862Sru 2490104862Sru@unnumberedsubsubsec Paragraph Settings 2491104862Sru 2492104862Sru@Defmpreg {PI, ms} 2493104862SruDefines the initial indent of a @code{.PP} paragraph. 2494104862Sru 2495104862SruEffective: next paragraph. 2496104862Sru 2497104862SruDefault: 5@dmn{n}. 2498104862Sru@endDefmpreg 2499104862Sru 2500104862Sru@Defmpreg {PD, ms} 2501104862SruDefines the space between paragraphs. 2502104862Sru 2503104862SruEffective: next paragraph. 2504104862Sru 2505104862SruDefault: 0.3@dmn{v}. 2506104862Sru@endDefmpreg 2507104862Sru 2508104862Sru@Defmpreg {QI, ms} 2509104862SruDefines the indent on both sides of a quoted (@code{.QP}) paragraph. 2510104862Sru 2511104862SruEffective: next paragraph. 2512104862Sru 2513104862SruDefault: 5@dmn{n}. 2514104862Sru@endDefmpreg 2515104862Sru 2516104862Sru@unnumberedsubsubsec Footnote Settings 2517104862Sru 2518104862Sru@Defmpreg {FL, ms} 2519104862SruDefines the length of a footnote. 2520104862Sru 2521104862SruEffective: next footnote. 2522104862Sru 2523104862SruDefault: @math{@code{@\n[LL]} * 5 / 6}. 2524104862Sru@endDefmpreg 2525104862Sru 2526104862Sru@Defmpreg {FI, ms} 2527104862SruDefines the footnote indent. 2528104862Sru 2529104862SruEffective: next footnote. 2530104862Sru 2531104862SruDefault: 2@dmn{n}. 2532104862Sru@endDefmpreg 2533104862Sru 2534104862Sru@Defmpreg {FF, ms} 2535104862SruThe footnote format: 2536104862Sru@table @code 2537104862Sru@item 0 2538104862SruPrints the footnote number as a superscript; indents the footnote (default). 2539104862Sru 2540104862Sru@item 1 2541104862SruPrints the number followed by a period (like 1.) 2542104862Sruand indents the footnote. 2543104862Sru 2544104862Sru@item 2 2545104862SruLike 1, without an indent. 2546104862Sru 2547104862Sru@item 3 2548104862SruLike 1, but prints the footnote number as a hanging paragraph. 2549104862Sru@end table 2550104862Sru 2551104862SruEffective: next footnote. 2552104862Sru 2553104862SruDefault: 0. 2554104862Sru@endDefmpreg 2555104862Sru 2556104862Sru@unnumberedsubsubsec Miscellaneous Number Registers 2557104862Sru 2558104862Sru@Defmpreg {MINGW, ms} 2559104862SruDefines the minimum width between columns in a multi-column document. 2560104862Sru 2561104862SruEffective: next page. 2562104862Sru 2563104862SruDefault: 2@dmn{n}. 2564104862Sru@endDefmpreg 2565104862Sru 2566104862Sru@c --------------------------------------------------------------------- 2567104862Sru 2568104862Sru@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms 2569104862Sru@subsection Cover page macros 2570104862Sru@cindex @code{ms} macros, cover page 2571104862Sru@cindex cover page macros, [@code{ms}] 2572104862Sru 2573104862SruUse the following macros to create a cover page for your document 2574104862Sruin the order shown. 2575104862Sru 2576104862Sru@Defmac {RP, [@code{no}], ms} 2577104862SruSpecifies the report format for your document. 2578104862SruThe report format creates a separate cover page. 2579104862SruThe default action (no @code{.RP} 2580104862Srumacro) is to print a subset of the 2581104862Srucover page on page 1 of your document. 2582104862Sru 2583104862SruIf you use the word @code{no} as an optional argument, 2584104862Sru@code{groff} prints a title page but 2585104862Srudoes not repeat any of the title page information 2586104862Sru(title, author, abstract, etc.) 2587104862Sruon page 1 of the document. 2588104862Sru@endDefmac 2589104862Sru 2590104862Sru@Defmac {DA, [@dots{}], ms} 2591104862Sru(optional) Print the current date, or the arguments to the macro if any, 2592104862Sruon the title page (if specified) and in the footers. 2593104862SruThis is the default for @code{nroff}. 2594104862Sru@endDefmac 2595104862Sru 2596104862Sru@Defmac {ND, [@dots{}], ms} 2597104862Sru(optional) Print the current date, or the arguments to the macro if any, 2598104862Sruon the title page (if specified) but not in the footers. 2599104862SruThis is the default for @code{troff}. 2600104862Sru@endDefmac 2601104862Sru 2602104862Sru@Defmac {TL, , ms} 2603104862SruSpecifies the document title. 2604104862Sru@code{groff} collects text following the @code{.TL} 2605104862Srumacro into the title, until reaching the author name or abstract. 2606104862Sru@endDefmac 2607104862Sru 2608104862Sru@Defmac {AU, , ms} 2609104862SruSpecifies the author's name, which appears on the 2610104862Sruline (or lines) immediately following. 2611104862SruYou can specify multiple authors as follows: 2612104862Sru 2613104862Sru@Example 2614104862Sru.AU 2615104862SruJohn Doe 2616104862Sru.AI 2617104862SruUniversity of West Bumblefuzz 2618104862Sru.AU 2619104862SruMartha Buck 2620104862Sru.AI 2621104862SruMonolithic Corporation 2622104862Sru 2623104862Sru... 2624104862Sru@endExample 2625104862Sru@endDefmac 2626104862Sru 2627104862Sru@Defmac {AI, , ms} 2628104862SruSpecifies the author's institution. 2629104862SruYou can specify multiple institutions in the same way 2630104862Sruthat you specify multiple authors. 2631104862Sru@endDefmac 2632104862Sru 2633104862Sru@Defmac {AB, [@code{no}], ms} 2634104862SruBegins the abstract. 2635104862SruThe default is to print the word @acronym{ABSTRACT}, 2636104862Srucentered and in italics, above the text of the abstract. 2637104862SruThe word @code{no} as an optional argument suppresses this heading. 2638104862Sru@endDefmac 2639104862Sru 2640104862Sru@Defmac {AE, , ms} 2641104862SruEnd the abstract. 2642104862Sru@endDefmac 2643104862Sru 2644104862SruThe following is example mark-up for a title page. 2645104862Sru@cindex title page, example markup 2646104862Sru@cindex example markup, title page 2647104862Sru 2648104862Sru@Example 2649104862Sru@cartouche 2650104862Sru.RP 2651104862Sru.TL 2652104862SruThe Inevitability of Code Bloat 2653104862Sruin Commercial and Free Software 2654104862Sru.AU 2655104862SruJ. Random Luser 2656104862Sru.AI 2657104862SruUniversity of West Bumblefuzz 2658104862Sru.AB 2659104862SruThis report examines the long-term growth 2660104862Sruof the code bases in two large, popular software 2661104862Srupackages; the free Emacs and the commercial 2662104862SruMicrosoft Word. 2663104862SruWhile differences appear in the type or order 2664104862Sruof features added, due to the different 2665104862Srumethodologies used, the results are the same 2666104862Sruin the end. 2667104862Sru.PP 2668104862SruThe free software approach is shown to be 2669104862Srusuperior in that while free software can 2670104862Srubecome as bloated as commercial offerings, 2671104862Srufree software tends to have fewer serious 2672104862Srubugs and the added features are in line with 2673104862Sruuser demand. 2674104862Sru.AE 2675104862Sru 2676104862Sru... the rest of the paper follows ... 2677104862Sru@end cartouche 2678104862Sru@endExample 2679104862Sru 2680104862Sru@c --------------------------------------------------------------------- 2681104862Sru 2682104862Sru@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms 2683104862Sru@subsection Body text 2684104862Sru@cindex @code{ms} macros, body text 2685104862Sru 2686104862SruThis section describes macros used to mark up the body of your document. 2687104862SruExamples include paragraphs, sections, and other groups. 2688104862Sru 2689104862Sru@menu 2690104862Sru* Paragraphs in ms:: 2691104862Sru* Headings in ms:: 2692104862Sru* Highlighting in ms:: 2693104862Sru* Lists in ms:: 2694104862Sru* Indents in ms:: 2695104862Sru* Tabstops in ms:: 2696104862Sru* ms Displays and Keeps:: 2697104862Sru* ms Insertions:: 2698104862Sru* Example multi-page table:: 2699104862Sru* ms Footnotes:: 2700104862Sru@end menu 2701104862Sru 2702104862Sru@c --------------------------------------------------------------------- 2703104862Sru 2704104862Sru@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text 2705104862Sru@subsubsection Paragraphs 2706104862Sru@cindex @code{ms} macros, paragraph handling 2707104862Sru 2708104862SruThe following paragraph types are available. 2709104862Sru 2710104862Sru@Defmac {PP, , ms} 2711104862SruSets a paragraph with an initial indent. 2712104862Sru@endDefmac 2713104862Sru 2714104862Sru@Defmac {LP, , ms} 2715104862SruSets a paragraph with no initial indent. 2716104862Sru@endDefmac 2717104862Sru 2718104862Sru@Defmac {QP, , ms} 2719104862SruSets a paragraph that is indented at both left and right margins. 2720104862SruThe effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element. 2721104862SruThe next paragraph or heading returns margins to normal. 2722104862Sru@endDefmac 2723104862Sru 2724104862Sru@Defmac {XP, , ms} 2725104862SruSets a paragraph whose lines are indented, 2726104862Sruexcept for the first line. 2727104862SruThis is a Berkeley extension. 2728104862Sru@endDefmac 2729104862Sru 2730104862SruThe following markup uses all four paragraph macros. 2731104862Sru 2732104862Sru@Example 2733104862Sru@cartouche 2734104862Sru.NH 2 2735104862SruCases used in the study 2736104862Sru.LP 2737104862SruThe following software and versions were 2738104862Sruconsidered for this report. 2739104862Sru.PP 2740104862SruFor commercial software, we chose 2741104862Sru.B "Microsoft Word for Windows" , 2742104862Srustarting with version 1.0 through the 2743104862Srucurrent version (Word 2000). 2744104862Sru.PP 2745104862SruFor free software, we chose 2746104862Sru.B Emacs , 2747104862Srufrom its first appearance as a standalone 2748104862Srueditor through the current version (v20). 2749104862SruSee [Bloggs 2002] for details. 2750104862Sru.QP 2751104862SruFranklin's Law applied to software: 2752104862Srusoftware expands to outgrow both 2753104862SruRAM and disk space over time. 2754104862Sru.LP 2755104862SruBibliography: 2756104862Sru.XP 2757104862SruBloggs, Joseph R., 2758104862Sru.I "Everyone's a Critic" , 2759104862SruUnderground Press, March 2002. 2760104862SruA definitive work that answers all questions 2761104862Sruand criticisms about the quality and usability of 2762104862Srufree software. 2763104862Sru 2764104862Sru@end cartouche 2765104862Sru@endExample 2766104862Sru 2767104862Sru@c --------------------------------------------------------------------- 2768104862Sru 2769104862Sru@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text 2770104862Sru@subsubsection Headings 2771104862Sru@cindex @code{ms} macros, headings 2772104862Sru 2773104862SruUse headings to create a hierarchical structure for your document. 2774104862SruThe @file{ms} macros print headings in @strong{bold}, 2775104862Sruusing the same font family and point size as the body text. 2776104862Sru 2777104862SruThe following describes the heading macros: 2778104862Sru 2779104862Sru@DefmacList {NH, @Var{curr-level}, ms} 2780104862Sru@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} 2781104862SruNumbered heading. 2782104862SruThe argument is either a numeric argument to indicate the 2783104862Srulevel of the heading, or the letter@w{ }@code{S} followed by numeric 2784104862Sruarguments to set the heading level explicitly. 2785104862Sru 2786104862SruIf you specify heading levels out of sequence, such as invoking 2787104862Sru@samp{.NH 3} after @samp{.NH 1}, @code{groff} 2788104862Sruprints a warning on standard error. 2789104862Sru@endDefmac 2790104862Sru 2791104862Sru@Defmac {SH, , ms} 2792104862SruUnnumbered subheading. 2793104862Sru@endDefmac 2794104862Sru 2795104862Sru@c --------------------------------------------------------------------- 2796104862Sru 2797104862Sru@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text 2798104862Sru@subsubsection Highlighting 2799104862Sru@cindex @code{ms} macros, highlighting 2800104862Sru 2801104862SruThe @file{ms} macros provide a variety of methods to highlight 2802104862Sruor emphasize text: 2803104862Sru 2804104862Sru@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2805104862SruSets its first argument in @strong{bold type}. 2806104862SruIf you specify a second argument, @code{groff} prints it in the 2807104862Sruprevious font after the bold text, with no intervening space 2808104862Sru(this allows you to set punctuation after the highlighted text 2809104862Sruwithout highlighting the punctuation). 2810104862SruSimilarly, it prints the third argument (if any) in the previous 2811104862Srufont @strong{before} the first argument. 2812104862SruFor example, 2813104862Sru 2814104862Sru@Example 2815104862Sru.B foo ) ( 2816104862Sru@endExample 2817104862Sru 2818104862Sruprints (@strong{foo}). 2819104862Sru 2820104862SruIf you give this macro no arguments, @code{groff} 2821104862Sruprints all text following in bold until 2822104862Sruthe next highlighting, paragraph, or heading macro. 2823104862Sru@endDefmac 2824104862Sru 2825104862Sru@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2826104862SruSets its first argument in roman (or regular) type. 2827104862SruIt operates similarly to the @code{B}@w{ }macro otherwise. 2828104862Sru@endDefmac 2829104862Sru 2830104862Sru@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2831104862SruSets its first argument in @emph{italic type}. 2832104862SruIt operates similarly to the @code{B}@w{ }macro otherwise. 2833104862Sru@endDefmac 2834104862Sru 2835104862Sru@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2836104862SruSets its first argument in a @code{constant width face}. 2837104862SruIt operates similarly to the @code{B}@w{ }macro otherwise. 2838104862Sru@endDefmac 2839104862Sru 2840104862Sru@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2841104862SruSets its first argument in bold italic type. 2842104862SruIt operates similarly to the @code{B}@w{ }macro otherwise. 2843104862Sru@endDefmac 2844104862Sru 2845104862Sru@Defmac {BX, [@Var{txt}], ms} 2846104862SruPrints its argument and draws a box around it. 2847104862SruIf you want to box a string that contains spaces, 2848104862Sruuse a digit-width space (@code{\0}). 2849104862Sru@endDefmac 2850104862Sru 2851104862Sru@Defmac {UL, [@Var{txt} [@Var{post}]], ms} 2852104862SruPrints its first argument with an underline. 2853104862SruIf you specify a second argument, @code{groff} 2854104862Sruprints it in the previous font after 2855104862Sruthe underlined text, with no intervening space. 2856104862Sru@endDefmac 2857104862Sru 2858104862Sru@Defmac {LG, , ms} 2859104862SruPrints all text following in larger type 2860104862Sru(two points larger than the current point size) until 2861104862Sruthe next font size, highlighting, paragraph, or heading macro. 2862104862SruYou can specify this macro multiple times 2863104862Sruto enlarge the point size as needed. 2864104862Sru@endDefmac 2865104862Sru 2866104862Sru@Defmac {SM, , ms} 2867104862SruPrints all text following in smaller type 2868104862Sru(two points smaller than the current point size) until 2869104862Sruthe next type size, highlighting, paragraph, or heading macro. 2870104862SruYou can specify this macro multiple times 2871104862Sruto reduce the point size as needed. 2872104862Sru@endDefmac 2873104862Sru 2874104862Sru@Defmac {NL, , ms} 2875104862SruPrints all text following in the normal point size 2876104862Sru(that is, the value of the @code{PS} register). 2877104862Sru@endDefmac 2878104862Sru 2879104862Sru@c --------------------------------------------------------------------- 2880104862Sru 2881104862Sru@node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text 2882104862Sru@subsubsection Lists 2883104862Sru@cindex @code{ms} macros, lists 2884104862Sru 2885104862SruThe @code{.IP} macro handles duties for all lists. 2886104862Sru 2887104862Sru@Defmac {IP, [@Var{marker} [@Var{width}]], ms} 2888104862SruThe @var{marker} is usually a bullet glyph (@code{\[bu]}) 2889104862Srufor unordered lists, a number (or auto-incrementing number 2890104862Sruregister) for numbered lists, or a word or phrase for indented 2891104862Sru(glossary-style) lists. 2892104862Sru 2893104862SruThe @var{width} specifies the indent for the body of each list item; 2894104862Sruits default unit is @samp{n}. 2895104862SruOnce specified, the indent remains the same for all 2896104862Srulist items in the document until specified again. 2897104862Sru@endDefmac 2898104862Sru 2899104862SruThe following is an example of a bulleted list. 2900104862Sru@cindex example markup, bulleted list [@code{ms}] 2901104862Sru@cindex bulleted list, example markup [@code{ms}] 2902104862Sru 2903104862Sru@Example 2904104862SruA bulleted list: 2905104862Sru.IP \[bu] 2 2906104862Srulawyers 2907104862Sru.IP \[bu] 2908104862Sruguns 2909104862Sru.IP \[bu] 2910104862Srumoney 2911104862Sru@endExample 2912104862Sru 2913104862SruProduces: 2914104862Sru 2915104862Sru@Example 2916104862SruA bulleted list: 2917104862Sru 2918104862Sruo lawyers 2919104862Sru 2920104862Sruo guns 2921104862Sru 2922104862Sruo money 2923104862Sru@endExample 2924104862Sru 2925104862Sru@sp 1 2926104862Sru 2927104862SruThe following is an example of a numbered list. 2928104862Sru@cindex example markup, numbered list [@code{ms}] 2929104862Sru@cindex numbered list, example markup [@code{ms}] 2930104862Sru 2931104862Sru@Example 2932104862Sru.nr step 1 1 2933104862SruA numbered list: 2934104862Sru.IP \n[step] 3 2935104862Srulawyers 2936104862Sru.IP \n+[step] 2937104862Sruguns 2938104862Sru.IP \n+[step] 2939104862Srumoney 2940104862Sru@endExample 2941104862Sru 2942104862SruProduces: 2943104862Sru 2944104862Sru@Example 2945104862SruA numbered list: 2946104862Sru 2947104862Sru1. lawyers 2948104862Sru 2949104862Sru2. guns 2950104862Sru 2951104862Sru3. money 2952104862Sru@endExample 2953104862Sru 2954104862SruNote the use of the auto-incrementing number 2955104862Sruregister in this example. 2956104862Sru 2957104862Sru@sp 1 2958104862SruThe following is an example of a glossary-style list. 2959104862Sru@cindex example markup, glossary-style list [@code{ms}] 2960104862Sru@cindex glossary-style list, example markup [@code{ms}] 2961104862Sru 2962104862Sru@Example 2963104862SruA glossary-style list: 2964104862Sru.IP lawyers 0.4i 2965104862SruTwo or more attorneys. 2966104862Sru.IP guns 2967104862SruFirearms, preferably 2968104862Srularge-caliber. 2969104862Sru.IP money 2970104862SruGotta pay for those 2971104862Srulawyers and guns! 2972104862Sru@endExample 2973104862Sru 2974104862SruProduces: 2975104862Sru 2976104862Sru@Example 2977104862SruA glossary-style list: 2978104862Sru 2979104862Srulawyers 2980104862Sru Two or more attorneys. 2981104862Sru 2982104862Sruguns Firearms, preferably large-caliber. 2983104862Sru 2984104862Srumoney 2985104862Sru Gotta pay for those lawyers and guns! 2986104862Sru@endExample 2987104862Sru 2988104862SruIn the last example, the @code{IP} macro places the definition 2989104862Sruon the same line as the term if it has enough space; otherwise, 2990104862Sruit breaks to the next line and starts the definition below the 2991104862Sruterm. 2992104862SruThis may or may not be the effect you want, especially if some 2993104862Sruof the definitions break and some do not. 2994104862SruThe following examples show two possible ways to force a break. 2995104862Sru 2996104862SruThe first workaround uses the @code{br} 2997104862Srurequest to force a break after printing the term or label. 2998104862Sru 2999104862Sru@Example 3000104862Sru@cartouche 3001104862SruA glossary-style list: 3002104862Sru.IP lawyers 0.4i 3003104862SruTwo or more attorneys. 3004104862Sru.IP guns 3005104862Sru.br 3006104862SruFirearms, preferably large-caliber. 3007104862Sru.IP money 3008104862SruGotta pay for those lawyers and guns! 3009104862Sru@end cartouche 3010104862Sru@endExample 3011104862Sru 3012104862Sru@sp 1 3013104862SruThe second workaround uses the @code{\p} escape to force the break. 3014104862SruNote the space following the escape; this is important. 3015104862SruIf you omit the space, @code{groff} prints the first word on 3016104862Sruthe same line as the term or label (if it fits) @strong{then} 3017104862Srubreaks the line. 3018104862Sru 3019104862Sru@Example 3020104862Sru@cartouche 3021104862SruA glossary-style list: 3022104862Sru.IP lawyers 0.4i 3023104862SruTwo or more attorneys. 3024104862Sru.IP guns 3025104862Sru\p Firearms, preferably large-caliber. 3026104862Sru.IP money 3027104862SruGotta pay for those lawyers and guns! 3028104862Sru@end cartouche 3029104862Sru@endExample 3030104862Sru 3031104862Sru@sp 1 3032104862SruTo set nested lists, use the @code{RS} and @code{RE} macros. 3033104862Sru@xref{Indents in ms}, for more information. 3034104862Sru@cindex @code{ms} macros, nested lists 3035104862Sru@cindex nested lists [@code{ms}] 3036104862Sru 3037104862SruFor example: 3038104862Sru 3039104862Sru@Example 3040104862Sru@cartouche 3041104862Sru.IP \[bu] 2 3042104862SruLawyers: 3043104862Sru.RS 3044104862Sru.IP \[bu] 3045104862SruDewey, 3046104862Sru.IP \[bu] 3047104862SruCheatham, 3048104862Sru.IP \[bu] 3049104862Sruand Howe. 3050104862Sru.RE 3051104862Sru.IP \[bu] 3052104862SruGuns 3053104862Sru@end cartouche 3054104862Sru@endExample 3055104862Sru 3056104862SruProduces: 3057104862Sru 3058104862Sru@Example 3059104862Sruo Lawyers: 3060104862Sru 3061104862Sru o Dewey, 3062104862Sru 3063104862Sru o Cheatham, 3064104862Sru 3065104862Sru o and Howe. 3066104862Sru 3067104862Sruo Guns 3068104862Sru@endExample 3069104862Sru 3070104862Sru@c --------------------------------------------------------------------- 3071104862Sru 3072104862Sru@node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text 3073104862Sru@subsubsection Indents 3074104862Sru 3075104862SruIn many situations, 3076104862Sruyou may need to indent a section of text 3077104862Sruwhile still wrapping and filling. 3078104862Sru@xref{Lists in ms}, 3079104862Srufor an example of nested lists. 3080104862Sru 3081104862Sru@DefmacList {RS, , ms} 3082104862Sru@DefmacListEnd {RE, , ms} 3083104862SruThese macros begin and end an indented section. 3084104862SruThe @code{PI} register controls the amount of indent, 3085104862Sruallowing the indented text to line up under hanging 3086104862Sruand indented paragraphs. 3087104862Sru@endDefmac 3088104862Sru 3089104862Sru@xref{ms Displays and Keeps}, 3090104862Srufor macros to indent and turn off filling. 3091104862Sru 3092104862Sru@c --------------------------------------------------------------------- 3093104862Sru 3094104862Sru@node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text 3095104862Sru@subsubsection Tab Stops 3096104862Sru 3097104862SruUse the @code{ta} request to define tab stops as needed. 3098104862Sru@xref{Tabs and Fields}. 3099104862Sru 3100104862Sru@Defmac{TA, , ms} 3101104862SruUse this macro to reset the tab stops to the default for @file{ms} 3102104862Sru(every 5n). 3103104862SruYou can redefine the @code{TA} macro to create a different set 3104104862Sruof default tab stops. 3105104862Sru@endDefmac 3106104862Sru 3107104862Sru@c --------------------------------------------------------------------- 3108104862Sru 3109104862Sru@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text 3110104862Sru@subsubsection Displays and keeps 3111104862Sru@cindex @code{ms} macros, displays 3112104862Sru@cindex @code{ms} macros, keeps 3113104862Sru@cindex keeps [@code{ms}] 3114104862Sru@cindex displays [@code{ms}] 3115104862Sru 3116104862SruUse displays to show text-based examples or figures 3117104862Sru(such as code listings). 3118104862Sru 3119104862SruDisplays turn off filling, so lines of code are displayed 3120104862Sruas-is without inserting @code{br} requests in between each line. 3121104862SruDisplays can be @dfn{kept} on a single page, or allowed 3122104862Sruto break across pages. 3123104862Sru 3124104862Sru@DefmacList {DS, @t{L}, ms} 3125104862Sru@DefmacItem {LD, , ms} 3126104862Sru@DefmacListEnd {DE, , ms} 3127104862SruLeft-justified display. 3128104862SruThe @samp{.DS L} call generates a page break, if necessary, 3129104862Sruto keep the entire display on one page. 3130104862SruThe @code{LD} macro allows the display to break across pages. 3131104862SruThe @code{DE} macro ends the display. 3132104862Sru@endDefmac 3133104862Sru 3134104862Sru@DefmacList {DS, @t{I}, ms} 3135104862Sru@DefmacItem {ID, , ms} 3136104862Sru@DefmacListEnd {DE, , ms} 3137104862SruIndents the display as defined by the @code{DI} register. 3138104862SruThe @samp{.DS I} call generates a page break, if necessary, 3139104862Sruto keep the entire display on one page. 3140104862SruThe @code{ID} macro allows the display to break across pages. 3141104862SruThe @code{DE} macro ends the display. 3142104862Sru@endDefmac 3143104862Sru 3144104862Sru@DefmacList {DS, @t{B}, ms} 3145104862Sru@DefmacItem {BD, , ms} 3146104862Sru@DefmacListEnd {DE, , ms} 3147104862SruSets a block-centered display: the entire display is left-justified, 3148104862Srubut indented so that the longest line in the display is centered 3149104862Sruon the page. 3150104862SruThe @samp{.DS B} call generates a page break, if necessary, 3151104862Sruto keep the entire display on one page. 3152104862SruThe @code{BD} macro allows the display to break across pages. 3153104862SruThe @code{DE} macro ends the display. 3154104862Sru@endDefmac 3155104862Sru 3156104862Sru@DefmacList {DS, @t{C}, ms} 3157104862Sru@DefmacItem {CD, , ms} 3158104862Sru@DefmacListEnd {DE, , ms} 3159104862SruSets a centered display: each line in the display is centered. 3160104862SruThe @samp{.DS C} call generates a page break, if necessary, 3161104862Sruto keep the entire display on one page. 3162104862SruThe @code{CD} macro allows the display to break across pages. 3163104862SruThe @code{DE} macro ends the display. 3164104862Sru@endDefmac 3165104862Sru 3166104862Sru@DefmacList {DS, @t{R}, ms} 3167104862Sru@DefmacItem {RD, , ms} 3168104862Sru@DefmacListEnd {DE, , ms} 3169104862SruRight-justifies each line in the display. 3170104862SruThe @samp{.DS R} call generates a page break, if necessary, 3171104862Sruto keep the entire display on one page. 3172104862SruThe @code{RD} macro allows the display to break across pages. 3173104862SruThe @code{DE} macro ends the display. 3174104862Sru@endDefmac 3175104862Sru 3176104862Sru@sp 1 3177104862SruOn occasion, you may want to @dfn{keep} other text together on a page. 3178104862SruFor example, you may want to keep two paragraphs together, or 3179104862Srua paragraph that refers to a table (or list, or other item) 3180104862Sruimmediately following. 3181104862SruThe @file{ms} macros provide the @code{KS} and @code{KE} 3182104862Srumacros for this purpose. 3183104862Sru 3184104862Sru@DefmacList {KS, , ms} 3185104862Sru@DefmacListEnd {KE, , ms} 3186104862SruThe @code{KS} macro begins a block of text to be kept on a 3187104862Srusingle page, and the @code{KE} macro ends the block. 3188104862Sru@endDefmac 3189104862Sru 3190104862Sru@DefmacList {KF, , ms} 3191104862Sru@DefmacListEnd {KE, , ms} 3192104862SruSpecifies a @dfn{floating keep}; 3193104862Sruif the keep cannot fit on the current page, @code{groff} 3194104862Sruholds the contents of the keep and allows text following 3195104862Sruthe keep (in the source file) to fill in the remainder of 3196104862Sruthe current page. 3197104862SruWhen the page breaks, whether by an explicit @code{bp} 3198104862Srurequest or by reaching the end of the page, @code{groff} 3199104862Sruprints the floating keep at the top of the new page. 3200104862SruThis is useful for printing large graphics or tables 3201104862Sruthat do not need to appear exactly where specified. 3202104862Sru@endDefmac 3203104862Sru 3204104862SruYou can also use the @code{ne} request to force a page break if 3205104862Sruthere is not enough vertical space remaining on the page. 3206104862Sru 3207104862Sru@sp 1 3208104862SruUse the following macros to draw a box around a section of 3209104862Srutext (such as a display). 3210104862Sru 3211104862Sru@DefmacList {B1, , ms} 3212104862Sru@DefmacListEnd {B2, , ms} 3213104862SruMarks the beginning and ending of text that is to have a 3214104862Srubox drawn around it. 3215104862SruThe @code{B1} macro begins the box; the @code{B2} macro ends it. 3216104862SruText in the box is automatically placed in a diversion (keep). 3217104862Sru@endDefmac 3218104862Sru 3219104862Sru@c --------------------------------------------------------------------- 3220104862Sru 3221104862Sru@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text 3222104862Sru@subsubsection Tables, figures, equations, and references 3223104862Sru@cindex @code{ms} macros, tables 3224104862Sru@cindex @code{ms} macros, figures 3225104862Sru@cindex @code{ms} macros, equations 3226104862Sru@cindex @code{ms} macros, references 3227104862Sru@cindex tables [@code{ms}] 3228104862Sru@cindex figures [@code{ms}] 3229104862Sru@cindex equations [@code{ms}] 3230104862Sru@cindex references [@code{ms}] 3231104862Sru 3232104862SruThe @file{ms} macros support the standard 3233104862Sru@code{groff} preprocessors: 3234104862Sru@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. 3235104862Sru@pindex tbl 3236104862Sru@pindex pic 3237104862Sru@pindex eqn 3238104862Sru@pindex refer 3239104862SruYou mark text meant for preprocessors by enclosing it 3240104862Sruin pairs of tags as follows. 3241104862Sru 3242104862Sru@DefmacList {TS, [@code{H}], ms} 3243104862Sru@DefmacListEnd {TE, , ms} 3244104862SruDenotes a table, to be processed by the @code{tbl} preprocessor. 3245104862SruThe optional argument@w{ }@code{H} to @code{TS} instructs @code{groff} 3246104862Sruto create a running header with the information 3247104862Sruup to the @code{TH} macro. 3248104862Sru@code{groff} prints the header at the beginning of the 3249104862Srutable; if the table runs onto another page, @code{groff} 3250104862Sruprints the header on the next page as well. 3251104862Sru@endDefmac 3252104862Sru 3253104862Sru@DefmacList {PS, , ms} 3254104862Sru@DefmacListEnd {PE, , ms} 3255104862SruDenotes a graphic, to be processed by the @code{pic} preprocessor. 3256104862SruYou can create a @code{pic} file by hand, using the @acronym{AT&T} 3257104862Sru@code{pic} manual available on the Web as a reference, or by using 3258104862Srua graphics program such as @code{xfig}. 3259104862Sru@endDefmac 3260104862Sru 3261104862Sru@DefmacList {EQ, [@Var{align}], ms} 3262104862Sru@DefmacListEnd {EN, , ms} 3263104862SruDenotes an equation, to be processed by the @code{eqn} preprocessor. 3264104862SruThe optional @var{align} argument can be @code{C}, @code{L}, or@w{ 3265104862Sru}@code{I} to center (the default), left-justify, or indent the equation. 3266104862Sru@endDefmac 3267104862Sru 3268104862Sru@DefmacList {[, , ms} 3269104862Sru@DefmacListEnd {], , ms} 3270104862SruDenotes a reference, to be processed by the @code{refer} preprocessor. 3271104862SruThe @acronym{GNU} @cite{refer(1)} man page provides a comprehensive 3272104862Srureference to the preprocessor and the format of the bibliographic 3273104862Srudatabase. 3274104862Sru@endDefmac 3275104862Sru 3276104862Sru@menu 3277104862Sru* Example multi-page table:: 3278104862Sru@end menu 3279104862Sru 3280104862Sru@c --------------------------------------------------------------------- 3281104862Sru 3282104862Sru@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text 3283104862Sru@subsubsection An example multi-page table 3284104862Sru@cindex example markup, multi-page table [@code{ms}] 3285104862Sru@cindex multi-page table, example markup [@code{ms}] 3286104862Sru 3287104862SruThe following is an example of how to set up a 3288104862Srutable that may print across two or more pages. 3289104862Sru 3290104862Sru@Example 3291104862Sru@cartouche 3292104862Sru.TS H 3293104862Sruallbox expand; 3294104862Srucb | cb . 3295104862SruText ...of heading... 3296104862Sru_ 3297104862Sru.TH 3298104862Sru.T& 3299104862Srul | l . 3300104862Sru... the rest of the table follows... 3301104862Sru.CW 3302104862Sru.TE 3303104862Sru@end cartouche 3304104862Sru@endExample 3305104862Sru 3306104862Sru@c --------------------------------------------------------------------- 3307104862Sru 3308104862Sru@node ms Footnotes, , Example multi-page table, ms Body Text 3309104862Sru@subsubsection Footnotes 3310104862Sru@cindex @code{ms} macros, footnotes 3311104862Sru@cindex footnotes [@code{ms}] 3312104862Sru 3313104862SruThe @file{ms} macro package has a flexible footnote system. 3314104862SruYou can specify either numbered footnotes or symbolic footnotes 3315104862Sru(that is, using a marker such as a dagger symbol). 3316104862Sru 3317104862Sru@Defstr {*, ms} 3318104862SruSpecifies the location of a numbered footnote marker in the text. 3319104862Sru@endDefesc 3320104862Sru 3321104862Sru@DefmacList {FS, , ms} 3322104862Sru@DefmacListEnd {FE, , ms} 3323104862SruSpecifies the text of the footnote. 3324104862SruThe default action is to create a numbered footnote; 3325104862Sruyou can create a symbolic footnote by specifying 3326104862Srua @dfn{mark} glyph 3327104862Sru(such as @code{\[dg]} for the dagger glyph) 3328104862Sruin the body text and as an argument to the @code{FS} macro, 3329104862Srufollowed by the text of the footnote 3330104862Sruand the @code{FE} macro. 3331104862Sru@endDefmac 3332104862Sru 3333104862SruYou can control how @code{groff} 3334104862Sruprints footnote numbers by changing the value of the 3335104862Sru@code{FF} register. @xref{ms Document Control Registers}. 3336104862Sru 3337104862Sru@c --------------------------------------------------------------------- 3338104862Sru 3339104862Sru@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms 3340104862Sru@subsection Page layout 3341104862Sru@cindex @code{ms} macros, page layout 3342104862Sru@cindex page layout [@code{ms}] 3343104862Sru 3344104862SruThe default output from the @file{ms} 3345104862Srumacros provides a minimalist page layout: 3346104862Sruit prints a single column, with the page number centered at the top 3347104862Sruof each page. 3348104862SruIt prints no footers. 3349104862Sru 3350104862SruYou can change the layout by setting 3351104862Sruthe proper number registers and strings. 3352104862Sru 3353104862Sru@menu 3354104862Sru* ms Headers and Footers:: 3355104862Sru* ms Margins:: 3356104862Sru* ms Multiple Columns:: 3357104862Sru* ms TOC:: 3358104862Sru* ms Strings and Special Characters:: 3359104862Sru@end menu 3360104862Sru 3361104862Sru@c --------------------------------------------------------------------- 3362104862Sru 3363104862Sru@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout 3364104862Sru@subsubsection Headers and footers 3365104862Sru@cindex @code{ms} macros, headers 3366104862Sru@cindex @code{ms} macros, footers 3367104862Sru@cindex headers [@code{ms}] 3368104862Sru@cindex footers [@code{ms}] 3369104862Sru 3370104862SruFor documents that do not distinguish between odd and even pages, 3371104862Sruset the following strings: 3372104862Sru 3373104862Sru@DefstrList {LH, ms} 3374104862Sru@DefstrItem {CH, ms} 3375104862Sru@DefstrListEnd {RH, ms} 3376104862SruSets the left, center, and right headers. 3377104862Sru@endDefstr 3378104862Sru 3379104862Sru@DefstrList {LF, ms} 3380104862Sru@DefstrItem {CF, ms} 3381104862Sru@DefstrListEnd {RF, ms} 3382104862SruSets the left, center, and right footers. 3383104862Sru@endDefstr 3384104862Sru 3385104862Sru@sp 1 3386104862SruFor documents that need different information printed in the 3387104862Srueven and odd pages, use the following macros: 3388104862Sru 3389104862Sru@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3390104862Sru@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3391104862Sru@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3392104862Sru@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3393104862SruThe @code{OH} and @code{EH} macros define headers for the odd and even pages; 3394104862Sruthe @code{OF} and @code{EF} macros define footers for the odd and even pages. 3395104862SruThis is more flexible than defining the individual strings. 3396104862Sru 3397104862SruYou can replace the quote (@code{'}) marks with any character not 3398104862Sruappearing in the header or footer text. 3399104862Sru@endDefmac 3400104862Sru 3401104862Sru@c --------------------------------------------------------------------- 3402104862Sru 3403104862Sru@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout 3404104862Sru@subsubsection Margins 3405104862Sru@cindex @code{ms} macros, margins 3406104862Sru 3407104862SruYou control margins using a set of number registers. 3408104862Sru@xref{ms Document Control Registers}, for details. 3409104862Sru 3410104862Sru@c --------------------------------------------------------------------- 3411104862Sru 3412104862Sru@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout 3413104862Sru@subsubsection Multiple columns 3414104862Sru@cindex @code{ms} macros, multiple columns 3415104862Sru@cindex multiple columns [@code{ms}] 3416104862Sru 3417104862SruThe @file{ms} macros can set text in as many columns as will 3418104862Srureasonably fit on the page. 3419104862SruThe following macros are available; 3420104862Sruall of them force a page break if a multi-column mode is already set. 3421104862SruHowever, if the current mode is single-column, starting a multi-column 3422104862Srumode does @strong{not} force a page break. 3423104862Sru 3424104862Sru@Defmac {1C, , ms} 3425104862SruSingle-column mode. 3426104862Sru@endDefmac 3427104862Sru 3428104862Sru@Defmac {2C, , ms} 3429104862SruTwo-column mode. 3430104862Sru@endDefmac 3431104862Sru 3432104862Sru@Defmac {MC, [@Var{width} [@Var{gutter}]], ms} 3433104862SruMulti-column mode. 3434104862SruIf you specify no arguments, it is equivalent to the 3435104862Sru@code{2C} macro. 3436104862SruOtherwise, @var{width} is the width of each column and 3437104862Sru@var{gutter} is the space between columns. 3438104862SruThe @code{MINGW} number register controls the default gutter width. 3439104862Sru@endDefmac 3440104862Sru 3441104862Sru@c --------------------------------------------------------------------- 3442104862Sru 3443104862Sru@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout 3444104862Sru@subsubsection Creating a table of contents 3445104862Sru@cindex @code{ms} macros, creating table of contents 3446104862Sru@cindex table of contents, creating [@code{ms}] 3447104862Sru 3448104862SruThe facilities in the @file{ms} macro package for creating 3449104862Srua table of contents are semi-automated at best. 3450104862SruAssuming that you want the table of contents to consist of 3451104862Sruthe document's headings, you need to repeat those headings 3452104862Sruwrapped in @code{XS} and @code{XE} macros. 3453104862Sru 3454104862Sru@DefmacList {XS, [@Var{page}], ms} 3455104862Sru@DefmacItem {XA, [@Var{page}], ms} 3456104862Sru@DefmacListEnd {XE, , ms} 3457104862SruThese macros define a table of contents 3458104862Sruor an individual entry in the table of contents, 3459104862Srudepending on their use. 3460104862SruThe macros are very simple; they cannot indent a heading based on its level. 3461104862SruThe easiest way to work around this is to add tabs 3462104862Sruto the table of contents string. 3463104862SruThe following is an example: 3464104862Sru 3465104862Sru@Example 3466104862Sru@cartouche 3467104862Sru.NH 1 3468104862SruIntroduction 3469104862Sru.XS 3470104862SruIntroduction 3471104862Sru.XE 3472104862Sru.LP 3473104862Sru... 3474104862Sru.CW 3475104862Sru.NH 2 3476104862SruMethodology 3477104862Sru.XS 3478104862Sru Methodology 3479104862Sru.XE 3480104862Sru.LP 3481104862Sru... 3482104862Sru@end cartouche 3483104862Sru@endExample 3484104862Sru 3485104862SruYou can manually create a table of contents 3486104862Sruby beginning with the @code{XS} macro for the first entry, 3487104862Sruspecifying the page number for that entry as the argument to @code{XS}. 3488104862SruAdd subsequent entries using the @code{XA} macro, 3489104862Sruspecifying the page number for that entry as the argument to @code{XA}. 3490104862SruThe following is an example: 3491104862Sru 3492104862Sru@Example 3493104862Sru@cartouche 3494104862Sru.XS 1 3495104862SruIntroduction 3496104862Sru.XA 2 3497104862SruA Brief History of the Universe 3498104862Sru.XA 729 3499104862SruDetails of Galactic Formation 3500104862Sru... 3501104862Sru.XE 3502104862Sru@end cartouche 3503104862Sru@endExample 3504104862Sru@endDefmac 3505104862Sru 3506104862Sru@Defmac {TC, [@code{no}], ms} 3507104862SruPrints the table of contents on a new page, 3508104862Srusetting the page number to@w{ }@strong{i} (Roman numeral one). 3509104862SruYou should usually place this macro at the end of the 3510104862Srufile, since @code{groff} is a single-pass formatter and 3511104862Srucan only print what has been collected up to the point 3512104862Sruthat the @code{TC} macro appears. 3513104862Sru 3514104862SruThe optional argument @code{no} suppresses printing 3515104862Sruthe title specified by the string register @code{TOC}. 3516104862Sru@endDefmac 3517104862Sru 3518104862Sru@Defmac{PX, [@code{no}], ms} 3519104862SruPrints the table of contents on a new page, 3520104862Sruusing the current page numbering sequence. 3521104862SruUse this macro to print a manually-generated table of contents 3522104862Sruat the beginning of your document. 3523104862Sru 3524104862SruThe optional argument @code{no} suppresses printing 3525104862Sruthe title specified by the string register @code{TOC}. 3526104862Sru@endDefmac 3527104862Sru 3528104862SruThe @cite{Groff and Friends HOWTO} 3529104862Sruincludes a @code{sed} script that automatically inserts 3530104862Sru@code{XS} and @code{XE} macro entries after each heading in a document. 3531104862Sru 3532104862SruAltering the @code{NH} macro to automatically build the table 3533104862Sruof contents is perhaps initially more difficult, but would save 3534104862Srua great deal of time in the long run if you use @file{ms} regularly. 3535104862Sru 3536104862Sru@c --------------------------------------------------------------------- 3537104862Sru 3538104862Sru@node ms Strings and Special Characters, , ms TOC, ms Page Layout 3539104862Sru@subsubsection Strings and Special Characters 3540104862Sru@cindex @code{ms} macros, strings 3541104862Sru@cindex @code{ms} macros, special characters 3542104862Sru@cindex @code{ms} macros, accent marks 3543104862Sru@cindex accent marks [@code{ms}] 3544104862Sru@cindex special characters [@code{ms}] 3545104862Sru@cindex strings [@code{ms}] 3546104862Sru 3547104862SruThe @file{ms} macros provide the following predefined strings. 3548104862SruYou can change the string definitions to help in creating 3549104862Srudocuments in languages other than English. 3550104862Sru 3551104862Sru@Defstr {REFERENCES, ms} 3552104862SruContains the string printed at the beginning of the 3553104862Srureferences (bibliography) page. 3554104862SruThe default is @samp{References}. 3555104862Sru@endDefstr 3556104862Sru 3557104862Sru@Defstr {ABSTRACT, ms} 3558104862SruContains the string printed at the beginning of the abstract. 3559104862SruThe default is @samp{ABSTRACT}. 3560104862Sru@endDefstr 3561104862Sru 3562104862Sru@Defstr {TOC, ms} 3563104862SruContains the string printed at the beginning of the table of contents. 3564104862Sru@endDefstr 3565104862Sru 3566104862Sru@DefstrList {MONTH1, ms} 3567104862Sru@DefstrItem {MONTH2, ms} 3568104862Sru@DefstrItem {MONTH3, ms} 3569104862Sru@DefstrItem {MONTH4, ms} 3570104862Sru@DefstrItem {MONTH5, ms} 3571104862Sru@DefstrItem {MONTH6, ms} 3572104862Sru@DefstrItem {MONTH7, ms} 3573104862Sru@DefstrItem {MONTH8, ms} 3574104862Sru@DefstrItem {MONTH9, ms} 3575104862Sru@DefstrItem {MONTH10, ms} 3576104862Sru@DefstrItem {MONTH11, ms} 3577104862Sru@DefstrListEnd {MONTH12, ms} 3578104862SruPrints the full name of the month in dates. 3579104862SruThe default is @samp{January}, @samp{February}, etc. 3580104862Sru@endDefstr 3581104862Sru 3582104862SruThe following special characters are available@footnote{For an 3583104862Sruexplanation what special characters are see @ref{Special Characters}.}: 3584104862Sru 3585104862Sru@Defstr {-, ms} 3586104862SruPrints an em dash. 3587104862Sru@endDefstr 3588104862Sru 3589104862Sru@DefstrList {*Q, ms} 3590104862Sru@DefstrListEnd {*U, ms} 3591104862SruPrints typographer's quotes in troff, 3592104862Sruplain quotes in nroff. 3593104862Sru@code{*Q} is the left quote and @code{*U} is the right quote. 3594104862Sru@endDefstr 3595104862Sru 3596104862SruImproved accent marks are available in the @file{ms} macros. 3597104862Sru 3598104862Sru@Defmac {AM, , ms} 3599104862SruSpecify this macro at the beginning of your document 3600104862Sruto enable extended accent marks and special characters. 3601104862SruThis is a Berkeley extension. 3602104862Sru 3603104862SruTo use the accent marks, place them @strong{after} 3604104862Sruthe character being accented. 3605104862Sru@endDefmac 3606104862Sru 3607104862SruThe following accent marks are available 3608104862Sruafter invoking the @code{AM} macro: 3609104862Sru 3610104862Sru@Defstr {\', ms} 3611104862SruAcute accent. 3612104862Sru@endDefstr 3613104862Sru 3614104862Sru@Defstr {\`, ms} 3615104862SruGrave accent. 3616104862Sru@endDefstr 3617104862Sru 3618104862Sru@Defstr {^, ms} 3619104862SruCircumflex. 3620104862Sru@endDefstr 3621104862Sru 3622104862Sru@Defstr {\,, ms} 3623104862SruCedilla. 3624104862Sru@endDefstr 3625104862Sru 3626104862Sru@Defstr {~, ms} 3627104862SruTilde. 3628104862Sru@endDefstr 3629104862Sru 3630104862Sru@deffn String @t{\*[:]} 3631104862Sru@ifnotinfo 3632104862Sru@stindex : @r{[}ms@r{]} 3633104862Sru@end ifnotinfo 3634104862Sru@ifinfo 3635104862Sru@stindex @r{<colon>} @r{[}ms@r{]} 3636104862Sru@end ifinfo 3637104862SruUmlaut. 3638104862Sru@end deffn 3639104862Sru 3640104862Sru@Defstr {v, ms} 3641104862SruHacek. 3642104862Sru@endDefstr 3643104862Sru 3644104862Sru@Defstr {_, ms} 3645104862SruMacron (overbar). 3646104862Sru@endDefstr 3647104862Sru 3648104862Sru@Defstr {., ms} 3649104862SruUnderdot. 3650104862Sru@endDefstr 3651104862Sru 3652104862Sru@Defstr {o, ms} 3653104862SruRing above. 3654104862Sru@endDefstr 3655104862Sru 3656104862SruThe following are standalone characters 3657104862Sruavailable after invoking the @code{AM} macro: 3658104862Sru 3659104862Sru@Defstr {?, ms} 3660104862SruUpside-down question mark. 3661104862Sru@endDefstr 3662104862Sru 3663104862Sru@Defstr {!, ms} 3664104862SruUpside-down exclamation point. 3665104862Sru@endDefstr 3666104862Sru 3667104862Sru@Defstr {8, ms} 3668104862SruGerman @ss{} ligature. 3669104862Sru@endDefstr 3670104862Sru 3671104862Sru@Defstr {3, ms} 3672104862SruYogh. 3673104862Sru@endDefstr 3674104862Sru 3675104862Sru@Defstr {Th, ms} 3676104862SruUppercase thorn. 3677104862Sru@endDefstr 3678104862Sru 3679104862Sru@Defstr {th, ms} 3680104862SruLowercase thorn. 3681104862Sru@endDefstr 3682104862Sru 3683104862Sru@Defstr {D-, ms} 3684104862SruUppercase eth. 3685104862Sru@endDefstr 3686104862Sru 3687104862Sru@Defstr {d-, ms} 3688104862SruLowercase eth. 3689104862Sru@endDefstr 3690104862Sru 3691104862Sru@Defstr {q, ms} 3692104862SruHooked o. 3693104862Sru@endDefstr 3694104862Sru 3695104862Sru@Defstr {ae, ms} 3696104862SruLowercase @ae{} ligature. 3697104862Sru@endDefstr 3698104862Sru 3699104862Sru@Defstr {Ae, ms} 3700104862SruUppercase @AE{} ligature. 3701104862Sru@endDefstr 3702104862Sru 3703104862Sru@c --------------------------------------------------------------------- 3704104862Sru 3705104862Sru@node Differences from AT&T ms, , ms Page Layout, ms 3706104862Sru@subsection Differences from @acronym{AT&T} @file{ms} 3707104862Sru@cindex @code{ms} macros, differences from @acronym{AT&T} 3708104862Sru@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences 3709104862Sru 3710104862SruThis section lists the (minor) differences between the 3711104862Sru@code{groff -ms} macros and @acronym{AT&T} 3712104862Sru@code{troff -ms} macros. 3713104862Sru 3714104862Sru@menu 3715104862Sru* Missing ms Macros:: 3716104862Sru* Additional ms Macros:: 3717104862Sru@end menu 3718104862Sru 3719104862Sru@c --------------------------------------------------------------------- 3720104862Sru 3721104862Sru@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms 3722104862Sru@subsubsection @code{troff} macros not appearing in @code{groff} 3723104862Sru 3724104862SruMacros missing from @code{groff -ms} 3725104862Sruare cover page macros specific to Bell Labs. 3726104862SruThe macros known to be missing are: 3727104862Sru 3728104862Sru@table @code 3729104862Sru@item .TM 3730104862SruTechnical memorandum; a cover sheet style 3731104862Sru 3732104862Sru@item .IM 3733104862SruInternal memorandum; a cover sheet style 3734104862Sru 3735104862Sru@item .MR 3736104862SruMemo for record; a cover sheet style 3737104862Sru 3738104862Sru@item .MF 3739104862SruMemo for file; a cover sheet style 3740104862Sru 3741104862Sru@item .EG 3742104862SruEngineer's notes; a cover sheet style 3743104862Sru 3744104862Sru@item .TR 3745104862SruComputing Science Tech Report; a cover sheet style 3746104862Sru 3747104862Sru@item .OK 3748104862SruOther keywords 3749104862Sru 3750104862Sru@item .CS 3751104862SruCover sheet information 3752104862Sru 3753104862Sru@item .MH 3754104862SruA cover sheet macro 3755104862Sru@end table 3756104862Sru 3757104862Sru@c --------------------------------------------------------------------- 3758104862Sru 3759104862Sru@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms 3760104862Sru@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff} 3761104862Sru 3762104862SruThe @code{groff -ms} macros have a few minor extensions 3763104862Srucompared to the @acronym{AT&T} @code{troff -ms} macros. 3764104862Sru 3765104862Sru@Defmac {AM, , ms} 3766104862SruImproved accent marks. 3767104862Sru@xref{ms Strings and Special Characters}, for details. 3768104862Sru@endDefmac 3769104862Sru 3770104862Sru@Defmac {DS, @t{I}, ms} 3771104862SruIndented display. 3772104862SruThe default behavior of @acronym{AT&T} @code{troff -ms} 3773104862Sruwas to indent; the @code{groff} default prints displays 3774104862Sruflush left with the body text. 3775104862Sru@endDefmac 3776104862Sru 3777104862Sru@Defmac {CW, , ms} 3778104862SruPrint text in @code{constant width} (Courier) font. 3779104862Sru@endDefmac 3780104862Sru 3781104862Sru@Defmac {IX, , ms} 3782104862SruIndexing term (printed on standard error). 3783104862SruYou can write a script to capture and process an index 3784104862Srugenerated in this manner. 3785104862Sru@endDefmac 3786104862Sru 3787104862Sru@sp 1 3788104862SruThe following additional number registers 3789104862Sruappear in @code{groff -ms}: 3790104862Sru 3791104862Sru@Defmpreg {MINGW, ms} 3792104862SruSpecifies a minimum space 3793104862Srubetween columns (for multi-column output); this takes the 3794104862Sruplace of the @code{GW} register that was documented but apparently 3795104862Srunot implemented in @acronym{AT&T} @code{troff}. 3796104862Sru@endDefmpreg 3797104862Sru 3798104862Sru@sp 1 3799104862SruSeveral new string registers are available as well. 3800104862SruYou can change these to handle (for example) the local language. 3801104862Sru@xref{ms Strings and Special Characters}, for details. 3802104862Sru 3803104862Sru 380469626Sru@c ===================================================================== 380569626Sru 380669626Sru@node me, mm, ms, Macro Packages 380769626Sru@section @file{me} 3808104862Sru@cindex @code{me} macro package 380969626Sru 381069626Sru@c XXX documentation 3811104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 3812104862SruSee the @file{meintro.me} and @file{meref.me} documents in 3813104862Srugroff's @file{doc} directory. 381469626Sru 381569626Sru 381669626Sru@c ===================================================================== 381769626Sru 381869626Sru@node mm, , me, Macro Packages 381969626Sru@section @file{mm} 3820104862Sru@cindex @code{mm} macro package 382169626Sru 382269626Sru@c XXX documentation 3823104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 3824104862SruSee the @cite{groff_mm(7)} man page (type @command{man groff_mm} at 3825104862Sruthe command line). 382669626Sru 382769626Sru 382869626Sru@c ===================================================================== 382969626Sru@c ===================================================================== 383069626Sru 383175584Sru@node gtroff Reference, Preprocessors, Macro Packages, Top 383275584Sru@chapter @code{gtroff} Reference 383375584Sru@cindex reference, @code{gtroff} 3834104862Sru@cindex @code{gtroff}, reference 383555839Sasmodai 383669626SruThis chapter covers @strong{all} of the facilities of @code{gtroff}. 383769626SruUsers of macro packages may skip it if not interested in details. 383855839Sasmodai 383955839Sasmodai 384055839Sasmodai@menu 384175584Sru* Text:: 384275584Sru* Input Conventions:: 384375584Sru* Measurements:: 384475584Sru* Expressions:: 384575584Sru* Identifiers:: 384675584Sru* Embedded Commands:: 384775584Sru* Registers:: 384875584Sru* Manipulating Filling and Adjusting:: 384975584Sru* Manipulating Hyphenation:: 385075584Sru* Manipulating Spacing:: 385175584Sru* Tabs and Fields:: 385275584Sru* Character Translations:: 385375584Sru* Troff and Nroff Mode:: 385475584Sru* Line Layout:: 3855104862Sru* Line Control:: 385675584Sru* Page Layout:: 385775584Sru* Page Control:: 385875584Sru* Fonts:: 385975584Sru* Sizes:: 386075584Sru* Strings:: 386175584Sru* Conditionals and Loops:: 386275584Sru* Writing Macros:: 386375584Sru* Page Motions:: 386475584Sru* Drawing Requests:: 386575584Sru* Traps:: 386675584Sru* Diversions:: 386775584Sru* Environments:: 386875584Sru* Suppressing output:: 3869104862Sru* Colors:: 387075584Sru* I/O:: 387175584Sru* Postprocessor Access:: 387275584Sru* Miscellaneous:: 387375584Sru* Gtroff Internals:: 387475584Sru* Debugging:: 387575584Sru* Implementation Differences:: 387655839Sasmodai@end menu 387755839Sasmodai 387869626Sru 387969626Sru@c ===================================================================== 388069626Sru 388175584Sru@node Text, Input Conventions, gtroff Reference, gtroff Reference 388255839Sasmodai@section Text 388369626Sru@cindex text, @code{gtroff} processing 388455839Sasmodai 388569626Sru@code{gtroff} input files contain text with control commands 388669626Sruinterspersed throughout. But, even without control codes, @code{gtroff} 388775584Srustill does several things with the input text: 388855839Sasmodai 388975584Sru@itemize @bullet 389075584Sru@item 389175584Srufilling and adjusting 389275584Sru 389375584Sru@item 389475584Sruadding additional space after sentences 389575584Sru 389675584Sru@item 389775584Sruhyphenating 389875584Sru 389975584Sru@item 390075584Sruinserting implicit line breaks 390175584Sru@end itemize 390275584Sru 390355839Sasmodai@menu 390475584Sru* Filling and Adjusting:: 390575584Sru* Hyphenation:: 390675584Sru* Sentences:: 390775584Sru* Tab Stops:: 390875584Sru* Implicit Line Breaks:: 390955839Sasmodai@end menu 391055839Sasmodai 391169626Sru@c --------------------------------------------------------------------- 391269626Sru 391355839Sasmodai@node Filling and Adjusting, Hyphenation, Text, Text 391455839Sasmodai@subsection Filling and Adjusting 391569626Sru@cindex filling 391669626Sru@cindex adjusting 391755839Sasmodai 391875584SruWhen @code{gtroff} reads text, it collects words from the input and fits 391969626Sruas many of them together on one output line as it can. This is known as 392055839Sasmodai@dfn{filling}. 392155839Sasmodai 392269626Sru@cindex leading spaces 392369626Sru@cindex spaces, leading and trailing 392469626Sru@cindex extra spaces 392569626Sru@cindex trailing spaces 392675584SruOnce @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 392775584Sruit. This means it widens the spacing between words until the text 392869626Srureaches the right margin (in the default adjustment mode). Extra spaces 392969626Srubetween words are preserved, but spaces at the end of lines are ignored. 393075584SruSpaces at the front of a line cause a @dfn{break} (breaks are 3931104862Sruexplained in @ref{Implicit Line Breaks}). 393255839Sasmodai 393369626Sru@xref{Manipulating Filling and Adjusting}. 393455839Sasmodai 393569626Sru@c --------------------------------------------------------------------- 393669626Sru 393755839Sasmodai@node Hyphenation, Sentences, Filling and Adjusting, Text 393855839Sasmodai@subsection Hyphenation 393955839Sasmodai@cindex hyphenation 394055839Sasmodai 394169626SruSince the odds are not great for finding a set of words, for every 394275584Sruoutput line, which fit nicely on a line without inserting excessive 394375584Sruamounts of space between words, @code{gtroff} hyphenates words so 394475584Sruthat it can justify lines without inserting too much space between 394569626Sruwords. It uses an internal hyphenation algorithm (a simplified version 394669626Sruof the algorithm used within @TeX{}) to indicate which words can be 394775584Sruhyphenated and how to do so. When a word is hyphenated, the first part 394875584Sruof the word is added to the current filled line being output (with 394975584Sruan attached hyphen), and the other portion is added to the next 395069626Sruline to be filled. 395155839Sasmodai 395269626Sru@xref{Manipulating Hyphenation}. 395355839Sasmodai 395469626Sru@c --------------------------------------------------------------------- 395555839Sasmodai 395655839Sasmodai@node Sentences, Tab Stops, Hyphenation, Text 395755839Sasmodai@subsection Sentences 395855839Sasmodai@cindex sentences 395955839Sasmodai 396069626SruAlthough it is often debated, some typesetting rules say there should be 396169626Srudifferent amounts of space after various punctuation marks. For 396269626Sruexample, the @cite{Chicago typsetting manual} says that a period at the 396369626Sruend of a sentence should have twice as much space following it as would 396469626Srua comma or a period as part of an abbreviation. 396555839Sasmodai 396669626Sru@c XXX exact citation of Chicago manual 396755839Sasmodai 396869626Sru@cindex sentence space 396969626Sru@cindex space between sentences 397069626Sru@cindex french-spacing 397169626Sru@code{gtroff} does this by flagging certain characters (normally 3972104862Sru@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters. 397369626SruWhen @code{gtroff} encounters one of these characters at the end of a 397475584Sruline, it appends a normal space followed by a @dfn{sentence space} in 397575584Sruthe formatted output. (This justifies one of the conventions mentioned 397675584Sruin @ref{Input Conventions}.) 397755839Sasmodai 397869626Sru@cindex transparent characters 397969626Sru@cindex character, transparent 3980104862Sru@cindex @code{dg} glyph, at end of sentence 3981104862Sru@cindex @code{rq} glyph, at end of sentence 3982104862Sru@cindex @code{"}, at end of sentence 3983104862Sru@cindex @code{'}, at end of sentence 3984104862Sru@cindex @code{)}, at end of sentence 3985104862Sru@cindex @code{]}, at end of sentence 3986104862Sru@cindex @code{*}, at end of sentence 3987104862SruIn addition, the following characters and symbols are treated 3988104862Srutransparently while handling end-of-sentence characters: @samp{"}, 3989104862Sru@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}. 399055839Sasmodai 399169626SruSee the @code{cflags} request in @ref{Using Symbols}, for more details. 399255839Sasmodai 3993104862Sru@cindex @code{\&}, at end of sentence 3994104862SruTo prevent the insertion of extra space after an end-of-sentence 399569626Srucharacter (at the end of a line), append @code{\&}. 399655839Sasmodai 399769626Sru@c --------------------------------------------------------------------- 399869626Sru 399955839Sasmodai@node Tab Stops, Implicit Line Breaks, Sentences, Text 400055839Sasmodai@subsection Tab Stops 400155839Sasmodai@cindex tab stops 400255839Sasmodai@cindex stops, tabulator 400369626Sru@cindex tab character 400469626Sru@cindex character, tabulator 400555839Sasmodai 400669626Sru@cindex @acronym{EBCDIC} encoding 4007104862Sru@cindex encoding, @acronym{EBCDIC} 400869626Sru@code{gtroff} translates @dfn{tabulator characters}, also called 400975584Sru@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 401069626Sru@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 401169626Srutabulator stop. These tab stops are initially located every half inch 401275584Sruacross the page. Using this, simple tables can be made easily. 401369626SruHowever, it can often be deceptive as the appearance (and width) of the 401469626Srutext on a terminal and the results from @code{gtroff} can vary greatly. 401555839Sasmodai 401655839SasmodaiAlso, a possible sticking point is that lines beginning with tab 401775584Srucharacters are still filled, again producing unexpected results. 401855839SasmodaiFor example, the following input 401955839Sasmodai 402069626Sru@multitable {12345678} {12345678} {12345678} {12345678} 402169626Sru@item 402269626Sru@tab 1 @tab 2 @tab 3 402369626Sru@item 402469626Sru@tab @tab 4 @tab 5 402569626Sru@end multitable 402655839Sasmodai 402755839Sasmodai@noindent 402875584Sruproduces 402955839Sasmodai 403069626Sru@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 403169626Sru@item 403269626Sru@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 403369626Sru@end multitable 403455839Sasmodai 403569626Sru@xref{Tabs and Fields}. 403655839Sasmodai 403769626Sru@c --------------------------------------------------------------------- 403855839Sasmodai 403955839Sasmodai@node Implicit Line Breaks, , Tab Stops, Text 404055839Sasmodai@subsection Implicit Line Breaks 404155839Sasmodai@cindex implicit line breaks 404255839Sasmodai@cindex implicit breaks of lines 404355839Sasmodai@cindex line, implicit breaks 404455839Sasmodai@cindex break, implicit 404555839Sasmodai@cindex line break 404655839Sasmodai 404769626SruAn important concept in @code{gtroff} is the @dfn{break}. When a break 404875584Sruoccurs, @code{gtroff} outputs the partially filled line 404975584Sru(unjustified), and resumes collecting and filling text on the next output 405069626Sruline. 405155839Sasmodai 405255839Sasmodai@cindex blank line 405355839Sasmodai@cindex empty line 405455839Sasmodai@cindex line, blank 4055104862Sru@cindex blank line macro (@code{blm}) 405675584SruThere are several ways to cause a break in @code{gtroff}. A blank 4057104862Sruline not only causes a break, but it also outputs a one-line vertical 405875584Sruspace (effectively a blank line). Note that this behaviour can be 405975584Srumodified with the blank line macro request @code{blm}. 4060104862Sru@xref{Blank Line Traps}. 406155839Sasmodai 406269626Sru@cindex fill mode 406369626Sru@cindex mode, fill 406475584SruA line that begins with a space causes a break and the space is 406575584Sruoutput at the beginning of the next line. Note that this space isn't 406669626Sruadjusted, even in fill mode. 406755839Sasmodai 406875584SruThe end of file also causes a break -- otherwise the last line of 406969626Sruthe document may vanish! 407055839Sasmodai 407175584SruCertain requests also cause breaks, implicitly or explicitly. This is 407275584Srudiscussed in @ref{Manipulating Filling and Adjusting}. 407355839Sasmodai 407455839Sasmodai 407569626Sru@c ===================================================================== 407669626Sru 407775584Sru@node Input Conventions, Measurements, Text, gtroff Reference 407855839Sasmodai@section Input Conventions 407955839Sasmodai@cindex input conventions 408055839Sasmodai@cindex conventions for input 408155839Sasmodai 408269626SruSince @code{gtroff} does filling automatically, it is traditional in 408369626Sru@code{groff} not to try and type things in as nicely formatted 408469626Sruparagraphs. These are some conventions commonly used when typing 408569626Sru@code{gtroff} text: 408655839Sasmodai 408769626Sru@itemize @bullet 408869626Sru@item 408975584SruBreak lines after punctuation, particularly at the end of a sentence 409069626Sruand in other logical places. Keep separate phrases on lines by 409169626Sruthemselves, as entire phrases are often added or deleted when editing. 409255839Sasmodai 409355839Sasmodai@item 409469626SruTry to keep lines less than 40-60@w{ }characters, to allow space for 409569626Sruinserting more text. 409669626Sru 409755839Sasmodai@item 409869626SruDo not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 409975584Srudon't try using spaces to get proper indentation). 410055839Sasmodai@end itemize 410155839Sasmodai 410255839Sasmodai 410369626Sru@c ===================================================================== 410469626Sru 410575584Sru@node Measurements, Expressions, Input Conventions, gtroff Reference 410655839Sasmodai@section Measurements 410755839Sasmodai@cindex measurements 410855839Sasmodai 410955839Sasmodai@cindex units of measurement 4110104862Sru@cindex basic unit (@code{u}) 4111104862Sru@cindex machine unit (@code{u}) 4112104862Sru@cindex measurement unit 411369626Sru@cindex @code{u} unit 411469626Sru@cindex unit, @code{u} 411575584Sru@code{gtroff} (like many other programs) requires numeric parameters to 411669626Sruspecify various measurements. Most numeric parameters@footnote{those 411769626Sruthat specify vertical or horizontal motion or a type size} may have a 411869626Sru@dfn{measurement unit} attached. These units are specified as a single 411969626Srucharacter which immediately follows the number or expression. Each of 412069626Sruthese units are understood, by @code{gtroff}, to be a multiple of its 412155839Sasmodai@dfn{basic unit}. So, whenever a different measurement unit is 412269626Sruspecified @code{gtroff} converts this into its @dfn{basic units}. This 412369626Srubasic unit, represented by a @samp{u}, is a device dependent measurement 412475584Sruwhich is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 412575584Sruinch. The values may be given as fractional numbers; however, 412675584Srufractional basic units are always rounded to integers. 412755839Sasmodai 412869626SruSome of the measurement units are completely independent of any of the 412969626Srucurrent settings (e.g.@: type size) of @code{gtroff}. 413055839Sasmodai 413169626Sru@table @code 413255839Sasmodai@item i 4133104862Sru@cindex inch unit (@code{i}) 413469626Sru@cindex @code{i} unit 413569626Sru@cindex unit, @code{i} 413655839SasmodaiInches. An antiquated measurement unit still in use in certain 413775584Srubackwards countries with incredibly low-cost computer equipment. One 413875584Sruinch is equal to@w{ }2.54@dmn{cm}. 413969626Sru 414055839Sasmodai@item c 4141104862Sru@cindex centimeter unit (@code{c}) 414269626Sru@cindex @code{c} unit 414369626Sru@cindex unit, @code{c} 414469626SruCentimeters. One centimeter is equal to@w{ }0.3937@dmn{in}. 414569626Sru 414655839Sasmodai@item p 4147104862Sru@cindex point unit (@code{p}) 414869626Sru@cindex @code{p} unit 414969626Sru@cindex unit, @code{p} 415055839SasmodaiPoints. This is a typesetter's measurement used for measure type size. 415169626SruIt is 72@w{ }points to an inch. 415269626Sru 415355839Sasmodai@item P 4154104862Sru@cindex pica unit (@code{P}) 415569626Sru@cindex @code{P} unit 415669626Sru@cindex unit, @code{P} 415769626SruPica. Another typesetting measurement. 6@w{ }Picas to an inch (and 415869626Sru12@w{ }points to a pica). 415969626Sru 416055839Sasmodai@item s 416169626Sru@itemx z 416269626Sru@cindex @code{s} unit 416369626Sru@cindex unit, @code{s} 416469626Sru@cindex @code{z} unit 416569626Sru@cindex unit, @code{z} 416669626Sru@xref{Fractional Type Sizes}, for a discussion of these units. 4167104862Sru 4168104862Sru@item f 4169104862Sru@cindex @code{f} unit 4170104862Sru@cindex unit, @code{f} 4171104862SruFractions. Value is 65536. 4172104862Sru@xref{Colors}, for usage. 417355839Sasmodai@end table 417455839Sasmodai 417575584SruThe other measurements understood by @code{gtroff} depend on 417669626Srusettings currently in effect in @code{gtroff}. These are very useful 417769626Srufor specifying measurements which should look proper with any size of 417869626Srutext. 417955839Sasmodai 418069626Sru@table @code 418155839Sasmodai@item m 4182104862Sru@cindex em unit (@code{m}) 418369626Sru@cindex @code{m} unit 418469626Sru@cindex unit, @code{m} 418569626SruEms. This unit is equal to the current font size in points. So called 418669626Srubecause it is @emph{approximately} the width of the letter@w{ }@samp{m} 418769626Sruin the current font. 418869626Sru 418955839Sasmodai@item n 4190104862Sru@cindex en unit (@code{n}) 419169626Sru@cindex @code{n} unit 419269626Sru@cindex unit, @code{n} 4193104862SruEns. In @code{groff}, this is half of an em. 419469626Sru 419555839Sasmodai@item v 4196104862Sru@cindex vertical space unit (@code{v}) 4197104862Sru@cindex space, vertical, unit (@code{v}) 419869626Sru@cindex @code{v} unit 419969626Sru@cindex unit, @code{v} 420055839SasmodaiVertical space. This is equivalent to the current line spacing. 420155839Sasmodai@xref{Sizes}, for more information about this. 420269626Sru 420355839Sasmodai@item M 420469626Sru@cindex @code{M} unit 420569626Sru@cindex unit, @code{M} 420655839Sasmodai100ths of an em. 420755839Sasmodai@end table 420855839Sasmodai 420955839Sasmodai@menu 421075584Sru* Default Units:: 421155839Sasmodai@end menu 421255839Sasmodai 421369626Sru@c --------------------------------------------------------------------- 421469626Sru 421555839Sasmodai@node Default Units, , Measurements, Measurements 421655839Sasmodai@subsection Default Units 421755839Sasmodai@cindex default units 421855839Sasmodai@cindex units, default 421955839Sasmodai 422069626SruMany requests take a default unit. While this can be helpful at times, 422169626Sruit can cause strange errors in some expressions. For example, the line 422269626Srulength request expects em units. Here are several attempts to get a 422369626Sruline length of 3.5@w{ }inches and their results: 422455839Sasmodai 422575584Sru@Example 422655839Sasmodai3.5i @result{} 3.5i 422755839Sasmodai7/2 @result{} 0i 422855839Sasmodai7/2i @result{} 0i 4229104862Sru(7 / 2)u @result{} 0i 423069626Sru7i/2 @result{} 0.1i 423155839Sasmodai7i/2u @result{} 3.5i 423275584Sru@endExample 423355839Sasmodai 423469626Sru@noindent 423575584SruEverything is converted to basic units first. In the above example it 423675584Sruis assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{ 423775584Sru}10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2 423875584Sruis first handled as 7@dmn{i}/2@dmn{m}, then converted to 423975584Sru1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 4240104862Sru0.1@dmn{i}. As can be seen, a scaling indicator after a closing 4241104862Sruparenthesis is simply ignored. 424255839Sasmodai 424369626Sru@cindex measurements, specifying safely 424475584SruThus, the safest way to specify measurements is to always 424569626Sruattach a scaling indicator. If you want to multiply or divide by a 424669626Srucertain scalar value, use @samp{u} as the unit for that value. 424769626Sru 424869626Sru 424969626Sru@c ===================================================================== 425069626Sru 425175584Sru@node Expressions, Identifiers, Measurements, gtroff Reference 425255839Sasmodai@section Expressions 425355839Sasmodai@cindex expressions 425455839Sasmodai 425575584Sru@code{gtroff} has most arithmetic operators common to other languages: 425655839Sasmodai 425755839Sasmodai@itemize @bullet 425855839Sasmodai@item 425969626Sru@cindex arithmetic operators 426069626Sru@cindex operators, arithmetic 426169626Sru@opindex + 426269626Sru@opindex - 426369626Sru@opindex / 426469626Sru@opindex * 426569626Sru@opindex % 426669626SruArithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 426769626Sru(division), @samp{*} (multiplication), @samp{%} (modulo). 426869626Sru 426969626Sru@code{gtroff} only provides integer arithmetic. The internal type used 427069626Srufor computing results is @samp{int}, which is usually a 32@dmn{bit} 427169626Srusigned integer. 427269626Sru 427355839Sasmodai@item 427469626Sru@cindex comparison operators 427569626Sru@cindex operators, comparison 427669626Sru@opindex < 427769626Sru@opindex > 427869626Sru@opindex >= 427969626Sru@opindex <= 428069626Sru@opindex = 428169626Sru@opindex == 428269626SruComparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 428369626Sru(less than or equal), @samp{>=} (greater than or equal), @samp{=} 428469626Sru(equal), @samp{==} (the same as @samp{=}). 428569626Sru 428655839Sasmodai@item 428769626Sru@cindex logical operators 428869626Sru@cindex operators, logical 428969626Sru@opindex & 4290104862Sru@ifnotinfo 429169626Sru@opindex : 4292104862Sru@end ifnotinfo 4293104862Sru@ifinfo 4294104862Sru@opindex @r{<colon>} 4295104862Sru@end ifinfo 429669626SruLogical: @samp{&} (logical and), @samp{:} (logical or). 429769626Sru 429855839Sasmodai@item 429969626Sru@cindex unary operators 430069626Sru@cindex operators, unary 430169626Sru@opindex - 430269626Sru@opindex + 430369626Sru@opindex ! 4304104862Sru@cindex @code{if} request, and the @samp{!} operator 4305104862Sru@cindex @code{while} request, and the @samp{!} operator 430669626SruUnary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 430769626Sru(just for completeness; does nothing in expressions), @samp{!} (logical 430869626Srunot; this works only within @code{if} and @code{while} requests). See 430969626Srubelow for the use of unary operators in motion requests. 431069626Sru 431155839Sasmodai@item 4312104862Sru@cindex extremum operators (@code{>?}, @code{<?}) 4313104862Sru@cindex operators, extremum (@code{>?}, @code{<?}) 431469626Sru@opindex >? 431569626Sru@opindex <? 4316104862SruExtrema: @samp{>?} (maximum), @samp{<?} (minimum). 431769626Sru 4318104862SruExample: 431969626Sru 4320104862Sru@Example 4321104862Sru.nr x 5 4322104862Sru.nr y 3 4323104862Sru.nr z (\n[x] >? \n[y]) 4324104862Sru@endExample 4325104862Sru 4326104862Sru@noindent 4327104862SruThe register@w{ }@code{z} now contains@w{ }5. 4328104862Sru 432955839Sasmodai@item 433069626Sru@cindex scaling operator 433169626Sru@cindex operator, scaling 4332104862SruScaling: @code{(@var{c};@var{e})}. Evaluate@w{ }@var{e} using@w{ }@var{c} 4333104862Sruas the default scaling indicator. If @var{c} is missing, ignore scaling 4334104862Sruindicators in the evaluation of@w{ }@var{e}. 433555839Sasmodai@end itemize 433655839Sasmodai 433769626Sru@cindex parentheses 433869626Sru@cindex order of evaluation in expressions 433969626Sru@cindex expression, order of evaluation 434069626Sru@opindex ( 434169626Sru@opindex ) 434269626SruParentheses may be used as in any other language. However, in 434369626Sru@code{gtroff} they are necessary to ensure order of evaluation. 434469626Sru@code{gtroff} has no operator precedence; expressions are evaluated left 434575584Sruto right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 434669626Sruparenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 434769626Sruexpected. 434855839Sasmodai 4349104862Sru@cindex @code{+}, and page motion 4350104862Sru@cindex @code{-}, and page motion 435169626Sru@cindex motion operators 435269626Sru@cindex operators, motion 435369626SruFor many requests which cause a motion on the page, the unary operators 4354104862Sru@samp{+} and @samp{-} work differently if leading an expression. They 4355104862Sruthen indicate a motion relative to the current position (down or up, 4356104862Srurespectively). 4357104862Sru 4358104862Sru@cindex @code{|}, and page motion 4359104862Sru@cindex absolute position operator (@code{|}) 4360104862Sru@cindex position, absolute, operator (@code{|}) 4361104862SruSimilarly, a leading @samp{|} operator indicates an absolute position. 4362104862SruFor vertical movements, it specifies the distance from the top of the 4363104862Srupage; for horizontal movements, it gives the distance from the beginning 4364104862Sruof the @emph{input} line. 4365104862Sru 4366104862Sru@cindex @code{bp} request, using @code{+} and@w{ }@code{-} 4367104862Sru@cindex @code{in} request, using @code{+} and@w{ }@code{-} 4368104862Sru@cindex @code{ll} request, using @code{+} and@w{ }@code{-} 4369104862Sru@cindex @code{lt} request, using @code{+} and@w{ }@code{-} 4370104862Sru@cindex @code{nm} request, using @code{+} and@w{ }@code{-} 4371104862Sru@cindex @code{nr} request, using @code{+} and@w{ }@code{-} 4372104862Sru@cindex @code{pl} request, using @code{+} and@w{ }@code{-} 4373104862Sru@cindex @code{pn} request, using @code{+} and@w{ }@code{-} 4374104862Sru@cindex @code{po} request, using @code{+} and@w{ }@code{-} 4375104862Sru@cindex @code{ps} request, using @code{+} and@w{ }@code{-} 4376104862Sru@cindex @code{pvs} request, using @code{+} and@w{ }@code{-} 4377104862Sru@cindex @code{rt} request, using @code{+} and@w{ }@code{-} 4378104862Sru@cindex @code{ti} request, using @code{+} and@w{ }@code{-} 4379104862Sru@cindex @code{\H}, using @code{+} and@w{ }@code{-} 4380104862Sru@cindex @code{\R}, using @code{+} and@w{ }@code{-} 4381104862Sru@cindex @code{\s}, using @code{+} and@w{ }@code{-} 438269626Sru@samp{+} and @samp{-} are also treated differently by the following 438369626Srurequests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 438469626Sru@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 4385104862Sru@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}. 4386104862SruHere, leading plus and minus signs indicate increments and decrements. 438755839Sasmodai 4388104862Sru@xref{Setting Registers}, for some examples. 438969626Sru 4390104862Sru@Defesc {\\B, ', anything, '} 4391104862Sru@cindex numeric expression, valid 4392104862Sru@cindex valid numeric expression 4393104862SruReturn@w{ }1 if @var{anything} is a valid numeric expression; 4394104862Sruor@w{ }0 if @var{anything} is empty or not a valid numeric expression. 4395104862Sru@endDefesc 4396104862Sru 4397104862Sru@cindex space characters, in expressions 4398104862Sru@cindex expressions, and space characters 439955839SasmodaiDue to the way arguments are parsed, spaces are not allowed in 440069626Sruexpressions, unless the entire expression is surrounded by parentheses. 440155839Sasmodai 440269626Sru@xref{Request Arguments}, and @ref{Conditionals and Loops}. 440355839Sasmodai 440469626Sru 440569626Sru@c ===================================================================== 440669626Sru 440775584Sru@node Identifiers, Embedded Commands, Expressions, gtroff Reference 440855839Sasmodai@section Identifiers 440955839Sasmodai@cindex identifiers 441055839Sasmodai 441169626SruLike any other language, @code{gtroff} has rules for properly formed 441269626Sru@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 441369626Srualmost any printable character, with the exception of the following 441469626Srucharacters: 441555839Sasmodai 441669626Sru@itemize @bullet 441769626Sru@item 441869626Sru@cindex whitespace characters 441969626Sru@cindex newline character 442069626Sru@cindex character, whitespace 442175584SruWhitespace characters (spaces, tabs, and newlines). 442269626Sru 442369626Sru@item 442469626Sru@cindex character, backspace 442569626Sru@cindex backspace character 442669626Sru@cindex @acronym{EBCDIC} encoding of backspace 442775584SruBackspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{ 442869626Sru}@code{0x16}) and character code @code{0x01}. 442969626Sru 443069626Sru@item 443169626Sru@cindex invalid input characters 443269626Sru@cindex input characters, invalid 443369626Sru@cindex characters, invalid input 4434104862Sru@cindex Unicode 443575584SruThe following input characters are invalid and are ignored if 443669626Sru@code{groff} runs on a machine based on @acronym{ASCII}, causing a 443769626Sruwarning message of type @samp{input} (see @ref{Debugging}, for more 443869626Srudetails): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 443969626Sru@code{0x80}-@code{0x9F}. 444069626Sru 444169626SruAnd here are the invalid input characters if @code{groff} runs on an 444269626Sru@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 444369626Sru@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 444469626Sru@code{0x30}-@code{0x3F}. 444569626Sru 444669626SruCurrently, some of these reserved codepoints are used internally, thus 444769626Srumaking it non-trivial to extend @code{gtroff} to cover Unicode or other 444875584Srucharacter sets and encodings which use characters of these ranges. 444969626Sru 445075584SruNote that invalid characters are removed before parsing; an 445169626Sruidentifier @code{foo}, followed by an invalid character, followed by 445275584Sru@code{bar} is treated as @code{foobar}. 445369626Sru@end itemize 445469626Sru 445569626SruFor example, any of the following is valid. 445669626Sru 445775584Sru@Example 445855839Sasmodaibr 445955839SasmodaiPP 446055839Sasmodai(l 446155839Sasmodaiend-list 446255839Sasmodai@@_ 446375584Sru@endExample 446455839Sasmodai 4465104862Sru@cindex @code{]}, as part of an identifier 446675584Sru@noindent 446769626SruNote that identifiers longer than two characters with a closing bracket 446869626Sru(@samp{]}) in its name can't be accessed with escape sequences which 446975584Sruexpect an identifier as a parameter. For example, @samp{\[foo]]} 447075584Sruaccesses the glyph @samp{foo}, followed by @samp{]}, whereas 447169626Sru@samp{\C'foo]'} really asks for glyph @samp{foo]}. 447255839Sasmodai 4473104862Sru@cindex @code{refer}, and macro names starting with @code{[} or @code{]} 4474104862Sru@cindex @code{[}, macro names starting with, and @code{refer} 4475104862Sru@cindex @code{]}, macro names starting with, and @code{refer} 4476104862Sru@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} 4477104862SruTo avoid problems with the @code{refer} preprocessor, macro names 4478104862Srushould not start with @samp{[} or @samp{]}. Due to backwards 4479104862Srucompatibility, everything after @samp{.[} and @samp{.]} is handled as 4480104862Srua special argument to @code{refer}. For example, @samp{.[foo} makes 4481104862Sru@code{refer} to start a reference, using @samp{foo} as a parameter. 448255839Sasmodai 448375584Sru@Defesc {\\A, ', ident, '} 448475584SruTest whether an identifier @var{ident} is valid in @code{gtroff}. It 448575584Sruexpands to the character@w{ }1 or@w{ }0 according to whether its 448675584Sruargument (usually delimited by quotes) is or is not acceptable as the 448775584Sruname of a string, macro, diversion, number register, environment, or 448875584Srufont. It returns@w{ }0 if no argument is given. This is useful for 448975584Srulooking up user input in some sort of associative table. 449069626Sru 449175584Sru@Example 449269626Sru\A'end-list' 449369626Sru @result{} 1 449475584Sru@endExample 449575584Sru@endDefesc 449669626Sru 449769626Sru@xref{Escapes}, for details on parameter delimiting characters. 449869626Sru 449969626SruIdentifiers in @code{gtroff} can be any length, but, in some contexts, 450069626Sru@code{gtroff} needs to be told where identifiers end and text begins 450169626Sru(and in different ways depending on their length): 450269626Sru 450369626Sru@itemize @bullet 450455839Sasmodai@item 450569626SruSingle character. 450669626Sru 4507104862Sru@cindex @code{(}, starting a two-character identifier 450855839Sasmodai@item 450969626SruTwo characters. Must be prefixed with @samp{(} in some situations. 451069626Sru 4511104862Sru@cindex @code{[}, starting an identifier 4512104862Sru@cindex @code{]}, ending an identifier 451355839Sasmodai@item 451469626SruArbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 451569626Sruand@w{ }@samp{]} in some situations. Any length identifier can be put 451669626Sruin brackets. 451755839Sasmodai@end itemize 451855839Sasmodai 451969626Sru@cindex undefined identifiers 4520104862Sru@cindex identifiers, undefined 452155839SasmodaiUnlike many other programming languages, undefined identifiers are 452255839Sasmodaisilently ignored or expanded to nothing. 452375584SruWhen @code{gtroff} finds an undefined identifier, it emits a 4524104862Sruwarning, doing the following: 452555839Sasmodai 452675584Sru@itemize @bullet 452775584Sru@item 452875584SruIf the identifier is a string, macro, or diversion, 452975584Sru@code{gtroff} defines it as empty. 453055839Sasmodai 453175584Sru@item 453275584SruIf the identifier is a number register, @code{gtroff} 453375584Srudefines it with a value of@w{ }0. 453475584Sru@end itemize 453575584Sru 4536104862Sru@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. 453775584Sru 4538104862SruNote that macros, strings, and diversions share the same name space. 453975584Sru 4540104862Sru@Example 4541104862Sru.de xxx 4542104862Sru. nop foo 4543104862Sru.. 4544104862Sru. 4545104862Sru.di xxx 4546104862Srubar 4547104862Sru.br 4548104862Sru.di 4549104862Sru. 4550104862Sru.xxx 4551104862Sru @result{} bar 4552104862Sru@endExample 4553104862Sru 4554104862Sru@noindent 4555104862SruAs can be seen in the previous example, @code{gtroff} reuses the 4556104862Sruidentifier @samp{xxx}, changing it from a macro to a diversion. 4557104862SruNo warning is emitted! The contents of the first macro definition is 4558104862Srulost. 4559104862Sru 456069626Sru@xref{Interpolating Registers}, and @ref{Strings}. 456155839Sasmodai 456269626Sru 456369626Sru@c ===================================================================== 456469626Sru 456575584Sru@node Embedded Commands, Registers, Identifiers, gtroff Reference 456655839Sasmodai@section Embedded Commands 456755839Sasmodai@cindex embedded commands 456855839Sasmodai@cindex commands, embedded 456955839Sasmodai 457069626SruMost documents need more functionality beyond filling, adjusting and 457169626Sruimplicit line breaking. In order to gain further functionality, 457269626Sru@code{gtroff} allows commands to be embedded into the text, in two ways. 457355839Sasmodai 457455839SasmodaiThe first is a @dfn{request} which takes up an entire line, and does 457575584Srusome large-scale operation (e.g.@: break lines, start new pages). 457655839Sasmodai 4577104862SruThe other is an @dfn{escape} which can be usually embedded anywhere 4578104862Sruin the text; most requests can accept it even as an argument. 457969626SruEscapes generally do more minor operations like sub- and superscripts, 458069626Sruprint a symbol, etc. 458155839Sasmodai 458255839Sasmodai@menu 458375584Sru* Requests:: 458475584Sru* Macros:: 458575584Sru* Escapes:: 458655839Sasmodai@end menu 458755839Sasmodai 458869626Sru@c --------------------------------------------------------------------- 458969626Sru 459055839Sasmodai@node Requests, Macros, Embedded Commands, Embedded Commands 459155839Sasmodai@subsection Requests 459255839Sasmodai@cindex requests 459355839Sasmodai 4594104862Sru@cindex control character (@code{.}) 4595104862Sru@cindex character, control (@code{.}) 4596104862Sru@cindex no-break control character (@code{'}) 4597104862Sru@cindex character, no-break control (@code{'}) 4598104862Sru@cindex control character, no-break (@code{'}) 459969626SruA request line begins with a control character, which is either a single 460069626Sruquote (@samp{'}, the @dfn{no-break control character}) or a period 460169626Sru(@samp{.}, the normal @dfn{control character}). These can be changed; 460269626Srusee @ref{Character Translations}, for details. After this there may be 460369626Sruoptional tabs or spaces followed by an identifier which is the name of 460469626Sruthe request. This may be followed by any number of space-separated 460575584Sruarguments (@emph{no} tabs here). 460655839Sasmodai 460775584Sru@cindex structuring source code of documents or macro packages 460875584Sru@cindex documents, structuring the source code 4609104862Sru@cindex macro packages, structuring the source code 461075584SruSince a control character followed by whitespace only is ignored, it 461175584Sruis common practice to use this feature for structuring the source code 461275584Sruof documents or macro packages. 461375584Sru 461475584Sru@Example 461575584Sru.de foo 461675584Sru. tm This is foo. 461775584Sru.. 461875584Sru. 461975584Sru. 462075584Sru.de bar 462175584Sru. tm This is bar. 462275584Sru.. 462375584Sru@endExample 462475584Sru 462575584Sru@cindex blank line 4626104862Sru@cindex blank line macro (@code{blm}) 462775584SruAnother possibility is to use the blank line macro request @code{blm} 462875584Sruby assigning an empty macro to it. 462975584Sru 463075584Sru@Example 463175584Sru.de do-nothing 463275584Sru.. 463375584Sru.blm do-nothing \" activate blank line macro 463475584Sru 463575584Sru.de foo 463675584Sru. tm This is foo. 463775584Sru.. 463875584Sru 463975584Sru 464075584Sru.de bar 464175584Sru. tm This is bar. 464275584Sru.. 464375584Sru 464475584Sru.blm \" deactivate blank line macro 464575584Sru@endExample 464675584Sru 4647104862Sru@xref{Blank Line Traps}. 464875584Sru 4649104862Sru@cindex zero width space character (@code{\&}) 4650104862Sru@cindex character, zero width space (@code{\&}) 4651104862Sru@cindex space character, zero width (@code{\&}) 465275584Sru@cindex @code{\&}, escaping control characters 465369626SruTo begin a line with a control character without it being interpreted, 465469626Sruprecede it with @code{\&}. This represents a zero width space, which 465575584Srumeans it does not affect the output. 465655839Sasmodai 465769626SruIn most cases the period is used as a control character. Several 465875584Srurequests cause a break implicitly; using the single quote control 465975584Srucharacter prevents this. 466055839Sasmodai 466155839Sasmodai@menu 466275584Sru* Request Arguments:: 466355839Sasmodai@end menu 466455839Sasmodai 466555839Sasmodai@node Request Arguments, , Requests, Requests 466655839Sasmodai@subsubsection Request Arguments 466755839Sasmodai@cindex request arguments 466855839Sasmodai@cindex arguments to requests 466955839Sasmodai 467069626SruArguments to requests (and macros) are processed much like the shell: 4671104862SruThe line is split into arguments according to 4672104862Sruspaces.@footnote{Plan@w{ }9's @code{troff} implementation also allows 4673104862Srutabs for argument separation -- @code{gtroff} intentionally doesn't 4674104862Srusupport this.} An argument which is intended to contain spaces can 4675104862Srueither be enclosed in double quotes, or have the spaces @dfn{escaped} 4676104862Sruwith backslashes. 467755839Sasmodai 467869626SruHere are a few examples: 467955839Sasmodai 468075584Sru@Example 468155839Sasmodai.uh The Mouse Problem 468255839Sasmodai.uh "The Mouse Problem" 468355839Sasmodai.uh The\ Mouse\ Problem 468475584Sru@endExample 468555839Sasmodai 4686104862Sru@cindex @code{\~}, difference to @code{\@key{SP}} 4687104862Sru@cindex @code{\@key{SP}}, difference to @code{\~} 468869626Sru@noindent 468969626SruThe first line is the @code{uh} macro being called with 3 arguments, 469069626Sru@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 469175584Srusame effect of calling the @code{uh} macro with one argument, @samp{The 469269626SruMouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 469369626Sruis ``classical'' in the sense that it can be found in most @code{troff} 469469626Srudocuments. Nevertheless, it is not optimal in all situations, since 469569626Sru@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 469669626Srucan't stretch. @code{gtroff} provides a different command @code{\~} to 469769626Sruinsert a stretchable, non-breaking space.} 469855839Sasmodai 4699104862Sru@cindex @code{"}, in a macro argument 4700104862Sru@cindex double quote, in a macro argument 470175584SruA double quote which isn't preceded by a space doesn't start a macro 470275584Sruargument. If not closing a string, it is printed literally. 470375584Sru 470475584SruFor example, 470575584Sru 470675584Sru@Example 470775584Sru.xxx a" "b c" "de"fg" 470875584Sru@endExample 470975584Sru 471075584Sru@noindent 471175584Sruhas the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 4712104862SruDon't rely on this obscure behaviour! 471375584Sru 4714104862SruThere are two possibilities to get a double quote reliably. 4715104862Sru 4716104862Sru@itemize @bullet 4717104862Sru@item 4718104862SruEnclose the whole argument with double quotes and use two consecutive double 4719104862Sruquotes to represent a single one. This traditional solution has the 4720104862Srudisadvantage that double quotes don't survive argument expansion again if 4721104862Srucalled in compatibility mode (using the @option{-C} option of @code{groff}): 4722104862Sru 4723104862Sru@Example 4724104862Sru.de xx 4725104862Sru. tm xx: `\\$1' `\\$2' `\\$3' 4726104862Sru. 4727104862Sru. yy "\\$1" "\\$2" "\\$3" 4728104862Sru.. 4729104862Sru.de yy 4730104862Sru. tm yy: `\\$1' `\\$2' `\\$3' 4731104862Sru.. 4732104862Sru.xx A "test with ""quotes""" . 4733104862Sru @result{} xx: `A' `test with "quotes"' `.' 4734104862Sru @result{} yy: `A' `test with ' `quotes""' 4735104862Sru@endExample 4736104862Sru 4737104862Sru@noindent 4738104862SruIf not in compatibility mode, you get the expected result 4739104862Sru 4740104862Sru@Example 4741104862Sruxx: `A' `test with "quotes"' `.' 4742104862Sruyy: `A' `test with "quotes"' `.' 4743104862Sru@endExample 4744104862Sru 4745104862Sru@noindent 4746104862Srusince @code{gtroff} preserves the input level. 4747104862Sru 4748104862Sru@item 4749104862SruUse the double quote glyph @code{\(dq}. This works with and without 4750104862Srucompatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq} 4751104862Sruback to a double quote input character. 4752104862Sru 4753104862SruNot that this method won't work with @acronym{UNIX} @code{troff} in general 4754104862Srusince the glyph `dq' isn't defined normally. 4755104862Sru@end itemize 4756104862Sru 4757104862Sru@cindex @code{ds} request, and double quotes 4758104862SruDouble quotes in the @code{ds} request are handled differently. 475969626Sru@xref{Strings}, for more details. 476055839Sasmodai 476169626Sru@c --------------------------------------------------------------------- 476255839Sasmodai 476355839Sasmodai@node Macros, Escapes, Requests, Embedded Commands 476455839Sasmodai@subsection Macros 476555839Sasmodai@cindex macros 476655839Sasmodai 476769626Sru@code{gtroff} has a @dfn{macro} facility for defining a series of lines 476869626Sruwhich can be invoked by name. They are called in the same manner as 476969626Srurequests -- arguments also may be passed in the same manner. 477055839Sasmodai 477169626Sru@xref{Writing Macros}, and @ref{Request Arguments}. 477255839Sasmodai 477369626Sru@c --------------------------------------------------------------------- 477455839Sasmodai 477555839Sasmodai@node Escapes, , Macros, Embedded Commands 477655839Sasmodai@subsection Escapes 477755839Sasmodai@cindex escapes 477855839Sasmodai 477969626SruEscapes may occur anywhere in the input to @code{gtroff}. They usually 478069626Srubegin with a backslash and are followed by a single character which 478169626Sruindicates the function to be performed. The escape character can be 478269626Sruchanged; see @ref{Character Translations}. 478355839Sasmodai 478469626SruEscape sequences which require an identifier as a parameter accept three 478569626Srupossible syntax forms. 478655839Sasmodai 478769626Sru@itemize @bullet 478869626Sru@item 478969626SruThe next single character is the identifier. 479055839Sasmodai 4791104862Sru@cindex @code{(}, starting a two-character identifier 479269626Sru@item 479369626SruIf this single character is an opening parenthesis, take the following 479469626Srutwo characters as the identifier. Note that there is no closing 479569626Sruparenthesis after the identifier. 479669626Sru 4797104862Sru@cindex @code{[}, starting an identifier 4798104862Sru@cindex @code{]}, ending an identifier 479969626Sru@item 480069626SruIf this single character is an opening bracket, take all characters 480169626Sruuntil a closing bracket as the identifier. 480269626Sru@end itemize 480369626Sru 480469626Sru@noindent 480569626SruExamples: 480669626Sru 480775584Sru@Example 480855839Sasmodai\fB 480955839Sasmodai\n(XX 481055839Sasmodai\*[TeX] 481175584Sru@endExample 481255839Sasmodai 4813104862Sru@cindex @code{'}, delimiting arguments 481469626Sru@cindex argument delimiting characters 481569626Sru@cindex characters, argument delimiting 481669626Sru@cindex delimiting characters for arguments 481769626SruOther escapes may require several arguments and/or some special format. 481869626SruIn such cases the argument is traditionally enclosed in single quotes 481969626Sru(and quotes are always used in this manual for the definitions of escape 482069626Srusequences). The enclosed text is then processed according to what that 482169626Sruescape expects. Example: 482255839Sasmodai 482375584Sru@Example 482455839Sasmodai\l'1.5i\(bu' 482575584Sru@endExample 482655839Sasmodai 4827104862Sru@cindex @code{\o}, possible quote characters 4828104862Sru@cindex @code{\b}, possible quote characters 4829104862Sru@cindex @code{\X}, possible quote characters 483069626SruNote that the quote character can be replaced with any other character 483169626Sruwhich does not occur in the argument (even a newline or a space 483269626Srucharacter) in the following escapes: @code{\o}, @code{\b}, and 483369626Sru@code{\X}. This makes e.g. 483469626Sru 483575584Sru@Example 483669626SruA caf 483769626Sru\o 483869626Srue\' 483969626Sru 484069626Sru 484169626Sruin Paris 484269626Sru @result{} A caf@'e in Paris 484375584Sru@endExample 484469626Sru 484569626Sru@noindent 484669626Srupossible, but it is better not to use this feature to avoid confusion. 484769626Sru 4848104862Sru@cindex @code{\%}, used as delimiter 4849104862Sru@cindex @code{\@key{SP}}, used as delimiter 4850104862Sru@cindex @code{\|}, used as delimiter 4851104862Sru@cindex @code{\^}, used as delimiter 4852104862Sru@cindex @code{\@{}, used as delimiter 4853104862Sru@cindex @code{\@}}, used as delimiter 4854104862Sru@cindex @code{\'}, used as delimiter 4855104862Sru@cindex @code{\`}, used as delimiter 4856104862Sru@cindex @code{\-}, used as delimiter 4857104862Sru@cindex @code{\_}, used as delimiter 4858104862Sru@cindex @code{\!}, used as delimiter 4859104862Sru@cindex @code{\?}, used as delimiter 4860104862Sru@cindex @code{\@@}, used as delimiter 4861104862Sru@cindex @code{\)}, used as delimiter 4862104862Sru@cindex @code{\/}, used as delimiter 4863104862Sru@cindex @code{\,}, used as delimiter 4864104862Sru@cindex @code{\&}, used as delimiter 4865104862Sru@ifnotinfo 4866104862Sru@cindex @code{\:}, used as delimiter 4867104862Sru@end ifnotinfo 4868104862Sru@ifinfo 4869104862Sru@cindex @code{\@r{<colon>}}, used as delimiter 4870104862Sru@end ifinfo 4871104862Sru@cindex @code{\~}, used as delimiter 4872104862Sru@cindex @code{\0}, used as delimiter 4873104862Sru@cindex @code{\a}, used as delimiter 4874104862Sru@cindex @code{\c}, used as delimiter 4875104862Sru@cindex @code{\d}, used as delimiter 4876104862Sru@cindex @code{\e}, used as delimiter 4877104862Sru@cindex @code{\E}, used as delimiter 4878104862Sru@cindex @code{\p}, used as delimiter 4879104862Sru@cindex @code{\r}, used as delimiter 4880104862Sru@cindex @code{\t}, used as delimiter 4881104862Sru@cindex @code{\u}, used as delimiter 488269626SruThe following escapes sequences (which are handled similarly to 488369626Srucharacters since they don't take a parameter) are also allowed as 488469626Srudelimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 488569626Sru@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 488669626Sru@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 4887104862Sru@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, 4888104862Sru@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. 4889104862SruAgain, don't use these if possible. 489069626Sru 4891104862Sru@cindex @code{\A}, allowed delimiters 4892104862Sru@cindex @code{\B}, allowed delimiters 4893104862Sru@cindex @code{\Z}, allowed delimiters 4894104862Sru@cindex @code{\C}, allowed delimiters 4895104862Sru@cindex @code{\w}, allowed delimiters 489669626SruNo newline characters as delimiters are allowed in the following 4897104862Sruescapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}. 489869626Sru 4899104862Sru@cindex @code{\D}, allowed delimiters 4900104862Sru@cindex @code{\h}, allowed delimiters 4901104862Sru@cindex @code{\H}, allowed delimiters 4902104862Sru@cindex @code{\l}, allowed delimiters 4903104862Sru@cindex @code{\L}, allowed delimiters 4904104862Sru@cindex @code{\N}, allowed delimiters 4905104862Sru@cindex @code{\R}, allowed delimiters 4906104862Sru@cindex @code{\s}, allowed delimiters 4907104862Sru@cindex @code{\S}, allowed delimiters 4908104862Sru@cindex @code{\v}, allowed delimiters 4909104862Sru@cindex @code{\x}, allowed delimiters 491069626SruFinally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 4911104862Sru@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, 4912104862Sruand @code{\x} can't use the following characters as delimiters: 491369626Sru 491469626Sru@itemize @bullet 491569626Sru@item 4916104862Sru@cindex numbers, and delimiters 4917104862Sru@cindex digits, and delimiters 491869626SruThe digits @code{0}-@code{9}. 491969626Sru 492069626Sru@item 4921104862Sru@cindex operators, as delimiters 4922104862Sru@cindex @code{+}, as delimiter 4923104862Sru@cindex @code{-}, as delimiter 4924104862Sru@cindex @code{/}, as delimiter 4925104862Sru@cindex @code{*}, as delimiter 4926104862Sru@cindex @code{%}, as delimiter 4927104862Sru@cindex @code{<}, as delimiter 4928104862Sru@cindex @code{>}, as delimiter 4929104862Sru@cindex @code{=}, as delimiter 4930104862Sru@cindex @code{&}, as delimiter 4931104862Sru@ifnotinfo 4932104862Sru@cindex @code{:}, as delimiter 4933104862Sru@end ifnotinfo 4934104862Sru@ifinfo 4935104862Sru@cindex <colon>, as delimiter 4936104862Sru@end ifinfo 4937104862Sru@cindex @code{(}, as delimiter 4938104862Sru@cindex @code{)}, as delimiter 4939104862Sru@cindex @code{.}, as delimiter 494069626SruThe (single-character) operators @samp{+-/*%<>=&:().}. 494169626Sru 494269626Sru@item 494369626Sru@cindex space character 494469626Sru@cindex character, space 494569626Sru@cindex tab character 494669626Sru@cindex character, tab 494769626Sru@cindex newline character 494869626Sru@cindex character, newline 494969626SruThe space, tab, and newline characters. 495069626Sru 495169626Sru@item 4952104862Sru@cindex @code{\%}, used as delimiter 4953104862Sru@ifnotinfo 4954104862Sru@cindex @code{\:}, used as delimiter 4955104862Sru@end ifnotinfo 4956104862Sru@ifinfo 4957104862Sru@cindex @code{\@r{<colon>}}, used as delimiter 4958104862Sru@end ifinfo 4959104862Sru@cindex @code{\@{}, used as delimiter 4960104862Sru@cindex @code{\@}}, used as delimiter 4961104862Sru@cindex @code{\'}, used as delimiter 4962104862Sru@cindex @code{\`}, used as delimiter 4963104862Sru@cindex @code{\-}, used as delimiter 4964104862Sru@cindex @code{\_}, used as delimiter 4965104862Sru@cindex @code{\!}, used as delimiter 4966104862Sru@cindex @code{\@@}, used as delimiter 4967104862Sru@cindex @code{\/}, used as delimiter 4968104862Sru@cindex @code{\c}, used as delimiter 4969104862Sru@cindex @code{\e}, used as delimiter 4970104862Sru@cindex @code{\p}, used as delimiter 4971104862SruAll escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}}, 497269626Sru@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 497369626Sru@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 497469626Sru@end itemize 497569626Sru 4976104862Sru@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 4977104862Sru@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 497875584SruTo have a backslash (actually, the current escape character) appear in the 497969626Sruoutput several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 498055839SasmodaiThese are very similar, and only differ with respect to being used in 4981104862Srumacros or diversions. @xref{Character Translations}, for an exact 4982104862Srudescription of those escapes. 498355839Sasmodai 4984104862Sru@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions}, 4985104862Sru@ref{Identifiers}, for more information. 498655839Sasmodai 498755839Sasmodai@menu 498875584Sru* Comments:: 498955839Sasmodai@end menu 499055839Sasmodai 499155839Sasmodai@node Comments, , Escapes, Escapes 499255839Sasmodai@subsubsection Comments 499355839Sasmodai@cindex comments 499455839Sasmodai 499555839SasmodaiProbably one of the most@footnote{Unfortunately, this is a lie. But 499669626Sruhopefully future @code{gtroff} hackers will believe it @code{:-)}} 499755839Sasmodaicommon forms of escapes is the comment. 499855839Sasmodai 499975584Sru@Defesc {\\", , , } 500069626SruStart a comment. Everything to the end of the input line is ignored. 500169626Sru 500255839SasmodaiThis may sound simple, but it can be tricky to keep the comments from 500369626Sruinterfering with the appearance of the final output. 500455839Sasmodai 5005104862Sru@cindex @code{ds}, @code{ds1} requests, and comments 5006104862Sru@cindex @code{as}, @code{as1} requests, and comments 500775584SruIf the escape is to the right of some text or a request, that portion 500875584Sruof the line is ignored, but the space leading up to it is noticed by 5009104862Sru@code{gtroff}. This only affects the @code{ds} and @code{as} 5010104862Srurequest and its variants. 501155839Sasmodai 5012104862Sru@cindex tabs, before comments 501369626Sru@cindex comments, lining up with tabs 501469626SruOne possibly irritating idiosyncracy is that tabs must not be used to 5015104862Sruline up comments. Tabs are not treated as whitespace between the 501669626Srurequest and macro arguments. 501755839Sasmodai 501869626Sru@cindex undefined request 501969626Sru@cindex request, undefined 502075584SruA comment on a line by itself is treated as a blank line, because 502169626Sruafter eliminating the comment, that is all that remains: 502255839Sasmodai 502375584Sru@Example 502469626SruTest 502569626Sru\" comment 502669626SruTest 502775584Sru@endExample 502869626Sru 502969626Sru@noindent 503075584Sruproduces 503169626Sru 503275584Sru@Example 503369626SruTest 503469626Sru 503569626SruTest 503675584Sru@endExample 503769626Sru 503875584SruTo avoid this, it is common to start the line with @code{.\"} which 503975584Srucauses the line to be treated as an undefined request and thus ignored 504075584Srucompletely. 504169626Sru 5042104862Sru@cindex @code{'}, as a comment 504355839SasmodaiAnother commenting scheme seen sometimes is three consecutive single 504469626Sruquotes (@code{'''}) at the beginning of a line. This works, but 504575584Sru@code{gtroff} gives a warning about an undefined macro (namely 504669626Sru@code{''}), which is harmless, but irritating. 504775584Sru@endDefesc 504855839Sasmodai 504975584Sru@Defesc {\\#, , , } 505075584SruTo avoid all this, @code{gtroff} has a new comment mechanism using the 505175584Sru@code{\#} escape. This escape works the same as @code{\"} except that 505275584Sruthe newline is also ignored: 505355839Sasmodai 505475584Sru@Example 505569626SruTest 505669626Sru\# comment 505769626SruTest 505875584Sru@endExample 505969626Sru 506069626Sru@noindent 506175584Sruproduces 506269626Sru 506375584Sru@Example 506469626SruTest Test 506575584Sru@endExample 506669626Sru 506769626Sru@noindent 506869626Sruas expected. 506975584Sru@endDefesc 507069626Sru 507175584Sru@Defreq {ig, yy} 507275584SruIgnore all input until @code{gtroff} encounters the macro named 507375584Sru@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not 507475584Sruspecified). This is useful for commenting out large blocks of text: 507555839Sasmodai 507675584Sru@Example 507775584Srutext text text... 507875584Sru.ig 507975584SruThis is part of a large block 508075584Sruof text that has been 508175584Srutemporarily(?) commented out. 508269626Sru 508375584SruWe can restore it simply by removing 508475584Sruthe .ig request and the ".." at the 508575584Sruend of the block. 508675584Sru.. 508775584SruMore text text text... 508875584Sru@endExample 508969626Sru 509075584Sru@noindent 509175584Sruproduces 509269626Sru 509375584Sru@Example 509475584Srutext text text@dots{} More text text text@dots{} 509575584Sru@endExample 509675584Sru 509775584Sru@noindent 509875584SruNote that the commented-out block of text does not 509975584Srucause a break. 510075584Sru 510175584SruThe input is read in copy-mode; auto-incremented registers @emph{are} 510275584Sruaffected (@pxref{Auto-increment}). 510375584Sru@endDefreq 510475584Sru 510575584Sru 510669626Sru@c ===================================================================== 510769626Sru 510875584Sru@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 510955839Sasmodai@section Registers 511055839Sasmodai@cindex registers 511155839Sasmodai 511269626SruNumeric variables in @code{gtroff} are called @dfn{registers}. There 511369626Sruare a number of built-in registers, supplying anything from the date to 511469626Srudetails of formatting parameters. 511555839Sasmodai 511669626Sru@xref{Identifiers}, for details on register identifiers. 511755839Sasmodai 511855839Sasmodai@menu 511975584Sru* Setting Registers:: 512075584Sru* Interpolating Registers:: 512175584Sru* Auto-increment:: 512275584Sru* Assigning Formats:: 512375584Sru* Built-in Registers:: 512455839Sasmodai@end menu 512555839Sasmodai 512669626Sru@c --------------------------------------------------------------------- 512769626Sru 512855839Sasmodai@node Setting Registers, Interpolating Registers, Registers, Registers 512955839Sasmodai@subsection Setting Registers 5130104862Sru@cindex setting registers (@code{nr}, @code{\R}) 5131104862Sru@cindex registers, setting (@code{nr}, @code{\R}) 513255839Sasmodai 513375584SruDefine or set registers using the @code{nr} request or the 513469626Sru@code{\R} escape. 513555839Sasmodai 5136104862Sru@DefreqList {nr, ident value} 5137104862Sru@DefescListEnd {\\R, ', ident value, '} 513875584SruSet number register @var{ident} to @var{value}. If @var{ident} 513975584Srudoesn't exist, @code{gtroff} creates it. 514055839Sasmodai 514175584SruThe argument to @code{\R} usually has to be enclosed in quotes. 514269626Sru@xref{Escapes}, for details on parameter delimiting characters. 5143104862Sru 5144104862SruThe @code{\R} escape doesn't produce an input token in @code{gtroff}; 5145104862Sruwith other words, it vanishes completely after @code{gtroff} has 5146104862Sruprocessed it. 514775584Sru@endDefreq 514869626Sru 514969626SruFor example, the following two lines are equivalent: 515069626Sru 515175584Sru@Example 5152104862Sru.nr a (((17 + (3 * 4))) % 4) 5153104862Sru\R'a (((17 + (3 * 4))) % 4)' 5154104862Sru @result{} 1 515575584Sru@endExample 515655839Sasmodai 515769626SruBoth @code{nr} and @code{\R} have two additional special forms to 515875584Sruincrement or decrement a register. 515955839Sasmodai 5160104862Sru@DefreqList {nr, ident @t{+}@Var{value}} 5161104862Sru@DefreqItem {nr, ident @t{-}@Var{value}} 5162104862Sru@DefescItem {\\R, ', ident @t{+}@Var{value}, '} 5163104862Sru@DefescListEnd {\\R, ', ident @t{-}@Var{value}, '} 516469626SruIncrement (decrement) register @var{ident} by @var{value}. 516555839Sasmodai 516675584Sru@Example 516769626Sru.nr a 1 516869626Sru.nr a +1 516969626Sru\na 517069626Sru @result{} 2 517175584Sru@endExample 517255839Sasmodai 517369626Sru@cindex negating register values 517469626SruTo assign the negated value of a register to another register, some care 517569626Srumust be taken to get the desired result: 517655839Sasmodai 517775584Sru@Example 517869626Sru.nr a 7 517969626Sru.nr b 3 518069626Sru.nr a -\nb 518169626Sru\na 518269626Sru @result{} 4 518369626Sru.nr a (-\nb) 518469626Sru\na 518569626Sru @result{} -3 518675584Sru@endExample 518769626Sru 518869626Sru@noindent 518969626SruThe surrounding parentheses prevent the interpretation of the minus sign 519069626Sruas a decrementing operator. An alternative is to start the assignment 519169626Sruwith a @samp{0}: 519269626Sru 519375584Sru@Example 519469626Sru.nr a 7 519569626Sru.nr b -3 519669626Sru.nr a \nb 519769626Sru\na 519869626Sru @result{} 4 519969626Sru.nr a 0\nb 520069626Sru\na 520169626Sru @result{} -3 520275584Sru@endExample 520375584Sru@endDefreq 520469626Sru 520575584Sru@Defreq {rr, ident} 5206104862Sru@cindex removing number register (@code{rr}) 5207104862Sru@cindex number register, removing (@code{rr}) 5208104862Sru@cindex register, removing (@code{rr}) 520969626SruRemove number register @var{ident}. If @var{ident} doesn't exist, the 521069626Srurequest is ignored. 521175584Sru@endDefreq 521269626Sru 521375584Sru@Defreq {rnn, ident1 ident2} 5214104862Sru@cindex renaming number register (@code{rnn}) 5215104862Sru@cindex number register, renaming (@code{rnn}) 5216104862Sru@cindex register, renaming (@code{rnn}) 521769626SruRename number register @var{ident1} to @var{ident2}. If either 521869626Sru@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 521975584Sru@endDefreq 522069626Sru 522175584Sru@Defreq {aln, ident1 ident2} 5222104862Sru@cindex alias, number register, creating (@code{aln}) 5223104862Sru@cindex creating alias, for number register (@code{aln}) 5224104862Sru@cindex number register, creating alias (@code{aln}) 5225104862Sru@cindex register, creating alias (@code{aln}) 522675584SruCreate an alias @var{ident1} for a number register @var{ident2}. The 522775584Srunew name and the old name are exactly equivalent. If @var{ident1} is 522875584Sruundefined, a warning of type @samp{reg} is generated, and the request 522975584Sruis ignored. @xref{Debugging}, for information about warnings. 523075584Sru@endDefreq 523169626Sru 523269626Sru@c --------------------------------------------------------------------- 523369626Sru 523455839Sasmodai@node Interpolating Registers, Auto-increment, Setting Registers, Registers 523555839Sasmodai@subsection Interpolating Registers 5236104862Sru@cindex interpolating registers (@code{\n}) 5237104862Sru@cindex registers, interpolating (@code{\n}) 523855839Sasmodai 523969626SruNumeric registers can be accessed via the @code{\n} escape. 524055839Sasmodai 5241104862Sru@DefescList {\\n, , i, } 5242104862Sru@DefescItem {\\n, @lparen{}, id, } 5243104862Sru@DefescListEnd {\\n, @lbrack{}, ident, @rbrack} 524475584Sru@cindex nested assignments 524575584Sru@cindex assignments, nested 524675584Sru@cindex indirect assignments 524775584Sru@cindex assignments, indirect 5248104862SruInterpolate number register with name @var{ident} (one-character name@w{ 5249104862Sru}@var{i}, two-character name @var{id}). This means that the value of the 5250104862Sruregister is expanded in-place while @code{gtroff} is parsing the input line. 5251104862SruNested assignments (also called indirect assignments) are possible. 525255839Sasmodai 525375584Sru@Example 525469626Sru.nr a 5 525555839Sasmodai.nr as \na+\na 525655839Sasmodai\n(as 525769626Sru @result{} 10 525875584Sru@endExample 525955839Sasmodai 526075584Sru@Example 526175584Sru.nr a1 5 526275584Sru.nr ab 6 526375584Sru.ds str b 526475584Sru.ds num 1 526575584Sru\n[a\n[num]] 526675584Sru @result{} 5 526775584Sru\n[a\*[str]] 526875584Sru @result{} 6 526975584Sru@endExample 527075584Sru@endDefesc 527175584Sru 527269626Sru@c --------------------------------------------------------------------- 527355839Sasmodai 527455839Sasmodai@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 527555839Sasmodai@subsection Auto-increment 527655839Sasmodai@cindex auto-increment 527755839Sasmodai@cindex increment, automatic 527855839Sasmodai 527975584SruNumber registers can also be auto-incremented and auto-decremented. 528075584SruThe increment or decrement value can be specified with a third 528169626Sruargument to the @code{nr} request or @code{\R} escape. 528255839Sasmodai 528375584Sru@Defreq {nr, ident value incr} 5284104862Sru@cindex @code{\R}, difference to @code{nr} 528569626SruSet number register @var{ident} to @var{value}; the increment for 528675584Sruauto-incrementing is set to @var{incr}. Note that the @code{\R} 528775584Sruescape doesn't support this notation. 528875584Sru@endDefreq 528969626Sru 529075584SruTo activate auto-incrementing, the escape @code{\n} has a special 529175584Srusyntax form. 529269626Sru 5293104862Sru@DefescList {\\n, +, i, } 5294104862Sru@DefescItem {\\n, -, i, } 5295104862Sru@DefescItem {\\n, @lparen{}+, id, } 5296104862Sru@DefescItem {\\n, @lparen{}-, id, } 5297104862Sru@DefescItem {\\n, +@lparen{}, id, } 5298104862Sru@DefescItem {\\n, -@lparen{}, id, } 5299104862Sru@DefescItem {\\n, @lbrack{}+, ident, @rbrack{}} 5300104862Sru@DefescItem {\\n, @lbrack{}-, ident, @rbrack{}} 5301104862Sru@DefescItem {\\n, +@lbrack{}, ident, @rbrack{}} 5302104862Sru@DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}} 530375584SruBefore interpolating, increment or decrement @var{ident} 5304104862Sru(one-character name@w{ }@var{i}, two-character name @var{id}) by the 530569626Sruauto-increment value as specified with the @code{nr} request (or the 530675584Sru@code{\R} escape). If no auto-increment value has been specified, 530775584Sruthese syntax forms are identical to @code{\n}. 530875584Sru@endDefesc 530969626Sru 531069626SruFor example, 531169626Sru 531275584Sru@Example 531355839Sasmodai.nr a 0 1 531455839Sasmodai.nr xx 0 5 531569626Sru.nr foo 0 -2 531655839Sasmodai\n+a, \n+a, \n+a, \n+a, \n+a 531755839Sasmodai.br 531869626Sru\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 531969626Sru.br 532069626Sru\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 532175584Sru@endExample 532255839Sasmodai 532369626Sru@noindent 532469626Sruproduces 532555839Sasmodai 532675584Sru@Example 532755839Sasmodai1, 2, 3, 4, 5 532869626Sru-5, -10, -15, -20, -25 532969626Sru-2, -4, -6, -8, -10 533075584Sru@endExample 533155839Sasmodai 533269626Sru@cindex increment value without changing the register 5333104862Sru@cindex value, incrementing without changing the register 533475584SruTo change the increment value without changing the value of a register 533575584Sru(@var{a} in the example), the following can be used: 533655839Sasmodai 533775584Sru@Example 533855839Sasmodai.nr a \na 10 533975584Sru@endExample 534055839Sasmodai 534169626Sru@c --------------------------------------------------------------------- 534255839Sasmodai 534369626Sru@node Assigning Formats, Built-in Registers, Auto-increment, Registers 534455839Sasmodai@subsection Assigning Formats 5345104862Sru@cindex assigning formats (@code{af}) 5346104862Sru@cindex formats, assigning (@code{af}) 534755839Sasmodai 534875584SruWhen a register is used in the text of an input file (as opposed to 534975584Srupart of an expression), it is textually replaced (or interpolated) 535075584Sruwith a representation of that number. This output format can be 535175584Sruchanged to a variety of formats (numbers, Roman numerals, etc.). This 535275584Sruis done using the @code{af} request. 535355839Sasmodai 535475584Sru@Defreq {af, ident format} 535569626SruChange the output format of a number register. The first argument 535669626Sru@var{ident} is the name of the number register to be changed, and the 535775584Srusecond argument @var{format} is the output format. The following 535875584Sruoutput formats are available: 535955839Sasmodai 536069626Sru@table @code 536155839Sasmodai@item 1 536275584SruDecimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{ 536369626Sru}@enddots{} 536469626Sru 536569626Sru@item 0@dots{}0 536669626SruDecimal numbers with as many digits as specified. So, @samp{00} would 536769626Sruresult in printing numbers as 01, 02, 03,@w{ }@enddots{} 536869626Sru 536969626SruIn fact, any digit instead of zero will do; @code{gtroff} only counts 537069626Sruhow many digits are specified. As a consequence, @code{af}'s default 537169626Sruformat @samp{1} could be specified as @samp{0} also (and exactly this is 537269626Srureturned by the @code{\g} escape, see below). 537369626Sru 537455839Sasmodai@item I 537575584Sru@cindex Roman numerals 537669626Sru@cindex numerals, Roman 537769626SruUpper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{} 537869626Sru 537955839Sasmodai@item i 538069626SruLower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{} 538169626Sru 538255839Sasmodai@item A 538375584SruUpper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{} 538469626Sru 538555839Sasmodai@item a 538675584SruLower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{} 538755839Sasmodai@end table 538855839Sasmodai 538975584SruOmitting the number register format causes a warning of type 539069626Sru@samp{missing}. @xref{Debugging}, for more details. Specifying a 539169626Srunonexistent format causes an error. 539255839Sasmodai 539375584SruThe following example produces @samp{10, X, j, 010}: 539469626Sru 539575584Sru@Example 539655839Sasmodai.nr a 10 539755839Sasmodai.af a 1 \" the default format 539855839Sasmodai\na, 539955839Sasmodai.af a I 540055839Sasmodai\na, 540155839Sasmodai.af a a 540255839Sasmodai\na, 540355839Sasmodai.af a 001 540455839Sasmodai\na 540575584Sru@endExample 540655839Sasmodai 540775584Sru@cindex Roman numerals, maximum and minimum 540869626Sru@cindex maximum values of Roman numerals 540969626Sru@cindex minimum values of Roman numerals 541069626SruThe largest number representable for the @samp{i} and @samp{I} formats 541175584Sruis 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 541275584Sruand @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 541369626Sru@code{gtroff}. Currently, the correct glyphs of Roman numeral five 541469626Sruthousand and Roman numeral ten thousand (Unicode code points 541569626Sru@code{U+2182} and @code{U+2181}, respectively) are not available. 541655839Sasmodai 541775584SruIf @var{ident} doesn't exist, it is created. 541855839Sasmodai 541969626Sru@cindex read-only register, changing format 5420104862Sru@cindex changing format, and read-only registers 542169626SruChanging the output format of a read-only register causes an error. It 542269626Sruis necessary to first copy the register's value to a writeable register, 542369626Sruthen apply the @code{af} request to this other register. 542475584Sru@endDefreq 542555839Sasmodai 5426104862Sru@DefescList {\\g, , i, } 5427104862Sru@DefescItem {\\g, @lparen{}, id, } 5428104862Sru@DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}} 5429104862Sru@cindex format of register (@code{\g}) 5430104862Sru@cindex register, format (@code{\g}) 543175584SruReturn the current format of the specified register @var{ident} 5432104862Sru(one-character name@w{ }@var{i}, two-character name @var{id}). For 543375584Sruexample, @samp{\ga} after the previous example would produce the 543475584Srustring @samp{000}. If the register hasn't been defined yet, nothing 543575584Sruis returned. 543675584Sru@endDefesc 543755839Sasmodai 543869626Sru@c --------------------------------------------------------------------- 543955839Sasmodai 544069626Sru@node Built-in Registers, , Assigning Formats, Registers 544169626Sru@subsection Built-in Registers 544269626Sru@cindex built-in registers 544369626Sru@cindex registers, built-in 544455839Sasmodai 544569626SruThe following lists some built-in registers which are not described 544669626Sruelsewhere in this manual. Any register which begins with a @samp{.} is 544769626Sruread-only. A complete listing of all built-in registers can be found in 5448104862Sruappendix@w{ }@ref{Register Index}. 544969626Sru 545055839Sasmodai@table @code 5451104862Sru@item .F 5452104862Sru@cindex current input file name register (@code{.F}) 5453104862Sru@cindex input file name, current, register (@code{.F}) 5454104862Sru@vindex .F 5455104862SruThis string-valued register returns the current input file name. 5456104862Sru 545755839Sasmodai@item .H 5458104862Sru@cindex horizontal resolution register (@code{.H}) 5459104862Sru@cindex resolution, horizontal, register (@code{.H}) 546055839Sasmodai@vindex .H 546155839SasmodaiHorizontal resolution in basic units. 546269626Sru 546355839Sasmodai@item .V 5464104862Sru@cindex vertical resolution register (@code{.V}) 5465104862Sru@cindex resolution, vertical, register (@code{.V}) 546655839Sasmodai@vindex .V 546755839SasmodaiVertical resolution in basic units. 546869626Sru 5469104862Sru@item seconds 5470104862Sru@cindex seconds, current time (@code{seconds}) 5471104862Sru@cindex time, current, seconds (@code{seconds}) 5472104862Sru@cindex current time, seconds (@code{seconds}) 5473104862Sru@vindex seconds 5474104862SruThe number of seconds after the minute, normally in the range@w{ }0 5475104862Sruto@w{ }59, but can be up to@w{ }61 to allow for leap seconds. Initialized 5476104862Sruat start-up of @code{gtroff}. 5477104862Sru 5478104862Sru@item minutes 5479104862Sru@cindex minutes, current time (@code{minutes}) 5480104862Sru@cindex time, current, minutes (@code{minutes}) 5481104862Sru@cindex current time, minutes (@code{minutes}) 5482104862Sru@vindex minutes 5483104862SruThe number of minutes after the hour, in the range@w{ }0 to@w{ }59. 5484104862SruInitialized at start-up of @code{gtroff}. 5485104862Sru 5486104862Sru@item hours 5487104862Sru@cindex hours, current time (@code{hours}) 5488104862Sru@cindex time, current, hours (@code{hours}) 5489104862Sru@cindex current time, hours (@code{hours}) 5490104862Sru@vindex hours 5491104862SruThe number of hours past midnight, in the range@w{ }0 to@w{ }23. 5492104862SruInitialized at start-up of @code{gtroff}. 5493104862Sru 549455839Sasmodai@item dw 5495104862Sru@cindex day of the week register (@code{dw}) 5496104862Sru@cindex date, day of the week register (@code{dw}) 549755839Sasmodai@vindex dw 549855839SasmodaiDay of the week (1-7). 549969626Sru 550055839Sasmodai@item dy 5501104862Sru@cindex day of the month register (@code{dy}) 5502104862Sru@cindex date, day of the month register (@code{dy}) 550355839Sasmodai@vindex dy 550469626SruDay of the month (1-31). 550569626Sru 550655839Sasmodai@item mo 5507104862Sru@cindex month of the year register (@code{mo}) 5508104862Sru@cindex date, month of the year register (@code{mo}) 550955839Sasmodai@vindex mo 551055839SasmodaiCurrent month (1-12). 551169626Sru 551269626Sru@item year 5513104862Sru@cindex date, year register (@code{year}, @code{yr}) 5514104862Sru@cindex year, current, register (@code{year}, @code{yr}) 551569626Sru@vindex year 551669626SruThe current year. 551769626Sru 551855839Sasmodai@item yr 551955839Sasmodai@vindex yr 552069626SruThe current year minus@w{ }1900. Unfortunately, the documentation of 552169626Sru@acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It 552269626Sruincorrectly claimed that @code{yr} contains the last two digits of the 5523104862Sruyear. That claim has never been true of either @acronym{AT&T} 5524104862Sru@code{troff} or GNU @code{troff}. Old @code{troff} input that looks 5525104862Srulike this: 552669626Sru 552775584Sru@Example 552869626Sru'\" The following line stopped working after 1999 552969626SruThis document was formatted in 19\n(yr. 553075584Sru@endExample 553169626Sru 553269626Sru@noindent 553369626Srucan be corrected as follows: 553469626Sru 553575584Sru@Example 553669626SruThis document was formatted in \n[year]. 553775584Sru@endExample 553869626Sru 553969626Sru@noindent 554069626Sruor, to be portable to older @code{troff} versions, as follows: 554169626Sru 554275584Sru@Example 554369626Sru.nr y4 1900+\n(yr 554469626SruThis document was formatted in \n(y4. 554575584Sru@endExample 554669626Sru 554755839Sasmodai@item .c 554855839Sasmodai@vindex .c 554955839Sasmodai@itemx c. 555055839Sasmodai@vindex c. 5551104862Sru@cindex input line number register (@code{.c}, @code{c.}) 5552104862Sru@cindex line number, input, register (@code{.c}, @code{c.}) 555369626SruThe current @emph{input} line number. Register @samp{.c} is read-only, 555469626Sruwhereas @samp{c.} (a @code{gtroff} extension) is writable also, 555569626Sruaffecting both @samp{.c} and @samp{c.}. 555669626Sru 555755839Sasmodai@item ln 555855839Sasmodai@vindex ln 5559104862Sru@cindex output line number register (@code{ln}) 5560104862Sru@cindex line number, output, register (@code{ln}) 556169626SruThe current @emph{output} line number after a call to the @code{nm} 556269626Srurequest to activate line numbering. 556369626Sru 556475584Sru@xref{Miscellaneous}, for more information about line numbering. 556569626Sru 556655839Sasmodai@item .x 556755839Sasmodai@vindex .x 5568104862Sru@cindex major version number register (@code{.x}) 5569104862Sru@cindex version number, major, register (@code{.x}) 557069626SruThe major version number. For example, if the version number is@w{ 557175584Sru}1.03 then @code{.x} contains@w{ }@samp{1}. 557269626Sru 557355839Sasmodai@item .y 557455839Sasmodai@vindex .y 5575104862Sru@cindex minor version number register (@code{.y}) 5576104862Sru@cindex version number, minor, register (@code{.y}) 557769626SruThe minor version number. For example, if the version number is@w{ 557875584Sru}1.03 then @code{.y} contains@w{ }@samp{03}. 557969626Sru 558069626Sru@item .Y 558169626Sru@vindex .Y 5582104862Sru@cindex revision number register (@code{.Y}) 558369626SruThe revision number of @code{groff}. 558469626Sru 5585104862Sru@item $$ 5586104862Sru@vindex $$ 5587104862Sru@cindex process ID of @code{gtroff} register (@code{$$}) 5588104862Sru@cindex @code{gtroff}, process ID register (@code{$$}) 5589104862SruThe process ID of @code{gtroff}. 5590104862Sru 559155839Sasmodai@item .g 559255839Sasmodai@vindex .g 5593104862Sru@cindex @code{gtroff}, identification register (@code{.g}) 5594104862Sru@cindex GNU-specific register (@code{.g}) 559569626SruAlways@w{ }1. Macros should use this to determine whether they are 559669626Srurunning under GNU @code{troff}. 559769626Sru 559855839Sasmodai@item .A 559955839Sasmodai@vindex .A 5600104862Sru@cindex @acronym{ASCII} approximation output register (@code{.A}) 560169626SruIf the command line option @option{-a} is used to produce an 560269626Sru@acronym{ASCII} approximation of the output, this is set to@w{ }1, zero 560369626Sruotherwise. @xref{Groff Options}. 560469626Sru 560555839Sasmodai@item .P 560655839Sasmodai@vindex .P 560769626SruThis register is set to@w{ }1 (and to@w{ }0 otherwise) if the current 560869626Srupage is actually being printed, i.e., if the @option{-o} option is being 560969626Sruused to only print selected pages. @xref{Groff Options}, for more 561069626Sruinformation. 561169626Sru 561269626Sru@item .T 561369626Sru@vindex .T 561469626SruIf @code{gtroff} is called with the @option{-T} command line option, the 561569626Srunumber register @code{.T} is set to@w{ }1, and zero otherwise. 561669626Sru@xref{Groff Options}. 561769626Sru 561875584Sru@stindex .T 5619104862Sru@cindex output device name string register (@code{.T}) 562075584SruAdditionally, @code{gtroff} predefines a single read-write string 562169626Sruregister @code{.T} which contains the current output device (for 562269626Sruexample, @samp{latin1} or @samp{ps}). 562355839Sasmodai@end table 562455839Sasmodai 562569626Sru 562669626Sru@c ===================================================================== 562769626Sru 562875584Sru@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 562955839Sasmodai@section Manipulating Filling and Adjusting 563055839Sasmodai@cindex manipulating filling and adjusting 563155839Sasmodai@cindex filling and adjusting, manipulating 563255839Sasmodai@cindex adjusting and filling, manipulating 563369626Sru@cindex justifying text 563469626Sru@cindex text, justifying 563555839Sasmodai 563655839Sasmodai@cindex break 563755839Sasmodai@cindex line break 5638104862Sru@cindex @code{bp} request, causing implicit linebreak 5639104862Sru@cindex @code{ce} request, causing implicit linebreak 5640104862Sru@cindex @code{cf} request, causing implicit linebreak 5641104862Sru@cindex @code{fi} request, causing implicit linebreak 5642104862Sru@cindex @code{fl} request, causing implicit linebreak 5643104862Sru@cindex @code{in} request, causing implicit linebreak 5644104862Sru@cindex @code{nf} request, causing implicit linebreak 5645104862Sru@cindex @code{rj} request, causing implicit linebreak 5646104862Sru@cindex @code{sp} request, causing implicit linebreak 5647104862Sru@cindex @code{ti} request, causing implicit linebreak 5648104862Sru@cindex @code{trf} request, causing implicit linebreak 564969626SruVarious ways of causing @dfn{breaks} were given in @ref{Implicit Line 565075584SruBreaks}. The @code{br} request likewise causes a break. Several 565175584Sruother requests also cause breaks, but implicitly. These are 565269626Sru@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 565369626Sru@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 565455839Sasmodai 565575584Sru@Defreq {br, } 565675584SruBreak the current line, i.e., the input collected so far is emitted 565769626Sruwithout adjustment. 565869626Sru 565975584SruIf the no-break control character is used, @code{gtroff} suppresses 566075584Sruthe break: 566169626Sru 566275584Sru@Example 566369626Srua 566469626Sru'br 566569626Srub 566669626Sru @result{} a b 566775584Sru@endExample 566875584Sru@endDefreq 566969626Sru 567075584SruInitially, @code{gtroff} fills and adjusts text to both margins. 567169626SruFilling can be disabled via the @code{nf} request and re-enabled with 567269626Sruthe @code{fi} request. 567369626Sru 5674104862Sru@DefreqList {fi, } 5675104862Sru@DefregListEnd {.u} 5676104862Sru@cindex fill mode (@code{fi}) 5677104862Sru@cindex mode, fill (@code{fi}) 567869626SruActivate fill mode (which is the default). This request implicitly 567975584Sruenables adjusting; it also inserts a break in the text currently being 568075584Srufilled. The read-only number register @code{.u} is set to@w{ }1. 568155839Sasmodai 568269626SruThe fill mode status is associated with the current environment 568369626Sru(@pxref{Environments}). 5684104862Sru 5685104862SruSee @ref{Line Control}, for interaction with the @code{\c} escape. 568675584Sru@endDefreq 568755839Sasmodai 568875584Sru@Defreq {nf, } 5689104862Sru@cindex no-fill mode (@code{nf}) 5690104862Sru@cindex mode, no-fill (@code{nf}) 569169626SruActivate no-fill mode. Input lines are output as-is, retaining line 569275584Srubreaks and ignoring the current line length. This command implicitly 569375584Srudisables adjusting; it also causes a break. The number register 569475584Sru@code{.u} is set to@w{ }0. 569569626Sru 569669626SruThe fill mode status is associated with the current environment 569769626Sru(@pxref{Environments}). 5698104862Sru 5699104862SruSee @ref{Line Control}, for interaction with the @code{\c} escape. 570075584Sru@endDefreq 570169626Sru 5702104862Sru@DefreqList {ad, [@Var{mode}]} 5703104862Sru@DefregListEnd {.j} 570469626SruSet adjusting mode. 570569626Sru 570675584SruActivation and deactivation of adjusting is done implicitly with 570775584Srucalls to the @code{fi} or @code{nf} requests. 570869626Sru 570969626Sru@var{mode} can have one of the following values: 571069626Sru 571169626Sru@table @code 571255839Sasmodai@item l 571355839Sasmodai@cindex ragged-right 571455839SasmodaiAdjust text to the left margin. This produces what is traditionally 571555839Sasmodaicalled ragged-right text. 571669626Sru 571755839Sasmodai@item r 571869626Sru@cindex ragged-left 571969626SruAdjust text to the right margin, producing ragged-left text. 572069626Sru 572155839Sasmodai@item c 572269626Sru@cindex centered text 5723104862Sru@cindex @code{ce} request, difference to @samp{.ad@w{ }c} 572469626SruCenter filled text. This is different to the @code{ce} request which 572569626Sruonly centers text without filling. 572669626Sru 572755839Sasmodai@item b 572855839Sasmodai@itemx n 572969626SruJustify to both margins. This is the default used by @code{gtroff}. 573055839Sasmodai@end table 573155839Sasmodai 573275584SruWith no argument, @code{gtroff} adjusts lines in the same way it did 573375584Srubefore adjusting was deactivated (with a call to @code{na}, for 573469626Sruexample). 573555839Sasmodai 573675584Sru@Example 573755839Sasmodaitext 573855839Sasmodai.ad r 573955839Sasmodaitext 574055839Sasmodai.ad c 574155839Sasmodaitext 574255839Sasmodai.na 574355839Sasmodaitext 574455839Sasmodai.ad \" back to centering 574555839Sasmodaitext 574675584Sru@endExample 574755839Sasmodai 5748104862Sru@cindex adjustment mode register (@code{.j}) 574975584SruThe current adjustment mode is available in the read-only number 575075584Sruregister @code{.j}; it can be stored and subsequently used to set 575175584Sruadjustment. 575255839Sasmodai 575369626SruThe adjustment mode status is associated with the current environment 575469626Sru(@pxref{Environments}). 575575584Sru@endDefreq 575655839Sasmodai 575775584Sru@Defreq {na, } 575869626SruDisable adjusting. This request won't change the current adjustment 575975584Srumode: A subsequent call to @code{ad} uses the previous adjustment 576069626Srusetting. 576155839Sasmodai 576269626SruThe adjustment mode status is associated with the current environment 576369626Sru(@pxref{Environments}). 576475584Sru@endDefreq 576569626Sru 5766104862Sru@DefreqList {brp, } 5767104862Sru@DefescListEnd {\\p, , , } 576869626SruAdjust the current line and cause a break. 576969626Sru 5770104862SruIn most cases this produces very ugly results since @code{gtroff} 577169626Srudoesn't have a sophisticated paragraph building algorithm (as @TeX{} 577275584Sruhave, for example); instead, @code{gtroff} fills and adjusts a paragraph 577369626Sruline by line: 577469626Sru 577575584Sru@Example 577669626Sru This is an uninteresting sentence. 577769626Sru This is an uninteresting sentence.\p 577869626Sru This is an uninteresting sentence. 577975584Sru@endExample 578069626Sru 578175584Sru@noindent 578269626Sruis formatted as 578369626Sru 578475584Sru@Example 578569626Sru This is an uninteresting sentence. This is an 578669626Sru uninteresting sentence. 578769626Sru This is an uninteresting sentence. 578875584Sru@endExample 5789104862Sru@endDefreq 579069626Sru 5791104862Sru@DefreqList {ss, word_space_size [@Var{sentence_space_size}]} 5792104862Sru@DefregItem {.ss} 5793104862Sru@DefregListEnd {.sss} 5794104862Sru@cindex word space size register (@code{.ss}) 5795104862Sru@cindex size of word space register (@code{.ss}) 5796104862Sru@cindex space between words register (@code{.ss}) 5797104862Sru@cindex sentence space size register (@code{.sss}) 5798104862Sru@cindex size of sentence space register (@code{.sss}) 5799104862Sru@cindex space between sentences register (@code{.sss}) 580069626SruChange the minimum size of a space between filled words. It takes its 580175584Sruunits as one twelfth of the space width parameter for the current 580275584Srufont. Initially both the @var{word_space_size} and 580375584Sru@var{sentence_space_size} are@w{ }12. 580469626Sru 580569626Sru@cindex fill mode 580669626Sru@cindex mode, fill 580775584SruIf two arguments are given to the @code{ss} request, the second 580875584Sruargument sets the sentence space size. If the second argument is not 580975584Srugiven, sentence space size is set to @var{word_space_size}. The 581075584Srusentence space size is used in two circumstances: If the end of a 581175584Srusentence occurs at the end of a line in fill mode, then both an 581275584Sruinter-word space and a sentence space are added; if two spaces follow 581375584Sruthe end of a sentence in the middle of a line, then the second space 581475584Sruis a sentence space. If a second argument is never given to the 581575584Sru@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 581675584Srusame as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 581775584Sruin @acronym{UNIX} @code{troff}, a sentence should always be followed 581875584Sruby either a newline or two spaces. 581969626Sru 582075584SruThe read-only number registers @code{.ss} and @code{.sss} hold the 582175584Sruvalues of the parameters set by the first and second arguments of the 582275584Sru@code{ss} request. 582355839Sasmodai 582469626SruThe word space and sentence space values are associated with the current 582569626Sruenvironment (@pxref{Environments}). 582655839Sasmodai 5827104862SruContrary to @acronym{AT&T} @code{troff}, this request is @emph{not} 5828104862Sruignored if a TTY output device is used; the given values are then 5829104862Srurounded down to a multiple of@w{ }12 (@pxref{Implementation Differences}). 583055839Sasmodai 583175584SruThe request is ignored if there is no parameter. 583275584Sru@endDefreq 583375584Sru 5834104862Sru@DefreqList {ce, [@Var{nnn}]} 5835104862Sru@DefregListEnd {.ce} 5836104862Sru@cindex centering lines (@code{ce}) 5837104862Sru@cindex lines, centering (@code{ce}) 583875584SruCenter text. While the @w{@samp{.ad c}} request also centers text, 583975584Sruit fills the text as well. @code{ce} does not fill the 5840104862Srutext it affects. This request causes a break. The number of lines 5841104862Srustill to be centered is associated with the current environment 5842104862Sru(@pxref{Environments}). 584355839Sasmodai 584475584SruThe following example demonstrates the differences. 584575584SruHere the input: 584669626Sru 584775584Sru@Example 584875584Sru.ll 4i 584975584Sru.ce 1000 585075584SruThis is a small text fragment which shows the differences 585175584Srubetween the `.ce' and the `.ad c' request. 585275584Sru.ce 0 585375584Sru 585475584Sru.ad c 585575584SruThis is a small text fragment which shows the differences 585675584Srubetween the `.ce' and the `.ad c' request. 585775584Sru@endExample 585875584Sru 585975584Sru@noindent 586075584SruAnd here the result: 586175584Sru 586275584Sru@Example 586375584Sru This is a small text fragment which 586475584Sru shows the differences 586575584Srubetween the `.ce' and the `.ad c' request. 586675584Sru 586775584Sru This is a small text fragment which 586875584Srushows the differences between the `.ce' 586975584Sru and the `.ad c' request. 587075584Sru@endExample 587175584Sru 587275584SruWith no arguments, @code{ce} centers the next line of text. @var{nnn} 587375584Sruspecifies the number of lines to be centered. If the argument is zero 587475584Sruor negative, centering is disabled. 587575584Sru 587669626SruThe basic length for centering text is the line length (as set with the 587769626Sru@code{ll} request) minus the indentation (as set with the @code{in} 587869626Srurequest). Temporary indentation is ignored. 587969626Sru 588075584SruAs can be seen in the previous example, it is a common idiom to turn 588175584Sruon centering for a large number of lines, and to turn off centering 588275584Sruafter text to be centered. This is useful for any request which takes 588375584Srua number of lines as an argument. 588469626Sru 588575584SruThe @code{.ce} read-only number register contains the number of lines 588675584Sruremaining to be centered, as set by the @code{ce} request. 588775584Sru@endDefreq 588855839Sasmodai 5889104862Sru@DefreqList {rj, [@Var{nnn}]} 5890104862Sru@DefregListEnd {.rj} 5891104862Sru@cindex justifying text (@code{rj}) 5892104862Sru@cindex text, justifying (@code{rj}) 5893104862Sru@cindex right-justifying (@code{rj}) 589469626SruJustify unfilled text to the right margin. Arguments are identical to 589575584Sruthe @code{ce} request. The @code{.rj} read-only number register is 589675584Sruthe number of lines to be right-justified as set by the @code{rj} 5897104862Srurequest. This request causes a break. The number of lines still to be 5898104862Sruright-justified is associated with the current environment 5899104862Sru(@pxref{Environments}). 590075584Sru@endDefreq 590155839Sasmodai 590255839Sasmodai 590369626Sru@c ===================================================================== 590455839Sasmodai 590575584Sru@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 590655839Sasmodai@section Manipulating Hyphenation 590755839Sasmodai@cindex manipulating hyphenation 590855839Sasmodai@cindex hyphenation, manipulating 590955839Sasmodai 591075584SruAs discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words. 591169626SruThere are a number of ways to influence hyphenation. 591255839Sasmodai 5913104862Sru@DefreqList {hy, [@Var{mode}]} 5914104862Sru@DefregListEnd {.hy} 591569626SruEnable hyphenation. The request has an optional numeric argument, 591669626Sru@var{mode}, to restrict hyphenation if necessary: 591755839Sasmodai 591869626Sru@table @code 591969626Sru@item 1 592069626SruThe default argument if @var{mode} is omitted. Hyphenate without 592169626Srurestrictions. This is also the start-up value of @code{gtroff}. 592255839Sasmodai 592355839Sasmodai@item 2 592455839SasmodaiDo not hyphenate the last word on a page or column. 592569626Sru 592655839Sasmodai@item 4 592755839SasmodaiDo not hyphenate the last two characters of a word. 592869626Sru 592955839Sasmodai@item 8 593055839SasmodaiDo not hyphenate the first two characters of a word. 593155839Sasmodai@end table 593255839Sasmodai 593369626SruValues in the previous table are additive. For example, the value@w{ 593469626Sru}12 causes @code{gtroff} to neither hyphenate the last two nor the first 593569626Srutwo characters of a word. 593669626Sru 5937104862Sru@cindex hyphenation restrictions register (@code{.hy}) 593875584SruThe current hyphenation restrictions can be found in the read-only 593975584Srunumber register @samp{.hy}. 594069626Sru 594169626SruThe hyphenation mode is associated with the current environment 594269626Sru(@pxref{Environments}). 594375584Sru@endDefreq 594469626Sru 594575584Sru@Defreq {nh, } 594675584SruDisable hyphenation (i.e., set the hyphenation mode to zero). Note 594775584Sruthat the hyphenation mode of the last call to @code{hy} is not 594875584Sruremembered. 594969626Sru 595069626SruThe hyphenation mode is associated with the current environment 595169626Sru(@pxref{Environments}). 595275584Sru@endDefreq 595369626Sru 5954104862Sru@DefreqList {hlm, [@Var{nnn}]} 5955104862Sru@DefregItem {.hlm} 5956104862Sru@DefregListEnd {.hlc} 5957104862Sru@cindex explicit hyphen (@code{\%}) 5958104862Sru@cindex hyphen, explicit (@code{\%}) 5959104862Sru@cindex consecutive hyphenated lines (@code{hlm}) 5960104862Sru@cindex lines, consecutive hyphenated (@code{hlm}) 5961104862Sru@cindex hyphenated lines, consecutive (@code{hlm}) 596275584SruSet the maximum number of consecutive hyphenated lines to @var{nnn}. 596375584SruIf this number is negative, there is no maximum. The default value 596475584Sruis@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated 596575584Sruwith the current environment (@pxref{Environments}). Only lines 596675584Sruoutput from a given environment count towards the maximum associated 596775584Sruwith that environment. Hyphens resulting from @code{\%} are counted; 596875584Sruexplicit hyphens are not. 596955839Sasmodai 597069626SruThe current setting of @code{hlm} is available in the @code{.hlm} 597175584Sruread-only number register. Also the number of immediately preceding 597275584Sruconsecutive hyphenated lines are available in the read-only number 597375584Sruregister @samp{.hlc}. 597475584Sru@endDefreq 597555839Sasmodai 597675584Sru@Defreq {hw, word1 word2 @dots{}} 597769626SruDefine how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 597869626Sruwords must be given with hyphens at the hyphenation points. For 597969626Sruexample: 598069626Sru 598175584Sru@Example 598269626Sru.hw in-sa-lub-rious 598375584Sru@endExample 598469626Sru 598569626Sru@noindent 598669626SruBesides the space character, any character whose hyphenation code value 598769626Sruis zero can be used to separate the arguments of @code{hw} (see the 598869626Srudocumentation for the @code{hcode} request below for more information). 598969626SruIn addition, this request can be used more than once. 599069626Sru 599169626SruHyphenation exceptions specified with the @code{hw} request are 599275584Sruassociated with the current hyphenation language; it causes an error 599369626Sruif there is no current hyphenation language. 599469626Sru 599569626SruThis request is ignored if there is no parameter. 599669626Sru 599769626SruIn old versions of @code{troff} there was a limited amount of space to 599869626Srustore such information; fortunately, with @code{gtroff}, this is no 599969626Srulonger a restriction. 600075584Sru@endDefreq 600169626Sru 6002104862Sru@DefescList {\\%, , , } 6003104862Sru@deffnx Escape @t{\:} 6004104862Sru@ifnotinfo 6005104862Sru@esindex \: 6006104862Sru@end ifnotinfo 6007104862Sru@ifinfo 6008104862Sru@esindex @r{<colon>} 6009104862Sru@end ifinfo 6010104862Sru@cindex hyphenation character (@code{\%}) 6011104862Sru@cindex character, hyphenation (@code{\%}) 6012104862Sru@cindex disabling hyphenation (@code{\%}) 6013104862Sru@cindex hyphenation, disabling (@code{\%}) 601475584SruTo tell @code{gtroff} how to hyphenate words on the fly, use the 601575584Sru@code{\%} escape, also known as the @dfn{hyphenation character}. 601675584SruPreceding a word with this character prevents it from being 601775584Sruhyphenated; putting it inside a word indicates to @code{gtroff} that 601875584Sruthe word may be hyphenated at that point. Note that this mechanism 601975584Sruonly affects that one occurrence of the word; to change the 602075584Sruhyphenation of a word for the entire document, use the @code{hw} 602175584Srurequest. 6022104862Sru 6023104862SruThe @code{\:} escape inserts a zero-width break point 6024104862Sru(that is, the word breaks but without adding a hyphen). 6025104862Sru 6026104862Sru@Example 6027104862Sru... check the /var/log/\:httpd/\:access_log file ... 6028104862Sru@endExample 6029104862Sru 6030104862Sru@cindex @code{\X}, followed by @code{\%} 6031104862Sru@cindex @code{\Y}, followed by @code{\%} 6032104862Sru@cindex @code{\%}, following @code{\X} or @code{\Y} 6033104862SruNote that @code{\X} and @code{\Y} start a word, that is, the @code{\%} 6034104862Sruescape in (say) @w{@samp{ \X'...'\%foobar}} and 6035104862Sru@w{@samp{ \Y'...'\%foobar}} no longer prevents hyphenation but inserts 6036104862Srua hyphenation point at the beginning of @samp{foobar}; most likely 6037104862Sruthis isn't what you want to do. 603875584Sru@endDefesc 603955839Sasmodai 604075584Sru@Defreq {hc, [@Var{char}]} 604175584SruChange the hyphenation character to @var{char}. This character then 604275584Sruworks the same as the @code{\%} escape, and thus, no longer appears in 604375584Sruthe output. Without an argument, @code{hc} resets the hyphenation 604475584Srucharacter to be @code{\%} (the default) only. 604555839Sasmodai 604669626SruThe hyphenation character is associated with the current environment 604769626Sru(@pxref{Environments}). 604875584Sru@endDefreq 604955839Sasmodai 6050104862Sru@DefreqList {hpf, pattern_file} 6051104862Sru@DefreqItem {hpfa, pattern_file} 6052104862Sru@DefreqListEnd {hpfcode, a b [c d @dots{}]} 6053104862Sru@cindex hyphenation patterns (@code{hpf}) 6054104862Sru@cindex patterns for hyphenation (@code{hpf}) 605575584SruRead in a file of hyphenation patterns. This file is searched for in 605675584Sruthe same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 605775584Srusearched for if the @option{-m@var{name}} option is specified. 605855839Sasmodai 6059104862SruIt should have the same format as (simple) @TeX{} patterns files. 6060104862SruMore specifically, the following scanning rules are implemented. 606169626Sru 6062104862Sru@itemize @bullet 6063104862Sru@item 6064104862SruA percent sign starts a comment (up to the end of the line) 6065104862Srueven if preceded by a backslash. 6066104862Sru 6067104862Sru@item 6068104862SruNo support for `digraphs' like @code{\$}. 6069104862Sru 6070104862Sru@item 6071104862Sru@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character 6072104862Srucode of @var{x} in the range 0-127) are recognized; other use of @code{^} 6073104862Srucauses an error. 6074104862Sru 6075104862Sru@item 6076104862SruNo macro expansion. 6077104862Sru 6078104862Sru@item 6079104862Sru@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} 6080104862Sru(possibly with whitespace before and after the braces). 6081104862SruEverything between the braces is taken as hyphenation patterns. 6082104862SruConsequently, @code{@{} and @code{@}} are not allowed in patterns. 6083104862Sru 6084104862Sru@item 6085104862SruSimilarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation 6086104862Sruexceptions. 6087104862Sru 6088104862Sru@item 6089104862Sru@code{\endinput} is recognized also. 6090104862Sru 6091104862Sru@item 6092104862SruFor backwards compatibility, if @code{\patterns} is missing, 6093104862Sruthe whole file is treated as a list of hyphenation patterns 6094104862Sru(only recognizing the @code{%} character as the start of a comment). 6095104862Sru@end itemize 6096104862Sru 609769626SruIf no @code{hpf} request is specified (either in the document or in a 609869626Srumacro package), @code{gtroff} won't hyphenate at all. 609969626Sru 6100104862SruThe @code{hpfa} request appends a file of patterns to the current list. 6101104862Sru 6102104862SruThe @code{hpfcode} request defines mapping values for character codes in 6103104862Sruhyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping 6104104862Sru(after reading the patterns) before replacing or appending them to 6105104862Sruthe current list of patterns. Its arguments are pairs of character codes 6106104862Sru-- integers from 0 to@w{ }255. The request maps character code@w{ }@var{a} 6107104862Sruto code@w{ }@var{b}, code@w{ }@var{c} to code@w{ }@var{d}, and so on. You 6108104862Srucan use character codes which would be invalid otherwise. 6109104862Sru 611055839Sasmodai@pindex troffrc 611169626Sru@pindex troffrc-end 611269626Sru@pindex hyphen.us 611369626SruThe set of hyphenation patterns is associated with the current language 611469626Sruset by the @code{hla} request. The @code{hpf} request is usually 611569626Sruinvoked by the @file{troffrc} or @file{troffrc-end} file; by default, 611669626Sru@file{troffrc} loads hyphenation patterns for American English (in file 611769626Sru@file{hyphen.us}). 611855839Sasmodai 6119104862SruA second call to @code{hpf} (for the same language) will replace the 6120104862Sruhyphenation patterns with the new ones. 6121104862Sru 612275584SruInvoking @code{hpf} causes an error if there is no current hyphenation 612369626Srulanguage. 612475584Sru@endDefreq 612555839Sasmodai 612675584Sru@Defreq {hcode, c1 code1 c2 code2 @dots{}} 6127104862Sru@cindex hyphenation code (@code{hcode}) 6128104862Sru@cindex code, hyphenation (@code{hcode}) 612975584SruSet the hyphenation code of character @var{c1} to @var{code1}, that of 613075584Sru@var{c2} to @var{code2}, etc. A hyphenation code must be a single 613175584Sruinput character (not a special character) other than a digit or a 613275584Sruspace. Initially each lower-case letter (@samp{a}-@samp{z}) has its 6133104862Sruhyphenation code set to itself, and each upper-case letter 613475584Sru(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case 613575584Sruversion of itself. 613669626Sru 613775584SruThis request is ignored if it has no parameter. 613875584Sru@endDefreq 613969626Sru 6140104862Sru@DefreqList {hym, [@Var{length}]} 6141104862Sru@DefregListEnd {.hym} 6142104862Sru@cindex hyphenation margin (@code{hym}) 6143104862Sru@cindex margin for hyphenation (@code{hym}) 6144104862Sru@cindex @code{ad} request, and hyphenation margin 614569626SruSet the (right) hyphenation margin to @var{length}. If the current 6146104862Sruadjustment mode is not @samp{b} or @samp{n}, the line is not 614775584Sruhyphenated if it is shorter than @var{length}. Without an argument, 614875584Sruthe hyphenation margin is reset to its default value, which is@w{ }0. 6149104862SruThe default scaling indicator for this request is @samp{m}. The 615075584Sruhyphenation margin is associated with the current environment 615169626Sru(@pxref{Environments}). 615269626Sru 615375584SruA negative argument resets the hyphenation margin to zero, emitting 615469626Srua warning of type @samp{range}. 615569626Sru 6156104862Sru@cindex hyphenation margin register (@code{.hym}) 615775584SruThe current hyphenation margin is available in the @code{.hym} read-only 615875584Srunumber register. 615975584Sru@endDefreq 616055839Sasmodai 6161104862Sru@DefreqList {hys, [@Var{hyphenation_space}]} 6162104862Sru@DefregListEnd {.hys} 6163104862Sru@cindex hyphenation space (@code{hys}) 6164104862Sru@cindex @code{ad} request, and hyphenation space 616569626SruSet the hyphenation space to @var{hyphenation_space}. If the current 6166104862Sruadjustment mode is @samp{b} or @samp{n}, don't hyphenate the line 616775584Sruif it can be justified by adding no more than @var{hyphenation_space} 616875584Sruextra space to each word space. Without argument, the hyphenation 616975584Sruspace is set to its default value, which is@w{ }0. The default 6170104862Sruscaling indicator for this request is @samp{m}. The hyphenation 617175584Sruspace is associated with the current environment 617275584Sru(@pxref{Environments}). 617369626Sru 617475584SruA negative argument resets the hyphenation space to zero, emitting a 617569626Sruwarning of type @samp{range}. 617669626Sru 6177104862Sru@cindex hyphenation space register (@code{.hys}) 617875584SruThe current hyphenation space is available in the @code{.hys} read-only 617975584Srunumber register. 618075584Sru@endDefreq 618155839Sasmodai 6182104862Sru@Defreq {shc, [@Var{glyph}]} 6183104862Sru@cindex soft hyphen character, setting (@code{shc}) 6184104862Sru@cindex character, soft hyphen, setting (@code{shc}) 6185104862Sru@cindex glyph, soft hyphen (@code{hy}) 6186104862Sru@cindex soft hyphen glyph (@code{hy}) 6187104862Sru@cindex @code{char} request, and soft hyphen character 6188104862Sru@cindex @code{tr} request, and soft hyphen character 6189104862SruSet the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft 6190104862Sruhyphen character} is a misnomer since it is an output glyph.} If the 6191104862Sruargument is omitted, the soft hyphen character is set to the default 6192104862Sruglyph @code{\(hy} (this is the start-up value of @code{gtroff} also). 6193104862SruThe soft hyphen character is the glyph that is inserted when a word is 619475584Sruhyphenated at a line break. If the soft hyphen character does not 619575584Sruexist in the font of the character immediately preceding a potential 619675584Srubreak point, then the line is not broken at that point. Neither 619755839Sasmodaidefinitions (specified with the @code{char} request) nor translations 619869626Sru(specified with the @code{tr} request) are considered when finding the 619969626Srusoft hyphen character. 620075584Sru@endDefreq 620155839Sasmodai 6202104862Sru@DefreqList {hla, language} 6203104862Sru@DefregListEnd {.hla} 6204104862Sru@cindex @code{hpf} request, and hyphenation language 6205104862Sru@cindex @code{hw} request, and hyphenation language 620655839Sasmodai@pindex troffrc 620769626Sru@pindex troffrc-end 620869626SruSet the current hyphenation language to the string @var{language}. 620969626SruHyphenation exceptions specified with the @code{hw} request and 6210104862Sruhyphenation patterns specified with the @code{hpf} and @code{hpfa} 6211104862Srurequests are both associated with the current hyphenation language. 6212104862SruThe @code{hla} request is usually invoked by the @file{troffrc} or the 621369626Sru@file{troffrc-end} files; @file{troffrc} sets the default language to 621469626Sru@samp{us}. 621555839Sasmodai 6216104862Sru@cindex hyphenation language register (@code{.hla}) 621769626SruThe current hyphenation language is available as a string in the 621869626Sruread-only number register @samp{.hla}. 621955839Sasmodai 622075584Sru@Example 622169626Sru.ds curr_language \n[.hla] 622269626Sru\*[curr_language] 622369626Sru @result{} us 622475584Sru@endExample 622575584Sru@endDefreq 622655839Sasmodai 622769626Sru 622869626Sru@c ===================================================================== 622969626Sru 623075584Sru@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 623155839Sasmodai@section Manipulating Spacing 623255839Sasmodai@cindex manipulating spacing 623355839Sasmodai@cindex spacing, manipulating 623455839Sasmodai 623575584Sru@Defreq {sp, [@Var{distance}]} 623675584SruSpace downwards @var{distance}. With no argument it advances 1@w{ 623775584Sru}line. A negative argument causes @code{gtroff} to move up the page 623869626Sruthe specified distance. If the argument is preceded by a @samp{|} 623975584Sruthen @code{gtroff} moves that distance from the top of the page. This 6240104862Srurequest causes a line break. The default scaling indicator is @samp{v}. 624175584Sru@endDefreq 624255839Sasmodai 6243104862Sru@DefreqList {ls, [@Var{nnn}]} 6244104862Sru@DefregListEnd {.L} 6245104862Sru@cindex double-spacing (@code{ls}) 624675584SruOutput @w{@var{nnn}@minus{}1} blank lines after each line of text. 624775584SruWith no argument, @code{gtroff} uses the previous value before the 624875584Srulast @code{ls} call. 624955839Sasmodai 625075584Sru@Example 625169626Sru.ls 2 \" This causes double-spaced output 625269626Sru.ls 3 \" This causes triple-spaced output 6253104862Sru.ls \" Again double-spaced 625475584Sru@endExample 625569626Sru 625669626SruThe line spacing is associated with the current environment 625769626Sru(@pxref{Environments}). 625869626Sru 6259104862Sru@cindex line spacing register (@code{.L}) 626075584SruThe read-only number register @code{.L} contains the current line 626175584Sruspacing setting. 626275584Sru@endDefreq 626355839Sasmodai 6264104862Sru@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} 6265104862Sruas alternatives to @code{ls}. 626675584Sru 6267104862Sru@DefescList {\\x, ', spacing, '} 6268104862Sru@DefregListEnd {.a} 626975584SruSometimes, extra vertical spacing is only needed occasionally, e.g.@: 627075584Sruto allow space for a tall construct (like an equation). The @code{\x} 627175584Sruescape does this. The escape is given a numerical argument, usually 627269626Sruenclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 6273104862Sruis @samp{v}. If this number is positive extra vertical space is 627475584Sruinserted below the current line. A negative number adds space above. 627575584SruIf this escape is used multiple times on the same line, the maximum of 627675584Sruthe values is used. 627769626Sru 627869626Sru@xref{Escapes}, for details on parameter delimiting characters. 627969626Sru 6280104862Sru@cindex extra post-vertical line space register (@code{.a}) 628175584SruThe @code{.a} read-only number register contains the most recent 628275584Sru(nonnegative) extra vertical line space. 628355839Sasmodai 6284104862SruUsing @code{\x} can be necessary in combination with the @code{\b} 6285104862Sruescape, as the following example shows. 6286104862Sru 628775584Sru@Example 6288104862SruThis is a test with the \[rs]b escape. 6289104862Sru.br 6290104862SruThis is a test with the \[rs]b escape. 6291104862Sru.br 6292104862SruThis is a test with \b'xyz'\x'-1m'\x'1m'. 6293104862Sru.br 6294104862SruThis is a test with the \[rs]b escape. 6295104862Sru.br 6296104862SruThis is a test with the \[rs]b escape. 629775584Sru@endExample 6298104862Sru 6299104862Sru@noindent 6300104862Sruproduces 6301104862Sru 6302104862Sru@Example 6303104862SruThis is a test with the \b escape. 6304104862SruThis is a test with the \b escape. 6305104862Sru x 6306104862SruThis is a test with y. 6307104862Sru z 6308104862SruThis is a test with the \b escape. 6309104862SruThis is a test with the \b escape. 6310104862Sru@endExample 631175584Sru@endDefesc 631255839Sasmodai 6313104862Sru@DefreqList {ns, } 6314104862Sru@DefreqItem {rs, } 6315104862Sru@DefregListEnd {.ns} 6316104862Sru@cindex @code{sp} request, and no-space mode 6317104862Sru@cindex no-space mode (@code{ns}) 6318104862Sru@cindex mode, no-space (@code{ns}) 631969626Sru@cindex blank lines, disabling 632069626Sru@cindex lines, blank, disabling 632175584SruEnable @dfn{no-space mode}. In this mode, spacing (either via 632275584Sru@code{sp} or via blank lines) is disabled. The @code{bp} request to 632375584Sruadvance to the next page is also disabled, except if it is accompanied 632475584Sruby a page number (see @ref{Page Control}, for more information). This 632575584Srumode ends when actual text is output or the @code{rs} request is 6326104862Sruencountered which ends no-space mode. The read-only number register 6327104862Sru@code{.ns} is set to@w{ }1 as long as no-space mode is active. 632855839Sasmodai 6329104862SruThis request is useful for macros that conditionally 6330104862Sruinsert vertical space before the text starts 6331104862Sru(for example, a paragraph macro could insert some space 6332104862Sruexcept when it is the first paragraph after a section header). 633375584Sru@endDefreq 633469626Sru 633569626Sru 633669626Sru@c ===================================================================== 633769626Sru 633875584Sru@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 633955839Sasmodai@section Tabs and Fields 6340104862Sru@cindex tabs, and fields 6341104862Sru@cindex fields, and tabs 634255839Sasmodai 634369626Sru@cindex @acronym{EBCDIC} encoding of a tab 634469626SruA tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{ 634569626Sru}5) causes a horizontal movement to the next tab stop (much 634669626Srulike it did on a typewriter). 634755839Sasmodai 634875584Sru@Defesc {\\t, , , } 6349104862Sru@cindex tab character, non-interpreted (@code{\t}) 6350104862Sru@cindex character, tab, non-interpreted (@code{\t}) 635169626SruThis escape is a non-interpreted tab character. In copy mode 635269626Sru(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 635375584Sru@endDefesc 635455839Sasmodai 6355104862Sru@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 6356104862Sru@DefregListEnd {.tabs} 635769626SruChange tab stop positions. This request takes a series of tab 635869626Sruspecifiers as arguments (optionally divided into two groups with the 635975584Sruletter @samp{T}) which indicate where each tab stop is to be 636075584Sru(overriding any previous settings). 636155839Sasmodai 636269626SruTab stops can be specified absolutely, i.e., as the distance from the 636375584Sruleft margin. For example, the following sets 6@w{ }tab stops every 636469626Sruone inch. 636569626Sru 636675584Sru@Example 636755839Sasmodai.ta 1i 2i 3i 4i 5i 6i 636875584Sru@endExample 636955839Sasmodai 637075584SruTab stops can also be specified using a leading @samp{+} 637175584Sruwhich means that the specified tab stop is set relative to 637269626Sruthe previous tab stop. For example, the following is equivalent to the 637369626Sruprevious example. 637455839Sasmodai 637575584Sru@Example 637655839Sasmodai.ta 1i +1i +1i +1i +1i +1i 637775584Sru@endExample 637855839Sasmodai 637969626Sru@code{gtroff} supports an extended syntax to specify repeat values after 638069626Sruthe @samp{T} mark (these values are always taken as relative) -- this is 638169626Sruthe usual way to specify tabs set at equal intervals. The following is, 638269626Sruyet again, the same as the previous examples. It does even more since 638369626Sruit defines an infinite number of tab stops separated by one inch. 638455839Sasmodai 638575584Sru@Example 638655839Sasmodai.ta T 1i 638775584Sru@endExample 638855839Sasmodai 638969626SruNow we are ready to interpret the full syntax given at the beginning: 639069626SruSet tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 639169626Srutabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 639269626Sruand then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 639369626Sru@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 639455839Sasmodai 639569626SruExample: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 639669626Sru20c 23c 28c 30c @dots{}}. 639769626Sru 639869626SruThe material in each tab column (i.e., the column between two tab stops) 639969626Srumay be justified to the right or left or centered in the column. This 640069626Sruis specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 640169626Sruspecifier. The default justification is @samp{L}. Example: 640269626Sru 640375584Sru@Example 6404104862Sru.ta 1i 2iC 3iR 640575584Sru@endExample 640655839Sasmodai 640769626SruSome notes: 640869626Sru 640969626Sru@itemize @bullet 641069626Sru@item 641169626SruThe default unit of the @code{ta} request is @samp{m}. 641269626Sru 641369626Sru@item 641469626SruA tab stop is converted into a non-breakable horizontal movement which 641569626Srucan be neither stretched nor squeezed. For example, 641669626Sru 641775584Sru@Example 641869626Sru.ds foo a\tb\tc 641969626Sru.ta T 5i 642069626Sru\*[foo] 642175584Sru@endExample 642269626Sru 642369626Sru@noindent 642469626Srucreates a single line which is a bit longer than 10@w{ }inches (a string 642569626Sruis used to show exactly where the tab characters are). Now consider the 642669626Srufollowing: 642769626Sru 642875584Sru@Example 642969626Sru.ds bar a\tb b\tc 643069626Sru.ta T 5i 643169626Sru\*[bar] 643275584Sru@endExample 643369626Sru 643469626Sru@noindent 643569626Sru@code{gtroff} first converts the tab stops of the line into unbreakable 643669626Sruhorizontal movements, then splits the line after the second @samp{b} 643769626Sru(assuming a sufficiently short line length). Usually, this isn't what 643869626Sruthe user wants. 643969626Sru 644069626Sru@item 644169626SruSuperfluous tabs (i.e., tab characters which do not correspond to a tab 644269626Srustop) are ignored except the first one which delimits the characters 644375584Srubelonging to the last tab stop for right-justifying or centering. 644469626SruConsider the following example 644569626Sru 644675584Sru@Example 644769626Sru.ds Z foo\tbar\tfoo 644869626Sru.ds ZZ foo\tbar\tfoobar 644969626Sru.ds ZZZ foo\tbar\tfoo\tbar 645069626Sru.ta 2i 4iR 645169626Sru\*[Z] 645269626Sru.br 645369626Sru\*[ZZ] 645469626Sru.br 645569626Sru\*[ZZZ] 645669626Sru.br 645775584Sru@endExample 645869626Sru 645969626Sru@noindent 646069626Sruwhich produces the following output: 646169626Sru 646275584Sru@Example 646369626Srufoo bar foo 646469626Srufoo bar foobar 646569626Srufoo bar foobar 646675584Sru@endExample 646769626Sru 646869626Sru@noindent 646969626SruThe first line right-justifies the second `foo' relative to the tab 647069626Srustop. The second line right-justifies `foobar'. The third line finally 647169626Sruright-justifies only `foo' because of the additional tab character which 647269626Srumarks the end of the string belonging to the last defined tab stop. 647369626Sru 647469626Sru@item 647569626SruTab stops are associated with the current environment 647669626Sru(@pxref{Environments}). 647769626Sru 647869626Sru@item 647975584SruCalling @code{ta} without an argument removes all tab stops. 648069626Sru 648169626Sru@item 6482104862Sru@cindex tab stops, for TTY output devices 6483104862SruThe start-up value of @code{gtroff} is @w{@samp{T 0.5i}} in troff mode 6484104862Sruand @w{@samp{T 0.8i}} in nroff mode (the latter is done with an 6485104862Sruexplicit call to the @code{ta} request in the file @file{tty.tmac}. 648669626Sru@end itemize 648769626Sru 6488104862Sru@cindex tab settings register (@code{.tabs}) 648975584SruThe read-only number register @code{.tabs} contains a string 649075584Srurepresentation of the current tab settings suitable for use as an 649175584Sruargument to the @code{ta} request. 649255839Sasmodai 649375584Sru@Example 649469626Sru.ds tab-string \n[.tabs] 649569626Sru\*[tab-string] 649669626Sru @result{} T120u 649775584Sru@endExample 6498104862Sru 6499104862Sru@cindex @code{.S} register, Plan@w{ }9 alias for @code{.tabs} 6500104862Sru@cindex @code{.tabs} register, Plan@w{ }9 alias (@code{.S}) 6501104862SruThe @code{troff} version of the Plan@w{ }9 operating system uses 6502104862Sruregister @code{.S} for the same purpose. 650375584Sru@endDefreq 650455839Sasmodai 6505104862Sru@Defreq {tc, [@Var{fill-glyph}]} 6506104862Sru@cindex tab repetition character (@code{tc}) 6507104862Sru@cindex character, tab repetition (@code{tc}) 6508104862Sru@cindex glyph, tab repetition (@code{tc}) 650975584SruNormally @code{gtroff} fills the space to the next tab stop with 651075584Sruwhitespace. This can be changed with the @code{tc} request. With no 651175584Sruargument @code{gtroff} reverts to using whitespace, which is the 6512104862Srudefault. The value of this @dfn{tab repetition character} is 6513104862Sruassociated with the current environment 6514104862Sru(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a 6515104862Srumisnomer since it is an output glyph.} 651675584Sru@endDefreq 651769626Sru 6518104862Sru@DefreqList {linetabs, n} 6519104862Sru@DefregListEnd {.linetabs} 6520104862Sru@cindex tab, line-tabs mode 6521104862Sru@cindex line-tabs mode 6522104862Sru@cindex mode, line-tabs 6523104862SruIf @var{n} is missing or not zero, enable @dfn{line-tabs} mode, 6524104862Sruor disable it otherwise (the default). 6525104862SruIn line-tabs mode, @code{gtroff} computes tab distances 6526104862Srurelative to the (current) output line instead of the input line. 6527104862Sru 6528104862SruFor example, the following code: 6529104862Sru 6530104862Sru@Example 6531104862Sru.ds x a\t\c 6532104862Sru.ds y b\t\c 6533104862Sru.ds z c 6534104862Sru.ta 1i 3i 6535104862Sru\*x 6536104862Sru\*y 6537104862Sru\*z 6538104862Sru@endExample 6539104862Sru 6540104862Sru@noindent 6541104862Sruin normal mode, results in the output 6542104862Sru 6543104862Sru@Example 6544104862Srua b c 6545104862Sru@endExample 6546104862Sru 6547104862Sru@noindent 6548104862Sruin line-tabs mode, the same code outputs 6549104862Sru 6550104862Sru@Example 6551104862Srua b c 6552104862Sru@endExample 6553104862Sru 6554104862SruLine-tabs mode is associated with the current environment. 6555104862SruThe read-only register @code{.linetabs} is set to@w{ }1 if in line-tabs 6556104862Srumode, and 0 in normal mode. 6557104862Sru@endDefreq 6558104862Sru 655969626Sru@menu 656075584Sru* Leaders:: 656175584Sru* Fields:: 656269626Sru@end menu 656369626Sru 656469626Sru@c --------------------------------------------------------------------- 656569626Sru 656669626Sru@node Leaders, Fields, Tabs and Fields, Tabs and Fields 656755839Sasmodai@subsection Leaders 656855839Sasmodai@cindex leaders 656955839Sasmodai 657069626SruSometimes it may may be desirable to use the @code{tc} request to fill a 6571104862Sruparticular tab stop with a given glyph (for example dots in a table 657269626Sruof contents), but also normal tab stops on the rest of the line. For 657369626Sruthis @code{gtroff} provides an alternate tab mechanism, called 657475584Sru@dfn{leaders} which does just that. 657555839Sasmodai 657669626Sru@cindex leader character 657769626SruA leader character (character code@w{ }1) behaves similarly to a tab 657869626Srucharacter: It moves to the next tab stop. The only difference is that 6579104862Srufor this movement, the fill glyph defaults to a period character and 658069626Srunot to space. 658155839Sasmodai 658275584Sru@Defesc {\\a, , , } 6583104862Sru@cindex leader character, non-interpreted (@code{\a}) 6584104862Sru@cindex character, leader, non-interpreted (@code{\a}) 658569626SruThis escape is a non-interpreted leader character. In copy mode 658669626Sru(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 658769626Srucharacter. 658875584Sru@endDefesc 658955839Sasmodai 6590104862Sru@Defreq {lc, [@Var{fill-glyph}]} 6591104862Sru@cindex leader repetition character (@code{lc}) 6592104862Sru@cindex character, leader repetition (@code{lc}) 6593104862Sru@cindex glyph, leader repetition (@code{lc}) 6594104862SruDeclare the @dfn{leader repetition character}.@footnote{@dfn{Leader 6595104862Srurepetition character} is a misnomer since it is an output glyph.} 6596104862SruWithout an argument, leaders act the same as tabs (i.e., using 6597104862Sruwhitespace for filling). @code{gtroff}'s start-up value is a dot 6598104862Sru(@samp{.}). The value of the leader repetition character is 6599104862Sruassociated with the current environment (@pxref{Environments}). 660075584Sru@endDefreq 660169626Sru 660255839Sasmodai@cindex table of contents 660355839Sasmodai@cindex contents, table of 660469626SruFor a table of contents, to name an example, tab stops may be defined so 660555839Sasmodaithat the section number is one tab stop, the title is the second with 660669626Sruthe remaining space being filled with a line of dots, and then the page 660769626Srunumber slightly separated from the dots. 660855839Sasmodai 660975584Sru@Example 661069626Sru.ds entry 1.1\tFoo\a\t12 661155839Sasmodai.lc . 661269626Sru.ta 1i 5i +.25i 661369626Sru\*[entry] 661475584Sru@endExample 661555839Sasmodai 661669626Sru@noindent 661769626SruThis produces 661869626Sru 661975584Sru@Example 662069626Sru1.1 Foo.......................................... 12 662175584Sru@endExample 662269626Sru 662369626Sru@c --------------------------------------------------------------------- 662469626Sru 662569626Sru@node Fields, , Leaders, Tabs and Fields 662655839Sasmodai@subsection Fields 662755839Sasmodai@cindex fields 662855839Sasmodai 6629104862Sru@cindex field delimiting character (@code{fc}) 6630104862Sru@cindex delimiting character, for fields (@code{fc}) 6631104862Sru@cindex character, field delimiting (@code{fc}) 6632104862Sru@cindex field padding character (@code{fc}) 6633104862Sru@cindex padding character, for fields (@code{fc}) 6634104862Sru@cindex character, field padding (@code{fc}) 663569626Sru@dfn{Fields} are a more general way of laying out tabular data. A field 663669626Sruis defined as the data between a pair of @dfn{delimiting characters}. 663769626SruIt contains substrings which are separated by @dfn{padding characters}. 663869626SruThe width of a field is the distance on the @emph{input} line from the 663969626Sruposition where the field starts to the next tab stop. A padding 664069626Srucharacter inserts stretchable space similar to @TeX{}'s @code{\hss} 664169626Srucommand (thus it can even be negative) to make the sum of all substring 664269626Srulengths plus the stretchable space equal to the field width. If more 664369626Sruthan one padding character is inserted, the available space is evenly 664469626Srudistributed among them. 664555839Sasmodai 664675584Sru@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 664769626SruDefine a delimiting and a padding character for fields. If the latter 664869626Sruis missing, the padding character defaults to a space character. If 664969626Sruthere is no argument at all, the field mechanism is disabled (which is 665075584Sruthe default). Note that contrary to e.g.@: the tab repetition 6651104862Srucharacter, delimiting and padding characters are @emph{not} associated 6652104862Sruto the current environment (@pxref{Environments}). 665369626Sru 665469626SruExample: 665569626Sru 665675584Sru@Example 665769626Sru.fc # ^ 665869626Sru.ta T 3i 665969626Sru#foo^bar^smurf# 666069626Sru.br 666169626Sru#foo^^bar^smurf# 666275584Sru@endExample 666369626Sru 666469626Sru@noindent 666569626Sruand here the result: 666669626Sru 666775584Sru@Example 666869626Srufoo bar smurf 666969626Srufoo bar smurf 667075584Sru@endExample 667175584Sru@endDefreq 667269626Sru 667369626Sru 667469626Sru@c ===================================================================== 667569626Sru 667675584Sru@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 667755839Sasmodai@section Character Translations 667855839Sasmodai@cindex character translations 667955839Sasmodai@cindex translations of characters 668055839Sasmodai 6681104862Sru@cindex control character, changing (@code{cc}) 6682104862Sru@cindex character, control, changing (@code{cc}) 6683104862Sru@cindex no-break control character, changing (@code{c2}) 6684104862Sru@cindex character, no-break control, changing (@code{c2}) 6685104862Sru@cindex control character, no-break, changing (@code{c2}) 668655839SasmodaiThe control character (@samp{.}) and the no-break control character 668755839Sasmodai(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 668855839Sasmodairespectively. 668955839Sasmodai 669075584Sru@Defreq {cc, [@Var{c}]} 6691104862SruSet the control character to@w{ }@var{c}. With no argument the default 669269626Srucontrol character @samp{.} is restored. The value of the control 669369626Srucharacter is associated with the current environment 669469626Sru(@pxref{Environments}). 669575584Sru@endDefreq 669655839Sasmodai 669775584Sru@Defreq {c2, [@Var{c}]} 6698104862SruSet the no-break control character to@w{ }@var{c}. With no argument the 669969626Srudefault control character @samp{'} is restored. The value of the 670069626Sruno-break control character is associated with the current environment 670169626Sru(@pxref{Environments}). 670275584Sru@endDefreq 670355839Sasmodai 670475584Sru@Defreq {eo, } 6705104862Sru@cindex disabling @code{\} (@code{eo}) 6706104862Sru@cindex @code{\}, disabling (@code{eo}) 670775584SruDisable the escape mechanism completely. After executing this 670875584Srurequest, the backslash character @samp{\} no longer starts an escape 670975584Srusequence. 671069626Sru 671169626SruThis request can be very helpful in writing macros since it is not 671269626Srunecessary then to double the escape character. Here an example: 671369626Sru 671475584Sru@Example 671569626Sru.\" This is a simplified version of the 671669626Sru.\" .BR request from the man macro package 671769626Sru.eo 671869626Sru.de BR 671969626Sru. ds result \& 672069626Sru. while (\n[.$] >= 2) \@{\ 672169626Sru. as result \fB\$1\fR\$2 672269626Sru. shift 2 672369626Sru. \@} 672469626Sru. if \n[.$] .as result \fB\$1 672569626Sru\*[result] 672669626Sru. ft R 672769626Sru.. 672869626Sru.ec 672975584Sru@endExample 673075584Sru@endDefreq 673169626Sru 673275584Sru@Defreq {ec, [@Var{c}]} 6733104862Sru@cindex escape character, changing (@code{ec}) 6734104862Sru@cindex character, escape, changing (@code{ec}) 6735104862SruSet the escape character to@w{ }@var{c}. With no argument the default 673675584Sruescape character @samp{\} is restored. It can be also used to 673775584Srure-enable the escape mechanism after an @code{eo} request. 673869626Sru 673975584SruNote that changing the escape character globally will likely break 6740104862Srumacro packages since @code{gtroff} has no mechanism to `intern' macros, 6741104862Srui.e., to convert a macro definition into an internal form which is 6742104862Sruindependent of its representation (@TeX{} has this mechanism). 6743104862SruIf a macro is called, it is executed literally. 674475584Sru@endDefreq 674569626Sru 6746104862Sru@DefreqList {ecs, } 6747104862Sru@DefreqListEnd {ecr, } 6748104862SruThe @code{ecs} request saves the current escape character 6749104862Sruin an internal register. 6750104862SruUse this request in combination with the @code{ec} request to 6751104862Srutemporarily change the escape character. 6752104862Sru 6753104862SruThe @code{ecr} request restores the escape character 6754104862Srusaved with @code{ecs}. 6755104862SruWithout a previous call to @code{ecs}, this request 6756104862Srusets the escape character to @code{\}. 6757104862Sru@endDefreq 6758104862Sru 6759104862Sru@DefescList {\\\\, , , } 6760104862Sru@DefescItem {\\e, , , } 6761104862Sru@DefescListEnd {\\E, , , } 6762104862SruPrint the current escape character (which is the backslash character 6763104862Sru@samp{\} by default). 6764104862Sru 6765104862Sru@code{\\} is a `delayed' backslash; more precisely, it is the default 6766104862Sruescape character followed by a backslash, which no longer has special 6767104862Srumeaning due to the leading escape character. It is @emph{not} an escape 6768104862Srusequence in the usual sense! In any unknown escape sequence 6769104862Sru@code{\@var{X}} the escape character is ignored and @var{X} is printed. 6770104862SruBut if @var{X} is equal to the current escape character, no warning is 6771104862Sruemitted. 6772104862Sru 6773104862SruAs a consequence, only at top-level or in a diversion a backslash glyph is 6774104862Sruprinted; in copy-in mode, it expands to a single backslash which then 6775104862Srucombines with the following character to an escape sequence. 6776104862Sru 6777104862SruThe @code{\E} escape differs from @code{\e} by printing an escape 6778104862Srucharacter that is not interpreted in copy mode. 6779104862SruUse this to define strings with escapes that work 6780104862Sruwhen used in copy mode (for example, as a macro argument). 6781104862SruThe following example defines strings to begin and end 6782104862Srua superscript: 6783104862Sru 6784104862Sru@Example 6785104862Sru.ds @{ \v'-.3m'\s'\Es[.s]*60/100' 6786104862Sru.ds @} \s0\v'.3m' 6787104862Sru@endExample 6788104862Sru 6789104862SruAnother example to demonstrate the differences between the various escape 6790104862Srusequences, using a strange escape character, @samp{-}. 6791104862Sru 6792104862Sru@Example 6793104862Sru.ec - 6794104862Sru.de xxx 6795104862Sru--A'123' 6796104862Sru.. 6797104862Sru.xxx 6798104862Sru @result{} -A'foo' 6799104862Sru@endExample 6800104862Sru 6801104862Sru@noindent 6802104862SruThe result is surprising for most users, expecting @samp{1} since 6803104862Sru@samp{foo} is a valid identifier. What has happened? As mentioned 6804104862Sruabove, the leading escape character makes the following character 6805104862Sruordinary. Written with the default escape character the sequence 6806104862Sru@samp{--} becomes @samp{\-} -- this is the minus sign. 6807104862Sru 6808104862SruIf the escape character followed by itself is a valid escape sequence, 6809104862Sruonly @code{\E} yields the expected result: 6810104862Sru 6811104862Sru@Example 6812104862Sru.ec - 6813104862Sru.de xxx 6814104862Sru-EA'123' 6815104862Sru.. 6816104862Sru.xxx 6817104862Sru @result{} 1 6818104862Sru@endExample 681975584Sru@endDefesc 682069626Sru 6821104862Sru@Defesc {\\., , , } 6822104862SruSimilar to @code{\\}, the sequence @code{\.} isn't a real escape sequence. 6823104862SruAs before, a warning message is suppressed if the escape character is 6824104862Srufollowed by a dot, and the dot itself is printed. 6825104862Sru 6826104862Sru@Example 6827104862Sru.de foo 6828104862Sru. nop foo 6829104862Sru. 6830104862Sru. de bar 6831104862Sru. nop bar 6832104862Sru\\.. 6833104862Sru. 6834104862Sru.. 6835104862Sru.foo 6836104862Sru.bar 6837104862Sru @result{} foo bar 6838104862Sru@endExample 6839104862Sru 6840104862Sru@noindent 6841104862SruThe first backslash is consumed while the macro is read, and the second 6842104862Sruis swallowed while exexuting macro @code{foo}. 6843104862Sru@endDefesc 6844104862Sru 684569626SruA @dfn{translation} is a mapping of an input character to an output 6846104862Sruglyph. The mapping occurs at output time, i.e., the input character 6847104862Srugets assigned the metric information of the mapped output character 6848104862Sruright before input tokens are converted to nodes (@pxref{Gtroff 6849104862SruInternals}, for more on this process). 685069626Sru 6851104862Sru@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 6852104862Sru@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 6853104862SruTranslate character @var{a} to glyph@w{ }@var{b}, character @var{c} to 6854104862Sruglyph@w{ }@var{d}, etc. If there is an odd number of arguments, the 6855104862Srulast one is translated to an unstretchable space (@w{@samp{\ }}). 685669626Sru 6857104862SruThe @code{trin} request is identical to @code{tr}, 6858104862Srubut when you unformat a diversion with @code{asciify} 6859104862Sruit ignores the translation. 6860104862Sru@xref{Diversions}, for details about the @code{asciify} request. 6861104862Sru 686269626SruSome notes: 686369626Sru 686469626Sru@itemize @bullet 686569626Sru@item 6866104862Sru@cindex @code{\(}, and translations 6867104862Sru@cindex @code{\[}, and translations 6868104862Sru@cindex @code{\'}, and translations 6869104862Sru@cindex @code{\`}, and translations 6870104862Sru@cindex @code{\-}, and translations 6871104862Sru@cindex @code{\_}, and translations 6872104862Sru@cindex @code{\C}, and translations 6873104862Sru@cindex @code{\N}, and translations 6874104862Sru@cindex @code{char} request, and translations 6875104862Sru@cindex special characters 687669626Sru@cindex character, special 6877104862Sru@cindex numbered glyph (@code{\N}) 6878104862Sru@cindex glyph, numbered (@code{\N}) 687969626SruSpecial characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 688069626Sru@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 6881104862Sruglyphs defined with the @code{char} request, and numbered glyphs 688269626Sru(@code{\N'@var{xxx}'}) can be translated also. 688369626Sru 688469626Sru@item 6885104862Sru@cindex @code{\e}, and translations 688669626SruThe @code{\e} escape can be translated also. 688769626Sru 688869626Sru@item 6889104862Sru@cindex @code{\%}, and translations 6890104862Sru@cindex @code{\~}, and translations 689175584SruCharacters can be mapped onto the @code{\%} and @code{\~} escapes (but 6892104862Sru@code{\%} and @code{\~} can't be mapped onto another glyph). 689369626Sru 689469626Sru@item 6895104862Sru@cindex backspace character, and translations 6896104862Sru@cindex character, backspace, and translations 6897104862Sru@cindex leader character, and translations 6898104862Sru@cindex character, leader, and translations 6899104862Sru@cindex newline character, and translations 6900104862Sru@cindex character, newline, and translations 6901104862Sru@cindex tab character, and translations 6902104862Sru@cindex character, tab, and translations 6903104862Sru@cindex @code{\a}, and translations 6904104862Sru@cindex @code{\t}, and translations 690569626SruThe following characters can't be translated: space (with one exception, 690669626Srusee below), backspace, newline, leader (and @code{\a}), tab (and 690769626Sru@code{\t}). 690869626Sru 690969626Sru@item 6910104862Sru@cindex @code{shc} request, and translations 691169626SruTranslations are not considered for finding the soft hyphen character 691269626Sruset with the @code{shc} request. 691369626Sru 691469626Sru@item 6915104862Sru@cindex @code{\&}, and translations 6916104862SruThe pair @samp{@var{c}\&} (this is an arbitrary character@w{ 691775584Sru}@var{c} followed by the zero width space character) maps this 691869626Srucharacter to nothing. 691969626Sru 692075584Sru@Example 692169626Sru.tr a\& 692269626Srufoo bar 692369626Sru @result{} foo br 692475584Sru@endExample 692569626Sru 692669626Sru@noindent 692769626SruIt is even possible to map the space character to nothing: 692869626Sru 692975584Sru@Example 693069626Sru.tr aa \& 693169626Srufoo bar 693269626Sru @result{} foobar 693375584Sru@endExample 693469626Sru 693569626Sru@noindent 693669626SruAs shown in the example, the space character can't be the first 6937104862Srucharacter/glyph pair as an argument of @code{tr}. Additionally, it is 6938104862Srunot possible to map the space character to any other glyph; requests 693975584Srulike @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 694069626Sru 694175584SruIf justification is active, lines are justified in spite of the 694269626Sru`empty' space character (but there is no minimal distance, i.e.@: the 694369626Sruspace character, between words). 694469626Sru 694569626Sru@item 6946104862SruAfter an output glyph has been constructed (this happens at the 6947104862Srumoment immediately before the glyph is appended to an output 6948104862Sruglyph list, either by direct output, in a macro, diversion, or 694969626Srustring), it is no longer affected by @code{tr}. 695069626Sru 6951104862Sru@item 6952104862SruTranslating character to glyphs where one of them or both are 6953104862Sruundefined is possible also; @code{tr} does not check whether the 6954104862Sruentities in its argument do exist. 695569626Sru 6956104862Sru@xref{Gtroff Internals}. 6957104862Sru 695869626Sru@item 6959104862Sru@code{troff} no longer has a hard-coded dependency on @w{Latin-1}; 6960104862Sruall @code{char@var{XXX}} entities have been removed from the font 6961104862Srudescription files. This has a notable consequence which shows up in 6962104862Sruwarnings like @code{can't find character with input code @var{XXX}} 6963104862Sruif the @code{tr} request isn't handled properly. 6964104862Sru 6965104862SruConsider the following translation: 6966104862Sru 6967104862Sru@Example 6968104862Sru.tr @'e@'E 6969104862Sru@endExample 6970104862Sru 6971104862Sru@noindent 6972104862SruThis maps input character @code{@'e} onto glyph @code{@'E}, which is 6973104862Sruidentical to glyph @code{char201}. But this glyph intentionally 6974104862Srudoesn't exist! Instead, @code{\[char201]} is treated as an input 6975104862Srucharacter entity and is by default mapped onto @code{\['E]}, and 6976104862Sru@code{gtroff} doesn't handle translations of translations. 6977104862Sru 6978104862SruThe right way to write the above translation is 6979104862Sru 6980104862Sru@Example 6981104862Sru.tr @'e\['E] 6982104862Sru@endExample 6983104862Sru 6984104862Sru@noindent 6985104862SruWith other words, the first argument of @code{tr} should be an input 6986104862Srucharacter or entity, and the second one a glyph entity. 6987104862Sru 6988104862Sru@item 698969626SruWithout an argument, the @code{tr} request is ignored. 699069626Sru@end itemize 699175584Sru@endDefreq 699269626Sru 6993104862Sru@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 699475584Sru@cindex @code{\!}, and @code{trnt} 699569626Sru@code{trnt} is the same as the @code{tr} request except that the 699675584Srutranslations do not apply to text that is transparently throughput 699775584Sruinto a diversion with @code{\!}. @xref{Diversions}, for more 699875584Sruinformation. 699969626Sru 700055839SasmodaiFor example, 700155839Sasmodai 700275584Sru@Example 700355839Sasmodai.tr ab 700455839Sasmodai.di x 700555839Sasmodai\!.tm a 700655839Sasmodai.di 700755839Sasmodai.x 700875584Sru@endExample 700955839Sasmodai 701069626Sru@noindent 701175584Sruprints @samp{b} to the standard error stream; if @code{trnt} is used 701275584Sruinstead of @code{tr} it prints @samp{a}. 701375584Sru@endDefreq 701455839Sasmodai 701555839Sasmodai 701669626Sru@c ===================================================================== 701769626Sru 701875584Sru@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 701969626Sru@section Troff and Nroff Mode 702069626Sru@cindex troff mode 702169626Sru@cindex mode, troff 702269626Sru@cindex nroff mode 702369626Sru@cindex mode, nroff 702469626Sru 702569626SruOriginally, @code{nroff} and @code{troff} were two separate programs, 7026104862Sruthe former for TTY output, the latter for everything else. With GNU 702775584Sru@code{troff}, both programs are merged into one executable, sending 7028104862Sruits output to a device driver (@code{grotty} for TTY devices, 702975584Sru@code{grops} for @sc{PostScript}, etc.) which interprets the 703075584Sruintermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 703175584Sruit makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 703275584Srusince the differences are hardcoded. For GNU @code{troff}, this 703375584Srudistinction is not appropriate because @code{gtroff} simply takes the 703475584Sruinformation given in the font files for a particular device without 7035104862Sruhandling requests specially if a TTY output device is used. 703669626Sru 703775584SruUsually, a macro package can be used with all output devices. 703875584SruNevertheless, it is sometimes necessary to make a distinction between 7039104862SruTTY and non-TTY devices: @code{gtroff} provides two built-in 704075584Sruconditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 704175584Sru@code{while} requests to decide whether @code{gtroff} shall behave 704275584Srulike @code{nroff} or like @code{troff}. 704369626Sru 7044104862Sru@Defreq {troff, } 704569626Sru@pindex troffrc 704669626Sru@pindex troffrc-end 704769626SruMake the @samp{t} built-in condition true (and the @samp{n} built-in 704875584Srucondition false) for @code{if}, @code{ie}, and @code{while} 704975584Sruconditional requests. This is the default if @code{gtroff} 705075584Sru(@emph{not} @code{groff}) is started with the @option{-R} switch to 705175584Sruavoid loading of the start-up files @file{troffrc} and 705275584Sru@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 7053104862Srumode if the output device is not a TTY (e.g.@: `ps'). 705475584Sru@endDefreq 705569626Sru 7056104862Sru@Defreq {nroff, } 705775584Sru@pindex tty.tmac 705869626SruMake the @samp{n} built-in condition true (and the @samp{t} built-in 705975584Srucondition false) for @code{if}, @code{ie}, and @code{while} 7060104862Sruconditional requests. This is the default if @code{gtroff} uses a TTY 706175584Sruoutput device; the code for switching to nroff mode is in the file 706275584Sru@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 706375584Sru@endDefreq 706469626Sru 706575584Sru@xref{Conditionals and Loops}, for more details on built-in 706675584Sruconditions. 706769626Sru 706869626Sru 706969626Sru@c ===================================================================== 707069626Sru 7071104862Sru@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference 707255839Sasmodai@section Line Layout 707355839Sasmodai@cindex line layout 707455839Sasmodai@cindex layout, line 707555839Sasmodai 707655839Sasmodai@cindex dimensions, line 707755839Sasmodai@cindex line dimensions 707869626SruThe following drawing shows the dimensions which @code{gtroff} uses for 707955839Sasmodaiplacing a line of output onto the page. They are labeled with the 708069626Srurequest which manipulates each dimension. 708155839Sasmodai 708275584Sru@Example 708369626Sru -->| in |<-- 708469626Sru |<-----------ll------------>| 708555839Sasmodai +----+----+----------------------+----+ 708655839Sasmodai | : : : | 708755839Sasmodai +----+----+----------------------+----+ 708869626Sru -->| po |<-- 708969626Sru |<--------paper width---------------->| 709075584Sru@endExample 709155839Sasmodai 709269626Sru@noindent 709355839SasmodaiThese dimensions are: 709455839Sasmodai 709555839Sasmodai@ftable @code 709655839Sasmodai@item po 7097104862Sru@cindex left margin (@code{po}) 7098104862Sru@cindex margin, left (@code{po}) 7099104862Sru@cindex page offset (@code{po}) 7100104862Sru@cindex offset, page (@code{po}) 710169626Sru@dfn{Page offset} -- this is the leftmost position of text on the final 710269626Sruoutput, defining the @dfn{left margin}. 710369626Sru 710455839Sasmodai@item in 7105104862Sru@cindex indentation (@code{in}) 7106104862Sru@cindex line indentation (@code{in}) 710769626Sru@dfn{Indentation} -- this is the distance from the left margin where 710875584Srutext is printed. 710955839Sasmodai 711055839Sasmodai@item ll 7111104862Sru@cindex line length (@code{ll}) 7112104862Sru@cindex length of line (@code{ll}) 711369626Sru@dfn{Line length} -- this is the distance from the left margin to right 711469626Srumargin. 711555839Sasmodai@end ftable 711655839Sasmodai 7117104862SruA simple demonstration: 711869626Sru 711975584Sru@Example 7120104862Sru.ll 3i 7121104862SruThis is text without indentation. 7122104862SruThe line length has been set to 3\~inch. 712355839Sasmodai.in +.5i 712455839Sasmodai.ll -.5i 7125104862SruNow the left and right margins are both increased. 7126104862Sru.in 7127104862Sru.ll 7128104862SruCalling .in and .ll without parameters restore 7129104862Sruthe previous values. 713075584Sru@endExample 713155839Sasmodai 7132104862SruResult: 7133104862Sru 7134104862Sru@Example 7135104862SruThis is text without indenta- 7136104862Srution. The line length has 7137104862Srubeen set to 3 inch. 7138104862Sru Now the left and 7139104862Sru right margins are 7140104862Sru both increased. 7141104862SruCalling .in and .ll without 7142104862Sruparameters restore the previ- 7143104862Sruous values. 7144104862Sru@endExample 7145104862Sru 7146104862Sru@DefreqList {po, [@Var{offset}]} 7147104862Sru@DefreqItem {po, @t{+}@Var{offset}} 7148104862Sru@DefreqItem {po, @t{-}@Var{offset}} 7149104862Sru@DefregListEnd {.o} 715075584Sru@pindex troffrc 715175584SruSet horizontal page offset to @var{offset} (or increment or decrement 715275584Sruthe current value by @var{offset}). Note that this request does not 715375584Srucause a break, so changing the page offset in the middle of text being 715475584Srufilled may not yield the expected result. The initial value is 7155104862Sru1@dmn{i}. For TTY output devices, it is set to 0 in the startup file 7156104862Sru@file{troffrc}; the default scaling indicator is @samp{m} (and 7157104862Srunot @samp{v} as incorrectly documented in the original 715875584Sru@acronym{UNIX} troff manual). 715955839Sasmodai 716075584SruThe current page offset can be found in the read-only number register 716169626Sru@samp{.o}. 716269626Sru 716369626SruIf @code{po} is called without an argument, the page offset is reset to 716469626Sruthe previous value before the last call to @code{po}. 716569626Sru 716675584Sru@Example 716769626Sru.po 3i 716869626Sru\n[.o] 716969626Sru @result{} 720 717069626Sru.po -1i 717169626Sru\n[.o] 717269626Sru @result{} 480 717369626Sru.po 717469626Sru\n[.o] 717569626Sru @result{} 720 717675584Sru@endExample 717775584Sru@endDefreq 717869626Sru 7179104862Sru@DefreqList {in, [@Var{indent}]} 7180104862Sru@DefreqItem {in, @t{+}@Var{indent}} 7181104862Sru@DefreqItem {in, @t{-}@Var{indent}} 7182104862Sru@DefregListEnd {.i} 718375584SruSet indentation to @var{indent} (or increment or decrement the 718469626Srucurrent value by @var{indent}). This request causes a break. 718569626SruInitially, there is no indentation. 718669626Sru 718769626SruIf @code{in} is called without an argument, the indentation is reset to 718869626Sruthe previous value before the last call to @code{in}. The default 7189104862Sruscaling indicator is @samp{m}. 719069626Sru 7191104862SruThe indentation is associated with the current environment 7192104862Sru(@pxref{Environments}). 719369626Sru 719469626SruIf a negative indentation value is specified (which is not allowed), 719569626Sru@code{gtroff} emits a warning of type @samp{range} and sets the 719669626Sruindentation to zero. 719769626Sru 719869626SruThe effect of @code{in} is delayed until a partially collected line (if 719975584Sruit exists) is output. A temporary indent value is reset to zero also. 720069626Sru 720169626SruThe current indentation (as set by @code{in}) can be found in the 720275584Sruread-only number register @samp{.i}. 720375584Sru@endDefreq 720469626Sru 7205104862Sru@DefreqList {ti, offset} 7206104862Sru@DefreqItem {ti, @t{+}@Var{offset}} 7207104862Sru@DefreqItem {ti, @t{-}@Var{offset}} 7208104862Sru@DefregListEnd {.in} 720969626SruTemporarily indent the next output line by @var{offset}. If an 721069626Sruincrement or decrement value is specified, adjust the temporary 721169626Sruindentation relative to the value set by the @code{in} request. 721269626Sru 721369626SruThis request causes a break; its value is associated with the current 7214104862Sruenvironment (@pxref{Environments}). The default scaling indicator 7215104862Sruis @samp{m}. A call of @code{ti} without an argument is ignored. 721669626Sru 721769626SruIf the total indentation value is negative (which is not allowed), 721869626Sru@code{gtroff} emits a warning of type @samp{range} and sets the 721969626Srutemporary indentation to zero. `Total indentation' is either 722069626Sru@var{offset} if specified as an absolute value, or the temporary plus 722169626Srunormal indentation, if @var{offset} is given as a relative value. 722269626Sru 722369626SruThe effect of @code{ti} is delayed until a partially collected line (if 722469626Sruit exists) is output. 722569626Sru 722675584SruThe read-only number register @code{.in} is the indentation that applies 722775584Sruto the current output line. 722869626Sru 722969626SruThe difference between @code{.i} and @code{.in} is that the latter takes 723069626Sruinto account whether a partially collected line still uses the old 723175584Sruindentation value or a temporary indentation value is active. 723275584Sru@endDefreq 723369626Sru 7234104862Sru@DefreqList {ll, [@Var{length}]} 7235104862Sru@DefreqItem {ll, @t{+}@Var{length}} 7236104862Sru@DefreqItem {ll, @t{-}@Var{length}} 7237104862Sru@DefregItem {.l} 7238104862Sru@DefregListEnd {.ll} 723975584SruSet the line length to @var{length} (or increment or decrement the 724069626Srucurrent value by @var{length}). Initially, the line length is set to 724169626Sru6.5@dmn{i}. The effect of @code{ll} is delayed until a partially 724275584Srucollected line (if it exists) is output. The default scaling 7243104862Sruindicator is @samp{m}. 724469626Sru 724569626SruIf @code{ll} is called without an argument, the line length is reset to 724669626Sruthe previous value before the last call to @code{ll}. If a negative 724769626Sruline length is specified (which is not allowed), @code{gtroff} emits a 724869626Sruwarning of type @samp{range} and sets the line length to zero. 724969626Sru 7250104862SruThe line length is associated with the current environment 7251104862Sru(@pxref{Environments}). 725269626Sru 7253104862Sru@cindex line length register (@code{.l}) 725469626SruThe current line length (as set by @code{ll}) can be found in the 725575584Sruread-only number register @samp{.l}. The read-only number register 725675584Sru@code{.ll} is the line length that applies to the current output line. 725769626Sru 725869626SruSimilar to @code{.i} and @code{.in}, the difference between @code{.l} 725969626Sruand @code{.ll} is that the latter takes into account whether a partially 726069626Srucollected line still uses the old line length value. 726175584Sru@endDefreq 726269626Sru 726369626Sru 726469626Sru@c ===================================================================== 726569626Sru 7266104862Sru@node Line Control, Page Layout, Line Layout, gtroff Reference 7267104862Sru@section Line Control 7268104862Sru@cindex line control 7269104862Sru@cindex control, line 7270104862Sru 7271104862SruIt is important to understand how @code{gtroff} handles input and output 7272104862Srulines. 7273104862Sru 7274104862SruMany escapes use positioning relative to the input line. For example, 7275104862Sruthis 7276104862Sru 7277104862Sru@Example 7278104862SruThis is a \h'|1.2i'test. 7279104862Sru 7280104862SruThis is a 7281104862Sru\h'|1.2i'test. 7282104862Sru@endExample 7283104862Sru 7284104862Sru@noindent 7285104862Sruproduces 7286104862Sru 7287104862Sru@Example 7288104862SruThis is a test. 7289104862Sru 7290104862SruThis is a test. 7291104862Sru@endExample 7292104862Sru 7293104862SruThe main usage of this feature is to define macros which act exactly 7294104862Sruat the place where called. 7295104862Sru 7296104862Sru@Example 7297104862Sru.\" A simple macro to underline a word 7298104862Sru.de underline 7299104862Sru. nop \\$1\l'|0\[ul]' 7300104862Sru.. 7301104862Sru@endExample 7302104862Sru 7303104862Sru@noindent 7304104862SruIn the above example, @samp{|0} specifies a negative distance from the 7305104862Srucurrent position (at the end of the just emitted argument @code{\$1}) back 7306104862Sruto the beginning of the input line. Thus, the @samp{\l} escape draws a 7307104862Sruline from right to left. 7308104862Sru 7309104862Sru@cindex input line continuation (@code{\}) 7310104862Sru@cindex line, input, continuation (@code{\}) 7311104862Sru@cindex continuation, input line (@code{\}) 7312104862Sru@cindex output line, continuation (@code{\c}) 7313104862Sru@cindex line, output, continuation (@code{\c}) 7314104862Sru@cindex continuation, output line (@code{\c}) 7315104862Sru@cindex interrupted line 7316104862Sru@cindex line, interrupted 7317104862Sru@code{gtroff} makes a difference between input and output line 7318104862Srucontinuation; the latter is also called @dfn{interrupting} a line. 7319104862Sru 7320104862Sru@DefescList {\\@key{RET}, , ,} 7321104862Sru@DefescItem {\\c, , ,} 7322104862Sru@DefregListEnd{.int} 7323104862SruContinue a line. @code{\@key{RET}} (this is a backslash at the end 7324104862Sruof a line immediately followed by a newline) works on the input level, 7325104862Srusuppressing the effects of the following newline in the input. 7326104862Sru 7327104862Sru@Example 7328104862SruThis is a \ 7329104862Sru.test 7330104862Sru @result{} This is a .test 7331104862Sru@endExample 7332104862Sru 7333104862SruThe @samp{|} operator is also affected. 7334104862Sru 7335104862Sru@cindex @code{\R}, after @code{\c} 7336104862Sru@code{\c} works on the output level. Anything after this escape on the 7337104862Srusame line is ignored, except @code{\R} which works as usual. Anything 7338104862Srubefore @code{\c} on the same line will be appended to the current partial 7339104862Sruoutput line. The next non-command line after an interrupted line counts 7340104862Sruas a new input line. 7341104862Sru 7342104862SruThe visual results depend on whether no-fill mode is active. 7343104862Sru 7344104862Sru@itemize @bullet 7345104862Sru@item 7346104862Sru@cindex @code{\c}, and no-fill mode 7347104862Sru@cindex no-fill mode, and @code{\c} 7348104862Sru@cindex mode, no-fill, and @code{\c} 7349104862SruIf no-fill mode is active (using the @code{nf} request), the next input 7350104862Srutext line after @code{\c} will be handled as a continuation of the same 7351104862Sruinput text line. 7352104862Sru 7353104862Sru@Example 7354104862Sru.nf 7355104862SruThis is a \c 7356104862Srutest. 7357104862Sru @result{} This is a test. 7358104862Sru@endExample 7359104862Sru 7360104862Sru@item 7361104862Sru@cindex @code{\c}, and fill mode 7362104862Sru@cindex fill mode, and @code{\c} 7363104862Sru@cindex mode, fill, and @code{\c} 7364104862SruIf fill mode is active (using the @code{fi} request), a word interrupted 7365104862Sruwith @code{\c} will be continued with the text on the next input text line, 7366104862Sruwithout an intervening space. 7367104862Sru 7368104862Sru@Example 7369104862SruThis is a te\c 7370104862Srust. 7371104862Sru @result{} This is a test. 7372104862Sru@endExample 7373104862Sru@end itemize 7374104862Sru 7375104862SruNote that an intervening control line which causes a break is stronger 7376104862Sruthan @code{\c}, flushing out the current partial line in the usual way. 7377104862Sru 7378104862Sru@cindex interrupted line register (@code{.int}) 7379104862SruThe @code{.int} register contains a positive value 7380104862Sruif the last output line was interrupted with @code{\c}; this is 7381104862Sruassociated with the current environment (@pxref{Environments}). 7382104862Sru 7383104862Sru@endDefesc 7384104862Sru 7385104862Sru@c ===================================================================== 7386104862Sru 7387104862Sru@node Page Layout, Page Control, Line Control, gtroff Reference 738855839Sasmodai@section Page Layout 738955839Sasmodai@cindex page layout 739055839Sasmodai@cindex layout, page 739155839Sasmodai 739269626Sru@code{gtroff} provides some very primitive operations for controlling 739369626Srupage layout. 739455839Sasmodai 7395104862Sru@DefreqList {pl, [@Var{length}]} 7396104862Sru@DefreqItem {pl, @t{+}@Var{length}} 7397104862Sru@DefreqItem {pl, @t{-}@Var{length}} 7398104862Sru@DefregListEnd {.p} 7399104862Sru@cindex page length (@code{pl}) 7400104862Sru@cindex length of page (@code{pl}) 740175584SruSet the @dfn{page length} to @var{length} (or increment or decrement 740275584Sruthe current value by @var{length}). This is the length of the 7403104862Sruphysical output page. The default scaling indicator is @samp{v}. 740455839Sasmodai 7405104862Sru@cindex page length register (@code{.p}) 740675584SruThe current setting can be found in the read-only number register 740769626Sru@samp{.p}. 740855839Sasmodai 740969626Sru@cindex top margin 741069626Sru@cindex margin, top 741169626Sru@cindex bottom margin 741269626Sru@cindex margin, bottom 741369626SruNote that this only specifies the size of the page, not the top and 741475584Srubottom margins. Those are not set by @code{gtroff} directly. 741575584Sru@xref{Traps}, for further information on how to do this. 741669626Sru 741769626SruNegative @code{pl} values are possible also, but not very useful: No 741869626Srutrap is sprung, and each line is output on a single page (thus 741969626Srusuppressing all vertical spacing). 742069626Sru 742175584SruIf no argument or an invalid argument is given, @code{pl} sets the page 742275584Srulength to 11@dmn{i}. 742375584Sru@endDefreq 742475584Sru 742555839Sasmodai@cindex headers 742655839Sasmodai@cindex footers 742755839Sasmodai@cindex titles 742869626Sru@code{gtroff} provides several operations which help in setting up top 742969626Sruand bottom titles (or headers and footers). 743055839Sasmodai 743175584Sru@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 7432104862Sru@cindex title line (@code{tl}) 7433104862Sru@cindex three-part title (@code{tl}) 7434104862Sru@cindex page number character (@code{%}) 743575584SruPrint a @dfn{title line}. It consists of three parts: a left 743675584Srujustified portion, a centered portion, and a right justified portion. 743775584SruThe argument separator @samp{'} can be replaced with any character not 743875584Sruoccurring in the title line. The @samp{%} character is replaced with 743975584Sruthe current page number. This character can be changed with the 744075584Sru@code{pc} request (see below). 744155839Sasmodai 744275584SruWithout argument, @code{tl} is ignored. 744375584Sru 744475584SruSome notes: 744575584Sru 744675584Sru@itemize @bullet 744775584Sru@item 744875584SruA title line is not restricted to the top or bottom of a page. 744975584Sru 745075584Sru@item 745175584Sru@code{tl} prints the title line immediately, ignoring a partially filled 745275584Sruline (which stays untouched). 745375584Sru 745475584Sru@item 745575584SruIt is not an error to omit closing delimiters. For example, 745675584Sru@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 745775584Srutitle line with the left justified word @samp{foo}; the centered and 745875584Sruright justfied parts are empty. 745975584Sru 746075584Sru@item 746175584Sru@code{tl} accepts the same parameter delimiting characters as the 746275584Sru@code{\A} escape; see @ref{Escapes}. 746375584Sru@end itemize 746475584Sru@endDefreq 746575584Sru 7466104862Sru@DefreqList {lt, [@Var{length}]} 7467104862Sru@DefreqItem {lt, @t{+}@Var{length}} 7468104862Sru@DefreqItem {lt, @t{-}@Var{length}} 7469104862Sru@DefregListEnd {.lt} 7470104862Sru@cindex length of title line (@code{lt}) 7471104862Sru@cindex title line, length (@code{lt}) 7472104862Sru@cindex title line length register (@code{.lt}) 747375584SruThe title line is printed using its own line length, which is 747475584Sruspecified (or incremented or decremented) with the @code{lt} request. 747575584SruInitially, the title line length is set to 6.5@dmn{i}. If a negative 747675584Sruline length is specified (which is not allowed), @code{gtroff} emits a 747775584Sruwarning of type @samp{range} and sets the title line length to zero. 7478104862SruThe default scaling indicator is @samp{m}. If @code{lt} is called 747975584Sruwithout an argument, the title length is reset to the previous value 748075584Srubefore the last call to @code{lt}. 748155839Sasmodai 748275584SruThe current setting of this is available in the @code{.lt} read-only 748375584Srunumber register; it is associated with the current environment 748475584Sru(@pxref{Environments}). 748575584Sru 748675584Sru@endDefreq 748775584Sru 7488104862Sru@DefreqList {pn, page} 7489104862Sru@DefreqItem {pn, @t{+}@Var{page}} 7490104862Sru@DefreqItem {pn, @t{-}@Var{page}} 7491104862Sru@DefregListEnd {.pn} 7492104862Sru@cindex page number (@code{pn}) 7493104862Sru@cindex number, page (@code{pn}) 749475584SruChange (increase or decrease) the page number of the @emph{next} page. 749575584SruThe only argument is the page number; the request is ignored without a 749675584Sruparameter. 749755839Sasmodai 749875584SruThe read-only number register @code{.pn} contains the number of the next 749975584Srupage: either the value set by a @code{pn} request, or the number of the 750075584Srucurrent page plus@w{ }1. 750175584Sru@endDefreq 750275584Sru 750375584Sru@Defreg {%} 7504104862Sru@cindex page number register (@code{%}) 750575584SruA read-write register holding the current page number. 750675584Sru@endDefreg 750755839Sasmodai 7508104862Sru@Defreq {pc, [@Var{char}]} 7509104862Sru@cindex changing the page number character (@code{pc}) 7510104862Sru@cindex page number character, changing (@code{pc}) 751175584Sru@vindex % 751275584SruChange the page number character (used by the @code{tl} request) to a 751375584Srudifferent character. With no argument, this mechanism is disabled. 7514104862SruNote that this doesn't affect the number register@w{ }@code{%}. 751575584Sru@endDefreq 751655839Sasmodai 751769626Sru@xref{Traps}. 751855839Sasmodai 751955839Sasmodai 752069626Sru@c ===================================================================== 752169626Sru 752275584Sru@node Page Control, Fonts, Page Layout, gtroff Reference 752355839Sasmodai@section Page Control 752455839Sasmodai@cindex page control 752555839Sasmodai@cindex control, page 752655839Sasmodai 7527104862Sru@DefreqList {bp, [@Var{page}]} 7528104862Sru@DefreqItem {bp, @t{+}@Var{page}} 7529104862Sru@DefreqListEnd {bp, @t{-}@Var{page}} 7530104862Sru@cindex new page (@code{bp}) 7531104862Sru@cindex page, new (@code{bp}) 753275584SruStop processing the current page and move to the next page. This 753375584Srurequest causes a break. It can also take an argument to set 753475584Sru(increase, decrease) the page number of the next page. The only 753575584Srudifference between @code{bp} and @code{pn} is that @code{pn} does not 753675584Srucause a break or actually eject a page. 753755839Sasmodai 753875584Sru@Example 753975584Sru.de newpage \" define macro 754075584Sru'bp \" begin page 754175584Sru'sp .5i \" vertical space 754275584Sru.tl 'left top'center top'right top' \" title 754375584Sru'sp .3i \" vertical space 754475584Sru.. \" end macro 754575584Sru@endExample 754655839Sasmodai 7547104862Sru@cindex @code{bp} request, and top-level diversion 7548104862Sru@cindex top-level diversion, and @code{bp} 7549104862Sru@cindex diversion, top-level, and @code{bp} 755075584Sru@code{bp} has no effect if not called within the top-level diversion 755175584Sru(@pxref{Diversions}). 755275584Sru@endDefreq 755375584Sru 755475584Sru@Defreq {ne, [@Var{space}]} 7555104862Sru@cindex orphan lines, preventing with @code{ne} 7556104862Sru@cindex conditional page break (@code{ne}) 7557104862Sru@cindex page break, conditional (@code{ne}) 755869626SruIt is often necessary to force a certain amount of space before a new 755969626Srupage occurs. This is most useful to make sure that there is not a 756069626Srusingle @dfn{orphan} line left at the bottom of a page. The @code{ne} 756175584Srurequest ensures that there is a certain distance, specified by the 756275584Srufirst argument, before the next page is triggered (see @ref{Traps}, 7563104862Srufor further information). The default scaling indicator for @code{ne} 7564104862Sruis @samp{v}; the default value of @var{space} is@w{ }1@dmn{v} if no 7565104862Sruargument is given. 756655839Sasmodai 756769626SruFor example, to make sure that no fewer than 2@w{ }lines get orphaned, 756869626Srudo the following before each paragraph: 756955839Sasmodai 757075584Sru@Example 757155839Sasmodai.ne 2 757275584Srutext text text 757375584Sru@endExample 7574104862Sru 7575104862Sru@code{ne} will then automatically cause a page break if there is space 7576104862Srufor one line only. 757775584Sru@endDefreq 757855839Sasmodai 7579104862Sru@DefreqList {sv, [@Var{space}]} 7580104862Sru@DefreqListEnd {os, } 7581104862Sru@cindex @code{ne} request, comparison with @code{sv} 758275584Sru@code{sv} is similar to the @code{ne} request; it reserves the 758375584Sruspecified amount of vertical space. If the desired amount of space 7584104862Sruexists before the next trap (or the bottom page boundary if no trap is 7585104862Sruset), the space is output immediately (ignoring a partially filled line 7586104862Sruwhich stays untouched). If there is not enough space, it is stored for 7587104862Srulater output via the @code{os} request. The default value is@w{ }1@dmn{v} 7588104862Sruif no argument is given; the default scaling indicator is @samp{v}. 7589104862Sru 7590104862Sru@cindex @code{sv} request, and no-space mode 7591104862Sru@cindex @code{os} request, and no-space mode 7592104862SruBoth @code{sv} and @code{os} ignore no-space mode. While the @code{sv} 7593104862Srurequest allows negative values for @var{space}, @code{os} will ignore 7594104862Sruthem. 759575584Sru@endDefreq 759655839Sasmodai 7597104862Sru@Defreg {nl} 7598104862SruThis register contains the current vertical position. If the vertical 7599104862Sruposition is zero and the top of page transition hasn't happened yet, 7600104862Sru@code{nl} is set to negative value. @code{gtroff} itself does this at 7601104862Sruthe very beginning of a document before anything has been printed, but 7602104862Sruthe main usage is to plant a header trap on a page if this page has 7603104862Srualready started. 760455839Sasmodai 7605104862SruConsider the following: 7606104862Sru 7607104862Sru@Example 7608104862Sru.de xxx 7609104862Sru. sp 7610104862Sru. tl ''Header'' 7611104862Sru. sp 7612104862Sru.. 7613104862Sru. 7614104862SruFirst page. 7615104862Sru.bp 7616104862Sru.wh 0 xxx 7617104862Sru.nr nl (-1) 7618104862SruSecond page. 7619104862Sru@endExample 7620104862Sru 7621104862Sru@noindent 7622104862SruResult: 7623104862Sru 7624104862Sru@Example 7625104862SruFirst page. 7626104862Sru 7627104862Sru... 7628104862Sru 7629104862Sru Header 7630104862Sru 7631104862SruSecond page. 7632104862Sru 7633104862Sru... 7634104862Sru@endExample 7635104862Sru 7636104862Sru@noindent 7637104862SruWithout resetting @code{nl} to a negative value, the just planted trap 7638104862Sruwould be active beginning with the @emph{next} page, not the current 7639104862Sruone. 7640104862Sru 7641104862Sru@xref{Diversions}, for a comparison with the @code{.h} and @code{.d} 7642104862Sruregisters. 7643104862Sru@endDefreg 7644104862Sru 764569626Sru@c ===================================================================== 764669626Sru 764775584Sru@node Fonts, Sizes, Page Control, gtroff Reference 764855839Sasmodai@section Fonts 764955839Sasmodai@cindex fonts 765055839Sasmodai 765175584Sru@code{gtroff} can switch fonts at any point in the text. 765255839Sasmodai 765375584SruThe basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 7654104862SruThese are Times Roman, Italic, Bold, and Bold Italic. For non-TTY 765575584Srudevices, there is also at least one symbol font which contains various 765675584Sruspecial symbols (Greek, mathematics). 765755839Sasmodai 765855839Sasmodai@menu 765975584Sru* Changing Fonts:: 766075584Sru* Font Families:: 766175584Sru* Font Positions:: 766275584Sru* Using Symbols:: 766375584Sru* Special Fonts:: 766475584Sru* Artificial Fonts:: 766575584Sru* Ligatures and Kerning:: 766655839Sasmodai@end menu 766755839Sasmodai 766869626Sru@c --------------------------------------------------------------------- 766969626Sru 767055839Sasmodai@node Changing Fonts, Font Families, Fonts, Fonts 767155839Sasmodai@subsection Changing Fonts 7672104862Sru@cindex fonts 767355839Sasmodai 7674104862Sru@DefreqList {ft, [@Var{font}]} 7675104862Sru@DefescItem {\\f, , f, } 7676104862Sru@DefescItem {\\f, @lparen{}, fn, } 7677104862Sru@DefescListEnd {\\f, @lbrack{}, font, @rbrack} 7678104862Sru@cindex changing fonts (@code{ft}, @code{\f}) 7679104862Sru@cindex fonts, changing (@code{ft}, @code{\f}) 7680104862Sru@cindex @code{sty} request, and changing fonts 7681104862Sru@cindex @code{fam} request, and changing fonts 7682104862Sru@cindex @code{\F}, and changing fonts 768375584Sru@kindex styles 768475584Sru@kindex family 768575584Sru@pindex DESC 768675584SruThe @code{ft} request and the @code{\f} escape change the current font 7687104862Sruto @var{font} (one-character name@w{ }@var{f}, two-character name 768875584Sru@var{fn}). 768975584Sru 769075584SruIf @var{font} is a style name (as set with the @code{sty} request or 769175584Sruwith the @code{styles} command in the @file{DESC} file), use it within 7692104862Sruthe current font family (as set with the @code{fam} request, @code{\F} 7693104862Sruescape, or with the @code{family} command in the @file{DESC} file). 769475584Sru 7695104862Sru@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP}) 7696104862Sru@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP}) 769775584SruWith no argument or using @samp{P} as an argument, @code{.ft} switches 7698104862Sruto the previous font. Use @code{\f[]} to do this with the escape. The 7699104862Sruold syntax forms @code{\fP} or @code{\f[P]} are also supported. 770055839Sasmodai 770175584SruFonts are generally specified as upper-case strings, which are usually 770275584Sru1@w{ }to 4 characters representing an abbreviation or acronym of the 770375584Srufont name. This is no limitation, just a convention. 770475584Sru 770575584SruThe example below produces two identical lines. 770675584Sru 770775584Sru@Example 770855839Sasmodaieggs, bacon, 770955839Sasmodai.ft B 771055839Sasmodaispam 771155839Sasmodai.ft 771255839Sasmodaiand sausage. 771355839Sasmodai 771455839Sasmodaieggs, bacon, \fBspam\fP and sausage. 771575584Sru@endExample 771655839Sasmodai 7717104862SruNote that @code{\f} doesn't produce an input token in @code{gtroff}. 7718104862SruAs a consequence, it can be used in requests like @code{mc} (which 7719104862Sruexpects a single character as an argument) to change the font on 7720104862Sruthe fly: 7721104862Sru 7722104862Sru@Example 7723104862Sru.mc \f[I]x\f[] 7724104862Sru@endExample 7725104862Sru 772675584Sru@xref{Font Positions}, for an alternative syntax. 772775584Sru@endDefreq 772855839Sasmodai 772975584Sru@Defreq {ftr, f [@Var{g}]} 7730104862Sru@cindex @code{ft} request, and font translations 7731104862Sru@cindex @code{ul} request, and font translations 7732104862Sru@cindex @code{bd} request, and font translations 7733104862Sru@cindex @code{\f}, and font translations 7734104862Sru@cindex @code{cs} request, and font translations 7735104862Sru@cindex @code{tkf} request, and font translations 7736104862Sru@cindex @code{special} request, and font translations 7737104862Sru@cindex @code{fspecial} request, and font translations 7738104862Sru@cindex @code{fp} request, and font translations 7739104862Sru@cindex @code{sty} request, and font translations 7740104862SruTranslate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named@w{ 7741104862Sru}@var{f} is referred to in a @code{\f} escape sequence, or in the 774275584Sru@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 7743104862Sru@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, 7744104862Srufont@w{ }@var{g} is used. If @var{g} is missing or equal to@w{ }@var{f} 774575584Sruthe translation is undone. 774675584Sru@endDefreq 774755839Sasmodai 774869626Sru@c --------------------------------------------------------------------- 774969626Sru 775055839Sasmodai@node Font Families, Font Positions, Changing Fonts, Fonts 775155839Sasmodai@subsection Font Families 775255839Sasmodai@cindex font families 775355839Sasmodai@cindex families, font 775475584Sru@cindex font styles 775575584Sru@cindex styles, font 775655839Sasmodai 775769626SruDue to the variety of fonts available, @code{gtroff} has added the 775875584Sruconcept of @dfn{font families} and @dfn{font styles}. The fonts are 775975584Sruspecified as the concatenation of the font family and style. Specifying 776075584Srua font without the family part causes @code{gtroff} to use that style of 776175584Sruthe current family. 776255839Sasmodai 7763104862Sru@cindex PostScript fonts 7764104862Sru@cindex fonts, PostScript 7765104862SruCurrently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and 7766104862Sru@option{-Tlbp} are set up to this mechanism. 776775584SruBy default, @code{gtroff} uses the Times family with the four styles 776875584Sru@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 776955839Sasmodai 777069626SruThis way, it is possible to use the basic four fonts and to select a 777175584Srudifferent font family on the command line (@pxref{Groff Options}). 777255839Sasmodai 7773104862Sru@DefreqList {fam, [@Var{family}]} 7774104862Sru@DefregItem {.fam} 7775104862Sru@DefescItem {\\F, , f, } 7776104862Sru@DefescItem {\\F, @lparen{}, fm, } 7777104862Sru@DefescItem {\\F, @lbrack{}, family, @rbrack} 7778104862Sru@DefregListEnd {.fn} 7779104862Sru@cindex changing font family (@code{fam}, @code{\F}) 7780104862Sru@cindex font family, changing (@code{fam}, @code{\F}) 7781104862SruSwitch font family to @var{family} (one-character name@w{ }@var{f}, 7782104862Srutwo-character name @var{fm}). If no argument is given, switch 7783104862Sruback to the previous font family. Use @code{\F[]} to do this with the 7784104862Sruescape. Note that @code{\FP} doesn't work; it selects font family 7785104862Sru@samp{P} instead. 778655839Sasmodai 7787104862SruThe value at start-up is @samp{T}. 7788104862SruThe current font family is available in the read-only number register 7789104862Sru@samp{.fam} (this is a string-valued register); it is associated with 7790104862Sruthe current environment. 7791104862Sru 779275584Sru@Example 779355839Sasmodaispam, 779475584Sru.fam H \" helvetica family 779575584Sruspam, \" used font is family H + style R = HR 779675584Sru.ft B \" family H + style B = font HB 779755839Sasmodaispam, 779875584Sru.fam T \" times family 779975584Sruspam, \" used font is family T + style B = TB 780075584Sru.ft AR \" font AR (not a style) 780155839Sasmodaibaked beans, 780275584Sru.ft R \" family T + style R = font TR 780355839Sasmodaiand spam. 780475584Sru@endExample 7805104862Sru 7806104862SruNote that @code{\F} doesn't produce an input token in @code{gtroff}. 7807104862SruAs a consequence, it can be used in requests like @code{mc} (which 7808104862Sruexpects a single character as an argument) to change the font family on 7809104862Sruthe fly: 7810104862Sru 7811104862Sru@Example 7812104862Sru.mc \F[P]x\F[] 7813104862Sru@endExample 7814104862Sru 7815104862SruThe @samp{.fn} register contains the current @dfn{real font name} 7816104862Sruof the current font. 7817104862SruThis is a string-valued register. 7818104862SruIf the current font is a style, the value of @code{\n[.fn]} 7819104862Sruis the proper concatenation of family and style name. 782075584Sru@endDefreq 782155839Sasmodai 782275584Sru@Defreq {sty, n style} 7823104862Sru@cindex changing font style (@code{sty}) 7824104862Sru@cindex font style, changing (@code{sty}) 7825104862Sru@cindex @code{cs} request, and font styles 7826104862Sru@cindex @code{bd} request, and font styles 7827104862Sru@cindex @code{tkf} request, and font styles 7828104862Sru@cindex @code{uf} request, and font styles 7829104862Sru@cindex @code{fspecial} request, and font styles 783075584SruAssociate @var{style} with font position@w{ }@var{n}. A font position 783175584Srucan be associated either with a font or with a style. The current 783275584Srufont is the index of a font position and so is also either a font or a 7833104862Srustyle. If it is a style, the font that is actually used is the font 7834104862Sruwhich name is the concatenation of the name of the current 783575584Srufamily and the name of the current style. For example, if the current 7836104862Srufont is@w{ }1 and font position@w{ }1 is associated with style 7837104862Sru@samp{R} and the current font family is @samp{T}, then font 783875584Sru@samp{TR} will be used. If the current font is not a style, then the 7839104862Srucurrent family is ignored. If the requests @code{cs}, @code{bd}, 7840104862Sru@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, 784175584Sruthey will instead be applied to the member of the current family 784275584Srucorresponding to that style. 784375584Sru 7844104862Sru@var{n}@w{ }must be a non-negative integer value. 784575584Sru 784675584Sru@pindex DESC 784775584Sru@kindex styles 784875584SruThe default family can be set with the @option{-f} option 784975584Sru(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 785075584Srufile controls which font positions (if any) are initially associated 785175584Sruwith styles rather than fonts. For example, the default setting for 785275584Sru@sc{PostScript} fonts 785375584Sru 785475584Sru@Example 785575584Srustyles R I B BI 785675584Sru@endExample 785775584Sru 785875584Sru@noindent 785975584Sruis equivalent to 786075584Sru 786175584Sru@Example 786275584Sru.sty 1 R 786375584Sru.sty 2 I 786475584Sru.sty 3 B 786575584Sru.sty 4 BI 786675584Sru@endExample 786775584Sru 7868104862Sru@code{fam} and @code{\F} always check whether the current font position 7869104862Sruis valid; this can give surprising results if the current font position is 787075584Sruassociated with a style. 787175584Sru 787275584SruIn the following example, we want to access the @sc{PostScript} font 787375584Sru@code{FooBar} from the font family @code{Foo}: 787475584Sru 787575584Sru@Example 787675584Sru.sty \n[.fp] Bar 787775584Sru.fam Foo 787875584Sru @result{} warning: can't find font `FooR' 787975584Sru@endExample 788075584Sru 788175584Sru@noindent 788275584SruThe default font position at start-up is@w{ }1; for the 788375584Sru@sc{PostScript} device, this is associated with style @samp{R}, so 788475584Sru@code{gtroff} tries to open @code{FooR}. 788575584Sru 788675584SruA solution to this problem is to use a dummy font like the following: 788775584Sru 788875584Sru@Example 788975584Sru.fp 0 dummy TR \" set up dummy font at position 0 789075584Sru.sty \n[.fp] Bar \" register style `Bar' 789175584Sru.ft 0 \" switch to font at position 0 789275584Sru.fam Foo \" activate family `Foo' 789375584Sru.ft Bar \" switch to font `FooBar' 789475584Sru@endExample 789575584Sru 789675584Sru@xref{Font Positions}. 789775584Sru@endDefreq 789875584Sru 789969626Sru@c --------------------------------------------------------------------- 790055839Sasmodai 790155839Sasmodai@node Font Positions, Using Symbols, Font Families, Fonts 790255839Sasmodai@subsection Font Positions 790355839Sasmodai@cindex font positions 790455839Sasmodai@cindex positions, font 790555839Sasmodai 790675584SruFor the sake of old phototypesetters and compatibility with old versions 790769626Sruof @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 790875584Sruon which various fonts are mounted. 790955839Sasmodai 7910104862Sru@DefreqList {fp, pos font [@Var{external-name}]} 7911104862Sru@DefregItem {.f} 7912104862Sru@DefregListEnd {.fp} 7913104862Sru@cindex mounting font (@code{fp}) 7914104862Sru@cindex font, mounting (@code{fp}) 791575584SruMount font @var{font} at position @var{pos} (which must be a 791675584Srunon-negative integer). This numeric position can then be referred to 791775584Sruwith font changing commands. When @code{gtroff} starts it is using 791875584Srufont position@w{ }1 (which must exist; position@w{ }0 is unused 791975584Sruusually at start-up). 792055839Sasmodai 7921104862Sru@cindex font position register (@code{.f}) 792275584SruThe current font in use, as a font position, is available in the 792375584Sruread-only number register @samp{.f}. This can be useful to remember the 792475584Srucurrent font for later recall. It is associated with the current 792575584Sruenvironment (@pxref{Environments}). 792655839Sasmodai 792775584Sru@Example 792875584Sru.nr save-font \n[.f] 792975584Sru.ft B 793075584Sru... text text text ... 793155839Sasmodai.ft \n[save-font] 793275584Sru@endExample 793355839Sasmodai 7934104862Sru@cindex next free font position register (@code{.fp}) 793575584SruThe number of the next free font position is available in the read-only 793675584Srunumber register @samp{.fp}. This is useful when mounting a new font, 793775584Srulike so: 793855839Sasmodai 793975584Sru@Example 794055839Sasmodai.fp \n[.fp] NEATOFONT 794175584Sru@endExample 794255839Sasmodai 794369626Sru@pindex DESC@r{, and font mounting} 794455839SasmodaiFonts not listed in the @file{DESC} file are automatically mounted on 794575584Sruthe next available font position when they are referenced. If a font 794675584Sruis to be mounted explicitly with the @code{fp} request on an unused 794775584Srufont position, it should be mounted on the first unused font position, 794875584Sruwhich can be found in the @code{.fp} register. Although @code{gtroff} 794975584Srudoes not enforce this strictly, it is not allowed to mount a font at a 795075584Sruposition whose number is much greater (approx.@: 1000 positions) than 795175584Sruthat of any currently used position. 795255839Sasmodai 795369626SruThe @code{fp} request has an optional third argument. This argument 795469626Srugives the external name of the font, which is used for finding the font 795555839Sasmodaidescription file. The second argument gives the internal name of the 795669626Srufont which is used to refer to the font in @code{gtroff} after it has 795775584Srubeen mounted. If there is no third argument then the internal name is 795875584Sruused as the external name. This feature makes it possible to use 795969626Srufonts with long names in compatibility mode. 796075584Sru@endDefreq 796155839Sasmodai 796275584SruBoth the @code{ft} request and the @code{\f} escape have alternative 796375584Srusyntax forms to access font positions. 796475584Sru 7965104862Sru@DefreqList {ft, nnn} 7966104862Sru@DefescItem {\\f, , n, } 7967104862Sru@DefescItem {\\f, @lparen{}, nn, } 7968104862Sru@DefescListEnd {\\f, @lbrack{}, nnn, @rbrack} 7969104862Sru@cindex changing font position (@code{\f}) 7970104862Sru@cindex font position, changing (@code{\f}) 7971104862Sru@cindex @code{sty} request, and font positions 7972104862Sru@cindex @code{fam} request, and font positions 7973104862Sru@cindex @code{\F}, and font positions 797475584Sru@kindex styles 797575584Sru@kindex family 797675584Sru@pindex DESC 7977104862SruChange the current font position to @var{nnn} (one-digit position@w{ 7978104862Sru}@var{n}, two-digit position @var{nn}), which must be a non-negative 797975584Sruinteger. 798075584Sru 798175584SruIf @var{nnn} is associated with a style (as set with the @code{sty} 798275584Srurequest or with the @code{styles} command in the @file{DESC} file), use 7983104862Sruit within the current font family (as set with the @code{fam} request, 7984104862Sruthe @code{\F} escape, or with the @code{family} command in the @file{DESC} 7985104862Srufile). 798675584Sru 798775584Sru@Example 798875584Sruthis is font 1 798975584Sru.ft 2 799075584Sruthis is font 2 799175584Sru.ft \" switch back to font 1 799275584Sru.ft 3 799375584Sruthis is font 3 799475584Sru.ft 799575584Sruthis is font 1 again 799675584Sru@endExample 799775584Sru 799875584Sru@xref{Changing Fonts}, for the standard syntax form. 799975584Sru@endDefreq 800075584Sru 800169626Sru@c --------------------------------------------------------------------- 800255839Sasmodai 800375584Sru@node Using Symbols, Special Fonts, Font Positions, Fonts 800455839Sasmodai@subsection Using Symbols 800555839Sasmodai@cindex using symbols 800655839Sasmodai@cindex symbols, using 800755839Sasmodai 800875584Sru@cindex glyph 800975584Sru@cindex character 801075584Sru@cindex ligature 801175584SruA @dfn{glyph} is a graphical representation of a @dfn{character}. 801275584SruWhile a character is an abstract entity containing semantic 801375584Sruinformation, a glyph is something which can be actually seen on screen 801475584Sruor paper. It is possible that a character has multiple glyph 801575584Srurepresentation forms (for example, the character `A' can be either 801675584Sruwritten in a roman or an italic font, yielding two different glyphs); 801775584Srusometimes more than one character maps to a single glyph (this is a 801875584Sru@dfn{ligature} -- the most common is `fi'). 801955839Sasmodai 802075584Sru@cindex symbol 802175584Sru@cindex special fonts 802275584Sru@kindex fonts 802375584Sru@pindex DESC 802475584SruA @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 802575584Sruglyph names of a particular font are defined in its font file. If the 802675584Sruuser requests a glyph not available in this font, @code{gtroff} looks 802775584Sruup an ordered list of @dfn{special fonts}. By default, the 802875584Sru@sc{PostScript} output device supports the two special fonts @samp{SS} 802975584Sru(slanted symbols) and @samp{S} (symbols) (the former is looked up 803075584Srubefore the latter). Other output devices use different names for 803175584Sruspecial fonts. Fonts mounted with the @code{fonts} keyword in the 803275584Sru@file{DESC} file are globally available. To install additional 803375584Sruspecial fonts locally (i.e.@: for a particular font), use the 803475584Sru@code{fspecial} request. 803555839Sasmodai 8036104862SruIn summary, @code{gtroff} tries the following to find a given symbol: 8037104862Sru 8038104862Sru@itemize @bullet 8039104862Sru@item 8040104862SruIf the symbol has been defined with the @code{char} request, use it. 8041104862SruThis hides a symbol with the same name in the current font. 8042104862Sru 8043104862Sru@item 8044104862SruCheck the current font. 8045104862Sru 8046104862Sru@item 8047104862SruIf the symbol has been defined with the @code{fchar} request, use it. 8048104862Sru 8049104862Sru@item 8050104862SruCheck all fonts given with the @code{fspecial} request, in the order 8051104862Sruof appearance in @code{fspecial} calls. 8052104862Sru 8053104862Sru@item 8054104862SruCheck all fonts given with the @code{special} request, in the order 8055104862Sruof appearance in @code{special} calls (inclusively the special fonts 8056104862Srudefined in the @file{DESC} file, which come first). 8057104862Sru 8058104862Sru@item 8059104862SruAs a last resort, consult all fonts loaded up to now (in the order they 8060104862Sruhave been called the first time) for special fonts and check them. 8061104862Sru@end itemize 8062104862Sru 806375584Sru@xref{Font Files}, and @ref{Special Fonts}, for more details. 806455839Sasmodai 8065104862Sru@DefescList {\\, @lparen{}, nm, } 8066104862Sru@DefescListEnd {\\, @lbrack{}, name, @rbrack} 806775584SruInsert a symbol @var{name} (two-character name @var{nm}). There is no 806875584Sruspecial syntax for one-character names -- the natural form 8069104862Sru@samp{\@var{n}} would collide with escapes.@footnote{Note that a 8070104862Sruone-character symbol is not the same as an input character, i.e., the 8071104862Srucharacter @code{a} is not the same as @code{\[a]}. By default, 8072104862Sru@code{groff} defines only a single one-character symbol, @code{\[-]}; 8073104862Sruit is usually accessed as @code{\-}. On the other hand, @code{gtroff} 8074104862Sruhas the special feature that @code{\[char@var{XXX}]} is the same as the 8075104862Sruinput character with character code @var{XXX}. For example, 8076104862Sru@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} 8077104862Sruencoding is active.} 807875584Sru 807975584SruIf @var{name} is undefined, a warning of type @samp{char} is generated, 808075584Sruand the escape is ignored. @xref{Debugging}, for information about 808175584Sruwarnings. 808275584Sru 8083104862Sru@cindex list of available glyphs (@cite{groff_char(7)} man page) 8084104862Sru@cindex available glyphs, list (@cite{groff_char(7)} man page) 8085104862Sru@cindex glyphs, available, list (@cite{groff_char(7)} man page) 8086104862SruThe list of available symbols is device dependent; see the 8087104862Sru@cite{groff_char(7)} man page for a complete list for the given output 8088104862Srudevice. For example, say 808975584Sru 8090104862Sru@Example 8091104862Sruman -Tdvi groff_char > groff_char.dvi 8092104862Sru@endExample 8093104862Sru 8094104862Sru@noindent 8095104862Srufor a list using the default DVI fonts (not all versions of the 8096104862Sru@code{man} program support the @option{-T} option). If you want to 8097104862Sruuse an additional macro package to change the used fonts, @code{groff} 8098104862Srumust be called directly: 8099104862Sru 8100104862Sru@Example 8101104862Srugroff -Tdvi -mec -man groff_char.7 > groff_char.dvi 8102104862Sru@endExample 8103104862Sru 810475584Sru@c XXX list of common symbols 810575584Sru@endDefesc 810675584Sru 810775584Sru@Defesc {\\C, ', xxx, '} 8108104862Sru@cindex named character (@code{\C}) 8109104862Sru@cindex character, named (@code{\C}) 8110104862SruTypeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a 8111104862Srumisnomer since it accesses an output glyph.} Normally it is more 8112104862Sruconvenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage 8113104862Sruthat it is compatible with newer versions of @acronym{AT&T} 8114104862Sru@code{troff} and is available in compatibility mode. 811575584Sru@endDefesc 811675584Sru 811775584Sru@Defesc {\\N, ', n, '} 8118104862Sru@cindex numbered glyph (@code{\N}) 8119104862Sru@cindex glyph, numbered (@code{\N}) 8120104862Sru@cindex @code{char} request, used with @code{\N} 8121104862Sru@cindex Unicode 8122104862SruTypeset the glyph with code@w{ }@var{n} in the current font 8123104862Sru(@code{n}@w{ }is @strong{not} the input character code). The 8124104862Srunumber @var{n}@w{ }can be any non-negative decimal integer. Most devices 8125104862Sruonly have glyphs with codes between 0 and@w{ }255; the Unicode 8126104862Sruoutput device uses codes in the range 0--65535. If the current 8127104862Srufont does not contain a glyph with that code, special fonts are 8128104862Sru@emph{not} searched. The @code{\N} escape sequence can be 8129104862Sruconveniently used in conjunction with the @code{char} request: 813075584Sru 813175584Sru@Example 813275584Sru.char \[phone] \f[ZD]\N'37' 813375584Sru@endExample 813475584Sru 813569626Sru@noindent 813669626Sru@pindex DESC 8137104862Sru@cindex unnamed glyphs 8138104862Sru@cindex glyphs, unnamed 8139104862SruThe code of each glyph is given in the fourth column in the font 814075584Srudescription file after the @code{charset} command. It is possible to 8141104862Sruinclude unnamed glyphs in the font description file by using a 814275584Sruname of @samp{---}; the @code{\N} escape sequence is the only way to 814375584Sruuse these. 814475584Sru@endDefesc 814555839Sasmodai 8146104862SruSome escape sequences directly map onto special glyphs. 814769626Sru 8148104862Sru@Defesc {\\', , , } 8149104862SruThis is a backslash followed by the apostrophe character, @acronym{ASCII} 8150104862Srucharacter @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same 8151104862Sruas @code{\[aa]}, the acute accent. 8152104862Sru@endDefesc 8153104862Sru 8154104862Sru@Defesc {\\`, , , } 8155104862SruThis is a backslash followed by @acronym{ASCII} character @code{0x60} 8156104862Sru(@acronym{EBCDIC} character @code{0x79} usually). The same as 8157104862Sru@code{\[ga]}, the grave accent. 8158104862Sru@endDefesc 8159104862Sru 8160104862Sru@Defesc {\\-, , , } 8161104862SruThis is the same as @code{\[-]}, the minus sign in the current font. 8162104862Sru@endDefesc 8163104862Sru 816475584Sru@Defreq {cflags, n c1 c2 @dots{}} 8165104862Sru@cindex glyph properties (@code{cflags}) 8166104862Sru@cindex character properties (@code{cflags}) 8167104862Sru@cindex properties of glyphs (@code{cflags}) 8168104862Sru@cindex properties of characters (@code{cflags}) 8169104862SruInput characters and symbols have certain properties associated 8170104862Sruwith it.@footnote{Note that the output glyphs themselves don't have 8171104862Srusuch properties. For @code{gtroff}, a glyph is a numbered box with 8172104862Srua given width, depth, and height, nothing else. All manipulations 8173104862Sruwith the @code{cflags} request work on the input level.} These 8174104862Sruproperties can be modified with the @code{cflags} request. The 8175104862Srufirst argument is the sum of the desired flags and the remaining 8176104862Sruarguments are the characters or symbols to have those properties. 8177104862SruIt is possible to omit the spaces between the characters or symbols. 817869626Sru 817955839Sasmodai@table @code 818055839Sasmodai@item 1 8181104862Sru@cindex end-of-sentence characters 8182104862Sru@cindex characters, end-of-sentence 8183104862SruThe character ends sentences (initially characters @samp{.?!} have this 8184104862Sruproperty). 818569626Sru 818655839Sasmodai@item 2 818769626Sru@cindex hyphenating characters 818869626Sru@cindex characters, hyphenation 8189104862SruLines can be broken before the character (initially no characters have 8190104862Sruthis property). 819169626Sru 819255839Sasmodai@item 4 8193104862Sru@cindex @code{hy} glyph, and @code{cflags} 8194104862Sru@cindex @code{em} glyph, and @code{cflags} 8195104862SruLines can be broken after the character (initially the character 8196104862Sru@samp{-} and the symbols @samp{\(hy} and @samp{\(em} have this property). 819769626Sru 819855839Sasmodai@item 8 819969626Sru@cindex overlapping characters 820069626Sru@cindex characters, overlapping 8201104862Sru@cindex @code{ul} glyph, and @code{cflags} 8202104862Sru@cindex @code{rn} glyph, and @code{cflags} 8203104862Sru@cindex @code{ru} glyph, and @code{cflags} 8204104862SruThe character overlaps horizontally (initially the symbols 8205104862Sru@samp{\(ul\(rn\(ru} have this property). 820669626Sru 820755839Sasmodai@item 16 8208104862Sru@cindex @code{br} glyph, and @code{cflags} 8209104862SruThe character overlaps vertically (initially symbol @samp{\(br} has 8210104862Sruthis property). 821169626Sru 821255839Sasmodai@item 32 821369626Sru@cindex transparent characters 821469626Sru@cindex character, transparent 8215104862Sru@cindex @code{"}, at end of sentence 8216104862Sru@cindex @code{'}, at end of sentence 8217104862Sru@cindex @code{)}, at end of sentence 8218104862Sru@cindex @code{]}, at end of sentence 8219104862Sru@cindex @code{*}, at end of sentence 8220104862Sru@cindex @code{dg} glyph, at end of sentence 8221104862Sru@cindex @code{rq} glyph, at end of sentence 8222104862SruAn end-of-sentence character followed by any number of characters with 822375584Sruthis property is treated as the end of a sentence if followed by a 822475584Srunewline or two spaces; in other words the character is 8225104862Sru@dfn{transparent} for the purposes of end-of-sentence recognition -- 822675584Sruthis is the same as having a zero space factor in @TeX{} (initially 8227104862Srucharacters @samp{"')]*} and the symbols @samp{\(dg\(rq} have this 8228104862Sruproperty). 822955839Sasmodai@end table 823075584Sru@endDefreq 823155839Sasmodai 8232104862Sru@DefreqList {char, g [@Var{string}]} 8233104862Sru@DefreqListEnd {fchar, g [@Var{string}]} 8234104862Sru@cindex defining character (@code{char}) 8235104862Sru@cindex character, defining (@code{char}) 8236104862Sru@cindex creating new characters (@code{char}) 8237104862Sru@cindex defining symbol (@code{char}) 8238104862Sru@cindex symbol, defining (@code{char}) 8239104862Sru@cindex defining glyph (@code{char}) 8240104862Sru@cindex glyph, defining (@code{char}) 8241104862Sru@cindex escape character, while defining glyph 8242104862Sru@cindex character, escape, while defining glyph 8243104862Sru@cindex @code{tr} request, and glyph definitions 8244104862Sru@cindex @code{cp} request, and glyph definitions 8245104862Sru@cindex @code{rc} request, and glyph definitions 8246104862Sru@cindex @code{lc} request, and glyph definitions 8247104862Sru@cindex @code{\l}, and glyph definitions 8248104862Sru@cindex @code{\L}, and glyph definitions 8249104862Sru@cindex @code{\&}, and glyph definitions 8250104862Sru@cindex @code{\e}, and glyph definitions 8251104862Sru@cindex @code{hcode} request, and glyph definitions 8252104862SruDefine a new glyph@w{ }@var{g} to be @var{string} (which can be 8253104862Sruempty).@footnote{@code{char} is a misnomer since an output glyph is 8254104862Srudefined.} Every time glyph@w{ }@var{g} needs to be printed, 825575584Sru@var{string} is processed in a temporary environment and the result is 825675584Sruwrapped up into a single object. Compatibility mode is turned off and 825775584Sruthe escape character is set to @samp{\} while @var{string} is being 825875584Sruprocessed. Any emboldening, constant spacing or track kerning is 825969626Sruapplied to this object rather than to individual characters in 8260104862Sru@var{string}. 8261104862Sru 8262104862SruA glyph defined by this request can be used just 8263104862Srulike a normal glyph provided by the output device. In particular, 8264104862Sruother characters can be translated to it with the @code{tr} or 8265104862Sru@code{trin} requests; it can be made the leader character by the 8266104862Sru@code{lc} request; repeated patterns can be drawn with the glyph 8267104862Sruusing the @code{\l} and @code{\L} escape sequences; words containing 8268104862Sruthe glyph can be hyphenated correctly if the @code{hcode} request 8269104862Sruis used to give the glyph's symbol a hyphenation code. 8270104862Sru 8271104862SruThere is a special anti-recursion feature: Use of @code{g} within 8272104862Sruthe glyph's definition is handled like normal characters and symbols 8273104862Srunot defined with @code{char}. 8274104862Sru 8275104862SruNote that the @code{tr} and @code{trin} requests take precedence if 8276104862Sru@code{char} accesses the same symbol. 8277104862Sru 8278104862Sru@Example 8279104862Sru.tr XY 8280104862SruX 8281104862Sru @result{} Y 8282104862Sru.char X Z 8283104862SruX 8284104862Sru @result{} Y 8285104862Sru.tr XX 8286104862SruX 8287104862Sru @result{} Z 8288104862Sru@endExample 8289104862Sru 8290104862SruThe @code{fchar} request defines a fallback glyph: 8291104862Sru@code{gtroff} only checks for glyphs defined with @code{fchar} 8292104862Sruif it cannot find the glyph in the current font. 8293104862Sru@code{gtroff} carries out this test before checking special fonts. 829475584Sru@endDefreq 829569626Sru 829675584Sru@Defreq {rchar, c1 c2 @dots{}} 8297104862Sru@cindex removing glyph definition (@code{rchar}) 8298104862Sru@cindex glyph, removing definition (@code{rchar}) 8299104862SruRemove the definitions of glyphs @var{c1}, @var{c2},@w{ 8300104862Sru}@enddots{} This undoes the effect of a @code{char} or @code{fchar} 8301104862Srurequest. 830255839Sasmodai 830375584SruIt is possible to omit the whitespace between arguments. 830475584Sru@endDefreq 830575584Sru 830669626Sru@xref{Special Characters}. 830755839Sasmodai 830869626Sru@c --------------------------------------------------------------------- 830969626Sru 831075584Sru@node Special Fonts, Artificial Fonts, Using Symbols, Fonts 831175584Sru@subsection Special Fonts 831275584Sru@cindex special fonts 831375584Sru@cindex fonts, special 831475584Sru 8315104862SruSpecial fonts are those that @code{gtroff} searches 8316104862Sruwhen it cannot find the requested glyph in the current font. 8317104862SruThe Symbol font is usually a special font. 831875584Sru 8319104862Sru@code{gtroff} provides the following two requests to add more special 8320104862Srufonts. @xref{Using Symbols}, for a detailed description of the glyph 8321104862Srusearching mechanism in @code{gtroff}. 832275584Sru 8323104862SruUsually, only non-TTY devices have special fonts. 8324104862Sru 8325104862Sru@DefreqList {special, s1 s2 @dots{}} 8326104862Sru@DefreqListEnd {fspecial, f s1 s2 @dots{}} 8327104862Sru@kindex fonts 8328104862Sru@pindex DESC 8329104862SruUse the @code{special} request to define special fonts. They are 8330104862Sruappended to the list of global special fonts in the given order. 8331104862SruThe first entries in this list are the fonts defined with the 8332104862Sru@code{fonts} command in the @file{DESC} file which are marked as 8333104862Sruspecial in the corresponding font description files. 8334104862Sru 8335104862SruUse the @code{fspecial} request to designate special fonts 8336104862Sruonly when font@w{ }@var{f} font is active. They are appended to the 8337104862Srulist of special fonts for @var{f} in the given order. Initially, this 8338104862Srulist is empty. 8339104862Sru@endDefreq 8340104862Sru 834175584Sru@c --------------------------------------------------------------------- 834275584Sru 834375584Sru@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts 834455839Sasmodai@subsection Artificial Fonts 834555839Sasmodai@cindex artificial fonts 834655839Sasmodai@cindex fonts, artificial 834755839Sasmodai 8348104862SruThere are a number of requests and escapes for artificially creating 8349104862Srufonts. These are largely vestiges of the days when output devices 8350104862Srudid not have a wide variety of fonts, and when @code{nroff} and 8351104862Sru@code{troff} were separate programs. Most of them are no longer 8352104862Srunecessary in GNU @code{troff}. Nevertheless, they are supported. 835355839Sasmodai 8354104862Sru@DefescList {\\H, ', height, '} 8355104862Sru@DefescItem {\\H, ', @t{+}@Var{height}, '} 8356104862Sru@DefescListEnd {\\H, ', @t{-}@Var{height}, '} 8357104862Sru@cindex changing the font height (@code{\H}) 8358104862Sru@cindex font height, changing (@code{\H}) 8359104862Sru@cindex height, font, changing (@code{\H}) 8360104862SruChange (increment, decrement) the height of the current font, but not 8361104862Sruthe width. If @var{height} is zero, restore the original height. 8362104862SruDefault scaling indicator is @samp{z}. 8363104862Sru 8364104862SruCurrently, only the @option{-Tps} device supports this feature. 8365104862Sru 8366104862SruNote that @code{\H} doesn't produce an input token in @code{gtroff}. 8367104862SruAs a consequence, it can be used in requests like @code{mc} (which 8368104862Sruexpects a single character as an argument) to change the font on 8369104862Sruthe fly: 8370104862Sru 8371104862Sru@Example 8372104862Sru.mc \H'+5z'x\H'0' 8373104862Sru@endExample 8374104862Sru 8375104862SruIn compatibility mode, @code{gtroff} behaves differently: If an 8376104862Sruincrement or decrement is used, it is always taken relative to the 8377104862Srucurrent point size and not relative to the previously selected font 8378104862Sruheight. Thus, 8379104862Sru 8380104862Sru@Example 8381104862Sru.cp 1 8382104862Sru\H'+5'test \H'+5'test 8383104862Sru@endExample 8384104862Sru 8385104862Sru@noindent 8386104862Sruprints the word @samp{test} twice with the same font height (five 8387104862Srupoints larger than the current font size). 8388104862Sru@endDefesc 8389104862Sru 8390104862Sru@DefescList {\\S, ', slant, '} 8391104862Sru@cindex changing the font slant (@code{\S}) 8392104862Sru@cindex font slant, changing (@code{\S}) 8393104862Sru@cindex slant, font, changing (@code{\S}) 8394104862SruSlant the current font by @var{slant} degrees. Positive values slant 8395104862Sruto the right. 8396104862Sru 8397104862SruCurrently, only the @option{-Tps} device supports this feature. 8398104862Sru 8399104862SruNote that @code{\S} doesn't produce an input token in @code{gtroff}. 8400104862SruAs a consequence, it can be used in requests like @code{mc} (which 8401104862Sruexpects a single character as an argument) to change the font on 8402104862Sruthe fly: 8403104862Sru 8404104862Sru@Example 8405104862Sru.mc \S'20'x\S'0' 8406104862Sru@endExample 8407104862Sru 8408104862SruThis request is incorrectly documented in the original @acronym{UNIX} 8409104862Srutroff manual; the slant is always set to an absolute value. 8410104862Sru@endDefesc 8411104862Sru 841275584Sru@Defreq {ul, [@Var{lines}]} 8413104862Sru@cindex underlining (@code{ul}) 8414104862SruThe @code{ul} request normally underlines subsequent lines if a TTY 841575584Sruoutput device is used. Otherwise, the lines are printed in italics 841675584Sru(only the term `underlined' is used in the following). The single 841775584Sruargument is the number of input lines to be underlined; with no 841875584Sruargument, the next line is underlined. If @var{lines} is zero or 841975584Srunegative, stop the effects of @code{ul} (if it was active). Requests 842075584Sruand empty lines do not count for computing the number of underlined 842175584Sruinput lines, even if they produce some output like @code{tl}. Lines 842275584Sruinserted by macros (e.g.@: invoked by a trap) do count. 842355839Sasmodai 842475584SruAt the beginning of @code{ul}, the current font is stored and the 842575584Sruunderline font is activated. Within the span of a @code{ul} request, 842675584Sruit is possible to change fonts, but after the last line affected by 842775584Sru@code{ul} the saved font is restored. 842875584Sru 8429104862SruThis number of lines still to be underlined is associated with the 8430104862Srucurrent environment (@pxref{Environments}). The underline font can be 8431104862Sruchanged with the @code{uf} request. 843275584Sru 843375584Sru@c XXX @xref should be changed to grotty 843475584Sru 8435104862Sru@c @xref{Troff and Nroff Mode}, for a discussion how underlining is 8436104862Sru@c implemented in for TTY output devices, and which problems can arise. 843775584Sru 843875584SruThe @code{ul} request does not underline spaces. 843975584Sru@endDefreq 844075584Sru 844175584Sru@Defreq {cu, [@Var{lines}]} 8442104862Sru@cindex continuous underlining (@code{cu}) 8443104862Sru@cindex underlining, continuous (@code{cu}) 844475584SruThe @code{cu} request is similar to @code{ul} but underlines spaces as 8445104862Sruwell (if a TTY output device is used). 844675584Sru@endDefreq 844755839Sasmodai 844875584Sru@Defreq {uf, font} 8449104862Sru@cindex underline font (@code{uf}) 8450104862Sru@cindex font for underlining (@code{uf}) 845175584SruSet the underline font (globally) used by @code{ul} and @code{cu}. By 845275584Srudefault, this is the font at position@w{ }2. @var{font} can be either 845375584Srua non-negative font position or the name of a font. 845475584Sru@endDefreq 845555839Sasmodai 8456104862Sru@DefreqList {bd, font [@Var{offset}]} 8457104862Sru@DefreqItem {bd, font1 font2 [@Var{offset}]} 8458104862Sru@DefregListEnd {.b} 8459104862Sru@cindex imitating bold face (@code{bd}) 8460104862Sru@cindex bold face, imitating (@code{bd}) 8461104862SruArtificially create a bold font by printing each glyph twice, 846275584Sruslightly offset. 846355839Sasmodai 846475584SruTwo syntax forms are available. 846575584Sru 846675584Sru@itemize @bullet 846775584Sru@item 846875584SruImitate a bold font unconditionally. The first argument specifies the 846975584Srufont to embolden, and the second is the number of basic units, minus 8470104862Sruone, by which the two glyphs are offset. If the second argument is 847175584Srumissing, emboldening is turned off. 847275584Sru 847375584Sru@var{font} can be either a non-negative font position or the name of a 847475584Srufont. 847575584Sru 847675584Sru@var{offset} is available in the @code{.b} read-only register if a 847775584Sruspecial font is active; in the @code{bd} request, its default unit is 847875584Sru@samp{u}. 847975584Sru 8480104862Sru@cindex @code{fspecial} request, and imitating bold 848175584Sru@kindex special 848275584Sru@cindex embolding of special fonts 848375584Sru@cindex special fonts, emboldening 848475584Sru@item 848575584SruImitate a bold form conditionally. Embolden @var{font1} by 848675584Sru@var{offset} only if font @var{font2} is the current font. This 848775584Srucommand can be issued repeatedly to set up different emboldening 848875584Sruvalues for different current fonts. If the second argument is 848975584Srumissing, emboldening is turned off for this particular current font. 849075584Sru 849175584SruThis affects special fonts only (either set up with the @code{special} 849275584Srucommand in font files or with the @code{fspecial} request). 849375584Sru@end itemize 849475584Sru@endDefreq 849575584Sru 849675584Sru@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 8497104862Sru@cindex constant glyph space mode (@code{cs}) 8498104862Sru@cindex mode for constant glyph space (@code{cs}) 8499104862Sru@cindex glyph, constant space 8500104862Sru@cindex @code{ps} request, and constant glyph space mode 8501104862SruSwitch to and from @dfn{constant glyph space mode}. If activated, the 8502104862Sruwidth of every glyph is @math{@var{width}/36} ems. The em size is 850375584Srugiven absolutely by @var{em-size}; if this argument is missing, the em 850475584Sruvalue is taken from the current font size (as set with the @code{ps} 850575584Srurequest) when the font is effectively in use. Without second and 8506104862Sruthird argument, constant glyph space mode is deactivated. 850775584Sru 8508104862SruDefault scaling indicator for @var{em-size} is @samp{z}; @var{width} is 8509104862Sruan integer. 851075584Sru@endDefreq 851175584Sru 851269626Sru@c --------------------------------------------------------------------- 851355839Sasmodai 851455839Sasmodai@node Ligatures and Kerning, , Artificial Fonts, Fonts 851555839Sasmodai@subsection Ligatures and Kerning 851655839Sasmodai@cindex ligatures and kerning 851755839Sasmodai@cindex kerning and ligatures 851855839Sasmodai 8519104862SruLigatures are groups of characters that are run together, i.e, producing 8520104862Srua single glyph. For example, the letters `f' and `i' can form a 8521104862Sruligature `fi' as in the word `file'. This produces a cleaner look 8522104862Sru(albeit subtle) to the printed output. Usually, ligatures are not 8523104862Sruavailable in fonts for TTY output devices. 852455839Sasmodai 852575584SruMost @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 8526104862Srutypesetter that was the target of @acronym{AT&T} @code{troff} also 8527104862Srusupported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or 8528104862Sru`expert' fonts may include ligatures for `ft' and `ct', although GNU 852975584Sru@code{troff} does not support these (yet). 853069626Sru 8531104862Sru@DefreqList {lg, [@Var{flag}]} 8532104862Sru@DefregListEnd {.lg} 8533104862Sru@cindex activating ligatures (@code{lg}) 8534104862Sru@cindex ligatures, activating (@code{lg}) 8535104862Sru@cindex ligatures enabled register (@code{.lg}) 8536104862SruSwitch the ligature mechanism on or off; if the parameter is non-zero 8537104862Sruor missing, ligatures are enabled, otherwise disabled. Default is on. 8538104862SruThe current ligature mode can be found in the read-only number register 8539104862Sru@code{.lg} (set to 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise). 854055839Sasmodai 854175584SruSetting the ligature mode to@w{ }2 enables the two-character ligatures 854275584Sru(fi, fl, and ff) and disables the three-character ligatures (ffi and 854375584Sruffl). 854475584Sru@endDefreq 854555839Sasmodai 854675584Sru@dfn{Pairwise kerning} is another subtle typesetting mechanism that 8547104862Srumodifies the distance between a glyph pair to improve readability. 854875584SruIn most cases (but not always) the distance is decreased. 854975584Sru@ifnotinfo 855075584SruFor example, compare the combination of the letters `V' and `A'. With 855175584Srukerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 855275584Sru@end ifnotinfo 8553104862SruTypewriter-like fonts and fonts for terminals where all glyphs 855475584Sruhave the same width don't use kerning. 855569626Sru 8556104862Sru@DefreqList {kern, [@Var{flag}]} 8557104862Sru@DefregListEnd {.kern} 8558104862Sru@cindex activating kerning (@code{kern}) 8559104862Sru@cindex kerning, activating (@code{kern}) 8560104862Sru@cindex kerning enabled register (@code{.kern}) 8561104862SruSwitch kerning on or off. If the parameter is non-zero or missing, 8562104862Sruenable pairwise kerning, otherwise disable it. The read-only number 8563104862Sruregister @code{.kern} is set to@w{ }1 if pairwise kerning is enabled, 8564104862Sru0@w{ }otherwise. 856575584Sru 8566104862Sru@cindex zero width space character (@code{\&}) 8567104862Sru@cindex character, zero width space (@code{\&}) 8568104862Sru@cindex space character, zero width (@code{\&}) 856955839SasmodaiIf the font description file contains pairwise kerning information, 8570104862Sruglyphs from that font are kerned. Kerning between two glyphs 857175584Srucan be inhibited by placing @code{\&} between them: @samp{V\&A}. 857255839Sasmodai 857375584Sru@xref{Font File Format}. 857475584Sru@endDefreq 857555839Sasmodai 857669626Sru@cindex track kerning 857769626Sru@cindex kerning, track 8578104862Sru@dfn{Track kerning} expands or reduces the space between glyphs. 857975584SruThis can be handy, for example, if you need to squeeze a long word 858075584Sruonto a single line or spread some text to fill a narrow column. It 858175584Srumust be used with great care since it is usually considered bad 858275584Srutypography if the reader notices the effect. 858369626Sru 858475584Sru@Defreq {tkf, f s1 n1 s2 n2} 8585104862Sru@cindex activating track kerning (@code{tkf}) 8586104862Sru@cindex track kerning, activating (@code{tkf}) 858775584SruEnable track kerning for font@w{ }@var{f}. If the current font is@w{ 8588104862Sru}@var{f} the width of every glyph is increased by an amount 858975584Srubetween @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 859075584Sruthe current point size is less than or equal to @var{s1} the width is 859175584Sruincreased by @var{n1}; if it is greater than or equal to @var{s2} the 859275584Sruwidth is increased by @var{n2}; if the point size is greater than or 859375584Sruequal to @var{s1} and less than or equal to @var{s2} the increase in 859475584Sruwidth is a linear function of the point size. 859569626Sru 8596104862SruThe default scaling indicator is @samp{z} for @var{s1} and @var{s2}, 8597104862Sru@samp{p} for @var{n1} and @var{n2}. 8598104862Sru 8599104862SruNote that the track kerning amount is added even to the rightmost glyph 8600104862Sruin a line; for large values it is thus recommended to increase the line 8601104862Srulength by the same amount to compensate it. 860275584Sru@endDefreq 860369626Sru 860475584SruSometimes, when typesetting letters of different fonts, more or less 860575584Sruspace at such boundaries are needed. There are two escapes to help 860675584Sruwith this. 860769626Sru 860875584Sru@Defesc {\\/, , , } 8609104862Sru@cindex italic correction (@code{\/}) 8610104862Sru@cindex correction, italic (@code{\/}) 8611104862Sru@cindex correction between italic and roman glyph (@code{\/}, @code{\,}) 8612104862Sru@cindex roman glyph, correction after italic glyph (@code{\/}) 8613104862Sru@cindex italic glyph, correction before roman glyph (@code{\/}) 8614104862Sru@cindex glyph, italic correction (@code{\/}) 8615104862SruIncrease the width of the preceding glyph so that the spacing 8616104862Srubetween that glyph and the following glyph is correct if the 8617104862Srufollowing glyph is a roman glyph. For example, if an 861875584Sruitalic@w{ }@code{f} is immediately followed by a roman right 8619104862Sruparenthesis, then in many fonts the top right portion of the@w{ }@code{f} 862075584Sruoverlaps the top left of the right parenthesis. Use this escape 8621104862Srusequence whenever an italic glyph is immediately followed by a 8622104862Sruroman glyph without any intervening space. This small amount of 862375584Sruspace is also called @dfn{italic correction}. 862475584Sru 862575584Sru@iftex 862669626Sru@example 862775584Sru@group 862875584Sru\f[I]f\f[R]) 862975584Sru @result{} {@it f}@r{)} 863075584Sru\f[I]f\/\f[R]) 863175584Sru @result{} @i{f}@r{)} 863275584Sru@end group 863369626Sru@end example 863475584Sru@end iftex 863575584Sru@endDefesc 863669626Sru 863775584Sru@Defesc {\\\,, , , } 8638104862Sru@cindex left italic correction (@code{\,}) 8639104862Sru@cindex correction, left italic (@code{\,}) 8640104862Sru@cindex glyph, left italic correction (@code{\,}) 8641104862Sru@cindex roman glyph, correction before italic glyph (@code{\,}) 8642104862Sru@cindex italic glyph, correction after roman glyph (@code{\,}) 8643104862SruModify the spacing of the following glyph so that the spacing 8644104862Srubetween that glyph and the preceding glyph is correct if the 8645104862Srupreceding glyph is a roman glyph. Use this escape sequence 8646104862Sruwhenever a roman glyph is immediately followed by an italic 8647104862Sruglyph without any intervening space. In analogy to above, this 864875584Sruspace could be called @dfn{left italic correction}, but this term 864975584Sruisn't used widely. 865055839Sasmodai 865175584Sru@iftex 865275584Sru@example 865375584Sru@group 865475584Sruq\f[I]f 865575584Sru @result{} @r{q}@i{f} 865675584Sruq\,\f[I]f 865775584Sru @result{} @r{q}@math{@ptexcomma}@i{f} 865875584Sru@end group 865975584Sru@end example 866075584Sru@end iftex 866175584Sru@endDefesc 866255839Sasmodai 866375584Sru@Defesc {\\&, , , } 866475584SruInsert a zero-width character, which is invisible. Its intended use 866575584Sruis to stop interaction of a character with its surrounding. 866675584Sru 866775584Sru@itemize @bullet 866875584Sru@item 8669104862SruIt prevents the insertion of extra space after an end-of-sentence 867075584Srucharacter. 867175584Sru 867275584Sru@Example 867375584SruTest. 867475584SruTest. 867575584Sru @result{} Test. Test. 867675584SruTest.\& 867775584SruTest. 867875584Sru @result{} Test. Test. 867975584Sru@endExample 868075584Sru 868175584Sru@item 868275584SruIt prevents interpretation of a control character at the beginning of 868375584Sruan input line. 868475584Sru 868575584Sru@Example 868675584Sru.Test 868775584Sru @result{} warning: `Test' not defined 868875584Sru\&.Test 868975584Sru @result{} .Test 869075584Sru@endExample 869175584Sru 869275584Sru@item 8693104862SruIt prevents kerning between two glyphs. 869475584Sru 869575584Sru@ifnotinfo 869675584Sru@example 869775584Sru@group 869875584SruVA 869975584Sru @result{} @r{VA} 870075584SruV\&A 870175584Sru @result{} @r{V@w{}A} 870275584Sru@end group 870375584Sru@end example 870475584Sru@end ifnotinfo 870575584Sru 870675584Sru@item 870775584SruIt is needed to map an arbitrary character to nothing in the @code{tr} 870875584Srurequest (@pxref{Character Translations}). 870975584Sru@end itemize 871075584Sru@endDefesc 871175584Sru 8712104862Sru@Defesc {\\), , , } 8713104862SruThis escape is similar to @code{\&} except that it behaves like a 8714104862Srucharacter declared with the @code{cflags} request to be transparent 8715104862Srufor the purposes of an end-of-sentence character. 871675584Sru 8717104862SruIts main usage is in macro definitions to protect against arguments 8718104862Srustarting with a control character. 8719104862Sru 8720104862Sru@Example 8721104862Sru.de xxx 8722104862Sru\)\\$1 8723104862Sru.. 8724104862Sru.de yyy 8725104862Sru\&\\$1 8726104862Sru.. 8727104862SruThis is a test.\c 8728104862Sru.xxx ' 8729104862SruThis is a test. 8730104862Sru @result{}This is a test.' This is a test. 8731104862SruThis is a test.\c 8732104862Sru.yyy ' 8733104862SruThis is a test. 8734104862Sru @result{}This is a test.' This is a test. 8735104862Sru@endExample 8736104862Sru@endDefesc 8737104862Sru 8738104862Sru 873969626Sru@c ===================================================================== 874069626Sru 874175584Sru@node Sizes, Strings, Fonts, gtroff Reference 874255839Sasmodai@section Sizes 874355839Sasmodai@cindex sizes 874455839Sasmodai 874555839Sasmodai@cindex baseline 874669626Sru@cindex type size 874769626Sru@cindex size of type 874869626Sru@cindex vertical spacing 874969626Sru@cindex spacing, vertical 875075584Sru@code{gtroff} uses two dimensions with each line of text, type size 875175584Sruand vertical spacing. The @dfn{type size} is approximately the height 8752104862Sruof the tallest glyph.@footnote{This is usually the parenthesis. 875375584SruNote that in most cases the real dimensions of the glyphs in a font 875475584Sruare @emph{not} related to its type size! For example, the standard 875575584Sru@sc{PostScript} font families `Times Roman', `Helvetica', and 875675584Sru`Courier' can't be used together at 10@dmn{pt}; to get acceptable 875775584Sruoutput, the size of `Helvetica' has to be reduced by one point, and 875875584Sruthe size of `Courier' must be increased by one point.} @dfn{Vertical 875975584Sruspacing} is the amount of space @code{gtroff} allows for a line of 876075584Srutext; normally, this is about 20%@w{ }larger than the current type 876175584Srusize. Ratios smaller than this can result in hard-to-read text; 876275584Srularger than this, it spreads the text out more vertically (useful for 876375584Sruterm papers). By default, @code{gtroff} uses 10@w{ }point type on 876475584Sru12@w{ }point spacing. 876555839Sasmodai 876655839Sasmodai@cindex leading 876755839SasmodaiThe difference between type size and vertical spacing is known, by 8768104862Srutypesetters, as @dfn{leading} (this is pronounced `ledding'). 876955839Sasmodai 877055839Sasmodai@menu 877175584Sru* Changing Type Sizes:: 877275584Sru* Fractional Type Sizes:: 877355839Sasmodai@end menu 877455839Sasmodai 877569626Sru@c --------------------------------------------------------------------- 877669626Sru 877755839Sasmodai@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 877855839Sasmodai@subsection Changing Type Sizes 877955839Sasmodai 8780104862Sru@DefreqList {ps, [@Var{size}]} 8781104862Sru@DefreqItem {ps, @t{+}@Var{size}} 8782104862Sru@DefreqItem {ps, @t{-}@Var{size}} 8783104862Sru@DefescItem {\\s, , size, } 8784104862Sru@DefregListEnd {.s} 8785104862Sru@cindex changing type sizes (@code{ps}, @code{\s}) 8786104862Sru@cindex type sizes, changing (@code{ps}, @code{\s}) 8787104862Sru@cindex point sizes, changing (@code{ps}, @code{\s}) 878875584SruUse the @code{ps} request or the @code{\s} escape to change (increase, 878975584Srudecrease) the type size (in points). Specify @var{size} as either an 879075584Sruabsolute point size, or as a relative change from the current size. 879175584SruThe size@w{ }0, or no argument, goes back to the previous size. 879255839Sasmodai 8793104862SruDefault scaling indicator of @code{size} is @samp{z}. If @code{size} 8794104862Sruis zero or negative, it is set to 1@dmn{u}. 879555839Sasmodai 8796104862Sru@cindex type size registers (@code{.s}, @code{.ps}) 8797104862Sru@cindex point size registers (@code{.s}, @code{.ps}) 879875584SruThe read-only number register @code{.s} returns the point size in 879975584Srupoints as a decimal fraction. This is a string. To get the point 880075584Srusize in scaled points, use the @code{.ps} register instead. 880175584Sru 880275584Sru@code{.s} is associated with the current environment 880375584Sru(@pxref{Environments}). 880475584Sru 880575584Sru@Example 880655839Sasmodaisnap, snap, 880755839Sasmodai.ps +2 880855839Sasmodaigrin, grin, 880955839Sasmodai.ps +2 881055839Sasmodaiwink, wink, \s+2nudge, nudge,\s+8 say no more! 881155839Sasmodai.ps 10 881275584Sru@endExample 881355839Sasmodai 881469626SruThe @code{\s} escape may be called in a variety of ways. Much like 881569626Sruother escapes there must be a way to determine where the argument ends 881669626Sruand the text begins. Any of the following forms are valid: 881755839Sasmodai 881869626Sru@table @code 881969626Sru@item \s@var{n} 882075584SruSet the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 882175584Sru0 or in the range 4 to@w{ }39. 882269626Sru 882369626Sru@item \s+@var{n} 882469626Sru@itemx \s-@var{n} 882575584SruIncrease or decrease the point size by @var{n}@w{ }points. @var{n}@w{ 882675584Sru}must be exactly one digit. 882769626Sru 882869626Sru@item \s(@var{nn} 882975584SruSet the point size to @var{nn}@w{ }points. @var{nn} must be exactly 883075584Srutwo digits. 883169626Sru 883269626Sru@item \s+(@var{nn} 883369626Sru@itemx \s-(@var{nn} 883469626Sru@itemx \s(+@var{nn} 883569626Sru@itemx \s(-@var{nn} 883675584SruIncrease or decrease the point size by @var{nn}@w{ }points. @var{nn} 883775584Srumust be exactly two digits. 883869626Sru@end table 883969626Sru 8840104862SruNote that @code{\s} doesn't produce an input token in @code{gtroff}. 8841104862SruAs a consequence, it can be used in requests like @code{mc} (which 8842104862Sruexpects a single character as an argument) to change the font on 8843104862Sruthe fly: 8844104862Sru 8845104862Sru@Example 8846104862Sru.mc \s[20]x\s[0] 8847104862Sru@endExample 8848104862Sru 884975584Sru@xref{Fractional Type Sizes}, for yet another syntactical form of 885075584Sruusing the @code{\s} escape. 8851104862Sru@endDefreq 885269626Sru 8853104862Sru@Defreq {sizes, s1 s2 @dots{} sn [0]} 885455839SasmodaiSome devices may only have certain permissible sizes, in which case 885575584Sru@code{gtroff} rounds to the nearest permissible size. 8856104862SruThe @file{DESC} file specifies which sizes are permissible for the device. 8857104862Sru 8858104862SruUse the @code{sizes} request to change the permissible sizes 8859104862Srufor the current output device. 8860104862SruArguments are in scaled points; 8861104862Sruthe @code{sizescale} line in the 8862104862Sru@file{DESC} file for the output device 8863104862Sruprovides the scaling factor. 8864104862SruFor example, if the scaling factor is 1000, 8865104862Sruthen the value 12000 is 12@w{ }points. 8866104862Sru 8867104862SruEach argument can be a single point size (such as @samp{12000}), 8868104862Sruor a range of sizes (such as @samp{4000-72000}). 8869104862SruYou can optionally end the list with a zero. 887075584Sru@endDefreq 887155839Sasmodai 8872104862Sru@DefreqList {vs, [@Var{space}]} 8873104862Sru@DefreqItem {vs, @t{+}@Var{space}} 8874104862Sru@DefreqItem {vs, @t{-}@Var{space}} 8875104862Sru@DefregListEnd {.v} 8876104862Sru@cindex changing vertical line spacing (@code{vs}) 8877104862Sru@cindex vertical line spacing, changing (@code{vs}) 8878104862Sru@cindex vertical line spacing register (@code{.v}) 887975584SruChange (increase, decrease) the vertical spacing by @var{space}. The 8880104862Srudefault scaling indicator is @samp{p}. 888175584Sru 888275584SruIf @code{vs} is called without an argument, the vertical spacing is 888375584Srureset to the previous value before the last call to @code{vs}. 888475584Sru 8885104862Sru@cindex @code{.V} register, and @code{vs} 888675584Sru@code{gtroff} creates a warning of type @samp{range} if @var{space} is 888775584Sruzero or negative; the vertical spacing is then set to the vertical 888875584Sruresolution (as given in the @code{.V} register). 888975584Sru 889075584SruThe read-only number register @code{.v} contains the current vertical 889175584Sruspacing; it is associated with the current environment 889275584Sru(@pxref{Environments}). 889375584Sru@endDefreq 889475584Sru 8895104862Sru@cindex vertical line spacing, effective value 8896104862SruThe effective vertical line spacing consists of four components. 889769626Sru 8898104862Sru@itemize @bullet 8899104862Sru@item 8900104862SruThe vertical line spacing as set with the @code{vs} request. 890155839Sasmodai 8902104862Sru@cindex post-vertical line spacing 8903104862Sru@cindex line spacing, post-vertical (@code{pvs}) 8904104862Sru@item 8905104862SruThe @dfn{post-vertical line spacing} as set with the @code{pvs} request. 8906104862SruThis is vertical space which will be added after a line has been 8907104862Sruoutput. 8908104862Sru 8909104862Sru@cindex extra pre-vertical line space (@code{\x}) 8910104862Sru@cindex line space, extra pre-vertical (@code{\x}) 8911104862Sru@item 8912104862SruThe @dfn{extra pre-vertical line space} as set with the @code{\x} request, 8913104862Sruusing a negative value. This is vertical space which will be added once 8914104862Srubefore the current line has been output. 8915104862Sru 8916104862Sru@cindex extra post-vertical line space (@code{\x}) 8917104862Sru@cindex line space, extra post-vertical (@code{\x}) 8918104862Sru@item 8919104862SruThe @dfn{extra post-vertical line space} as set with the @code{\x} request, 8920104862Sruusing a positive value. This is vertical space which will be added once 8921104862Sruafter the current line has been output. 8922104862Sru@end itemize 8923104862Sru 8924104862Sru@cindex double-spacing (@code{vs}, @code{pvs}) 8925104862SruIt is usually better to use @code{vs} or @code{pvs} instead of @code{ls} 8926104862Sruto produce double-spaced documents: @code{vs} and @code{pvs} have a finer 8927104862Srugranularity for the inserted vertical space compared to @code{ls}; 8928104862Srufurthermore, certain preprocessors assume single-spacing. 8929104862Sru 8930104862Sru@xref{Manipulating Spacing}, for more details on the @code{\x} escape 8931104862Sruand the @code{ls} request. 8932104862Sru 8933104862Sru@DefreqList {pvs, [@Var{space}]} 8934104862Sru@DefreqItem {pvs, @t{+}@Var{space}} 8935104862Sru@DefreqItem {pvs, @t{-}@Var{space}} 8936104862Sru@DefregListEnd {.pvs} 8937104862Sru@cindex @code{ls} request, alternative to (@code{pvs}) 8938104862Sru@cindex post-vertical line spacing, changing (@code{pvs}) 8939104862Sru@cindex post-vertical line spacing register (@code{.pvs}) 8940104862SruChange (increase, decrease) the post-vertical spacing by 8941104862Sru@var{space}. The default scaling indicator is @samp{p}. 8942104862Sru 8943104862SruIf @code{pvs} is called without an argument, the post-vertical spacing is 8944104862Srureset to the previous value before the last call to @code{pvs}. 8945104862Sru 8946104862Sru@code{gtroff} creates a warning of type @samp{range} if @var{space} is 8947104862Sruzero or negative; the vertical spacing is then set to zero. 8948104862Sru 8949104862SruThe read-only number register @code{.pvs} contains the current 8950104862Srupost-vertical spacing; it is associated with the current environment 8951104862Sru(@pxref{Environments}). 8952104862Sru@endDefreq 8953104862Sru 8954104862Sru 895569626Sru@c --------------------------------------------------------------------- 895669626Sru 895755839Sasmodai@node Fractional Type Sizes, , Changing Type Sizes, Sizes 895855839Sasmodai@subsection Fractional Type Sizes 895955839Sasmodai@cindex fractional type sizes 8960104862Sru@cindex fractional point sizes 896155839Sasmodai@cindex type sizes, fractional 8962104862Sru@cindex point sizes, fractional 8963104862Sru@cindex sizes, fractional 896455839Sasmodai 896569626Sru@cindex @code{s} unit 896669626Sru@cindex unit, @code{s} 896769626Sru@cindex @code{z} unit 896869626Sru@cindex unit, @code{z} 8969104862Sru@cindex @code{ps} request, with fractional type sizes 8970104862Sru@cindex @code{cs} request, with fractional type sizes 8971104862Sru@cindex @code{tkf} request, with fractional type sizes 8972104862Sru@cindex @code{\H}, with fractional type sizes 8973104862Sru@cindex @code{\s}, with fractional type sizes 897475584SruA @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 897575584Sruwhere @var{sizescale} is specified in the @file{DESC} file (1@w{ }by 897675584Srudefault). There is a new scale indicator @samp{z} which has the 897775584Srueffect of multiplying by @var{sizescale}. Requests and escape 897875584Srusequences in @code{gtroff} interpret arguments that represent a point 897975584Srusize as being in units of scaled points, but they evaluate each such 898075584Sruargument using a default scale indicator of @samp{z}. Arguments 898175584Srutreated in this way are the argument to the @code{ps} request, the 898275584Sruthird argument to the @code{cs} request, the second and fourth 898375584Sruarguments to the @code{tkf} request, the argument to the @code{\H} 898475584Sruescape sequence, and those variants of the @code{\s} escape sequence 898575584Sruthat take a numeric expression as their argument (see below). 898655839Sasmodai 898769626SruFor example, suppose @var{sizescale} is@w{ }1000; then a scaled point 898875584Sruis equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 898969626Sruequivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 899069626Sru10250@w{ }scaled points, which is equal to 10.25@w{ }points. 899155839Sasmodai 899275584Sru@code{gtroff} disallows the use of the @samp{z} scale indicator in 899375584Sruinstances where it would make no sense, such as a numeric 899469626Sruexpression whose default scale indicator was neither @samp{u} nor 899575584Sru@samp{z}. Similarly it would make 899655839Sasmodaino sense to use a scaling indicator other than @samp{z} or @samp{u} in a 899755839Sasmodainumeric expression whose default scale indicator was @samp{z}, and so 899869626Sru@code{gtroff} disallows this as well. 899955839Sasmodai 900055839SasmodaiThere is also new scale indicator @samp{s} which multiplies by the 900169626Srunumber of units in a scaled point. So, for example, @samp{\n[.ps]s} is 900269626Sruequal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 900355839Sasmodaiscale indicators. 900455839Sasmodai 900575584Sru@Defreg {.ps} 900675584SruA read-only number register returning the point size in scaled points. 900769626Sru 900875584Sru@code{.ps} is associated with the current environment 900975584Sru(@pxref{Environments}). 901075584Sru@endDefreg 901175584Sru 9012104862Sru@DefregList {.psr} 9013104862Sru@DefregListEnd {.sr} 9014104862Sru@cindex last-requested point size registers (@code{.psr}, @code{.sr}) 9015104862Sru@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) 9016104862Sru@cindex @code{.ps} register, in comparison with @code{.psr} 9017104862Sru@cindex @code{.s} register, in comparison with @code{.sr} 901869626SruThe last-requested point size in scaled points is contained in the 901975584Sru@code{.psr} read-only number register. The last requested point size 902075584Sruin points as a decimal fraction can be found in @code{.sr}. This is a 902175584Srustring-valued read-only number register. 902269626Sru 902375584SruNote that the requested point sizes are device-independent, whereas 902475584Sruthe values returned by the @code{.ps} and @code{.s} registers are not. 9025104862SruFor example, if a point size of 11@dmn{pt} is requested, and a 9026104862Sru@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file) 9027104862Sruspecifies 10.95@dmn{pt} instead, this value is actually used. 902875584Sru 902975584SruBoth registers are associated with the current environment 903075584Sru(@pxref{Environments}). 903175584Sru@endDefreg 903275584Sru 903375584SruThe @code{\s} escape has the following syntax for working with 903475584Srufractional type sizes: 903575584Sru 903669626Sru@table @code 903769626Sru@item \s[@var{n}] 903869626Sru@itemx \s'@var{n}' 9039104862SruSet the point size to @var{n}@w{ }scaled points; @var{n}@w{ }is a numeric 904055839Sasmodaiexpression with a default scale indicator of @samp{z}. 904155839Sasmodai 904269626Sru@item \s[+@var{n}] 904369626Sru@itemx \s[-@var{n}] 904469626Sru@itemx \s+[@var{n}] 904569626Sru@itemx \s-[@var{n}] 904669626Sru@itemx \s'+@var{n}' 904769626Sru@itemx \s'-@var{n}' 904869626Sru@itemx \s+'@var{n}' 904969626Sru@itemx \s-'@var{n}' 9050104862SruIncrease or or decrease the point size by @var{n}@w{ }scaled points; 9051104862Sru@var{n}@w{ }is a numeric expression with a default scale indicator of 905269626Sru@samp{z}. 905369626Sru@end table 905455839Sasmodai 905569626Sru@xref{Font Files}. 905655839Sasmodai 905755839Sasmodai 905869626Sru@c ===================================================================== 905955839Sasmodai 906075584Sru@node Strings, Conditionals and Loops, Sizes, gtroff Reference 906155839Sasmodai@section Strings 906255839Sasmodai@cindex strings 906355839Sasmodai 906469626Sru@code{gtroff} has string variables, which are entirely for user 906575584Sruconvenience (i.e.@: there are no built-in strings exept @code{.T}, but 906675584Srueven this is a read-write string variable). 906755839Sasmodai 9068104862Sru@DefreqList {ds, name [@Var{string}]} 9069104862Sru@DefreqItem {ds1, name [@Var{string}]} 9070104862Sru@DefescItem {\\*, , n, } 9071104862Sru@DefescItem {\\*, @lparen{}, nm, } 9072104862Sru@DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}} 9073104862Sru@cindex string interpolation (@code{\*}) 9074104862Sru@cindex string expansion (@code{\*}) 9075104862Sru@cindex interpolation of strings (@code{\*}) 9076104862Sru@cindex expansion of strings (@code{\*}) 9077104862Sru@cindex string arguments 9078104862Sru@cindex arguments, of strings 9079104862SruDefine and access a string variable @var{name} (one-character name@w{ 9080104862Sru}@var{n}, two-character name @var{nm}). If @var{name} already exists, 9081104862Sru@code{ds} overwrites the previous definition. Only the syntax form 9082104862Sruusing brackets can take arguments which are handled identically to 9083104862Srumacro arguments; the single exception is that a closing bracket as an 9084104862Sruargument must be enclosed in double quotes. @xref{Request Arguments}, 9085104862Sruand @ref{Parameters}. 908655839Sasmodai 908775584SruExample: 908875584Sru 908975584Sru@Example 9090104862Sru.ds foo a \\$1 test 909175584Sru. 9092104862SruThis is \*[foo nice]. 9093104862Sru @result{} This is a nice test. 909475584Sru@endExample 909555839Sasmodai 909675584SruThe @code{\*} escape @dfn{interpolates} (expands in-place) a 909775584Srupreviously-defined string variable. To be more precise, the stored 909875584Srustring is pushed onto the input stack which is then parsed by 909975584Sru@code{gtroff}. Similar to number registers, it is possible to nest 9100104862Srustrings, i.e. string variables can be called within string variables. 910155839Sasmodai 9102104862SruIf the string named by the @code{\*} escape does not exist, it is 9103104862Srudefined as empty, and a warning of type @samp{mac} is emitted (see 910475584Sru@ref{Debugging}, for more details). 910575584Sru 910655839Sasmodai@cindex comments, with @code{ds} 9107104862Sru@cindex @code{ds} request, and comments 910869626Sru@strong{Caution:} Unlike other requests, the second argument to the 910969626Sru@code{ds} request takes up the entire line including trailing spaces. 911069626SruThis means that comments on a line with such a request can introduce 911169626Sruunwanted space into a string. 911255839Sasmodai 911375584Sru@Example 911469626Sru.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 911575584Sru@endExample 911655839Sasmodai 911769626Sru@noindent 911869626SruInstead the comment should be put on another line or have the comment 911969626Sruescape adjacent with the end of the string. 912055839Sasmodai 912175584Sru@Example 912269626Sru.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 912375584Sru@endExample 912455839Sasmodai 912569626Sru@cindex trailing quotes 912669626Sru@cindex quotes, trailing 912769626Sru@cindex leading spaces with @code{ds} 912869626Sru@cindex spaces with @code{ds} 9129104862Sru@cindex @code{ds} request, and leading spaces 913075584SruTo produce leading space the string can be started with a double 913175584Sruquote. No trailing quote is needed; in fact, any trailing quote is 913275584Sruincluded in your string. 913355839Sasmodai 913475584Sru@Example 913555839Sasmodai.ds sign " Yours in a white wine sauce, 913675584Sru@endExample 913755839Sasmodai 913869626Sru@cindex multi-line strings 913969626Sru@cindex strings, multi-line 9140104862Sru@cindex newline character, in strings, escaping 9141104862Sru@cindex escaping newline characters, in strings 914269626SruStrings are not limited to a single line of text. A string can span 914375584Sruseveral lines by escaping the newlines with a backslash. The 914475584Sruresulting string is stored @emph{without} the newlines. 914555839Sasmodai 914675584Sru@Example 914755839Sasmodai.ds foo lots and lots \ 914855839Sasmodaiof text are on these \ 914955839Sasmodainext several lines 915075584Sru@endExample 915155839Sasmodai 9152104862SruIt is not possible to have real newlines in a string. To put a single 9153104862Srudouble quote character into a string, use two consecutive double quote 9154104862Srucharacters. 915569626Sru 9156104862SruThe @code{ds1} request turns off compatibility mode 9157104862Sruwhile interpreting a string. To be more precise, a @dfn{compatibility 9158104862Srusave} input token is inserted at the beginning of the string, and a 9159104862Sru@dfn{compatibility restore} input token at the end. 9160104862Sru 9161104862Sru@Example 9162104862Sru.nr xxx 12345 9163104862Sru.ds aa The value of xxx is \\n[xxx]. 9164104862Sru.ds1 bb The value of xxx ix \\n[xxx]. 9165104862Sru. 9166104862Sru.cp 1 9167104862Sru. 9168104862Sru\*(aa 9169104862Sru @result{} warning: number register `[' not defined 9170104862Sru @result{} The value of xxx is 0xxx]. 9171104862Sru\*(bb 9172104862Sru @result{} The value of xxx ix 12345. 9173104862Sru@endExample 9174104862Sru 9175104862Sru@cindex name space, common, of macros, diversions, and strings 9176104862Sru@cindex common name space of macros, diversions, and strings 9177104862Sru@cindex macros, shared name space with strings and diversions 9178104862Sru@cindex strings, shared name space with macros and diversions 9179104862Sru@cindex diversions, shared name space with macros and strings 918075584SruStrings, macros, and diversions (and boxes) share the same name space. 918175584SruInternally, even the same mechanism is used to store them. This has 918275584Srusome interesting consequences. For example, it is possible to call a 918375584Srumacro with string syntax and vice versa. 918469626Sru 918575584Sru@Example 918675584Sru.de xxx 918775584Srua funny test. 918875584Sru.. 918975584SruThis is \*[xxx] 919075584Sru @result{} This is a funny test. 919169626Sru 919275584Sru.ds yyy a funny test 919375584SruThis is 919475584Sru.yyy 919575584Sru @result{} This is a funny test. 919675584Sru@endExample 919769626Sru 9198104862SruDiversions and boxes can be also called with string syntax. 919969626Sru 920075584SruAnother consequence is that you can copy one-line diversions or boxes 920175584Sruto a string. 920275584Sru 920375584Sru@Example 920475584Sru.di xxx 920575584Srua \fItest\fR 920675584Sru.br 920775584Sru.di 920875584Sru.ds yyy This is \*[xxx]\c 920975584Sru\*[yyy]. 921075584Sru @result{} @r{This is a }@i{test}. 921175584Sru@endExample 921275584Sru 921369626Sru@noindent 921475584SruAs the previous example shows, it is possible to store formatted 921575584Sruoutput in strings. The @code{\c} escape prevents the insertion of an 921675584Sruadditional blank line in the output. 921769626Sru 921875584SruCopying diversions longer than a single output line produces 921975584Sruunexpected results. 922055839Sasmodai 922175584Sru@Example 922275584Sru.di xxx 922375584Srua funny 922475584Sru.br 922575584Srutest 922675584Sru.br 922775584Sru.di 922875584Sru.ds yyy This is \*[xxx]\c 922975584Sru\*[yyy]. 923075584Sru @result{} test This is a funny. 923175584Sru@endExample 923269626Sru 923375584SruUsually, it is not predictable whether a diversion contains one or 923475584Srumore output lines, so this mechanism should be avoided. With 923575584Sru@acronym{UNIX} @code{troff}, this was the only solution to strip off a 923675584Srufinal newline from a diversion. Another disadvantage is that the 923775584Sruspaces in the copied string are already formatted, making them 923875584Sruunstretchable. This can cause ugly results. 923955839Sasmodai 9240104862Sru@cindex stripping final newline in diversions 9241104862Sru@cindex diversion, stripping final newline 9242104862Sru@cindex final newline, stripping in diversions 9243104862Sru@cindex newline, final, stripping in diversions 9244104862Sru@cindex horizontal space, unformatting 9245104862Sru@cindex space, horizontal, unformatting 9246104862Sru@cindex unformatting horizontal space 924775584SruA clean solution to this problem is available in GNU @code{troff}, 924875584Sruusing the requests @code{chop} to remove the final newline of a 924975584Srudiversion, and @code{unformat} to make the horizontal spaces 925075584Srustretchable again. 925169626Sru 925275584Sru@Example 925375584Sru.box xxx 925475584Srua funny 925575584Sru.br 925675584Srutest 925775584Sru.br 925875584Sru.box 925975584Sru.chop xxx 926075584Sru.unformat xxx 926175584SruThis is \*[xxx]. 926275584Sru @result{} This is a funny test. 926375584Sru@endExample 926455839Sasmodai 926575584Sru@xref{Gtroff Internals}, for more information. 926675584Sru@endDefreq 926769626Sru 9268104862Sru@DefreqList {as, name [@Var{string}]} 9269104862Sru@DefreqListEnd {as1, name [@Var{string}]} 9270104862Sru@cindex appending to a string (@code{as}) 9271104862Sru@cindex string, appending (@code{as}) 927275584SruThe @code{as} request is similar to @code{ds} but appends @var{string} 927375584Sruto the string stored as @var{name} instead of redefining it. If 927475584Sru@var{name} doesn't exist yet, it is created. 927555839Sasmodai 927675584Sru@Example 927775584Sru.as sign " with shallots, onions and garlic, 927875584Sru@endExample 9279104862Sru 9280104862SruThe @code{as1} request is similar to @code{as}, but compatibility mode 9281104862Sruis switched off while the appended string is interpreted. To be more 9282104862Sruprecise, a @dfn{compatibility save} input token is inserted at the 9283104862Srubeginning of the appended string, and a @dfn{compatibility restore} 9284104862Sruinput token at the end. 928575584Sru@endDefreq 928655839Sasmodai 928775584SruRudimentary string manipulation routines are given with the next two 928875584Srurequests. 928969626Sru 929075584Sru@Defreq {substring, str n1 [@Var{n2}]} 9291104862Sru@cindex substring (@code{substring}) 9292104862SruReplace the string named @var{str} with the substring 929375584Srudefined by the indices @var{n1} and@w{ }@var{n2}. The first character 9294104862Sruin the string has index@w{ }0. If @var{n2} is omitted, it is taken to 929575584Srube equal to the string's length. If the index value @var{n1} or 9296104862Sru@var{n2} is negative, it is counted from the end of the 9297104862Srustring, going backwards: The last character has index@w{ }@minus{}1, the 9298104862Srucharacter before the last character has index@w{ }@minus{}2, etc. 929975584Sru 930075584Sru@Example 930175584Sru.ds xxx abcdefgh 9302104862Sru.substring xxx 1 -4 930375584Sru\*[xxx] 930475584Sru @result{} bcde 930575584Sru@endExample 930675584Sru@endDefreq 930775584Sru 930875584Sru@Defreq {length, reg str} 9309104862Sru@cindex length of a string (@code{length}) 9310104862Sru@cindex string, length of (@code{length}) 9311104862SruCompute the number of characters of @var{str} and return it in the 9312104862Srunumber register @var{reg}. If @var{reg} doesn't exist, it is created. 9313104862Sru@code{str} is read in copy mode. 931475584Sru 931575584Sru@Example 9316104862Sru.ds xxx abcd\h'3i'efgh 9317104862Sru.length yyy \n[xxx] 931875584Sru\n[yyy] 9319104862Sru @result{} 14 932075584Sru@endExample 932175584Sru@endDefreq 932275584Sru 932375584Sru@Defreq {rn, xx yy} 9324104862Sru@cindex renaming request (@code{rn}) 9325104862Sru@cindex request, renaming (@code{rn}) 9326104862Sru@cindex renaming macro (@code{rn}) 9327104862Sru@cindex macro, renaming (@code{rn}) 9328104862Sru@cindex renaming string (@code{rn}) 9329104862Sru@cindex string, renaming (@code{rn}) 9330104862Sru@cindex renaming diversion (@code{rn}) 9331104862Sru@cindex diversion, renaming (@code{rn}) 9332104862SruRename the request, macro, diversion, or string @var{xx} to @var{yy}. 933375584Sru@endDefreq 933475584Sru 933575584Sru@Defreq {rm, xx} 9336104862Sru@cindex removing request (@code{rm}) 9337104862Sru@cindex request, removing (@code{rm}) 9338104862Sru@cindex removing macro (@code{rm}) 9339104862Sru@cindex macro, removing (@code{rm}) 9340104862Sru@cindex removing string (@code{rm}) 9341104862Sru@cindex string, removing (@code{rm}) 9342104862Sru@cindex removing diversion (@code{rm}) 9343104862Sru@cindex diversion, removing (@code{rm}) 9344104862SruRemove the request, macro, diversion, or string @var{xx}. @code{gtroff} 9345104862Srutreats subsequent invocations as if the object had never been defined. 934675584Sru@endDefreq 934775584Sru 934875584Sru@Defreq {als, new old} 9349104862Sru@cindex alias, string, creating (@code{als}) 9350104862Sru@cindex alias, macro, creating (@code{als}) 9351104862Sru@cindex alias, diversion, creating (@code{als}) 9352104862Sru@cindex creating alias, for string (@code{als}) 9353104862Sru@cindex creating alias, for macro (@code{als}) 9354104862Sru@cindex creating alias, for diversion (@code{als}) 9355104862Sru@cindex string, creating alias (@code{als}) 9356104862Sru@cindex macro, creating alias (@code{als}) 9357104862Sru@cindex diversion, creating alias (@code{als}) 935875584SruCreate an alias named @var{new} for the request, string, macro, or 935975584Srudiversion object named @var{old}. The new name and the old name are 936075584Sruexactly equivalent (it is similar to a hard rather than a soft 936175584Srulink). If @var{old} is undefined, @code{gtroff} generates a warning of 936275584Srutype @samp{mac} and ignores the request. 936375584Sru@endDefreq 936475584Sru 936575584Sru@Defreq {chop, xx} 936675584SruRemove (chop) the last character from the macro, string, or diversion 9367104862Srunamed @var{xx}. This is useful for removing the newline from the end 936875584Sruof diversions that are to be interpolated as strings. This command 936975584Srucan be used repeatedly; see @ref{Gtroff Internals}, for details on 9370104862Srunodes inserted additionally by @code{gtroff}. 937175584Sru@endDefreq 937275584Sru 937369626Sru@xref{Identifiers}, and @ref{Comments}. 937469626Sru 937569626Sru 937669626Sru@c ===================================================================== 937769626Sru 937875584Sru@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 937955839Sasmodai@section Conditionals and Loops 938055839Sasmodai@cindex conditionals and loops 938155839Sasmodai@cindex loops and conditionals 938255839Sasmodai 938375584Sru@menu 938475584Sru* Operators in Conditionals:: 938575584Sru* if-else:: 938675584Sru* while:: 938775584Sru@end menu 938855839Sasmodai 938975584Sru@c --------------------------------------------------------------------- 939075584Sru 939175584Sru@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 939275584Sru@subsection Operators in Conditionals 939375584Sru 9394104862Sru@cindex @code{if} request, operators to use with 9395104862Sru@cindex @code{while} request, operators to use with 939675584SruIn @code{if} and @code{while} requests, there are several more 939775584Sruoperators available: 939875584Sru 939955839Sasmodai@table @code 940055839Sasmodai@item e 940155839Sasmodai@itemx o 940269626SruTrue if the current page is even or odd numbered (respectively). 940369626Sru 940455839Sasmodai@item n 940575584SruTrue if the document is being processed in nroff mode (i.e., the 940675584Sru@code{.nroff} command has been issued). 940769626Sru 940869626Sru@item t 940975584SruTrue if the document is being processed in troff mode (i.e., the 941075584Sru@code{.troff} command has been issued). 941169626Sru 941275584Sru@item v 9413104862SruAlways false. This condition is for compatibility with other 9414104862Sru@code{troff} versions only. 941575584Sru 941655839Sasmodai@item '@var{xxx}'@var{yyy}' 941769626SruTrue if the string @var{xxx} is equal to the string @var{yyy}. Other 941875584Srucharacters can be used in place of the single quotes; the same set of 941975584Srudelimiters as for the @code{\D} escape is used (@pxref{Escapes}). 942075584Sru@code{gtroff} formats the strings before being compared: 942169626Sru 942275584Sru@Example 942375584Sru.ie "|"\fR|\fP" \ 942475584Srutrue 942575584Sru.el \ 942675584Srufalse 942775584Sru @result{} true 942875584Sru@endExample 942975584Sru 943075584Sru@noindent 9431104862SruThe resulting motions, glyph sizes, and fonts have to 943275584Srumatch,@footnote{The created output nodes must be identical. 943375584Sru@xref{Gtroff Internals}.} and not the individual motion, size, and 943475584Srufont requests. In the previous example, @samp{|} and @samp{\fR|\fP} 9435104862Sruboth result in a roman @samp{|} glyph with the same point size and 943675584Sruat the same location on the page, so the strings are equal. If 943775584Sru@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result 943875584Sruwould be ``false'' because (the first) @samp{|} produces an italic 943975584Sru@samp{|} rather than a roman one. 944075584Sru 944175584Sru@item r @var{xxx} 944255839SasmodaiTrue if there is a number register named @var{xxx}. 944369626Sru 944475584Sru@item d @var{xxx} 944555839SasmodaiTrue if there is a string, macro, diversion, or request named @var{xxx}. 944669626Sru 9447104862Sru@item m @var{xxx} 9448104862SruTrue if there is a color named @var{xxx}. 9449104862Sru 9450104862Sru@item c @var{g} 9451104862SruTrue if there is a glyph @var{g} available@footnote{The name of this 9452104862Sruconditional operator is a misnomer since it tests names of output 9453104862Sruglyphs.}; @var{g} is either an @acronym{ASCII} character or a special 9454104862Srucharacter (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition 9455104862Sruis also true if @var{g} has been defined by the @code{char} request. 945655839Sasmodai@end table 945755839Sasmodai 945875584SruNote that these operators can't be combined with other operators like 945975584Sru@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 946075584Srubetween the exclamation mark and the operator) can be used to negate 946175584Sruthe result. 946255839Sasmodai 946375584Sru@Example 946475584Sru.nr xxx 1 946575584Sru.ie !r xxx \ 946675584Srutrue 946775584Sru.el \ 946875584Srufalse 946975584Sru @result{} false 947075584Sru@endExample 947175584Sru 947275584SruA whitespace after @samp{!} always evaluates to zero (this bizarre 947375584Srubehaviour is due to compatibility with @acronym{UNIX} @code{troff}). 947475584Sru 947575584Sru@Example 947675584Sru.nr xxx 1 947775584Sru.ie ! r xxx \ 947875584Srutrue 947975584Sru.el \ 948075584Srufalse 948175584Sru @result{} r xxx true 948275584Sru@endExample 948375584Sru 948475584SruIt is possible to omit the whitespace before the argument to the 948575584Sru@samp{r}, @samp{d}, and @samp{c} operators. 948675584Sru 948775584Sru@xref{Expressions}. 948875584Sru 948969626Sru@c --------------------------------------------------------------------- 949069626Sru 949175584Sru@node if-else, while, Operators in Conditionals, Conditionals and Loops 949255839Sasmodai@subsection if-else 949355839Sasmodai@cindex if-else 949455839Sasmodai 949569626Sru@code{gtroff} has if-then-else constructs like other languages, although 949655839Sasmodaithe formatting can be painful. 949755839Sasmodai 949875584Sru@Defreq {if, expr anything} 949975584SruEvaluate the expression @var{expr}, and executes @var{anything} (the 950075584Sruremainder of the line) if @var{expr} evaluates to non-zero (true). 950175584Sru@var{anything} is interpreted as though it was on a line by itself 950275584Sru(except that leading spaces are swallowed). @xref{Expressions}, for 950375584Srumore info. 950455839Sasmodai 950575584Sru@Example 950675584Sru.nr xxx 1 950775584Sru.nr yyy 2 950875584Sru.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 950975584Sru @result{} true 951075584Sru@endExample 951175584Sru@endDefreq 951269626Sru 9513104862Sru@Defreq{nop, anything} 9514104862SruExecutes @var{anything}. 9515104862SruThis is similar to @code{.if@w{ }1}. 9516104862Sru@endDefreq 951769626Sru 9518104862Sru@DefreqList {ie, expr anything} 9519104862Sru@DefreqListEnd {el, anything} 952075584SruUse the @code{ie} and @code{el} requests to write an if-then-else. 952169626SruThe first request is the `if' part and the latter is the `else' part. 952255839Sasmodai 952375584Sru@Example 9524104862Sru.ie n .ls 2 \" double-spacing in nroff 9525104862Sru.el .ls 1 \" single-spacing in troff 952675584Sru@endExample 952775584Sru@endDefreq 952869626Sru 9529104862Sru@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument 9530104862Sru@c to @deffn 9531104862Sru@c 9532104862Sru@c and in 4.2 you still can't use @{ in macros. 953355839Sasmodai 9534104862Sru@c @DefescList {\@{, , , } 9535104862Sru@c @DefescListEnd {\@}, , , } 9536104862Sru@deffn Escape @t{\@{} 9537104862Sru@deffnx Escape @t{\@}} 953875584Sru@esindex \@{ 953975584Sru@esindex \@} 9540104862Sru@cindex begin of conditional block (@code{\@{}) 9541104862Sru@cindex end of conditional block (@code{\@}}) 9542104862Sru@cindex conditional block, begin (@code{\@{}) 9543104862Sru@cindex conditional block, end (@code{\@}}) 9544104862Sru@cindex block, conditional, begin (@code{\@{}) 9545104862Sru@cindex block, condititional, end (@code{\@}}) 954675584SruIn many cases, an if (or if-else) construct needs to execute more than 954775584Sruone request. This can be done using the @code{\@{} and @code{\@}} 954869626Sruescapes. The following example shows the possible ways to use these 954969626Sruescapes (note the position of the opening and closing braces). 955055839Sasmodai 955175584Sru@Example 955255839Sasmodai.ie t \@{\ 955355839Sasmodai. ds lq `` 955455839Sasmodai. ds rq '' 955555839Sasmodai.\@} 955655839Sasmodai.el \ 955755839Sasmodai.\@{\ 955855839Sasmodai. ds lq " 955955839Sasmodai. ds rq "\@} 956075584Sru@endExample 956175584Sru@c @endDefesc 9562104862Sru@end deffn 956355839Sasmodai 956469626Sru@xref{Expressions}. 956555839Sasmodai 956669626Sru@c --------------------------------------------------------------------- 956755839Sasmodai 956855839Sasmodai@node while, , if-else, Conditionals and Loops 956955839Sasmodai@subsection while 957055839Sasmodai@cindex while 957155839Sasmodai 957269626Sru@code{gtroff} provides a looping construct using the @code{while} 957369626Srurequest, which is used much like the @code{if} (and related) requests. 957455839Sasmodai 957575584Sru@Defreq {while, expr anything} 957675584SruEvaluate the expression @var{expr}, and repeatedly execute 957775584Sru@var{anything} (the remainder of the line) until @var{expr} evaluates 957875584Sruto@w{ }0. 957975584Sru 958075584Sru@Example 958155839Sasmodai.nr a 0 1 958275584Sru.while (\na < 9) \@{\ 958375584Sru\n+a, 958475584Sru.\@} 958575584Sru\n+a 958675584Sru @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 958775584Sru@endExample 958855839Sasmodai 958975584SruSome remarks. 959075584Sru 9591104862Sru@cindex @code{de} request, and @code{while} 959275584Sru@itemize @bullet 959375584Sru@item 959475584SruThe body of a @code{while} request is treated like the body of a 959575584Sru@code{de} request: @code{gtroff} temporarily stores it in a macro 959675584Sruwhich is deleted after the loop has been exited. It can considerably 959775584Sruslow down a macro if the body of the @code{while} request (within the 959875584Srumacro) is large. Each time the macro is executed, the @code{while} 959975584Srubody is parsed and stored again as a temporary macro. 960075584Sru 960175584Sru@Example 960275584Sru.de xxx 960375584Sru. nr num 10 960475584Sru. while (\\n[num] > 0) \@{\ 960575584Sru. \" many lines of code 960675584Sru. nr num -1 960775584Sru. \@} 960875584Sru.. 960975584Sru@endExample 961075584Sru 961175584Sru@cindex recursive macros 961275584Sru@cindex macros, recursive 961369626Sru@noindent 961475584SruThe traditional and ofter better solution (@acronym{UNIX} @code{troff} 961575584Srudoesn't have the @code{while} request) is to use a recursive macro 961675584Sruinstead which is parsed only once during its definition. 961755839Sasmodai 961875584Sru@Example 961975584Sru.de yyy 962075584Sru. if (\\n[num] > 0) \@{\ 962175584Sru. \" many lines of code 962275584Sru. nr num -1 962375584Sru. yyy 962475584Sru. \@} 962575584Sru.. 962675584Sru. 962775584Sru.de xxx 962875584Sru. nr num 10 962975584Sru. yyy 963075584Sru.. 963175584Sru@endExample 963255839Sasmodai 963369626Sru@noindent 963475584SruNote that the number of available recursion levels is set to@w{ }1000 963575584Sru(this is a compile-time constant value of @code{gtroff}). 963655839Sasmodai 963775584Sru@item 963875584SruThe closing brace of a @code{while} body must end a line. 963955839Sasmodai 964075584Sru@Example 964175584Sru.if 1 \@{\ 964275584Sru. nr a 0 1 964375584Sru. while (\n[a] < 10) \@{\ 964475584Sru. nop \n+[a] 964575584Sru.\@}\@} 964675584Sru @result{} unbalanced \@{ \@} 964775584Sru@endExample 964875584Sru@end itemize 964975584Sru@endDefreq 965075584Sru 965175584Sru@Defreq {break, } 9652104862Sru@cindex @code{while} request, confusing with @code{br} 9653104862Sru@cindex @code{break} request, in a @code{while} loop 9654104862Sru@cindex @code{continue} request, in a @code{while} loop 965575584SruBreak out of a @code{while} loop. Be sure not to confuse this with 965675584Sruthe @code{br} request (causing a line break). 965775584Sru@endDefreq 965875584Sru 965975584Sru@Defreq {continue, } 9660104862SruFinish the current iteration of a @code{while} loop, immediately 966175584Srurestarting the next iteration. 966275584Sru@endDefreq 966375584Sru 966469626Sru@xref{Expressions}. 966569626Sru 966669626Sru 966769626Sru@c ===================================================================== 966869626Sru 966975584Sru@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 967055839Sasmodai@section Writing Macros 967155839Sasmodai@cindex writing macros 967255839Sasmodai@cindex macros, writing 967355839Sasmodai 967475584SruA @dfn{macro} is a collection of text and embedded commands which can 967575584Srube invoked multiple times. Use macros to define common operations. 967655839Sasmodai 9677104862Sru@DefreqList {de, name [@Var{end}]} 9678104862Sru@DefreqItem {de1, name [@Var{end}]} 9679104862Sru@DefreqListEnd {dei, name [@Var{end}]} 968075584SruDefine a new macro named @var{name}. @code{gtroff} copies subsequent 968175584Srulines (starting with the next one) into an internal buffer until it 968275584Sruencounters the line @samp{..} (two dots). The optional second 968375584Sruargument to @code{de} changes this to a macro to @samp{.@var{end}}. 968455839Sasmodai 9685104862SruThere can be whitespace after the first dot in the line containing the 9686104862Sruending token (either @samp{.} or macro @samp{@var{end}}). 968775584Sru 968875584SruHere a small example macro called @samp{P} which causes a break and 968975584Sruinserts some vertical space. It could be used to separate paragraphs. 969075584Sru 969175584Sru@Example 969255839Sasmodai.de P 969375584Sru. br 969475584Sru. sp .8v 969555839Sasmodai.. 969675584Sru@endExample 969755839Sasmodai 9698104862SruThe following example defines a macro within another. Remember that 9699104862Sruexpansion must be protected twice; once for reading the macro and 9700104862Sruonce for executing. 970175584Sru 9702104862Sru@Example 9703104862Sru\# a dummy macro to avoid a warning 9704104862Sru.de end 9705104862Sru.. 9706104862Sru. 9707104862Sru.de foo 9708104862Sru. de bar end 9709104862Sru. nop \f[B]Hallo \\\\$1!\f[] 9710104862Sru. end 9711104862Sru.. 9712104862Sru. 9713104862Sru.foo 9714104862Sru.bar Joe 9715104862Sru @result{} @b{Hallo Joe!} 9716104862Sru@endExample 971775584Sru 9718104862Sru@noindent 9719104862SruSince @code{\f} has no expansion, it isn't necessary to protect its 9720104862Srubackslash. Had we defined another macro within @code{bar} which takes 9721104862Srua parameter, eight backslashes would be necessary before @samp{$1}. 972275584Sru 9723104862SruThe @code{de1} request turns off compatibility mode 9724104862Sruwhile executing the macro. On entry, the current compatibility mode 9725104862Sruis saved and restored at exit. 9726104862Sru 9727104862Sru@Example 9728104862Sru.nr xxx 12345 9729104862Sru. 9730104862Sru.de aa 9731104862SruThe value of xxx is \\n[xxx]. 9732104862Sru.. 9733104862Sru.de1 bb 9734104862SruThe value of xxx ix \\n[xxx]. 9735104862Sru.. 9736104862Sru. 9737104862Sru.cp 1 9738104862Sru. 9739104862Sru.aa 9740104862Sru @result{} warning: number register ' not defined 9741104862Sru @result{} The value of xxx is 0xxx]. 9742104862Sru.bb 9743104862Sru @result{} The value of xxx ix 12345. 9744104862Sru@endExample 9745104862Sru 9746104862SruThe @code{dei} request defines a macro indirectly. 9747104862SruThat is, it expands strings whose names 9748104862Sruare @var{name} or @var{end} before performing the append. 9749104862Sru 9750104862SruThis: 9751104862Sru 9752104862Sru@Example 9753104862Sru.ds xx aa 9754104862Sru.ds yy bb 9755104862Sru.dei xx yy 9756104862Sru@endExample 9757104862Sru 9758104862Sru@noindent 9759104862Sruis equivalent to: 9760104862Sru 9761104862Sru@Example 9762104862Sru.de aa bb 9763104862Sru@endExample 9764104862Sru 9765104862Sru@pindex trace.tmac 9766104862SruUsing @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}. 9767104862Sru 9768104862SruNote that macro identifiers are shared with identifiers for strings and 9769104862Srudiversions. 977075584Sru@endDefreq 977175584Sru 9772104862Sru@DefreqList {am, xx} 9773104862Sru@DefreqItem {am1, xx} 9774104862Sru@DefreqListEnd {ami, xx yy} 9775104862Sru@cindex appending to a macro (@code{am}) 9776104862Sru@cindex macro, appending (@code{am}) 977775584SruWorks similarly to @code{de} except it appends onto the macro named 977875584Sru@var{xx}. So, to make the previously defined @samp{P} macro actually 977975584Srudo indented instead of block paragraphs, add the necessary code to the 978075584Sruexisting macro like this: 978155839Sasmodai 978275584Sru@Example 978355839Sasmodai.am P 978455839Sasmodai.ti +5n 978555839Sasmodai.. 978675584Sru@endExample 9787104862Sru 9788104862SruThe @code{am1} request turns off compatibility mode 9789104862Sruwhile executing the appended macro piece. To be more precise, a 9790104862Sru@dfn{compatibility save} input token is inserted at the beginning of 9791104862Sruthe appended code, and a @dfn{compatibility restore} input token at 9792104862Sruthe end. 9793104862Sru 9794104862SruThe @code{ami} request appends indirectly, 9795104862Srumeaning that @code{gtroff} expands strings whose names 9796104862Sruare @var{xx} or @var{yy} before performing the append. 9797104862Sru 9798104862Sru@pindex trace.tmac 9799104862SruUsing @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. 980075584Sru@endDefreq 980155839Sasmodai 9802104862Sru@xref{Strings}, for the @code{als} request to rename a macro. 980355839Sasmodai 9804104862SruThe @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and 9805104862Sru@code{as} requests (together with its variants) only create a new object 9806104862Sruif the name of the macro, diversion or string diversion is currently 9807104862Sruundefined or if it is defined to be a request; normally they modify the 9808104862Sruvalue of an existing object. 9809104862Sru 9810104862Sru@Defreq {return, } 9811104862SruExit a macro, immediately returning to the caller. 981275584Sru@endDefreq 981355839Sasmodai 981455839Sasmodai@menu 981575584Sru* Copy-in Mode:: 981675584Sru* Parameters:: 981755839Sasmodai@end menu 981855839Sasmodai 981969626Sru@c --------------------------------------------------------------------- 982069626Sru 982155839Sasmodai@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 982255839Sasmodai@subsection Copy-in Mode 982355839Sasmodai@cindex copy-in mode 982455839Sasmodai@cindex mode, copy-in 982555839Sasmodai 982675584Sru@cindex @code{\n}, when reading text for a macro 982775584Sru@cindex @code{\$}, when reading text for a macro 982875584Sru@cindex @code{\*}, when reading text for a macro 982975584Sru@cindex @code{\\}, when reading text for a macro 983075584Sru@cindex \@key{RET}, when reading text for a macro 9831104862SruWhen @code{gtroff} reads in the text for a macro, string, or diversion, 9832104862Sruit copies the text (including request lines, but excluding escapes) into 9833104862Sruan internal buffer. Escapes are converted into an internal form, 983469626Sruexcept for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 983569626Sru@code{\@key{RET}} which are evaluated and inserted into the text where 983669626Sruthe escape was located. This is known as @dfn{copy-in} mode or 983769626Sru@dfn{copy} mode. 983855839Sasmodai 983955839SasmodaiWhat this means is that you can specify when these escapes are to be 984069626Sruevaluated (either at copy-in time or at the time of use) by insulating 984169626Sruthe escapes with an extra backslash. Compare this to the @code{\def} 984269626Sruand @code{\edef} commands in @TeX{}. 984355839Sasmodai 984475584SruThe following example prints the numbers 20 and@w{ }10: 984555839Sasmodai 984675584Sru@Example 984755839Sasmodai.nr x 20 984855839Sasmodai.de y 984955839Sasmodai.nr x 10 985055839Sasmodai\&\nx 985155839Sasmodai\&\\nx 985255839Sasmodai.. 985355839Sasmodai.y 985475584Sru@endExample 985555839Sasmodai 985669626Sru@c --------------------------------------------------------------------- 985755839Sasmodai 985855839Sasmodai@node Parameters, , Copy-in Mode, Writing Macros 985955839Sasmodai@subsection Parameters 986055839Sasmodai@cindex parameters 986155839Sasmodai 9862104862SruThe arguments to a macro or string can be examined using a variety of 9863104862Sruescapes. 9864104862Sru 9865104862Sru@Defreg {.$} 9866104862Sru@cindex number of arguments register (@code{.$}) 9867104862SruThe number of arguments passed to a macro or string. This is a read-only 9868104862Srunumber register. 9869104862Sru@endDefreg 9870104862Sru 987155839SasmodaiAny individual argument can be retrieved with one of the following 987255839Sasmodaiescapes: 987355839Sasmodai 9874104862Sru@DefescList {\\$, , n, } 9875104862Sru@DefescItem {\\$, @lparen{}, nn, } 9876104862Sru@DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}} 987769626Sru@cindex copy-in mode, and macro arguments 9878104862Sru@cindex macro, arguments (@code{\$}) 9879104862Sru@cindex arguments, macro (@code{\$}) 9880104862SruRetrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} 9881104862Sruargument. As usual, the first form only accepts a single number 9882104862Sru(larger than zero), the second a two-digit number (larger or equal 9883104862Sruto@w{ }10), and the third any positive integer value (larger 9884104862Sruthan zero). Macros and strings can have an unlimited number of arguments. 9885104862SruNote that due to copy-in mode, use two backslashes on these in actual use 9886104862Sruto prevent interpolation until the macro is actually invoked. 988775584Sru@endDefesc 988855839Sasmodai 988975584Sru@Defreq {shift, [@Var{n}]} 9890104862SruShift the arguments 1@w{ }position, or as 989169626Srumany positions as specified by its argument. After executing this 9892104862Srurequest, argument@w{ }@var{i} becomes argument @math{@var{i}-@var{n}}; 989375584Sruarguments 1 to@w{ }@var{n} are no longer available. Shifting by 989469626Srunegative amounts is currently undefined. 989575584Sru@endDefreq 989655839Sasmodai 9897104862Sru@DefescList {\\$*, , , } 9898104862Sru@DefescListEnd {\\$@@, , , } 989969626SruIn some cases it is convenient to use all of the arguments at once (for 990069626Sruexample, to pass the arguments along to another macro). The @code{\$*} 990175584Sruescape concatenates all the arguments separated by spaces. A 990275584Srusimilar escape is @code{\$@@}, which concatenates all the 990369626Sruarguments with each surrounded by double quotes, and separated by 9904104862Sruspaces. If not in compatibility mode, the input level of double quotes 9905104862Sruis preserved (see @ref{Request Arguments}). 990675584Sru@endDefesc 990755839Sasmodai 990875584Sru@Defesc {\\$0, , , } 9909104862Sru@cindex macro name register (@code{\$0}) 9910104862Sru@cindex @code{als} request, and @code{\$0} 991175584SruThe name used to invoke the current macro. 991275584SruThe @code{als} request can make a macro have more than one name. 991355839Sasmodai 991475584Sru@Example 9915104862Sru.de generic-macro 9916104862Sru. ... 9917104862Sru. if \\n[error] \@{\ 9918104862Sru. tm \\$0: Houston, we have a problem. 9919104862Sru. return 9920104862Sru. \@} 992155839Sasmodai.. 9922104862Sru. 9923104862Sru.als foo generic-macro 9924104862Sru.als bar generic-macro 992575584Sru@endExample 992675584Sru@endDefesc 992755839Sasmodai 992869626Sru@xref{Request Arguments}. 992955839Sasmodai 993055839Sasmodai 993169626Sru@c ===================================================================== 993269626Sru 993375584Sru@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 993455839Sasmodai@section Page Motions 993555839Sasmodai@cindex page motions 993655839Sasmodai@cindex motions, page 993755839Sasmodai 9938104862Sru@xref{Manipulating Spacing}, for a discussion of the main request for 9939104862Sruvertical motion, @code{sp}. 994055839Sasmodai 9941104862Sru@DefreqList {mk, [@Var{reg}]} 9942104862Sru@DefreqListEnd {rt, [@Var{dist}]} 9943104862Sru@cindex marking vertical page location (@code{mk}) 9944104862Sru@cindex page location, vertical, marking (@code{mk}) 9945104862Sru@cindex location, vertical, page, marking (@code{mk}) 9946104862Sru@cindex vertical page location, marking (@code{mk}) 9947104862Sru@cindex returning to marked vertical page location (@code{rt}) 9948104862Sru@cindex page location, vertical, returning to marked (@code{rt}) 9949104862Sru@cindex location, vertical, page, returning to marked (@code{rt}) 9950104862Sru@cindex vertical page location, returning to marked (@code{rt}) 995155839SasmodaiThe request @code{mk} can be used to mark a location on a page, for 9952104862Srumovement to later. This request takes a register name as an argument 9953104862Sruin which to store the current page location. With no argument it 9954104862Srustores the location in an internal register. The results of this can 9955104862Srube used later by the @code{rt} or the @code{sp} request (or the 9956104862Sru@code{\v} escape). 995755839Sasmodai 9958104862SruThe @code{rt} request returns @emph{upwards} to the location marked 9959104862Sruwith the last @code{mk} request. If used with an argument, return to 9960104862Srua position which distance from the top of the page is @var{dist} (no 9961104862Sruprevious call to @code{mk} is necessary in this case). Default scaling 9962104862Sruindicator is @samp{v}. 9963104862Sru 9964104862SruHere a primitive solution for a two-column macro. 9965104862Sru 996675584Sru@Example 9967104862Sru.nr column-length 1.5i 9968104862Sru.nr column-gap 4m 9969104862Sru.nr bottom-margin 1m 9970104862Sru. 997175584Sru@endExample 9972104862Sru@Example 9973104862Sru.de 2c 9974104862Sru. br 9975104862Sru. mk 9976104862Sru. ll \\n[column-length]u 9977104862Sru. wh -\\n[bottom-margin]u 2c-trap 9978104862Sru. nr right-side 0 9979104862Sru.. 9980104862Sru. 9981104862Sru@endExample 9982104862Sru@Example 9983104862Sru.de 2c-trap 9984104862Sru. ie \\n[right-side] \@{\ 9985104862Sru. nr right-side 0 9986104862Sru. po -(\\n[column-length]u + \\n[column-gap]u) 9987104862Sru. \" remove trap 9988104862Sru. wh -\\n[bottom-margin]u 9989104862Sru. \@} 9990104862Sru. el \@{\ 9991104862Sru. \" switch to right side 9992104862Sru. nr right-side 1 9993104862Sru. po +(\\n[column-length]u + \\n[column-gap]u) 9994104862Sru. rt 9995104862Sru. \@} 9996104862Sru.. 9997104862Sru. 9998104862Sru@endExample 9999104862Sru@Example 10000104862Sru.pl 1.5i 10001104862Sru.ll 4i 10002104862SruThis is a small test which shows how the 10003104862Srurt request works in combination with mk. 10004104862Sru 10005104862Sru.2c 10006104862SruStarting here, text is typeset in two columns. 10007104862SruNote that this implementation isn't robust 10008104862Sruand thus not suited for a real two-column 10009104862Srumacro. 10010104862Sru@endExample 10011104862Sru 10012104862SruResult: 10013104862Sru 10014104862Sru@Example 10015104862SruThis is a small test which shows how the 10016104862Srurt request works in combination with mk. 10017104862Sru 10018104862SruStarting here, isn't robust 10019104862Srutext is typeset and thus not 10020104862Sruin two columns. suited for a 10021104862SruNote that this real two-column 10022104862Sruimplementation macro. 10023104862Sru@endExample 1002475584Sru@endDefreq 1002555839Sasmodai 1002669626SruThe following escapes give fine control of movements about the page. 1002755839Sasmodai 1002875584Sru@Defesc {\\v, ', e, '} 10029104862Sru@cindex vertical motion (@code{\v}) 10030104862Sru@cindex motion, vertical (@code{\v}) 10031104862SruMove vertically, usually from the current location on the page (if no 10032104862Sruabsolute position operator @samp{|} is used). The 10033104862Sruargument@w{ }@var{e} specifies the distance to move; positive is 10034104862Srudownwards and negative upwards. The default scaling indicator for this 10035104862Sruescape is @samp{v}. Beware, however, that @code{gtroff} continues text 10036104862Sruprocessing at the point where the motion ends, so you should always 10037104862Srubalance motions to avoid interference with text processing. 10038104862Sru 10039104862Sru@code{\v} doesn't trigger a trap. This can be quite useful; for example, 10040104862Sruconsider a page bottom trap macro which prints a marker in the margin to 10041104862Sruindicate continuation of a footnote or something similar. 1004275584Sru@endDefesc 1004355839Sasmodai 10044104862SruThere are some special-case escapes for vertical motion. 1004555839Sasmodai 10046104862Sru@Defesc {\\r, , , } 10047104862SruMove upwards@w{ }1@dmn{v}. 10048104862Sru@endDefesc 1004969626Sru 10050104862Sru@Defesc {\\u, , , } 10051104862SruMove upwards@w{ }.5@dmn{v}. 10052104862Sru@endDefesc 1005369626Sru 10054104862Sru@Defesc {\\d, , , } 10055104862SruMove down@w{ }.5@dmn{v}. 10056104862Sru@endDefesc 1005755839Sasmodai 1005875584Sru@Defesc {\\h, ', e, '} 10059104862Sru@cindex inserting horizontal space (@code{\h}) 10060104862Sru@cindex horizontal space (@code{\h}) 10061104862Sru@cindex space, horizontal (@code{\h}) 10062104862Sru@cindex horizontal motion (@code{\h}) 10063104862Sru@cindex motion, horizontal (@code{\h}) 10064104862SruMove horizontally, usually from the current location (if no absolute 10065104862Sruposition operator @samp{|} is used). The expression@w{ }@var{e} 10066104862Sruindicates how far to move: positive is rightwards and negative 10067104862Sruleftwards. The default scaling indicator for this escape is @samp{m}. 1006875584Sru@endDefesc 1006955839Sasmodai 10070104862SruThere are a number of special-case escapes for horizontal motion. 1007155839Sasmodai 10072104862Sru@Defesc {\\@key{SP}, , , } 10073104862Sru@cindex space, unbreakable 10074104862Sru@cindex unbreakable space 1007575584SruAn unbreakable and unpaddable (i.e.@: not expanded during filling) 1007669626Sruspace. (Note: This is a backslash followed by a space.) 10077104862Sru@endDefesc 1007869626Sru 10079104862Sru@Defesc {\\~, , , } 1008075584SruAn unbreakable space that stretches like a normal inter-word space 1008175584Sruwhen a line is adjusted. 10082104862Sru@endDefesc 1008369626Sru 10084104862Sru@Defesc {\\|, , , } 10085104862SruA 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to 1008675584Sruzero). 10087104862Sru@endDefesc 1008869626Sru 10089104862Sru@Defesc {\\^, , , } 10090104862SruA 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to 1009175584Sruzero). 10092104862Sru@endDefesc 1009369626Sru 10094104862Sru@Defesc {\\0, , , } 10095104862Sru@cindex space, width of a digit (@code{\0}) 10096104862Sru@cindex digit width space (@code{\0}) 1009775584SruA space the size of a digit. 10098104862Sru@endDefesc 1009969626Sru 1010075584SruThe following string sets the @TeX{} logo: 1010169626Sru 1010275584Sru@Example 1010375584Sru.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 1010475584Sru@endExample 1010555839Sasmodai 10106104862Sru@DefescList {\\w, ', text, '} 10107104862Sru@DefregItem {st} 10108104862Sru@DefregItem {sb} 10109104862Sru@DefregItem {rst} 10110104862Sru@DefregItem {rsb} 10111104862Sru@DefregItem {ct} 10112104862Sru@DefregItem {ssc} 10113104862Sru@DefregListEnd {skw} 10114104862Sru@cindex width escape (@code{\w}) 10115104862SruReturn the width of the specified @var{text} in basic units. 1011675584SruThis allows horizontal movement based on the width of some 1011775584Sruarbitrary text (e.g.@: given as an argument to a macro). 1011855839Sasmodai 1011975584Sru@Example 10120104862SruThe length of the string `abc' is \w'abc'u. 10121104862Sru @result{} The length of the string `abc' is 72u. 1012275584Sru@endExample 1012355839Sasmodai 1012469626SruFont changes may occur in @var{text} which don't affect current 1012569626Srusettings. 1012655839Sasmodai 1012769626SruAfter use, @code{\w} sets several registers: 1012855839Sasmodai 1012955839Sasmodai@table @code 1013055839Sasmodai@item st 1013169626Sru@itemx sb 10132104862SruThe highest and lowest point of the baseline, respectively, in @var{text}. 1013369626Sru 1013455839Sasmodai@item rst 1013569626Sru@itemx rsb 1013655839SasmodaiLike the @code{st} and @code{sb} registers, but takes account of the 10137104862Sruheights and depths of glyphs. With other words, this gives the 10138104862Sruhighest and lowest point of @var{text}. 1013969626Sru 1014055839Sasmodai@item ct 10141104862SruDefines the kinds of glyphs occurring in @var{text}: 1014269626Sru 1014355839Sasmodai@table @asis 1014455839Sasmodai@item 0 10145104862Sruonly short glyphs, no descenders or tall glyphs. 1014669626Sru 1014755839Sasmodai@item 1 1014875584Sruat least one descender. 1014969626Sru 1015055839Sasmodai@item 2 10151104862Sruat least one tall glyph. 1015269626Sru 1015355839Sasmodai@item 3 10154104862Sruat least one each of a descender and a tall glyph. 1015555839Sasmodai@end table 1015669626Sru 1015755839Sasmodai@item ssc 1015869626SruThe amount of horizontal space (possibly negative) that should be added 10159104862Sruto the last glyph before a subscript. 1016069626Sru 1016155839Sasmodai@item skw 10162104862SruHow far to right of the center of the last glyph in the @code{\w} 1016375584Sruargument, the center of an accent from a roman font should be placed 10164104862Sruover that glyph. 1016555839Sasmodai@end table 1016675584Sru@endDefesc 1016755839Sasmodai 10168104862Sru@DefescList {\\k, , p, } 10169104862Sru@DefescItem {\\k, @lparen{}, ps, } 10170104862Sru@DefescListEnd {\\k, @lbrack{}, position, @rbrack} 10171104862Sru@cindex saving horizontal input line position (@code{\k}) 10172104862Sru@cindex horizontal input line position, saving (@code{\k}) 10173104862Sru@cindex input line position, horizontal, saving (@code{\k}) 10174104862Sru@cindex position, horizontal input line, saving (@code{\k}) 10175104862Sru@cindex line, input, horizontal position, saving (@code{\k}) 10176104862SruStore the current horizontal position in the @emph{input} line in 10177104862Srunumber register with name @var{position} (one-character name@w{ }@var{p}, 10178104862Srutwo-character name @var{ps}). Use this, for example, to return to the 10179104862Srubeginning of a string for highlighting or other decoration. 1018075584Sru@endDefesc 1018169626Sru 10182104862Sru@Defreg {hp} 10183104862Sru@cindex horizontal input line position register (@code{hp}) 10184104862Sru@cindex input line, horizontal position, register (@code{hp}) 10185104862Sru@cindex position, horizontal, in input line, register (@code{hp}) 10186104862Sru@cindex line, input, horizontal position, register (@code{hp}) 10187104862SruThe current horizontal position at the input line. 10188104862Sru@endDefreg 10189104862Sru 1019075584Sru@Defreg {.k} 10191104862Sru@cindex horizontal output line position register (@code{.k}) 10192104862Sru@cindex output line, horizontal position, register (@code{.k}) 10193104862Sru@cindex position, horizontal, in output line, register (@code{.k}) 10194104862Sru@cindex line, output, horizontal position, register (@code{.k}) 1019575584SruA read-only number register containing the current horizontal output 1019675584Sruposition. 1019775584Sru@endDefreg 1019855839Sasmodai 10199104862Sru@Defesc {\\o, ', @Var{a}@Var{b}@Var{c}, '} 10200104862Sru@cindex overstriking glyphs (@code{\o}) 10201104862Sru@cindex glyphs, overstriking (@code{\o}) 10202104862SruOverstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs 10203104862Sruare centered, and the resulting spacing is the largest width of the 10204104862Sruaffected glyphs. 10205104862Sru@endDefesc 1020655839Sasmodai 10207104862Sru@Defesc {\\z, , g, , } 10208104862Sru@cindex zero-width printing (@code{\z}, @code{\Z}) 10209104862Sru@cindex printing, zero-width (@code{\z}, @code{\Z}) 10210104862SruPrint glyph @var{g} with zero width, i.e., without spacing. Use 10211104862Sruthis to overstrike glyphs left-aligned. 10212104862Sru@endDefesc 1021355839Sasmodai 10214104862Sru@Defesc {\\Z, ', anything, '} 10215104862Sru@cindex zero-width printing (@code{\z}, @code{\Z}) 10216104862Sru@cindex printing, zero-width (@code{\z}, @code{\Z}) 10217104862SruPrint @var{anything}, then restore the horizontal and vertical position. 10218104862SruThe argument may not contain tabs or leaders. 10219104862Sru 10220104862SruThe following is an example of a strike-through macro: 10221104862Sru 10222104862Sru@Example 10223104862Sru.de ST 10224104862Sru.nr ww \w'\\$1' 10225104862Sru\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1 10226104862Sru.. 10227104862Sru. 10228104862SruThis is 10229104862Sru.ST "a test" 10230104862Sruan actual emergency! 10231104862Sru@endExample 10232104862Sru@endDefesc 10233104862Sru 10234104862Sru 1023569626Sru@c ===================================================================== 1023655839Sasmodai 1023775584Sru@node Drawing Requests, Traps, Page Motions, gtroff Reference 1023869626Sru@section Drawing Requests 1023969626Sru@cindex drawing requests 1024069626Sru@cindex requests for drawing 1024169626Sru 1024269626Sru@code{gtroff} provides a number of ways to draw lines and other figures 1024369626Sruon the page. Used in combination with the page motion commands (see 1024469626Sru@ref{Page Motions}, for more info), a wide variety of figures can be 1024569626Srudrawn. However, for complex drawings these operations can be quite 1024669626Srucumbersome, and it may be wise to use graphic preprocessors like 1024769626Sru@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 1024869626Sruinformation. 1024969626Sru 1025055839SasmodaiAll drawing is done via escapes. 1025155839Sasmodai 10252104862Sru@DefescList {\\l, ', @Var{l}, '} 10253104862Sru@DefescListEnd {\\l, ', @Var{l}@Var{g}, '} 10254104862Sru@cindex drawing horizontal lines (@code{\l}) 10255104862Sru@cindex horizontal line, drawing (@code{\l}) 10256104862Sru@cindex line, horizontal, drawing (@code{\l}) 10257104862SruDraw a line horizontally. @var{l} is the length of the line to be 10258104862Srudrawn. If it is positive, start the line at the current location and 10259104862Srudraw to the right; its end point is the new current location. Negative 10260104862Sruvalues are handled differently: The line starts at the current location 10261104862Sruand draws to the left, but the current location doesn't move. 1026255839Sasmodai 10263104862Sru@var{l} can also be specified absolutely (i.e.@: with a leading 10264104862Sru@samp{|}) which draws back to the beginning of the input line. 10265104862SruDefault scaling indicator is @samp{m}. 1026669626Sru 10267104862Sru@cindex underscore glyph (@code{\[ru]}) 10268104862Sru@cindex glyph, underscore (@code{\[ru]}) 10269104862Sru@cindex line drawing glyph 10270104862Sru@cindex glyph, for line drawing 10271104862SruThe optional second parameter@w{ }@var{g} is a glyph to draw the line 1027275584Sruwith. If this second argument is not specified, @code{gtroff} uses 10273104862Sruthe underscore glyph, @code{\[ru]}. 1027455839Sasmodai 10275104862Sru@cindex zero width space character (@code{\&}) 10276104862Sru@cindex character, zero width space (@code{\&}) 10277104862Sru@cindex space character, zero width (@code{\&}) 1027869626SruTo separate the two arguments (to prevent @code{gtroff} from 10279104862Sruinterpreting a drawing glyph as a scaling indicator if the glyph is 10280104862Srurepresented by a single character) use @code{\&}. 1028155839Sasmodai 1028269626SruHere a small useful example: 1028355839Sasmodai 1028475584Sru@Example 1028555839Sasmodai.de box 10286104862Sru\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 1028755839Sasmodai.. 1028875584Sru@endExample 1028955839Sasmodai 1029069626Sru@noindent 1029169626SruNote that this works by outputting a box rule (a vertical line), then 10292104862Sruthe text given as an argument and then another box rule. Finally, the 10293104862Sruline drawing escapes both draw from the current location to the 10294104862Srubeginning of the @emph{input} line -- this works because the line 10295104862Srulength is negative, not moving the current point. 1029675584Sru@endDefesc 1029755839Sasmodai 10298104862Sru@DefescList {\\L, ', @Var{l}, '} 10299104862Sru@DefescListEnd {\\L, ', @Var{l}@Var{g}, '} 10300104862Sru@cindex drawing vertical lines (@code{\L}) 10301104862Sru@cindex vertical line drawing (@code{\L}) 10302104862Sru@cindex line, vertical, drawing (@code{\L}) 10303104862Sru@cindex line drawing glyph 10304104862Sru@cindex glyph for line drawing 10305104862Sru@cindex box rule glyph (@code{\[br]}) 10306104862Sru@cindex glyph, box rule (@code{\[br]}) 10307104862SruDraw vertical lines. Its parameters are 10308104862Srusimilar to the @code{\l} escape, except that the default scaling 10309104862Sruindicator is @samp{v}. The movement is downwards for positive values, 10310104862Sruand upwards for negative values. The default glyph is the box rule 10311104862Sruglyph, @code{\[br]}. As with the vertical motion escapes, text 10312104862Sruprocessing blindly continues where the line ends. 1031355839Sasmodai 10314104862Sru@Example 10315104862SruThis is a \L'3v'test. 10316104862Sru@endExample 1031769626Sru 10318104862Sru@noindent 10319104862SruHere the result, produced with @code{grotty}. 10320104862Sru 1032175584Sru@Example 10322104862SruThis is a 10323104862Sru | 10324104862Sru | 10325104862Sru |test. 1032675584Sru@endExample 1032775584Sru@endDefesc 1032855839Sasmodai 1032975584Sru@Defesc {\\D, ', command arg @dots{}, '} 1033075584SruThe @code{\D} escape provides a variety of drawing functions. 10331104862SruNote that on character devices, only vertical and horizontal lines are 10332104862Srusupported within @code{grotty}; other devices may only support a subset 10333104862Sruof the available drawing functions. 1033455839Sasmodai 10335104862SruThe default scaling indicator for all subcommands of @code{\D} is 10336104862Sru@samp{m} for horizontal distances and @samp{v} for vertical ones. 10337104862SruExceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} 10338104862Sruwhich use @code{u} as the default. 10339104862Sru 1034055839Sasmodai@table @code 1034169626Sru@item \D'l @var{dx} @var{dy}' 10342104862Sru@cindex line, drawing (@w{@code{\D'l @dots{}'}}) 10343104862Sru@cindex drawing a line (@w{@code{\D'l @dots{}'}}) 1034469626SruDraw a line from the current location to the relative point specified by 1034569626Sru(@var{dx},@var{dy}). 1034655839Sasmodai 10347104862SruThe following example is a macro for creating a box around a text string; 10348104862Srufor simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}. 1034969626Sru 1035075584Sru@Example 10351104862Sru.de BOX 10352104862Sru. nr @@wd \w'\\$1' 10353104862Sru\h'.2m'\ 10354104862Sru\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 10355104862Sru\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 10356104862Sru\D'l (\\n[@@wd]u + .4m) 0'\ 10357104862Sru\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 10358104862Sru\D'l -(\\n[@@wd]u + .4m) 0'\ 10359104862Sru\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 10360104862Sru\\$1\ 10361104862Sru\h'.2m' 10362104862Sru.. 1036375584Sru@endExample 1036455839Sasmodai 10365104862Sru@noindent 10366104862SruFirst, the width of the string is stored in register @code{@@wd}. Then, 10367104862Srufour lines are drawn to form a box, properly offset by the box margin. 10368104862SruThe registers @code{rst} and @code{rsb} are set by the @code{\w} escape, 10369104862Srucontaining the largest height and depth of the whole string. 10370104862Sru 1037155839Sasmodai@item \D'c @var{d}' 10372104862Sru@cindex circle, drawing (@w{@code{\D'c @dots{}'}}) 10373104862Sru@cindex drawing a circle (@w{@code{\D'c @dots{}'}}) 10374104862SruDraw a circle with a diameter of@w{ }@var{d} with the leftmost point at the 1037569626Srucurrent position. 1037669626Sru 1037755839Sasmodai@item \D'C @var{d}' 10378104862Sru@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) 10379104862Sru@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) 10380104862Sru@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) 10381104862SruDraw a solid circle with the same parameters as an outlined circle. No 10382104862Sruoutline is drawn. 1038369626Sru 10384104862Sru@item \D'e @var{x} @var{y}' 10385104862Sru@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) 10386104862Sru@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) 10387104862SruDraw an ellipse with a horizontal diameter of @var{x} and a vertical 10388104862Srudiameter of @var{y} with the leftmost point at the current position. 1038969626Sru 10390104862Sru@item \D'E @var{x} @var{y}' 10391104862Sru@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) 10392104862Sru@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) 10393104862Sru@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) 1039469626SruDraw a solid ellipse with the same parameters as an outlined ellipse. 10395104862SruNo outline is drawn. 1039669626Sru 1039755839Sasmodai@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 10398104862Sru@cindex arc, drawing (@w{@code{\D'a @dots{}'}}) 10399104862Sru@cindex drawing an arc (@w{@code{\D'a @dots{}'}}) 1040055839SasmodaiDraw an arc clockwise from the current location through the two 10401104862Sruspecified relative locations (@var{dx1},@var{dy1}) and 10402104862Sru(@var{dx2},@var{dy2}). The coordinates of the first point are relative 10403104862Sruto the current position, and the coordinates of the second point are 10404104862Srurelative to the first point. 1040569626Sru 10406104862Sru@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 10407104862Sru@cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) 10408104862Sru@cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) 10409104862SruDraw a spline from the current location to the relative point 10410104862Sru(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. 1041169626Sru 1041255839Sasmodai@item \D'f @var{n}' 10413104862Sru@cindex gray shading (@w{@code{\D'f @dots{}'}}) 10414104862Sru@cindex shading filled objects (@w{@code{\D'f @dots{}'}}) 1041569626SruSet the shade of gray to be used for filling solid objects to@w{ 1041669626Sru}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 1041769626Srucorresponds solid white and 1000 to solid black, and values in between 1041869626Srucorrespond to intermediate shades of gray. This applies only to solid 10419104862Srucircles, solid ellipses, and solid polygons. By default, a level of 10420104862Sru1000 is used. 1042155839Sasmodai 10422104862Sru@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 10423104862Sru@cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) 10424104862Sru@cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) 10425104862SruDraw a polygon from the current location to the relative position 10426104862Sru(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. 10427104862SruWhen the specified data points are exhausted, a line is drawn back 10428104862Sruto the starting point. 1042969626Sru 10430104862Sru@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 10431104862Sru@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) 10432104862Sru@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) 10433104862Sru@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) 1043455839SasmodaiDraw a solid polygon with the same parameters as an outlined polygon. 10435104862SruNo outline is drawn. 1043655839Sasmodai 10437104862SruHere a better variant of the box macro to fill the box with some color. 10438104862SruNote that the box must be drawn before the text since colors in 10439104862Sru@code{gtroff} are not transparent; the filled polygon would hide the 10440104862Srutext completely. 1044169626Sru 1044275584Sru@Example 10443104862Sru.de BOX 10444104862Sru. nr @@wd \w'\\$1' 10445104862Sru\h'.2m'\ 10446104862Sru\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 10447104862Sru\M[lightcyan]\ 10448104862Sru\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 10449104862Sru (\\n[@@wd]u + .4m) 0 \ 10450104862Sru 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 10451104862Sru -(\\n[@@wd]u + .4m) 0'\ 10452104862Sru\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 10453104862Sru\M[]\ 10454104862Sru\\$1\ 10455104862Sru\h'.2m' 10456104862Sru.. 1045775584Sru@endExample 1045855839Sasmodai 1045955839Sasmodai@item \D't @var{n}' 10460104862Sru@cindex line thickness (@w{@code{\D't @dots{}'}}) 10461104862Sru@cindex thickness of lines (@w{@code{\D't @dots{}'}}) 10462104862SruSet the current line thickness to @var{n}@w{ }machine units. A value of 1046369626Sruzero selects the smallest available line thickness. A negative value 1046469626Srumakes the line thickness proportional to the current point size (this is 10465104862Sruthe default behaviour of @acronym{AT&T} @code{troff}). 1046655839Sasmodai@end table 1046775584Sru@endDefesc 1046855839Sasmodai 10469104862Sru@xref{Graphics Commands}. 10470104862Sru 1047175584Sru@Defesc {\\b, ', string, '} 10472104862Sru@cindex pile, glyph (@code{\b}) 10473104862Sru@cindex glyph pile (@code{\b}) 10474104862Sru@cindex stacking glyphs (@code{\b}) 10475104862Sru@dfn{Pile} a sequence of glyphs vertically, and center it vertically 10476104862Sruon the current line. Use it to build large brackets and braces. 1047755839Sasmodai 10478104862SruHere an example how to create a large opening brace: 10479104862Sru 1048075584Sru@Example 10481104862Sru\b'\[lt]\[bv]\[lk]\[bv]\[lb]' 1048275584Sru@endExample 10483104862Sru 10484104862Sru@cindex @code{\b}, limitations 10485104862Sru@cindex limitations of @code{\b} escape 10486104862SruThe first glyph is on the top, the last glyph in @var{string} is 10487104862Sruat the bottom. Note that @code{gtroff} separates the glyphs 10488104862Sruvertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m} 10489104862Sruabove the current baseline; the largest glyph width is used as the 10490104862Sruwidth for the whole object. This rather unflexible positioning 10491104862Srualgorithm doesn't work with @option{-Tdvi} since the bracket pieces vary 10492104862Sruin height for this device. Instead, use the @code{eqn} preprocessor. 10493104862Sru 10494104862Sru@xref{Manipulating Spacing}, how to adjust the vertical spacing with 10495104862Sruthe @code{\x} escape. 1049675584Sru@endDefesc 1049755839Sasmodai 1049855839Sasmodai 1049969626Sru@c ===================================================================== 1050055839Sasmodai 1050175584Sru@node Traps, Diversions, Drawing Requests, gtroff Reference 1050255839Sasmodai@section Traps 1050355839Sasmodai@cindex traps 1050455839Sasmodai 1050575584Sru@dfn{Traps} are locations, which, when reached, call a specified 1050669626Srumacro. These traps can occur at a given location on the page, at a 10507104862Srugiven location in the current diversion, at a blank line, 10508104862Sruafter a certain number of input lines, or at the end of input. 1050955839Sasmodai 10510104862Sru@cindex planting a trap 10511104862Sru@cindex trap, planting 10512104862SruSetting a trap is also called @dfn{planting}. 10513104862Sru@cindex trap, springing 10514104862Sru@cindex springing a trap 10515104862SruIt is also said that a trap is @dfn{sprung} if the associated macro 10516104862Sruis executed. 10517104862Sru 1051855839Sasmodai@menu 1051975584Sru* Page Location Traps:: 1052075584Sru* Diversion Traps:: 1052175584Sru* Input Line Traps:: 10522104862Sru* Blank Line Traps:: 1052375584Sru* End-of-input Traps:: 1052455839Sasmodai@end menu 1052555839Sasmodai 1052669626Sru@c --------------------------------------------------------------------- 1052769626Sru 1052855839Sasmodai@node Page Location Traps, Diversion Traps, Traps, Traps 1052955839Sasmodai@subsection Page Location Traps 1053055839Sasmodai@cindex page location traps 1053155839Sasmodai@cindex traps, page location 1053255839Sasmodai 1053375584Sru@dfn{Page location traps} perform an action when @code{gtroff} 10534104862Srureaches or passes a certain vertical location on the page. Page 10535104862Srulocation traps have a variety of purposes, including: 1053655839Sasmodai 1053775584Sru@itemize 1053875584Sru@item 1053975584Srusetting headers and footers 1054075584Sru 1054175584Sru@item 1054275584Srusetting body text in multiple columns 1054375584Sru 1054475584Sru@item 1054575584Srusetting footnotes 1054675584Sru@end itemize 1054775584Sru 10548104862Sru@DefreqList {vpt, flag} 10549104862Sru@DefregListEnd {.vpt} 10550104862Sru@cindex enabling vertical position traps (@code{vpt}) 10551104862Sru@cindex vertical position traps, enabling (@code{vpt}) 10552104862Sru@cindex vertical position trap enable register (@code{.vpt}) 10553104862SruEnable vertical position traps if @var{flag} is non-zero, or disables 1055475584Sruthem otherwise. Vertical position traps are traps set by the @code{wh} 1055575584Sruor @code{dt} requests. Traps set by the @code{it} request are not 1055675584Sruvertical position traps. The parameter that controls whether vertical 1055775584Sruposition traps are enabled is global. Initially vertical position traps 1055875584Sruare enabled. The current setting of this is available in the 1055975584Sru@code{.vpt} read-only number register. 1056075584Sru@endDefreq 1056175584Sru 10562104862Sru@Defreq {wh, dist [@Var{macro}]} 10563104862SruSet a page location trap. Positive values for @var{dist} set 1056475584Sruthe trap relative to the top of the page; negative values set 10565104862Sruthe trap relative to the bottom of the page. Default scaling 10566104862Sruindicator is @samp{v}. 1056775584Sru 1056875584Sru@var{macro} is the name of the macro to execute when the 10569104862Srutrap is sprung. If @var{macro} is missing, remove the first trap 10570104862Sru(if any) at @var{dist}. 1057175584Sru 1057269626Sru@cindex page headers 1057369626Sru@cindex page footers 1057469626Sru@cindex headers 1057569626Sru@cindex footers 1057675584SruThe following is a simple example of how many macro packages 1057775584Sruset headers and footers. 1057855839Sasmodai 1057975584Sru@Example 1058069626Sru.de hd \" Page header 10581104862Sru' sp .5i 10582104862Sru. tl 'Title''date' 10583104862Sru' sp .3i 1058455839Sasmodai.. 10585104862Sru. 1058669626Sru.de fo \" Page footer 10587104862Sru' sp 1v 10588104862Sru. tl ''%'' 10589104862Sru' bp 1059055839Sasmodai.. 10591104862Sru. 1059269626Sru.wh 0 hd \" trap at top of the page 1059369626Sru.wh -1i fo \" trap one inch from bottom 1059475584Sru@endExample 10595104862Sru 10596104862SruA trap at or below the bottom of the page is ignored; it can be made 10597104862Sruactive by either moving it up or increasing the page length so that the 10598104862Srutrap is on the page. 10599104862Sru 10600104862SruIt is possible to have more than one trap at the same location; to do so, 10601104862Sruthe traps must be defined at different locations, then moved together with 10602104862Sruthe @code{ch} request; otherwise the second trap would replace the first 10603104862Sruone. Earlier defined traps hide later defined traps if moved to the same 10604104862Sruposition (the many empty lines caused by the @code{bp} request are omitted): 10605104862Sru 10606104862Sru@Example 10607104862Sru.de a 10608104862Sru. nop a 10609104862Sru.. 10610104862Sru.de b 10611104862Sru. nop b 10612104862Sru.. 10613104862Sru.de c 10614104862Sru. nop c 10615104862Sru.. 10616104862Sru. 10617104862Sru.wh 1i a 10618104862Sru.wh 2i b 10619104862Sru.wh 3i c 10620104862Sru.bp 10621104862Sru @result{} a b c 10622104862Sru@endExample 10623104862Sru@Example 10624104862Sru.ch b 1i 10625104862Sru.ch c 1i 10626104862Sru.bp 10627104862Sru @result{} a 10628104862Sru@endExample 10629104862Sru@Example 10630104862Sru.ch a 0.5i 10631104862Sru.bp 10632104862Sru @result{} a b 10633104862Sru@endExample 1063475584Sru@endDefreq 1063555839Sasmodai 1063675584Sru@Defreg {.t} 10637104862Sru@cindex distance to next trap register (@code{.t}) 10638104862Sru@cindex trap, distance, register (@code{.t}) 1063975584SruA read-only number register holding the distance to the next trap. 10640104862Sru 10641104862SruIf there are no traps between the current position and the bottom of the 10642104862Srupage, it contains the distance to the page bottom. In a diversion, the 10643104862Srudistance to the page bottom is infinite (the returned value is the biggest 10644104862Sruinteger which can be represented in @code{groff}) if there are no diversion 10645104862Srutraps. 1064675584Sru@endDefreg 1064755839Sasmodai 10648104862Sru@Defreq {ch, macro dist} 10649104862Sru@cindex changing trap location (@code{ch}) 10650104862Sru@cindex trap, changing location (@code{ch}) 10651104862SruChange the location of a trap. 1065275584SruThe first argument is the name of the macro to be invoked at 1065375584Sruthe trap, and the second argument is the new location for the trap 10654104862Sru(note that the parameters are specified the opposite of the @code{wh} 10655104862Srurequest). This is useful for building up footnotes in a diversion to 10656104862Sruallow more space at the bottom of the page for them. 1065755839Sasmodai 10658104862SruDefault scaling indicator for @var{dist} is @samp{v}. If @var{dist} 10659104862Sruis missing, the trap is removed. 10660104862Sru 1066169626Sru@c XXX 1066269626Sru 1066369626Sru@ignore 1066475584Sru@Example 1066555839Sasmodai... (simplified) footnote example ... 1066675584Sru@endExample 1066769626Sru@end ignore 1066875584Sru@endDefreq 1066955839Sasmodai 1067075584Sru@Defreg {.ne} 1067175584SruThe read-only number register @code{.ne} contains the amount of space 1067275584Sruthat was needed in the last @code{ne} request that caused a trap to be 1067375584Srusprung. Useful in conjunction with the @code{.trunc} register. 1067475584Sru@xref{Page Control}, for more information. 1067575584Sru@endDefreg 1067655839Sasmodai 1067775584Sru@Defreg {.trunc} 10678104862Sru@cindex @code{ne} request, and the @code{.trunc} register 10679104862Sru@cindex truncated vertical space register (@code{.trunc}) 1068075584SruA read-only register containing the amount of vertical space truncated 1068175584Sruby the most recently sprung vertical position trap, or, if the trap was 1068275584Srusprung by an @code{ne} request, minus the amount of vertical motion 1068375584Sruproduced by the @code{ne} request. In other words, at the point a trap 1068475584Sruis sprung, it represents the difference of what the vertical position 1068575584Sruwould have been but for the trap, and what the vertical position 1068675584Sruactually is. 1068775584Sru@endDefreg 1068855839Sasmodai 1068969626Sru@c --------------------------------------------------------------------- 1069055839Sasmodai 1069155839Sasmodai@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 1069255839Sasmodai@subsection Diversion Traps 1069355839Sasmodai@cindex diversion traps 1069455839Sasmodai@cindex traps, diversion 1069555839Sasmodai 1069675584Sru@Defreq {dt, dist macro} 10697104862Sru@cindex @code{.t} register, and diversions 10698104862Sru@cindex setting diversion trap (@code{dt}) 10699104862Sru@cindex diversion trap, setting (@code{dt}) 10700104862Sru@cindex trap, diversion, setting (@code{dt}) 10701104862SruSet a trap @emph{within} a diversion. 10702104862Sru@var{dist} is the location of the trap 10703104862Sru(identical to the @code{.wh} request; default scaling indicator is 10704104862Sru@samp{v}) and @var{macro} is the name of the macro to be invoked. The 1070575584Srunumber register @code{.t} still works within diversions. 1070655839Sasmodai@xref{Diversions}, for more information. 1070775584Sru@endDefreq 1070855839Sasmodai 1070969626Sru@c --------------------------------------------------------------------- 1071069626Sru 10711104862Sru@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps 1071255839Sasmodai@subsection Input Line Traps 1071355839Sasmodai@cindex input line traps 1071455839Sasmodai@cindex traps, input line 1071555839Sasmodai 10716104862Sru@DefreqList {it, n macro} 10717104862Sru@DefreqItem {itc, n macro} 10718104862Sru@cindex setting input line trap (@code{it}) 10719104862Sru@cindex input line trap, setting (@code{it}) 10720104862Sru@cindex trap, input line, setting (@code{it}) 10721104862SruSet an input line trap. 10722104862Sru@var{n}@w{ }is the number of lines of input which may be read before 10723104862Sruspringing the trap, @var{macro} is the macro to be invoked. 1072469626SruRequest lines are not counted as input lines. 1072569626Sru 1072675584SruFor example, one possible use is to have a macro which prints the 1072769626Srunext @var{n}@w{ }lines in a bold font. 1072855839Sasmodai 1072975584Sru@Example 1073055839Sasmodai.de B 10731104862Sru. it \\$1 B-end 10732104862Sru. ft B 1073355839Sasmodai.. 10734104862Sru. 1073555839Sasmodai.de B-end 10736104862Sru. ft R 1073755839Sasmodai.. 1073875584Sru@endExample 10739104862Sru 10740104862Sru@cindex input line traps and interrupted lines (@code{itc}) 10741104862Sru@cindex interrupted lines and input line traps (@code{itc}) 10742104862Sru@cindex traps, input line, and interrupted lines (@code{itc}) 10743104862Sru@cindex lines, interrupted, and input line traps (@code{itc}) 10744104862SruThe @code{itc} request is identical, 10745104862Sruexcept that a line interrupted with @code{\c} 10746104862Srucounts as one input line. 10747104862Sru 10748104862SruBoth requests are associated with the current environment 10749104862Sru(@pxref{Environments}); switching to another environment disables the 10750104862Srucurrent input trap, and going back reactivates it, restoring the number 10751104862Sruof already processed lines. 1075275584Sru@endDefreq 1075355839Sasmodai 1075469626Sru@c --------------------------------------------------------------------- 1075569626Sru 10756104862Sru@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps 10757104862Sru@subsection Blank Line Traps 10758104862Sru@cindex blank line traps 10759104862Sru@cindex traps, blank line 10760104862Sru 10761104862Sru@Defreq {blm, macro} 10762104862Sru@cindex blank line macro (@code{blm}) 10763104862SruSet a blank line trap. 10764104862Sru@code{gtroff} executes @var{macro} when it encounters a blank line in 10765104862Sruthe input file. 10766104862Sru@endDefreq 10767104862Sru 10768104862Sru@c --------------------------------------------------------------------- 10769104862Sru 10770104862Sru@node End-of-input Traps, , Blank Line Traps, Traps 1077155839Sasmodai@subsection End-of-input Traps 1077255839Sasmodai@cindex end-of-input traps 1077355839Sasmodai@cindex traps, end-of-input 1077455839Sasmodai 1077575584Sru@Defreq {em, macro} 10776104862Sru@cindex setting end-of-input trap (@code{em}) 10777104862Sru@cindex end-of-input trap, setting (@code{em}) 10778104862Sru@cindex trap, end-of-input, setting (@code{em}) 10779104862Sru@cindex end-of-input macro (@code{em}) 10780104862Sru@cindex macro, end-of-input (@code{em}) 10781104862SruSet a trap at the end of input. @var{macro} is executed after the 10782104862Srulast line of the input file has been processed. 1078355839Sasmodai 1078469626SruFor example, if the document had to have a section at the bottom of the 1078569626Srulast page for someone to approve it, the @code{em} request could be 1078669626Sruused. 1078755839Sasmodai 1078875584Sru@Example 1078955839Sasmodai.de approval 10790104862Sru. ne 5v 10791104862Sru. sp |(\\n[.t] - 6v) 10792104862Sru. in +4i 10793104862Sru. lc _ 10794104862Sru. br 1079555839SasmodaiApproved:\t\a 10796104862Sru. sp 1079755839SasmodaiDate:\t\t\a 1079855839Sasmodai.. 10799104862Sru. 1080055839Sasmodai.em approval 1080175584Sru@endExample 1080275584Sru@endDefreq 1080355839Sasmodai 1080455839Sasmodai 1080569626Sru@c ===================================================================== 1080669626Sru 1080775584Sru@node Diversions, Environments, Traps, gtroff Reference 1080855839Sasmodai@section Diversions 1080955839Sasmodai@cindex diversions 1081055839Sasmodai 1081169626SruIn @code{gtroff} it is possible to @dfn{divert} text into a named 1081269626Srustorage area. Due to the similarity to defining macros it is sometimes 1081369626Srusaid to be stored in a macro. This is used for saving text for output 1081469626Sruat a later time, which is useful for keeping blocks of text on the same 10815104862Srupage, footnotes, tables of contents, and indices. 1081655839Sasmodai 10817104862Sru@cindex top-level diversion 10818104862Sru@cindex diversion, top-level 10819104862SruFor orthogonality it is said that @code{gtroff} is in the @dfn{top-level 10820104862Srudiversion} if no diversion is active (i.e., the data is diverted to the 10821104862Sruoutput device). 1082275584Sru 10823104862Sru@DefreqList {di, macro} 10824104862Sru@DefreqListEnd {da, macro} 10825104862Sru@cindex beginning diversion (@code{di}) 10826104862Sru@cindex diversion, beginning (@code{di}) 10827104862Sru@cindex ending diversion (@code{di}) 10828104862Sru@cindex diversion, ending (@code{di}) 10829104862Sru@cindex appending to a diversion (@code{da}) 10830104862Sru@cindex diversion, appending (@code{da}) 10831104862SruBegin a diversion. Like the @code{de} 1083269626Srurequest, it takes an argument of a macro name to divert subsequent text 1083375584Sruinto. The @code{da} macro appends to an existing diversion. 1083455839Sasmodai 1083575584Sru@code{di} or @code{da} without an argument ends the diversion. 10836104862Sru@endDefreq 1083769626Sru 10838104862Sru@DefreqList {box, macro} 10839104862Sru@DefreqListEnd {boxa, macro} 10840104862SruBegin (or appends to) a diversion like the 10841104862Sru@code{di} and @code{da} requests. 10842104862SruThe difference is that @code{box} and @code{boxa} 10843104862Srudo not include a partially-filled line in the diversion. 1084469626Sru 10845104862SruCompare this: 10846104862Sru 1084775584Sru@Example 10848104862SruBefore the box. 10849104862Sru.box xxx 10850104862SruIn the box. 10851104862Sru.br 10852104862Sru.box 10853104862SruAfter the box. 10854104862Sru.br 10855104862Sru @result{} Before the box. After the box. 10856104862Sru.xxx 10857104862Sru @result{} In the box. 1085875584Sru@endExample 10859104862Sru 10860104862Sru@noindent 10861104862Sruwith this: 10862104862Sru 10863104862Sru@Example 10864104862SruBefore the diversion. 10865104862Sru.di yyy 10866104862SruIn the diversion. 10867104862Sru.br 10868104862Sru.di 10869104862SruAfter the diversion. 10870104862Sru.br 10871104862Sru @result{} After the diversion. 10872104862Sru.yyy 10873104862Sru @result{} Before the diversion. In the diversion. 10874104862Sru@endExample 10875104862Sru 10876104862Sru@code{box} or @code{boxa} without an argument ends the diversion. 1087775584Sru@endDefreq 1087855839Sasmodai 10879104862Sru@DefregList {.z} 10880104862Sru@DefregListEnd {.d} 10881104862Sru@cindex @code{nl} register, and @code{.d} 1088269626Sru@cindex nested diversions 1088369626Sru@cindex diversion, nested 10884104862Sru@cindex diversion name register (@code{.z}) 10885104862Sru@cindex vertical position in diversion register (@code{.d}) 10886104862Sru@cindex position, vertical, in diversion, register (@code{.d}) 10887104862Sru@cindex diversion, vertical position in, register (@code{.d}) 1088875584SruDiversions may be nested. The read-only number register @code{.z} 1088975584Srucontains the name of the current diversion (this is a string-valued 1089075584Sruregister). The read-only number register @code{.d} contains the current 1089175584Sruvertical place in the diversion. If not in a diversion it is the same 1089275584Sruas the register @code{nl}. 1089375584Sru@endDefreg 1089469626Sru 1089575584Sru@Defreg {.h} 10896104862Sru@cindex high-water mark register (@code{.h}) 10897104862Sru@cindex mark, high-water, register (@code{.h}) 10898104862Sru@cindex position of lowest text line (@code{.h}) 10899104862Sru@cindex text line, position of lowest (@code{.h}) 1090075584SruThe @dfn{high-water mark} on the current page. It corresponds to the 1090175584Srutext baseline of the lowest line on the page. This is a read-only 1090275584Sruregister. 10903104862Sru 10904104862Sru@Example 10905104862Sru.tm .h==\n[.h], nl==\n[nl] 10906104862Sru @result{} .h==0, nl==-1 10907104862SruThis is a test. 10908104862Sru.br 10909104862Sru.sp 2 10910104862Sru.tm .h==\n[.h], nl==\n[nl] 10911104862Sru @result{} .h==40, nl==120 10912104862Sru@endExample 10913104862Sru 10914104862Sru@cindex @code{.h} register, difference to @code{nl} 10915104862Sru@cindex @code{nl} register, difference to @code{.h} 10916104862Sru@noindent 10917104862SruAs can be seen in the previous example, empty lines are not considered 10918104862Sruin the return value of the @code{.h} register. 1091975584Sru@endDefreg 1092055839Sasmodai 10921104862Sru@DefregList {dn} 10922104862Sru@DefregListEnd {dl} 1092375584SruAfter completing a diversion, the read-write number registers @code{dn} 1092455839Sasmodaiand @code{dl} contain the vertical and horizontal size of the diversion. 1092555839Sasmodai 10926104862Sru@Example 1092755839Sasmodai.\" Center text both horizontally & vertically 10928104862Sru. 10929104862Sru.\" Enclose macro definitions in .eo and .ec 10930104862Sru.\" to avoid the doubling of the backslash 10931104862Sru.eo 10932104862Sru.\" macro .(c starts centering mode 1093355839Sasmodai.de (c 10934104862Sru. br 10935104862Sru. ev (c 10936104862Sru. evc 0 10937104862Sru. in 0 10938104862Sru. nf 10939104862Sru. di @@c 1094055839Sasmodai.. 10941104862Sru@endExample 10942104862Sru@Example 10943104862Sru.\" macro .)c terminates centering mode 1094455839Sasmodai.de )c 10945104862Sru. br 10946104862Sru. ev 10947104862Sru. di 10948104862Sru. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 10949104862Sru. sp \n[@@s]u 10950104862Sru. ce 1000 10951104862Sru. @@c 10952104862Sru. ce 0 10953104862Sru. sp \n[@@s]u 10954104862Sru. br 10955104862Sru. fi 10956104862Sru. rr @@s 10957104862Sru. rm @@s 10958104862Sru. rm @@c 1095955839Sasmodai.. 10960104862Sru.\" End of macro definitions, restore escape mechanism 10961104862Sru.ec 10962104862Sru@endExample 1096375584Sru@endDefreg 1096455839Sasmodai 10965104862Sru@DefescList {\\!, , , } 10966104862Sru@DefescListEnd {\\?, , @Var{anything}, \\?} 10967104862Sru@cindex transparent output (@code{\!}, @code{\?}) 10968104862Sru@cindex output, transparent (@code{\!}, @code{\?}) 10969104862SruPrevent requests, macros, and escapes from being 1097075584Sruinterpreted when read into a diversion. This takes the given text 1097175584Sruand @dfn{transparently} embeds it into the diversion. This is useful for 1097269626Srumacros which shouldn't be invoked until the diverted text is actually 1097369626Sruoutput. 1097455839Sasmodai 1097575584SruThe @code{\!} escape transparently embeds text up to 1097675584Sruand including the end of the line. 1097775584SruThe @code{\?} escape transparently embeds text until the next 1097875584Sruoccurrence of the @code{\?} escape. For example: 1097955839Sasmodai 1098075584Sru@Example 1098169626Sru\?@var{anything}\? 1098275584Sru@endExample 1098369626Sru 1098469626Sru@noindent 1098569626Sru@var{anything} may not contain newlines; use @code{\!} to embed 1098669626Srunewlines in a diversion. The escape sequence @code{\?} is also 1098769626Srurecognized in copy mode and turned into a single internal code; it is 10988104862Sruthis code that terminates @var{anything}. Thus the following example 1098975584Sruprints@w{ }4. 1099069626Sru 1099175584Sru@Example 1099255839Sasmodai.nr x 1 1099355839Sasmodai.nf 1099455839Sasmodai.di d 1099555839Sasmodai\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 1099655839Sasmodai.di 1099755839Sasmodai.nr x 2 1099855839Sasmodai.di e 1099955839Sasmodai.d 1100055839Sasmodai.di 1100155839Sasmodai.nr x 3 1100255839Sasmodai.di f 1100355839Sasmodai.e 1100455839Sasmodai.di 1100555839Sasmodai.nr x 4 1100655839Sasmodai.f 1100775584Sru@endExample 11008104862Sru 11009104862SruBoth escapes read the data in copy mode. 11010104862Sru 11011104862Sru@cindex @code{\!}, in top-level diversion 11012104862Sru@cindex top-level diversion, and @code{\!} 11013104862Sru@cindex diversion, top-level, and @code{\!} 11014104862SruIf @code{\!} is used in the top-level diversion, its argument is 11015104862Srudirectly embedded into the @code{gtroff} intermediate output. This can 11016104862Srube used for example to control a postprocessor which processes the data 11017104862Srubefore it is sent to the device driver. 11018104862Sru 11019104862Sru@cindex @code{\?}, in top-level diversion 11020104862Sru@cindex top-level diversion, and @code{\?} 11021104862Sru@cindex diversion, top-level, and @code{\?} 11022104862SruThe @code{\?} escape used in the top-level diversion produces no output 11023104862Sruat all; its argument is simply ignored. 1102475584Sru@endDefesc 1102555839Sasmodai 11026104862Sru@cindex @code{\!}, and @code{output} 11027104862Sru@cindex @code{output} request, and @code{\!} 11028104862Sru@Defreq {output, string} 11029104862SruEmit @var{string} directly to the @code{gtroff} intermediate output 11030104862Sru(subject to copy-mode interpretation); this is similar to @code{\!} used 11031104862Sruat the top level. An initial double quote in @var{string} is stripped off 11032104862Sruto allow initial blanks. 11033104862Sru 11034104862SruThis request can't be used before the first page has started -- if you get 11035104862Sruan error, simply insert @code{.br} before the @code{output} request. 11036104862Sru 11037104862SruWithout argument, @code{output} is ignored. 11038104862Sru 11039104862SruUse with caution! It is normally only needed for mark-up used by a 11040104862Srupostprocessor which does something with the output before sending it to 11041104862Sruthe output device, filtering out @code{string} again. 11042104862Sru@endDefreq 11043104862Sru 1104475584Sru@Defreq {asciify, div} 11045104862Sru@cindex unformatting diversions (@code{asciify}) 11046104862Sru@cindex diversion, unformatting (@code{asciify}) 11047104862Sru@cindex @code{trin} request, and @code{asciify} 11048104862Sru@dfn{Unformat} the diversion specified by @var{div} 11049104862Sruin such a way that @acronym{ASCII} characters, characters translated with 11050104862Sruthe @code{trin} request, space characters, and some escape sequences that 1105175584Sruwere formatted and diverted are treated like ordinary input 1105275584Srucharacters when the diversion is reread. It can be also used for gross 11053104862Sruhacks; for example, the following sets register@w{ }@code{n} to@w{ }1. 1105455839Sasmodai 1105575584Sru@Example 1105669626Sru.tr @@. 1105769626Sru.di x 1105875584Sru@@nr n 1 1105955839Sasmodai.br 1106055839Sasmodai.di 1106169626Sru.tr @@@@ 1106269626Sru.asciify x 1106355839Sasmodai.x 1106475584Sru@endExample 1106555839Sasmodai 1106669626Sru@xref{Copy-in Mode}. 1106775584Sru@endDefreq 1106855839Sasmodai 11069104862Sru@Defreq {unformat, div} 11070104862SruLike @code{asciify}, unformat the specified diversion. 11071104862SruHowever, @code{unformat} only unformats spaces and tabs 11072104862Srubetween words. 11073104862SruUnformatted tabs are treated as input tokens, 11074104862Sruand spaces are stretchable again. 1107555839Sasmodai 11076104862SruThe vertical size of lines is not preserved; glyph information (font, 11077104862Srufont size, space width, etc.)@: is retained. 11078104862Sru@endDefreq 11079104862Sru 11080104862Sru 1108169626Sru@c ===================================================================== 1108269626Sru 1108375584Sru@node Environments, Suppressing output, Diversions, gtroff Reference 1108455839Sasmodai@section Environments 1108555839Sasmodai@cindex environments 1108655839Sasmodai 1108769626SruIt happens frequently that some text should be printed in a certain 1108869626Sruformat regardless of what may be in effect at the time, for example, in 1108969626Srua trap invoked macro to print headers and footers. To solve this 1109075584Sru@code{gtroff} processes text in @dfn{environments}. An 1109169626Sruenvironment contains most of the parameters that control text 1109269626Sruprocessing. It is possible to switch amongst these environments; by 1109369626Srudefault @code{gtroff} processes text in environment@w{ }0. The 1109469626Srufollowing is the information kept in an environment. 1109555839Sasmodai 1109669626Sru@itemize @bullet 1109769626Sru@item 11098104862Srufont parameters (size, family, style, glyph height and slant, space 1109969626Sruand sentence space size) 1110055839Sasmodai 1110155839Sasmodai@item 1110269626Srupage parameters (line length, title length, vertical spacing, 11103104862Sruline spacing, indentation, line numbering, centering, right-justifying, 11104104862Sruunderlining, hyphenation data) 1110569626Sru 1110655839Sasmodai@item 1110769626Srufill and adjust mode 1110869626Sru 1110955839Sasmodai@item 11110104862Srutab stops, tab and leader characters, escape character, 11111104862Sruno-break and hyphen indicators, margin character data 1111269626Sru 1111355839Sasmodai@item 1111469626Srupartially collected lines 11115104862Sru 11116104862Sru@item 11117104862Sruinput traps 11118104862Sru 11119104862Sru@item 11120104862Srudrawing and fill colours 1112155839Sasmodai@end itemize 1112255839Sasmodai 1112369626SruThese environments may be given arbitrary names (see @ref{Identifiers}, 1112469626Srufor more info). Old versions of @code{troff} only had environments 11125104862Srunamed @samp{0}, @samp{1}, and @samp{2}. 1112655839Sasmodai 11127104862Sru@DefreqList {ev, [@Var{env}]} 11128104862Sru@DefregListEnd {.ev} 11129104862Sru@cindex switching environments (@code{ev}) 11130104862Sru@cindex environment, switching (@code{ev}) 11131104862Sru@cindex environment number/name register (@code{.ev}) 11132104862SruSwitch to another environment. The argument @var{env} is the name of 1113375584Sruthe environment to switch to. With no argument, @code{gtroff} switches 1113475584Sruback to the previous environment. There is no limit on the number of 1113575584Srunamed environments; they are created the first time that they are 1113675584Srureferenced. The @code{.ev} read-only register contains the name or 1113775584Srunumber of the current environment. This is a string-valued register. 1113855839Sasmodai 1113975584SruNote that a call to @code{ev} (with argument) pushes the previously 1114069626Sruactive environment onto a stack. If, say, environments @samp{foo}, 1114169626Sru@samp{bar}, and @samp{zap} are called (in that order), the first 1114275584Sru@code{ev} request without parameter switches back to environment 1114375584Sru@samp{bar} (which is popped off the stack), and a second call 1114475584Sruswitches back to environment @samp{foo}. 1114569626Sru 1114675584SruHere is an example: 1114769626Sru 1114875584Sru@Example 1114955839Sasmodai.ev footnote-env 1115055839Sasmodai.fam N 1115155839Sasmodai.ps 6 1115255839Sasmodai.vs 8 1115355839Sasmodai.ll -.5i 1115455839Sasmodai.ev 1115575584Sru 1115655839Sasmodai... 1115775584Sru 1115855839Sasmodai.ev footnote-env 1115955839Sasmodai\(dg Note the large, friendly letters. 1116055839Sasmodai.ev 1116175584Sru@endExample 1116275584Sru@endDefreq 1116355839Sasmodai 1116475584Sru@Defreq {evc, env} 11165104862Sru@cindex copying environment (@code{evc}) 11166104862Sru@cindex environment, copying (@code{evc}) 11167104862SruCopy the environment @var{env} into the current environment. 11168104862Sru 11169104862SruThe following environment data is not copied: 11170104862Sru 11171104862Sru@itemize @bullet 11172104862Sru@item 11173104862SruPartially filled lines. 11174104862Sru 11175104862Sru@item 11176104862SruThe status whether the previous line was interrupted. 11177104862Sru 11178104862Sru@item 11179104862SruThe number of lines still to center, or to right-justify, or to underline 11180104862Sru(with or without underlined spaces); they are set to zero. 11181104862Sru 11182104862Sru@item 11183104862SruThe status whether a temporary indent is active. 11184104862Sru 11185104862Sru@item 11186104862SruInput traps and its associated data. 11187104862Sru 11188104862Sru@item 11189104862SruLine numbering mode is disabled; it can be reactivated with 11190104862Sru@w{@samp{.nm +0}}. 11191104862Sru 11192104862Sru@item 11193104862SruThe number of consecutive hyphenated lines (set to zero). 11194104862Sru@end itemize 1119575584Sru@endDefreq 1119655839Sasmodai 11197104862Sru@DefregList {.cht} 11198104862Sru@DefregItem {.cdp} 11199104862Sru@DefregListEnd {.csk} 11200104862Sru@cindex environment, last glyph 11201104862SruThe @code{\n[.cht]} register contains the 11202104862Srumaximum extent (above the baseline) 11203104862Sruof the last glyph added to the current environment. 1120455839Sasmodai 11205104862SruThe @code{\n[.cdp]} register contains the 11206104862Srumaximum extent (below the baseline) 11207104862Sruof the last glyph added to the current environment. 11208104862Sru 11209104862SruThe @code{\n[.csk]} register contains the 11210104862Sru@dfn{skew} (how far to the right of the glyph's center 11211104862Sruthat @code{gtroff} shold place an accent) 11212104862Sruof the last glyph added to the current environment. 11213104862Sru@endDefreg 11214104862Sru 11215104862Sru 1121669626Sru@c ===================================================================== 1121755839Sasmodai 11218104862Sru@node Suppressing output, Colors, Environments, gtroff Reference 1121975584Sru@section Suppressing output 1122075584Sru 1122175584Sru@Defesc {\\O, , num, } 11222104862Sru@cindex suppressing output (@code{\O}) 11223104862Sru@cindex output, suppressing (@code{\O}) 11224104862SruDisable or enable output depending on the value of @var{num}: 1122575584Sru 1122675584Sru@table @samp 1122775584Sru@item \O0 11228104862SruDisable any glyphs from being emitted to the device driver, provided that 11229104862Sruthe escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}). 11230104862SruMotion is not suppressed so effectively @code{\O[0]} means @emph{pen up}. 1123175584Sru 1123275584Sru@item \O1 11233104862SruEnable output of glyphs, provided that the escape occurs at the outer 11234104862Srulevel. 1123575584Sru@end table 1123675584Sru 1123775584Sru@vindex opminx 1123875584Sru@vindex opminy 1123975584Sru@vindex opmaxx 1124075584Sru@vindex opmaxy 1124175584Sru@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 1124275584Sru@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 1124375584Sru@xref{Register Index}. These four registers mark the top left and 1124475584Srubottom right hand corners of a box which encompasses all written glyphs. 1124575584Sru 11246104862SruFor example the input text: 1124775584Sru 11248104862Sru@Example 11249104862SruHello \O[0]world \O[1]this is a test. 11250104862Sru@endExample 11251104862Sru 11252104862Sru@noindent 11253104862Sruproduces the following output: 11254104862Sru 11255104862Sru@Example 11256104862SruHello this is a test. 11257104862Sru@endExample 11258104862Sru 1125975584Sru@table @samp 1126075584Sru@item \O2 11261104862SruProvided that the escape occurs at the outer level, enable output of 11262104862Sruglyphs and also write out to @code{stderr} the page number and four 11263104862Sruregisters encompassing the glyphs previously written since the last call 11264104862Sruto @code{\O}. 1126575584Sru 1126675584Sru@item \O3 11267104862SruBegin a nesting level. At start-up, @code{gtroff} is at outer level. 11268104862Sru 11269104862Sru@item \O4 11270104862SruEnd a nesting level. 11271104862Sru 11272104862Sru@item \O[5@var{P}@var{filename}] 11273104862SruThis escape is @code{grohtml} specific. Provided that this escape 11274104862Sruoccurs at the outer nesting level write the @code{filename} to 11275104862Sru@code{stderr}. The position of the image, @var{P}, must be specified 11276104862Sruand must be one of @code{l}, @code{r}, @code{c}, or@w{ }@code{i} (left, 11277104862Sruright, centered, inline). @var{filename} will be associated with the 11278104862Sruproduction of the next inline image. 1127975584Sru@end table 1128075584Sru@endDefesc 1128175584Sru 11282104862Sru@c ===================================================================== 1128375584Sru 11284104862Sru@node Colors, I/O, Suppressing output, gtroff Reference 11285104862Sru@section Colors 11286104862Sru@cindex colors 11287104862Sru 11288104862Sru@DefreqList {color, [@Var{n}]} 11289104862Sru@DefregListEnd {.color} 11290104862SruIf @var{n} is missing or non-zero, activate colors (this is the default); 11291104862Sruotherwise, turn it off. 11292104862Sru 11293104862SruThe read-only number register @code{.color} is@w{ }1 if colors are active, 11294104862Sru0@w{ }otherwise. 11295104862Sru 11296104862SruInternally, @code{color} sets a global flag; it does not produce a token. 11297104862SruSimilar to the @code{cp} request, you should use it at the beginning of 11298104862Sruyour document to control color output. 11299104862Sru 11300104862SruColors can be also turned off with the @option{-c} command line option. 11301104862Sru@endDefreq 11302104862Sru 11303104862Sru@Defreq {defcolor, ident scheme color_components} 11304104862SruDefine color with name @var{ident}. @var{scheme} can be one of the 11305104862Srufollowing values: @code{rgb} (three components), @code{cym} (three 11306104862Srucomponents), @code{cmyk} (four components), and @code{gray} or 11307104862Sru@code{grey} (one component). 11308104862Sru 11309104862Sru@cindex default color 11310104862Sru@cindex color, default 11311104862SruColor components can be given either as a hexadecimal string or as 11312104862Srupositive decimal integers in the range 0--65535. A hexadecimal string 11313104862Srucontains all color components concatenated. It must start with either 11314104862Sru@code{#} or @code{##}; the former specifies hex values in the range 11315104862Sru0--255 (which are internally multiplied by@w{ }257), the latter in the 11316104862Srurange 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} 11317104862Sru(magenta). The default color name @c{default} can't be redefined; its 11318104862Sruvalue is device-specific (usually black). It is possible that the 11319104862Srudefault color for @code{\m} and @code{\M} is not identical. 11320104862Sru 11321104862Sru@cindex @code{f} unit, and colors 11322104862Sru@cindex unit, @code{f}, and colors 11323104862SruA new scaling indicator@w{ }@code{f} has been introduced which multiplies 11324104862Sruits value by 65536; this makes it convenient to specify color components 11325104862Sruas fractions in the range 0 to@w{ }1 (1f equals 65536u). Example: 11326104862Sru 11327104862Sru@Example 11328104862Sru.defcolor darkgreen rgb 0.1f 0.5f 0.2f 11329104862Sru@endExample 11330104862Sru 11331104862SruNote that @code{f} is the default scaling indicator for the 11332104862Sru@code{defcolor} request, thus the above statement is equivalent to 11333104862Sru 11334104862Sru@Example 11335104862Sru.defcolor darkgreen rgb 0.1 0.5 0.2 11336104862Sru@endExample 11337104862Sru@endDefreq 11338104862Sru 11339104862Sru@DefescList {\\m, , c, } 11340104862Sru@DefescItem {\\m, @lparen{}, co, } 11341104862Sru@DefescListEnd {\\m, @lbrack{}, color, @rbrack} 11342104862SruSet drawing color. The following example shows how to turn the next four 11343104862Sruwords red. 11344104862Sru 11345104862Sru@Example 11346104862Sru\m[red]these are in red\m[] and these words are in black. 11347104862Sru@endExample 11348104862Sru 11349104862SruThe escape @code{\m[]} returns to the previous color. 11350104862Sru 11351104862SruThe drawing color is associated with the current environment 11352104862Sru(@pxref{Environments}). 11353104862Sru 11354104862SruNote that @code{\m} doesn't produce an input token in @code{gtroff}. 11355104862SruAs a consequence, it can be used in requests like @code{mc} (which 11356104862Sruexpects a single character as an argument) to change the color on 11357104862Sruthe fly: 11358104862Sru 11359104862Sru@Example 11360104862Sru.mc \m[red]x\m[] 11361104862Sru@endExample 11362104862Sru@endDefesc 11363104862Sru 11364104862Sru@DefescList {\\M, , c, } 11365104862Sru@DefescItem {\\M, @lparen{}, co, } 11366104862Sru@DefescListEnd {\\M, @lbrack{}, color, @rbrack} 11367104862SruSet background color for filled objects drawn with the 11368104862Sru@code{\D'@dots{}'} commands. 11369104862Sru 11370104862SruA red ellipse can be created with the following code: 11371104862Sru 11372104862Sru@Example 11373104862Sru\M[red]\h'0.5i'\D'E 2i 1i'\M[] 11374104862Sru@endExample 11375104862Sru 11376104862SruThe escape @code{\M[]} returns to the previous fill color. 11377104862Sru 11378104862SruThe fill color is associated with the current environment 11379104862Sru(@pxref{Environments}). 11380104862Sru 11381104862SruNote that @code{\M} doesn't produce an input token in @code{gtroff}. 11382104862Sru@endDefesc 11383104862Sru 11384104862Sru 1138575584Sru@c ===================================================================== 1138675584Sru 11387104862Sru@node I/O, Postprocessor Access, Colors, gtroff Reference 1138855839Sasmodai@section I/O 1138955839Sasmodai@cindex i/o 1139069626Sru@cindex input and output requests 1139169626Sru@cindex requests for input and output 1139269626Sru@cindex output and input requests 1139355839Sasmodai 1139475584Sru@code{gtroff} has several requests for including files: 1139575584Sru 1139675584Sru@Defreq {so, file} 11397104862Sru@cindex including a file (@code{so}) 11398104862Sru@cindex file, inclusion (@code{so}) 11399104862SruRead in the specified @var{file} and 1140075584Sruincludes it in place of the @code{so} request. This is quite useful for 1140175584Srularge documents, e.g.@: keeping each chapter in a separate file. 1140255839Sasmodai@xref{gsoelim}, for more information. 11403104862Sru 11404104862SruSince @code{gtroff} replaces the @code{so} request with the contents 11405104862Sruof @code{file}, it makes a difference whether the data is terminated with 11406104862Srua newline or not: Assuming that file @file{xxx} contains the word 11407104862Sru@samp{foo} without a final newline, this 11408104862Sru 11409104862Sru@Example 11410104862SruThis is 11411104862Sru.so xxx 11412104862Srubar 11413104862Sru@endExample 11414104862Sru 11415104862Sru@noindent 11416104862Sruyields @samp{This is foobar}. 1141775584Sru@endDefreq 1141855839Sasmodai 11419104862Sru@Defreq {pso, command} 11420104862SruRead the standard output from the specified @var{command} 11421104862Sruand includes it in place of the @code{pso} request. 11422104862Sru 11423104862Sru@cindex safer mode 11424104862Sru@cindex mode, safer 11425104862Sru@cindex unsafe mode 11426104862Sru@cindex mode, unsafe 11427104862SruThis request causes an error if used in safer mode (which is the default). 11428104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 11429104862Srumode. 11430104862Sru 11431104862SruThe comment regarding a final newline for the @code{so} request is valid 11432104862Srufor @code{pso} also. 11433104862Sru@endDefreq 11434104862Sru 1143575584Sru@Defreq {mso, file} 11436104862SruIdentical to the @code{so} request except that @code{gtroff} searches for 11437104862Sruthe specified @var{file} in the same directories as macro files for the 1143875584Sruthe @option{-m} command line option. If the file name to be included 1143975584Sruhas the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 1144075584Sruto include @file{tmac.@var{name}} and vice versa. 1144175584Sru@endDefreq 1144255839Sasmodai 11443104862Sru@DefreqList {trf, file} 11444104862Sru@DefreqListEnd {cf, file} 11445104862Sru@cindex transparent output (@code{cf}, @code{trf}) 11446104862Sru@cindex output, transparent (@code{cf}, @code{trf}) 11447104862SruTransparently output the contents of @var{file}. Each line is output 11448104862Sruas if it were preceded by @code{\!}; however, the lines are not subject 11449104862Sruto copy mode interpretation. If the file does not end with a newline, 11450104862Sruthen a newline is added (@code{trf} only). For example, to define a 11451104862Srumacro@w{ }@code{x} containing the contents of file@w{ }@file{f}, use 1145255839Sasmodai 1145375584Sru@Example 1145455839Sasmodai.di x 1145555839Sasmodai.trf f 1145655839Sasmodai.di 1145775584Sru@endExample 1145855839Sasmodai 11459104862SruBoth @code{trf} and @code{cf}, when used in a diversion, 1146075584Sruembeds an object in the diversion which, when reread, causes the 11461104862Srucontents of @var{file} to be transparently copied through to the 11462104862Sruoutput. In @acronym{UNIX} @code{troff}, the contents of @var{file} 1146369626Sruis immediately copied through to the output regardless of whether there 1146469626Sruis a current diversion; this behaviour is so anomalous that it must be 11465104862Sruconsidered a bug. 1146655839Sasmodai 11467104862Sru@cindex @code{trf} request, and invalid characters 11468104862Sru@cindex characters, invalid for @code{trf} request 11469104862Sru@cindex invalid characters for @code{trf} request 11470104862SruWhile @code{cf} copies the contents of @var{file} completely unprocessed, 11471104862Sru@code{trf} disallows characters such as NUL that are not valid 11472104862Sru@code{gtroff} input characters (@pxref{Identifiers}). 11473104862Sru 11474104862SruBoth requests cause a line break. 1147575584Sru@endDefreq 1147655839Sasmodai 11477104862Sru@Defreq {nx, [@Var{file}]} 11478104862Sru@cindex processing next file (@code{nx}) 11479104862Sru@cindex file, processing next (@code{nx}) 11480104862Sru@cindex next file, processing (@code{nx}) 11481104862SruForce @code{gtroff} to continue processing of 11482104862Sruthe file specified as an argument. If no argument is given, immediately 11483104862Srujump to the end of file. 1148475584Sru@endDefreq 1148555839Sasmodai 11486104862Sru@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]} 11487104862Sru@cindex reading from standard input (@code{rd}) 11488104862Sru@cindex standard input, reading from (@code{rd}) 11489104862Sru@cindex input, standard, reading from (@code{rd}) 11490104862SruRead from standard input, and include what is read as though it 11491104862Sruwere part of the input file. Text is read until a blank line 11492104862Sruis encountered. 11493104862Sru 11494104862SruIf standard input is a TTY input device (keyboard), write @var{prompt} 11495104862Sruto standard error, followed by a colon (or send BEL for a beep if no 11496104862Sruargument is given). 11497104862Sru 11498104862SruArguments after @var{prompt} are available for the input. For example, 11499104862Sruthe line 11500104862Sru 11501104862Sru@Example 11502104862Sru.rd data foo bar 11503104862Sru@endExample 11504104862Sru 11505104862Sruwith the input @w{@samp{This is \$2.}} prints 11506104862Sru 11507104862Sru@Example 11508104862SruThis is bar. 11509104862Sru@endExample 1151075584Sru@endDefreq 1151155839Sasmodai 1151255839Sasmodai@cindex form letters 1151355839Sasmodai@cindex letters, form 1151475584SruUsing the @code{nx} and @code{rd} requests, 1151575584Sruit is easy to set up form letters. The form 11516104862Sruletter template is constructed like this, putting the following lines 11517104862Sruinto a file called @file{repeat.let}: 1151855839Sasmodai 1151975584Sru@Example 1152055839Sasmodai.ce 1152155839Sasmodai\*(td 1152255839Sasmodai.sp 2 1152355839Sasmodai.nf 1152455839Sasmodai.rd 1152555839Sasmodai.sp 1152655839Sasmodai.rd 1152755839Sasmodai.fi 1152855839SasmodaiBody of letter. 1152955839Sasmodai.bp 1153055839Sasmodai.nx repeat.let 1153175584Sru@endExample 1153255839Sasmodai 11533104862Sru@cindex @code{ex} request, used with @code{nx} and @code{rd} 1153469626Sru@noindent 11535104862SruWhen this is run, a file containing the following lines should be 11536104862Sruredirected in. Note that requests included in this file are executed 11537104862Sruas though they were part of the form letter. The last block of input 11538104862Sruis the @code{ex} request which tells @code{groff} to stop processing. If 11539104862Sruthis was not there, @code{groff} would not know when to stop. 1154055839Sasmodai 1154175584Sru@Example 1154255839SasmodaiTrent A. Fisher 1154355839Sasmodai708 NW 19th Av., #202 1154455839SasmodaiPortland, OR 97209 1154555839Sasmodai 1154655839SasmodaiDear Trent, 1154755839Sasmodai 1154855839SasmodaiLen Adollar 1154955839Sasmodai4315 Sierra Vista 1155055839SasmodaiSan Diego, CA 92103 1155155839Sasmodai 1155255839SasmodaiDear Mr. Adollar, 1155355839Sasmodai 1155455839Sasmodai.ex 1155575584Sru@endExample 1155655839Sasmodai 1155775584Sru@Defreq {pi, pipe} 11558104862SruPipe the output of @code{gtroff} to the shell command(s) 1155975584Sruspecified by @var{pipe}. This request must occur before 1156075584Sru@code{gtroff} has a chance to print anything. 11561104862Sru 11562104862Sru@cindex safer mode 11563104862Sru@cindex mode, safer 11564104862Sru@cindex unsafe mode 11565104862Sru@cindex mode, unsafe 11566104862Sru@code{pi} causes an error if used in safer mode (which is the default). 11567104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 11568104862Srumode. 11569104862Sru 11570104862SruMultiple calls to @code{pi} are allowed, acting as a chain. For example, 11571104862Sru 11572104862Sru@Example 11573104862Sru.pi foo 11574104862Sru.pi bar 11575104862Sru... 11576104862Sru@endExample 11577104862Sru 11578104862Sruis the same as @w{@samp{.pi foo | bar}}. 11579104862Sru 11580104862Sru@cindex @code{groff}, and @code{pi} request 11581104862Sru@cindex @code{pi} request, and @code{groff} 11582104862SruNote that the intermediate output format of @code{gtroff} is piped to 11583104862Sruthe specified commands. Consequently, calling @code{groff} without the 11584104862Sru@option{-Z} option normally causes a fatal error. 1158575584Sru@endDefreq 1158655839Sasmodai 11587104862Sru@DefreqList {sy, cmds} 11588104862Sru@DefregListEnd {systat} 11589104862SruExecute the shell command(s) specified by @var{cmds}. The output is not 11590104862Srusaved anyplace, so it is up to the user to do so. 1159169626Sru 11592104862Sru@cindex safer mode 11593104862Sru@cindex mode, safer 11594104862Sru@cindex unsafe mode 11595104862Sru@cindex mode, unsafe 11596104862SruThis request causes an error if used in safer mode (which is the default). 11597104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 11598104862Srumode. 1159969626Sru 11600104862SruFor example, the following code fragment introduces the current time into a 11601104862Srudocument: 1160255839Sasmodai 1160369626Sru@cindex time, current 1160469626Sru@cindex current time 1160555839Sasmodai@pindex perl 1160675584Sru@Example 1160755839Sasmodai.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 1160855839Sasmodai (localtime(time))[2,1,0]' > /tmp/x\n[$$] 1160955839Sasmodai.so /tmp/x\n[$$] 1161055839Sasmodai.sy rm /tmp/x\n[$$] 1161155839Sasmodai\nH:\nM:\nS 1161275584Sru@endExample 1161355839Sasmodai 1161469626Sru@noindent 1161569626SruNote that this works by having the @code{perl} script (run by @code{sy}) 1161675584Sruprint out the @code{nr} requests which set the number registers 11617104862Sru@code{H}, @code{M}, and @code{S}, and then reads those commands in with 1161869626Sruthe @code{so} request. 1161955839Sasmodai 11620104862SruFor most practical purposes, the number registers @code{seconds}, 11621104862Sru@code{minutes}, and @code{hours} which are initialized at start-up of 11622104862Sru@code{gtroff} should be sufficient. Use the @code{af} request to get a 11623104862Sruformatted output: 11624104862Sru 11625104862Sru@Example 11626104862Sru.af hours 00 11627104862Sru.af minutes 00 11628104862Sru.af seconds 00 11629104862Sru\n[hours]:\n[minutes]:\n[seconds] 11630104862Sru@endExample 11631104862Sru 11632104862Sru@cindex @code{system()} return value register (@code{systat}) 1163375584SruThe @code{systat} read-write number register contains the return value 1163475584Sruof the @code{system()} function executed by the last @code{sy} request. 1163575584Sru@endDefreq 1163655839Sasmodai 11637104862Sru@DefreqList {open, stream file} 11638104862Sru@DefreqListEnd {opena, stream file} 11639104862Sru@cindex opening file (@code{open}) 11640104862Sru@cindex file, opening (@code{open}) 11641104862Sru@cindex appending to a file (@code{opena}) 11642104862Sru@cindex file, appending to (@code{opena}) 11643104862SruOpen the specified @var{file} for writing and 1164475584Sruassociates the specified @var{stream} with it. 1164555839Sasmodai 11646104862SruThe @code{opena} request is like @code{open}, but if the file exists, 11647104862Sruappend to it instead of truncating it. 11648104862Sru 11649104862Sru@cindex safer mode 11650104862Sru@cindex mode, safer 11651104862Sru@cindex unsafe mode 11652104862Sru@cindex mode, unsafe 11653104862SruBoth @code{open} and @code{opena} cause an error if used in safer mode 11654104862Sru(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U} 11655104862Sruoption to activate unsafe mode. 1165675584Sru@endDefreq 1165755839Sasmodai 11658104862Sru@DefreqList {write, stream data} 11659104862Sru@DefreqListEnd {writec, stream data} 1166069626Sru@cindex copy-in mode, and @code{write} requests 1166169626Sru@cindex mode, copy-in, and @code{write} requests 11662104862Sru@cindex writing to file (@code{write}) 11663104862Sru@cindex file, writing to (@code{write}) 11664104862SruWrite to the file associated with the specified @var{stream}. 1166575584SruThe stream must previously have 1166669626Srubeen the subject of an open request. The remainder of the line is 1166769626Sruinterpreted as the @code{ds} request reads its second argument: A 1166875584Sruleading @samp{"} is stripped, and it is read in copy-in mode. 11669104862Sru 11670104862SruThe @code{writec} request is like @code{write}, but only 11671104862Sru@code{write} appends a newline to the data. 1167275584Sru@endDefreq 1167355839Sasmodai 11674104862Sru@Defreq {writem, stream xx} 11675104862Sru@cindex @code{asciify} request, and @code{writem} 11676104862SruWrite the contents of the macro or string @var{xx} 11677104862Sruto the file associated with the specified @var{stream}. 11678104862Sru 11679104862Sru@var{xx} is read in copy mode, i.e., already formatted elements are 11680104862Sruignored. Consequently, diversions must be unformatted with the 11681104862Sru@code{asciify} request before calling @code{writem}. Usually, this 11682104862Srumeans a loss of information. 11683104862Sru@endDefreq 11684104862Sru 1168575584Sru@Defreq {close, stream} 11686104862Sru@cindex closing file (@code{close}) 11687104862Sru@cindex file, closing (@code{close}) 11688104862SruClose the specified @var{stream}; 1168975584Sruthe stream is no longer an acceptable argument to the 1169069626Sru@code{write} request. 1169155839Sasmodai 11692104862SruHere a simple macro to write an index entry. 1169369626Sru 1169475584Sru@Example 11695104862Sru.open idx test.idx 11696104862Sru. 11697104862Sru.de IX 11698104862Sru. write idx \\n[%] \\$* 11699104862Sru.. 11700104862Sru. 11701104862Sru.IX test entry 11702104862Sru. 11703104862Sru.close idx 1170475584Sru@endExample 1170575584Sru@endDefreq 1170655839Sasmodai 11707104862Sru@DefescList {\\V, , e, } 11708104862Sru@DefescItem {\\V, @lparen{}, ev, } 11709104862Sru@DefescListEnd {\\V, @lbrack{}, env, @rbrack} 11710104862SruInterpolate the contents of the specified environment variable 11711104862Sru@var{env} (one-character name@w{ }@var{e}, two-character name @var{ev}) 11712104862Sruas returned by the function @code{getenv}. @code{\V} is interpreted 11713104862Sruin copy-in mode. 1171475584Sru@endDefesc 1171555839Sasmodai 1171655839Sasmodai 1171769626Sru@c ===================================================================== 1171869626Sru 1171975584Sru@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 1172055839Sasmodai@section Postprocessor Access 1172155839Sasmodai@cindex postprocessor access 1172255839Sasmodai@cindex access of postprocessor 1172355839Sasmodai 1172475584SruThere are two escapes which give information directly to the 1172575584Srupostprocessor. This is particularly useful for embedding 1172669626Sru@sc{PostScript} into the final document. 1172755839Sasmodai 1172875584Sru@Defesc {\\X, ', xxx, '} 1172975584SruEmbeds its argument into the @code{gtroff} 1173069626Sruoutput preceded with @w{@samp{x X}}. 11731104862Sru 11732104862Sru@cindex @code{\&}, in @code{\X} 11733104862Sru@cindex @code{\)}, in @code{\X} 11734104862Sru@cindex @code{\%}, in @code{\X} 11735104862Sru@ifnotinfo 11736104862Sru@cindex @code{\:}, in @code{\X} 11737104862Sru@end ifnotinfo 11738104862Sru@ifinfo 11739104862Sru@cindex @code{\@r{<colon>}}, in @code{\X} 11740104862Sru@end ifinfo 11741104862SruThe escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored 11742104862Sruwithin @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single 11743104862Sruspace characters. All other escapes (except @code{\\} which produces a 11744104862Srubackslash) cause an error. 11745104862Sru 11746104862Sru@kindex use_charnames_in_special 11747104862Sru@pindex DESC@r{, and @code{use_charnames_in_special}} 11748104862Sru@cindex @code{\X}, and special characters 11749104862SruIf the @samp{use_charnames_in_special} keyword is set in the @file{DESC} 11750104862Srufile, special characters no longer cause an error; the name @var{xx} is 11751104862Srurepresented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command. 11752104862SruAdditionally, the backslash is represented as @code{\\}. 11753104862Sru 11754104862Sru@samp{use_charnames_in_special} is currently used by @code{grohtml} only. 1175575584Sru@endDefesc 1175655839Sasmodai 11757104862Sru@DefescList {\\Y, , n, } 11758104862Sru@DefescItem {\\Y, @lparen{}, nm, } 11759104862Sru@DefescListEnd {\\Y, @lbrack{}, name, @rbrack} 11760104862SruThis is approximately equivalent to @samp{\X'\*[@var{name}]'} 11761104862Sru(one-character name@w{ }@var{n}, two-character name @var{nm}). 11762104862SruHowever, the contents of the string or macro @var{name} are not 11763104862Sruinterpreted; also it is permitted for @var{name} to have been defined 11764104862Sruas a macro and thus contain newlines (it is not permitted for the 11765104862Sruargument to @code{\X} to contain newlines). The inclusion of 11766104862Srunewlines requires an extension to the @acronym{UNIX} @code{troff} 11767104862Sruoutput format, and confuses drivers that do not know about this 11768104862Sruextension (@pxref{Device Control Commands}). 1176975584Sru@endDefesc 1177055839Sasmodai 1177169626Sru@xref{Output Devices}. 1177255839Sasmodai 1177355839Sasmodai 1177469626Sru@c ===================================================================== 1177555839Sasmodai 1177675584Sru@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 1177769626Sru@section Miscellaneous 1177855839Sasmodai 1177969626SruThis section documents parts of @code{gtroff} which cannot (yet) be 1178055839Sasmodaicategorized elsewhere in this manual. 1178155839Sasmodai 11782104862Sru@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]} 11783104862Sru@cindex printing line numbers (@code{nm}) 11784104862Sru@cindex line numbers, printing (@code{nm}) 11785104862Sru@cindex numbers, line, printing (@code{nm}) 11786104862SruPrint line numbers. 1178775584Sru@var{start} is the line number of the @emph{next} 11788104862Sruoutput line. @var{inc} indicates which line numbers are printed. 11789104862SruFor example, the value@w{ }5 means to emit only line numbers which 11790104862Sruare multiples of@w{ }5; this defaults to@w{ }1. @var{space} is the 11791104862Sruspace to be left between the number and the text; this defaults to 11792104862Sruone digit space. The fourth argument is the indentation of the line 11793104862Srunumbers, defaulting to zero. Both @var{space} and @var{indent} are 11794104862Srugiven as multiples of digit spaces; they can be negative also. 11795104862SruWithout any arguments, line numbers are turned off. 1179655839Sasmodai 11797104862Sru@code{gtroff} reserves three digit spaces for the line number (which is 11798104862Sruprinted right-justified) plus the amount given by @var{indent}; the 11799104862Sruoutput lines are concatenated to the line numbers, separated by 11800104862Sru@var{space}, and @emph{without} reducing the line length. Depending 11801104862Sruon the value of the horizontal page offset (as set with the 11802104862Sru@code{po} request), line numbers which are longer than the reserved 11803104862Sruspace stick out to the left, or the whole line is moved to the right. 1180469626Sru 11805104862SruParameters corresponding to missing arguments are not changed; any 11806104862Srunon-digit argument (to be more precise, any argument starting with a 11807104862Srucharacter valid as a delimiter for identifiers) is also treated as 11808104862Srumissing. 1180955839Sasmodai 11810104862SruIf line numbering has been disabled with a call to @code{nm} without 11811104862Sruan argument, it can be reactivated with @samp{.nm +0}, using the 11812104862Srupreviously active line numbering parameters. 1181369626Sru 11814104862SruThe parameters of @code{nm} are associated with the current environment 11815104862Sru(@pxref{Environments}). The current output line number is available 11816104862Sruin the number register @code{ln}. 1181769626Sru 1181875584Sru@Example 11819104862Sru.po 1m 11820104862Sru.ll 2i 11821104862SruThis test shows how line numbering works with groff. 11822104862Sru.nm 999 11823104862SruThis test shows how line numbering works with groff. 11824104862Sru.br 11825104862Sru.nm xxx 3 2 11826104862Sru.ll -\w'0'u 11827104862SruThis test shows how line numbering works with groff. 11828104862Sru.nn 2 11829104862SruThis test shows how line numbering works with groff. 1183075584Sru@endExample 11831104862Sru 11832104862Sru@noindent 11833104862SruAnd here the result: 11834104862Sru 11835104862Sru@Example 11836104862Sru This test shows how 11837104862Sru line numbering works 11838104862Sru 999 with groff. This 11839104862Sru1000 test shows how line 11840104862Sru1001 numbering works with 11841104862Sru1002 groff. 11842104862Sru This test shows how 11843104862Sru line numbering 11844104862Sru works with groff. 11845104862Sru This test shows how 11846104862Sru1005 line numbering 11847104862Sru works with groff. 11848104862Sru@endExample 1184975584Sru@endDefreq 1185055839Sasmodai 11851104862Sru@Defreq {nn, [@Var{skip}]} 11852104862SruTemporarily turn off line numbering. The argument is the number 11853104862Sruof lines not to be numbered; this defaults to@w{ }1. 11854104862Sru@endDefreq 1185555839Sasmodai 11856104862Sru@Defreq {mc, glyph [@Var{dist}]} 11857104862Sru@cindex margin glyph (@code{mc}) 11858104862Sru@cindex glyph, for margins (@code{mc}) 11859104862SruPrint a @dfn{margin character} to the right of the 11860104862Srutext.@footnote{@dfn{Margin character} is a misnomer since it is an 11861104862Sruoutput glyph.} The first argument is the glyph to be 11862104862Sruprinted. The second argument is the distance away from the right 11863104862Srumargin. If missing, the previously set value is used; default is 11864104862Sru10@dmn{pt}). For text lines that are too long (that is, longer than 11865104862Sruthe text length plus @var{dist}), the margin character is directly 11866104862Sruappended to the lines. 11867104862Sru 11868104862SruWith no arguments the margin character is turned off. 11869104862SruIf this occurs before a break, no margin character is printed. 11870104862Sru 11871104862Sru@cindex @code{tl} request, and @code{mc} 11872104862SruFor empty lines and lines produced by the @code{tl} request no margin 11873104862Srucharacter is emitted. 11874104862Sru 11875104862SruThe margin character is associated with the current environment 11876104862Sru(@pxref{Environments}). 11877104862Sru 1187869626Sru@pindex nrchbar 1187969626Sru@pindex changebar 1188069626SruThis is quite useful for indicating text that has changed, and, in fact, 1188169626Sruthere are programs available for doing this (they are called 1188255839Sasmodai@code{nrchbar} and @code{changebar} and can be found in any 1188355839Sasmodai@samp{comp.sources.unix} archive. 1188455839Sasmodai 1188575584Sru@Example 11886104862Sru.ll 3i 11887104862Sru.mc | 11888104862SruThis paragraph is highlighted with a margin 11889104862Srucharacter. 11890104862Sru.sp 11891104862SruNote that vertical space isn't marked. 11892104862Sru.br 11893104862Sru\& 11894104862Sru.br 11895104862SruBut we can fake it with `\&'. 1189675584Sru@endExample 1189755839Sasmodai 11898104862SruResult: 1189955839Sasmodai 11900104862Sru@Example 11901104862SruThis paragraph is highlighted | 11902104862Sruwith a margin character. | 1190369626Sru 11904104862SruNote that vertical space isn't | 11905104862Srumarked. | 11906104862Sru | 11907104862SruBut we can fake it with `\&'. | 1190875584Sru@endExample 1190975584Sru@endDefreq 1191055839Sasmodai 11911104862Sru@DefreqList {psbb, filename} 11912104862Sru@DefregItem {llx} 11913104862Sru@DefregItem {lly} 11914104862Sru@DefregItem {urx} 11915104862Sru@DefregListEnd {ury} 11916104862Sru@cindex PostScript, bounding box 11917104862Sru@cindex bounding box 11918104862SruRetrieve the bounding box of the PostScript image 11919104862Srufound in @var{filename}. 11920104862SruThe file must conform to 11921104862SruAdobe's @dfn{Document Structuring Conventions} (DSC); 11922104862Sruthe command searches for a @code{%%BoundingBox} comment 11923104862Sruand extracts the bounding box values into the number registers 11924104862Sru@code{llx}, @code{lly}, @code{urx}, and @code{ury}. 11925104862SruIf an error occurs (for example, @code{psbb} cannot find 11926104862Sruthe @code{%%BoundingBox} comment), 11927104862Sruit sets the four number registers to zero. 11928104862Sru@endDefreq 1192969626Sru 11930104862Sru 1193169626Sru@c ===================================================================== 1193269626Sru 1193375584Sru@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 1193475584Sru@section @code{gtroff} Internals 1193575584Sru 1193675584Sru@cindex input token 1193775584Sru@cindex token, input 1193875584Sru@cindex output node 1193975584Sru@cindex node, output 1194075584Sru@code{gtroff} processes input in three steps. One or more input 11941104862Srucharacters are converted to an @dfn{input token}.@footnote{Except the 11942104862Sruescapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R}, 11943104862Sru@code{\s}, and @code{\S} which are processed immediately if not in 11944104862Srucopy-in mode.} Then, one or more input tokens are converted to an 11945104862Sru@dfn{output node}. Finally, output nodes are converted to the 11946104862Sruintermediate output language understood by all output devices. 1194775584Sru 11948104862SruActually, before step one happens, @code{gtroff} converts certain 11949104862Sruescape sequences into reserved input characters (not accessible by 11950104862Sruthe user); such reserved characters are used for other internal 11951104862Sruprocessing also -- this is the very reason why not all characters 11952104862Sruare valid input. @xref{Identifiers}, for more on this topic. 11953104862Sru 11954104862SruFor example, the input string @samp{fi\[:u]} is converted into a 1195575584Srucharacter token @samp{f}, a character token @samp{i}, and a special 1195675584Srutoken @samp{:u} (representing u@w{ }umlaut). Later on, the character 1195775584Srutokens @samp{f} and @samp{i} are merged to a single output node 11958104862Srurepresenting the ligature glyph @samp{fi} (provided the current font 11959104862Sruhas a glyph for this ligature); the same happens with @samp{:u}. All 11960104862Sruoutput glyph nodes are `processed' which means that they are invariably 11961104862Sruassociated with a given font, font size, advance width, etc. During 11962104862Sruthe formatting process, @code{gtroff} itself adds various nodes to 11963104862Srucontrol the data flow. 1196475584Sru 1196575584SruMacros, diversions, and strings collect elements in two chained lists: 1196675584Srua list of input tokens which have been passed unprocessed, and a list 1196775584Sruof output nodes. Consider the following the diversion. 1196875584Sru 1196975584Sru@Example 1197075584Sru.di xxx 1197175584Srua 1197275584Sru\!b 1197375584Sruc 1197475584Sru.br 1197575584Sru.di 1197675584Sru@endExample 1197775584Sru 1197875584Sru@noindent 1197975584SruIt contains these elements. 1198075584Sru 1198175584Sru@multitable {@i{vertical size node}} {token list} {element number} 1198275584Sru@item node list @tab token list @tab element number 1198375584Sru 1198475584Sru@item @i{line start node} @tab --- @tab 1 1198575584Sru@item @i{glyph node @code{a}} @tab --- @tab 2 1198675584Sru@item @i{word space node} @tab --- @tab 3 1198775584Sru@item --- @tab @code{b} @tab 4 1198875584Sru@item --- @tab @code{\n} @tab 5 1198975584Sru@item @i{glyph node @code{c}} @tab --- @tab 6 1199075584Sru@item @i{vertical size node} @tab --- @tab 7 1199175584Sru@item @i{vertical size node} @tab --- @tab 8 1199275584Sru@item --- @tab @code{\n} @tab 9 1199375584Sru@end multitable 1199475584Sru 11995104862Sru@cindex @code{\v}, internal representation 1199675584Sru@noindent 1199775584SruElements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two 1199875584Sru(which are always present) specify the vertical extent of the last 11999104862Sruline, possibly modified by @code{\x}. The @code{br} request finishes 1200075584Sruthe current partial line, inserting a newline input token which is 1200175584Srusubsequently converted to a space when the diversion is reread. Note 1200275584Sruthat the word space node has a fixed width which isn't stretchable 1200375584Sruanymore. To convert horizontal space nodes back to input tokens, use 1200475584Sruthe @code{unformat} request. 1200575584Sru 1200675584SruMacros only contain elements in the token list (and the node list is 1200775584Sruempty); diversions and strings can contain elements in both lists. 1200875584Sru 12009104862SruNote that the @code{chop} request simply reduces the number of elements in a 12010104862Srumacro, string, or diversion by one. Exceptions are @dfn{compatibility save} 12011104862Sruand @dfn{compatibility ignore} input tokens which are ignored. The 12012104862Sru@code{substring} request also ignores those input tokens. 1201375584Sru 12014104862SruSome requests like @code{tr} or @code{cflags} work on glyph 12015104862Sruidentifiers only; this means that the associated glyph can be changed 12016104862Sruwithout destroying this association. This can be very helpful for 12017104862Srusubstituting glyphs. In the following example, we assume that 12018104862Sruglyph @samp{foo} isn't available by default, so we provide a 12019104862Srusubstitution using the @code{fchar} request and map it to input 12020104862Srucharacter @samp{x}. 12021104862Sru 12022104862Sru@Example 12023104862Sru.fchar \[foo] foo 12024104862Sru.tr x \[foo] 12025104862Sru@endExample 12026104862Sru 12027104862Sru@noindent 12028104862SruNow let us assume that we install an additional special font 12029104862Sru@samp{bar} which has glyph @samp{foo}. 12030104862Sru 12031104862Sru@Example 12032104862Sru.special bar 12033104862Sru.rchar \[foo] 12034104862Sru@endExample 12035104862Sru 12036104862Sru@noindent 12037104862SruSince glyphs defined with @code{fchar} are searched before glyphs 12038104862Sruin special fonts, we must call @code{rchar} to remove the definition 12039104862Sruof the fallback glyph. Anyway, the translation is still active; 12040104862Sru@samp{x} now maps to the real glyph @samp{foo}. 12041104862Sru 12042104862Sru 1204375584Sru@c ===================================================================== 1204475584Sru 1204575584Sru@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 1204655839Sasmodai@section Debugging 1204755839Sasmodai@cindex debugging 1204855839Sasmodai 1204969626Sru@code{gtroff} is not easy to debug, but there are some useful features 1205069626Sruand strategies for debugging. 1205155839Sasmodai 12052104862Sru@Defreq {lf, line filename} 12053104862Sru@pindex soelim 12054104862Sru@cindex multi-file documents 12055104862Sru@cindex documents, multi-file 12056104862Sru@cindex setting input line number (@code{lf}) 12057104862Sru@cindex input line number, setting (@code{lf}) 12058104862Sru@cindex number, input line, setting (@code{lf}) 12059104862SruChange the line number and the file name @code{gtroff} shall use for 12060104862Sruerror and warning messages. @var{line} is the input line number of the 12061104862Sru@emph{next} line. 12062104862Sru 12063104862SruWithout argument, the request is ignored. 12064104862Sru 12065104862SruThis is a debugging aid for documents which are split into many files, 12066104862Sruthen put together with @code{soelim} and other preprocessors. Usually, 12067104862Sruit isn't invoked manually. 1206875584Sru@endDefreq 1206969626Sru 12070104862Sru@DefreqList {tm, string} 12071104862Sru@DefreqItem {tm1, string} 12072104862Sru@DefreqListEnd {tmc, string} 12073104862Sru@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc}) 12074104862Sru@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc}) 12075104862SruSend @var{string} to the standard error output; 12076104862Sruthis is very useful for printing debugging messages among other things. 12077104862Sru 12078104862Sru@var{string} is read in copy mode. 12079104862Sru 12080104862SruThe @code{tm} request ignores leading spaces of @var{string}; @code{tm1} 12081104862Sruhandles its argument similar to the @code{ds} request: a leading double 12082104862Sruquote in @var{string} is stripped to allow initial blanks. 12083104862Sru 12084104862SruThe @code{tmc} request is similar to @code{tm1} but does 12085104862Srunot append a newline (as is done in @code{tm} and @code{tm1}). 12086104862Sru@endDefreq 12087104862Sru 1208875584Sru@Defreq {ab, [@Var{string}]} 12089104862Sru@cindex aborting (@code{ab}) 1209075584SruSimilar to the @code{tm} request, except that 1209175584Sruit causes @code{gtroff} to stop processing. With no argument it 12092104862Sruprints @samp{User Abort.} to standard error. 1209375584Sru@endDefreq 1209475584Sru 1209575584Sru@Defreq {ex, } 12096104862Sru@cindex @code{ex} request, use in debugging 12097104862Sru@cindex exiting (@code{ex}) 12098104862SruThe @code{ex} request also causes @code{gtroff} to stop processing; 12099104862Srusee also @ref{I/O}. 1210075584Sru@endDefreq 1210175584Sru 1210255839SasmodaiWhen doing something involved it is useful to leave the debugging 1210369626Srustatements in the code and have them turned on by a command line flag. 1210455839Sasmodai 1210575584Sru@Example 1210655839Sasmodai.if \n(DB .tm debugging output 1210775584Sru@endExample 1210855839Sasmodai 1210969626Sru@noindent 1211069626SruTo activate these statements say 1211155839Sasmodai 1211275584Sru@Example 1211355839Sasmodaigroff -rDB=1 file 1211475584Sru@endExample 1211555839Sasmodai 1211669626SruIf it is known in advance that there will be many errors and no useful 1211769626Sruoutput, @code{gtroff} can be forced to suppress formatted output with 1211869626Sruthe @option{-z} flag. 1211969626Sru 1212075584Sru@Defreq {pm, } 12121104862Sru@cindex dumping symbol table (@code{pm}) 12122104862Sru@cindex symbol table, dumping (@code{pm}) 12123104862SruPrint the entire symbol table on @code{stderr}. Names of all defined 12124104862Srumacros, strings, and diversions are print together with their size in 12125104862Srubytes. Since @code{gtroff} sometimes adds nodes by itself, the 12126104862Srureturned size can be larger than expected. 12127104862Sru 12128104862SruThis request differs from @acronym{UNIX} @code{troff}: @code{gtroff} 12129104862Srureports the sizes of diversions, ignores an additional argument to 12130104862Sruprint only the total of the sizes, and the size isn't returned in 12131104862Srublocks of 128 characters. 1213275584Sru@endDefreq 1213369626Sru 1213475584Sru@Defreq {pnr, } 12135104862Sru@cindex dumping number registers (@code{pnr}) 12136104862Sru@cindex number registers, dumping (@code{pnr}) 12137104862SruPrint the names and contents of all 1213875584Srucurrently defined number registers on @code{stderr}. 1213975584Sru@endDefreq 1214069626Sru 1214175584Sru@Defreq {ptr, } 12142104862Sru@cindex dumping traps (@code{ptr}) 12143104862Sru@cindex traps, dumping (@code{ptr}) 12144104862SruPrint the names and positions of all traps 1214575584Sru(not including input line traps and diversion traps) on @code{stderr}. 1214675584SruEmpty slots in the page trap list are printed as well, because they can 1214775584Sruaffect the priority of subsequently planted traps. 1214875584Sru@endDefreq 1214969626Sru 12150104862Sru@Defreq {fl, } 12151104862Sru@cindex flush output (@code{fl}) 12152104862Sru@cindex output, flush (@code{fl}) 1215369626Sru@cindex interactive use of @code{gtroff} 1215469626Sru@cindex @code{gtroff}, interactive use 12155104862SruInstruct @code{gtroff} to flush its output immediately. The intent 12156104862Sruis for interactive use, but this behaviour is currently not 12157104862Sruimplemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff}, 12158104862SruTTY output is sent to a device driver also (@code{grotty}), making it 12159104862Srunon-trivial to communicate interactively. 12160104862Sru 12161104862SruThis request causes a line break. 1216275584Sru@endDefreq 1216369626Sru 1216475584Sru@Defreq {backtrace, } 12165104862Sru@cindex backtrace of input stack (@code{backtrace}) 12166104862Sru@cindex input stack, backtrace (@code{backtrace}) 12167104862SruPrint a backtrace of the input stack to the standard error stream. 12168104862Sru 12169104862SruConsider the following in file @file{test}: 12170104862Sru 12171104862Sru@Example 12172104862Sru.de xxx 12173104862Sru. backtrace 12174104862Sru.. 12175104862Sru.de yyy 12176104862Sru. xxx 12177104862Sru.. 12178104862Sru. 12179104862Sru.yyy 12180104862Sru@endExample 12181104862Sru 12182104862Sru@noindent 12183104862SruOn execution, @code{gtroff} prints the following: 12184104862Sru 12185104862Sru@Example 12186104862Srutest:2: backtrace: macro `xxx' 12187104862Srutest:5: backtrace: macro `yyy' 12188104862Srutest:8: backtrace: file `test' 12189104862Sru@endExample 12190104862Sru 12191104862SruThe option @option{-b} of @code{gtroff} internally calls a variant of 12192104862Sruthis request on each error and warning. 1219375584Sru@endDefreq 1219469626Sru 12195104862Sru@Defreg {slimit} 12196104862Sru@cindex input stack, setting limit 12197104862SruUse the @code{slimit} number register 12198104862Sruto set the maximum number of objects on the input stack. 12199104862SruIf @code{slimit} is less than or equal to@w{ }0, 12200104862Sruthere is no limit set. 12201104862SruWith no limit, a buggy recursive macro can exhaust virtual memory. 12202104862Sru 12203104862SruThe default value is 1000; this is a compile-time constant. 12204104862Sru@endDefreg 12205104862Sru 12206104862Sru@Defreq {warnscale, si} 12207104862SruSet the scaling indicator used in warnings to @var{si}. Valid values for 12208104862Sru@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At 12209104862Srustartup, it is set to @samp{i}. 12210104862Sru@endDefreq 12211104862Sru 12212104862Sru@Defreq {spreadwarn, [@Var{limit}]} 12213104862SruMake @code{gtroff} emit a warning if the additional space inserted for 12214104862Srueach space between words in an output line is larger or equal to 12215104862Sru@var{limit}. A negative value is changed to zero; no argument toggles the 12216104862Sruwarning on and off without changing @var{limit}. The default scaling 12217104862Sruindicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and 12218104862Sru@var{limit} is set to 3@dmn{m}. 12219104862Sru 12220104862SruFor example, 12221104862Sru 12222104862Sru@Example 12223104862Sru.spreadwarn 0.2m 12224104862Sru@endExample 12225104862Sru 12226104862Sru@noindent 12227104862Sruwill cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each 12228104862Sruinterword space in a line. 12229104862Sru 12230104862SruThis request is active only if text is justified to both margins (using 12231104862Sru@w{@samp{.ad b}}). 12232104862Sru@endDefreq 12233104862Sru 1223469626Sru@cindex warnings 1223569626Sru@code{gtroff} has command line options for printing out more warnings 1223669626Sru(@option{-w}) and for printing backtraces (@option{-b}) when a warning 1223769626Sruor an error occurs. The most verbose level of warnings is @option{-ww}. 1223869626Sru 12239104862Sru@DefreqList {warn, [@Var{flags}]} 12240104862Sru@DefregListEnd {.warn} 12241104862Sru@cindex level of warnings (@code{warn}) 12242104862Sru@cindex warnings, level (@code{warn}) 12243104862SruControl the level of warnings checked for. The @var{flags} are the sum 1224475584Sruof the numbers associated with each warning that is to be enabled; all 1224575584Sruother warnings are disabled. The number associated with each warning is 1224675584Srulisted below. For example, @w{@code{.warn 0}} disables all warnings, 1224775584Sruand @w{@code{.warn 1}} disables all warnings except that about missing 12248104862Sruglyphs. If no argument is given, all warnings are enabled. 1224955839Sasmodai 1225075584SruThe read-only number register @code{.warn} contains the current warning 1225175584Srulevel. 1225275584Sru@endDefreq 1225369626Sru 1225469626Sru@menu 1225575584Sru* Warnings:: 1225669626Sru@end menu 1225769626Sru 1225875584Sru@c --------------------------------------------------------------------- 1225975584Sru 1226069626Sru@node Warnings, , Debugging, Debugging 1226155839Sasmodai@subsection Warnings 1226255839Sasmodai@cindex warnings 1226355839Sasmodai 1226469626SruThe warnings that can be given to @code{gtroff} are divided into the 1226569626Srufollowing categories. The name associated with each warning is used by 1226669626Sruthe @option{-w} and @option{-W} options; the number is used by the 1226769626Sru@code{warn} request and by the @code{.warn} register. 1226855839Sasmodai 1226955839Sasmodai@table @samp 1227069626Sru@item char 1227155839Sasmodai@itemx 1 12272104862SruNon-existent glyphs.@footnote{@code{char} is a misnomer since it reports 12273104862Srumissing glyphs -- there aren't missing input characters, only invalid 12274104862Sruones.} This is enabled by default. 1227569626Sru 1227669626Sru@item number 1227755839Sasmodai@itemx 2 1227855839SasmodaiInvalid numeric expressions. This is enabled by default. 1227969626Sru@xref{Expressions}. 1228069626Sru 1228169626Sru@item break 1228255839Sasmodai@itemx 4 1228369626Sru@cindex fill mode 1228469626Sru@cindex mode, fill 1228569626SruIn fill mode, lines which could not be broken so that their length was 1228669626Sruless than the line length. This is enabled by default. 1228769626Sru 1228869626Sru@item delim 1228955839Sasmodai@itemx 8 1229055839SasmodaiMissing or mismatched closing delimiters. 1229169626Sru 1229269626Sru@item el 1229355839Sasmodai@itemx 16 12294104862Sru@cindex @code{ie} request, and warnings 12295104862Sru@cindex @code{el} request, and warnings 1229655839SasmodaiUse of the @code{el} request with no matching @code{ie} request. 1229769626Sru@xref{if-else}. 1229869626Sru 1229969626Sru@item scale 1230055839Sasmodai@itemx 32 1230155839SasmodaiMeaningless scaling indicators. 1230269626Sru 1230369626Sru@item range 1230455839Sasmodai@itemx 64 1230555839SasmodaiOut of range arguments. 1230669626Sru 1230769626Sru@item syntax 1230855839Sasmodai@itemx 128 1230955839SasmodaiDubious syntax in numeric expressions. 1231069626Sru 1231169626Sru@item di 1231255839Sasmodai@itemx 256 12313104862Sru@cindex @code{di} request, and warnings 12314104862Sru@cindex @code{da} request, and warnings 1231555839SasmodaiUse of @code{di} or @code{da} without an argument when there is no 1231655839Sasmodaicurrent diversion. 1231769626Sru 1231869626Sru@item mac 1231955839Sasmodai@itemx 512 12320104862Sru@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings 12321104862Sru@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings 12322104862Sru@cindex @code{ds}, @code{ds1} requests, and warnings 12323104862Sru@cindex @code{as}, @code{as1} requests, and warnings 12324104862Sru@cindex @code{di} request, and warnings 12325104862Sru@cindex @code{da} request, and warnings 12326104862Sru@cindex @code{box}, @code{boxa} requests, and warnings 12327104862Sru@cindex @code{\*}, and warnings 1232869626SruUse of undefined strings, macros and diversions. When an undefined 12329104862Srustring, macro, or diversion is used, that string is automatically 12330104862Srudefined as empty. So, in most cases, at most one warning is given 12331104862Srufor each name. 1233269626Sru 12333104862Sru@item reg 1233455839Sasmodai@itemx 1024 12335104862Sru@cindex @code{nr} request, and warnings 12336104862Sru@cindex @code{\R}, and warnings 12337104862Sru@cindex @code{\n}, and warnings 1233869626SruUse of undefined number registers. When an undefined number register is 1233969626Sruused, that register is automatically defined to have a value of@w{ }0. 12340104862SruSo, in most cases, at most one warning is given for use of a particular 12341104862Sruname. 1234269626Sru 12343104862Sru@item tab 1234455839Sasmodai@itemx 2048 12345104862Sru@cindex @code{\t}, and warnings 1234655839SasmodaiUse of a tab character where a number was expected. 1234769626Sru 12348104862Sru@item right-brace 1234955839Sasmodai@itemx 4096 12350104862Sru@cindex @code{\@}}, and warnings 1235155839SasmodaiUse of @code{\@}} where a number was expected. 1235269626Sru 12353104862Sru@item missing 1235455839Sasmodai@itemx 8192 1235555839SasmodaiRequests that are missing non-optional arguments. 1235669626Sru 12357104862Sru@item input 1235855839Sasmodai@itemx 16384 12359104862SruInvalid input characters. 1236069626Sru 12361104862Sru@item escape 1236255839Sasmodai@itemx 32768 12363104862SruUnrecognized escape sequences. When an unrecognized escape sequence 12364104862Sru@code{\@var{X}} is encountered, the escape character is ignored, and 12365104862Sru@var{X} is printed. 1236669626Sru 12367104862Sru@item space 1236855839Sasmodai@itemx 65536 1236969626Sru@cindex compatibility mode 1237069626SruMissing space between a request or macro and its argument. This warning 1237175584Sruis given when an undefined name longer than two characters is 1237269626Sruencountered, and the first two characters of the name make a defined 1237375584Sruname. The request or macro is not invoked. When this warning is 1237469626Srugiven, no macro is automatically defined. This is enabled by default. 1237575584SruThis warning never occurs in compatibility mode. 1237669626Sru 12377104862Sru@item font 1237855839Sasmodai@itemx 131072 1237969626SruNon-existent fonts. This is enabled by default. 1238069626Sru 12381104862Sru@item ig 12382104862Sru@itemx 262144 12383104862SruInvalid escapes in text ignored with the @code{ig} request. These are 12384104862Sruconditions that are errors when they do not occur in ignored text. 12385104862Sru 12386104862Sru@item color 12387104862Sru@itemx 524288 12388104862SruColor related warnings. 12389104862Sru 1239055839Sasmodai@item all 1239169626SruAll warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 1239269626Sruintended that this covers all warnings that are useful with traditional 1239369626Srumacro packages. 1239469626Sru 1239555839Sasmodai@item w 1239655839SasmodaiAll warnings. 1239755839Sasmodai@end table 1239855839Sasmodai 1239955839Sasmodai 1240069626Sru@c ===================================================================== 1240169626Sru 12402104862Sru@node Implementation Differences, , Debugging, gtroff Reference 1240355839Sasmodai@section Implementation Differences 1240455839Sasmodai@cindex implementation differences 1240555839Sasmodai@cindex differences in implementation 12406104862Sru@cindex incompatibilities with @acronym{AT&T} @code{troff} 1240769626Sru@cindex compatibility mode 1240869626Sru@cindex mode, compatibility 1240955839Sasmodai 1241069626SruGNU @code{troff} has a number of features which cause incompatibilities 1241169626Sruwith documents written with old versions of @code{troff}. 1241255839Sasmodai 1241369626Sru@cindex long names 1241469626Sru@cindex names, long 1241569626SruLong names cause some incompatibilities. @acronym{UNIX} @code{troff} 1241675584Sruinterprets 1241755839Sasmodai 1241875584Sru@Example 1241955839Sasmodai.dsabcd 1242075584Sru@endExample 1242155839Sasmodai 12422104862Sru@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff} 12423104862Sru@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff} 1242469626Sru@noindent 1242569626Sruas defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 1242675584Sru@code{troff} interprets this as a call of a macro named 1242775584Sru@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 1242869626Sru@code{\*[} or @code{\n[} as references to a string or number register 1242975584Srucalled @samp{[}. In GNU @code{troff}, however, this is normally 1243069626Sruinterpreted as the start of a long name. In compatibility mode GNU 1243175584Sru@code{troff} interprets long names in the traditional way 1243275584Sru(which means that they are not recognized as names). 1243355839Sasmodai 12434104862Sru@DefreqList {cp, [@Var{n}]} 12435104862Sru@DefreqItem {do, cmd} 12436104862Sru@DefregListEnd {.C} 12437104862SruIf @var{n} is missing or non-zero, turn on compatibility mode; 12438104862Sruotherwise, turn it off. 12439104862Sru 12440104862SruThe read-only number register @code{.C} is@w{ }1 if compatibility mode is 12441104862Sruon, 0@w{ }otherwise. 12442104862Sru 12443104862SruCompatibility mode can be also turned on with the @option{-C} command line 12444104862Sruoption. 12445104862Sru 12446104862SruThe @code{do} request turns off compatibility mode 12447104862Sruwhile executing its arguments as a @code{gtroff} command. 12448104862Sru 12449104862Sru@Example 12450104862Sru.do fam T 12451104862Sru@endExample 12452104862Sru 12453104862Sru@noindent 12454104862Sruexecutes the @code{fam} request when compatibility mode 12455104862Sruis enabled. 12456104862Sru 12457104862Sru@code{gtroff} restores the previous compatibility setting 12458104862Srubefore interpreting any files sourced by the @var{cmd}. 12459104862Sru@endDefreq 12460104862Sru 12461104862Sru@cindex input level in delimited arguments 12462104862Sru@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff} 12463104862SruTwo other features are controlled by @option{-C}. If not in 12464104862Srucompatibility mode, GNU @code{troff} preserves the input level in 12465104862Srudelimited arguments: 12466104862Sru 12467104862Sru@Example 12468104862Sru.ds xx ' 12469104862Sru\w'abc\*(xxdef' 12470104862Sru@endExample 12471104862Sru 12472104862Sru@noindent 12473104862SruIn compatibility mode, the string @samp{72def'} is returned; without 12474104862Sru@option{-C} the resulting string is @samp{168} (assuming a TTY output 12475104862Srudevice). 12476104862Sru 12477104862Sru@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff} 12478104862Sru@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff} 12479104862Sru@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff} 12480104862Sru@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff} 12481104862SruFinally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M}, 12482104862Sru@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the 12483104862Srubeginning of a line only in compatibility mode (this is a rather obscure 12484104862Srufeature). For example, the code 12485104862Sru 12486104862Sru@Example 12487104862Sru.de xx 12488104862SruHallo! 12489104862Sru.. 12490104862Sru\fB.xx\fP 12491104862Sru@endExample 12492104862Sru 12493104862Sruprints @samp{Hallo!} in bold face if in compatibility mode, and 12494104862Sru@samp{.xx} in bold face otherwise. 12495104862Sru 12496104862Sru@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff} 12497104862Sru@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff} 12498104862Sru@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff} 12499104862Sru@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff} 12500104862Sru@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff} 12501104862Sru@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff} 12502104862Sru@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff} 12503104862Sru@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff} 12504104862Sru@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff} 12505104862Sru@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff} 12506104862Sru@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff} 12507104862Sru@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 12508104862Sru@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff} 12509104862Sru@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff} 1251069626SruGNU @code{troff} does not allow the use of the escape sequences 1251175584Sru@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 1251269626Sru@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 1251369626Sru@code{\%}, and @code{\c} in names of strings, macros, diversions, number 1251469626Sruregisters, fonts or environments; @acronym{UNIX} @code{troff} does. The 1251569626Sru@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 1251669626Sruavoiding use of these escape sequences in names. 1251755839Sasmodai 1251855839Sasmodai@cindex fractional point sizes 12519104862Sru@cindex fractional type sizes 1252055839Sasmodai@cindex point sizes, fractional 12521104862Sru@cindex type sizes, fractional 12522104862Sru@cindex sizes, fractional 12523104862Sru@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff} 1252469626SruFractional point sizes cause one noteworthy incompatibility. In 1252569626Sru@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 1252669626Sruindicators and thus 1252755839Sasmodai 1252875584Sru@Example 1252955839Sasmodai.ps 10u 1253075584Sru@endExample 1253155839Sasmodai 1253269626Sru@noindent 1253375584Srusets the point size to 10@w{ }points, whereas in GNU @code{troff} it 1253475584Srusets the point size to 10@w{ }scaled points. @xref{Fractional Type 1253569626SruSizes}, for more information. 1253655839Sasmodai 12537104862Sru@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} 12538104862Sru@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff} 12539104862Sru@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff} 12540104862Sru@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff} 12541104862Sru@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff} 12542104862Sru@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff} 12543104862Sru@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff} 12544104862Sru@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff} 1254569626SruIn GNU @code{troff} there is a fundamental difference between 12546104862Sru(unformatted) input characters and (formatted) output glyphs. 12547104862SruEverything that affects how a glyph is output is stored 12548104862Sruwith the glyph node; once a glyph node has been constructed it is 1254955839Sasmodaiunaffected by any subsequent requests that are executed, including 1255069626Sru@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 12551104862SruNormally glyphs are constructed from input characters at the 12552104862Srumoment immediately before the glyph is added to the current output 1255369626Sruline. Macros, diversions and strings are all, in fact, the same type of 12554104862Sruobject; they contain lists of input characters and glyph nodes in 12555104862Sruany combination. A glyph node does not behave like an input 1255669626Srucharacter for the purposes of macro processing; it does not inherit any 1255769626Sruof the special properties that the input character from which it was 1255869626Sruconstructed might have had. For example, 1255955839Sasmodai 1256075584Sru@Example 1256155839Sasmodai.di x 1256255839Sasmodai\\\\ 1256355839Sasmodai.br 1256455839Sasmodai.di 1256555839Sasmodai.x 1256675584Sru@endExample 1256755839Sasmodai 12568104862Sru@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 12569104862Sru@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 12570104862Sru@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff} 12571104862Sru@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 12572104862Sru@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff} 12573104862Sru@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff} 12574104862Sru@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff} 1257569626Sru@noindent 1257675584Sruprints @samp{\\} in GNU @code{troff}; each pair of input backslashes 1257769626Sruis turned into one output backslash and the resulting output backslashes 1257869626Sruare not interpreted as escape characters when they are reread. 1257969626Sru@acronym{UNIX} @code{troff} would interpret them as escape characters 1258069626Sruwhen they were reread and would end up printing one @samp{\}. The 1258169626Srucorrect way to obtain a printable backslash is to use the @code{\e} 1258275584Sruescape sequence: This always prints a single instance of the current 1258369626Sruescape character, regardless of whether or not it is used in a 1258475584Srudiversion; it also works in both GNU @code{troff} and @acronym{UNIX} 12585104862Sru@code{troff}.@footnote{To be completely independent of the current 12586104862Sruescape character, use @code{\(rs} which represents a reverse solidus 12587104862Sru(backslash) glyph.} To store, for some reason, an escape sequence in a 1258869626Srudiversion that will be interpreted when the diversion is reread, either 1258969626Sruuse the traditional @code{\!} transparent output facility, or, if this 1259069626Sruis unsuitable, the new @code{\?} escape sequence. 1259155839Sasmodai 12592104862Sru@xref{Diversions}, and @ref{Gtroff Internals}, for more information. 1259375584Sru 1259455839Sasmodai 1259569626Sru 1259669626Sru@c ===================================================================== 1259769626Sru@c ===================================================================== 1259869626Sru 1259975584Sru@node Preprocessors, Output Devices, gtroff Reference, Top 1260069626Sru@chapter Preprocessors 1260169626Sru@cindex preprocessors 1260269626Sru 1260369626SruThis chapter describes all preprocessors that come with @code{groff} or 1260469626Sruwhich are freely available. 1260569626Sru 1260669626Sru@menu 1260775584Sru* geqn:: 1260875584Sru* gtbl:: 1260975584Sru* gpic:: 1261075584Sru* ggrn:: 1261175584Sru* grap:: 1261275584Sru* grefer:: 1261375584Sru* gsoelim:: 1261469626Sru@end menu 1261569626Sru 1261669626Sru 1261769626Sru@c ===================================================================== 1261869626Sru 1261969626Sru@node geqn, gtbl, Preprocessors, Preprocessors 1262069626Sru@section @code{geqn} 12621104862Sru@cindex @code{eqn}, the program 12622104862Sru@cindex @code{geqn}, the program 1262355839Sasmodai 1262469626Sru@c XXX 1262555839Sasmodai 1262655839Sasmodai@menu 1262775584Sru* Invoking geqn:: 1262855839Sasmodai@end menu 1262955839Sasmodai 1263069626Sru@c --------------------------------------------------------------------- 1263169626Sru 1263255839Sasmodai@node Invoking geqn, , geqn, geqn 1263369626Sru@subsection Invoking @code{geqn} 1263455839Sasmodai@cindex invoking @code{geqn} 1263555839Sasmodai@cindex @code{geqn}, invoking 1263655839Sasmodai 1263769626Sru@c XXX 1263855839Sasmodai 1263955839Sasmodai 1264069626Sru@c ===================================================================== 1264169626Sru 1264269626Sru@node gtbl, gpic, geqn, Preprocessors 1264369626Sru@section @code{gtbl} 12644104862Sru@cindex @code{tbl}, the program 12645104862Sru@cindex @code{gtbl}, the program 1264655839Sasmodai 1264769626Sru@c XXX 1264855839Sasmodai 1264955839Sasmodai@menu 1265075584Sru* Invoking gtbl:: 1265155839Sasmodai@end menu 1265255839Sasmodai 1265369626Sru@c --------------------------------------------------------------------- 1265469626Sru 1265555839Sasmodai@node Invoking gtbl, , gtbl, gtbl 1265669626Sru@subsection Invoking @code{gtbl} 1265755839Sasmodai@cindex invoking @code{gtbl} 1265855839Sasmodai@cindex @code{gtbl}, invoking 1265955839Sasmodai 1266069626Sru@c XXX 1266155839Sasmodai 1266269626Sru 1266369626Sru@c ===================================================================== 1266469626Sru 1266569626Sru@node gpic, ggrn, gtbl, Preprocessors 1266669626Sru@section @code{gpic} 12667104862Sru@cindex @code{pic}, the program 12668104862Sru@cindex @code{gpic}, the program 1266955839Sasmodai 1267069626Sru@c XXX 1267155839Sasmodai 1267255839Sasmodai@menu 1267375584Sru* Invoking gpic:: 1267455839Sasmodai@end menu 1267555839Sasmodai 1267669626Sru@c --------------------------------------------------------------------- 1267769626Sru 1267855839Sasmodai@node Invoking gpic, , gpic, gpic 1267969626Sru@subsection Invoking @code{gpic} 1268055839Sasmodai@cindex invoking @code{gpic} 1268155839Sasmodai@cindex @code{gpic}, invoking 1268255839Sasmodai 1268369626Sru@c XXX 1268455839Sasmodai 1268555839Sasmodai 1268669626Sru@c ===================================================================== 1268769626Sru 1268869626Sru@node ggrn, grap, gpic, Preprocessors 1268969626Sru@section @code{ggrn} 12690104862Sru@cindex @code{grn}, the program 12691104862Sru@cindex @code{ggrn}, the program 1269269626Sru 1269369626Sru@c XXX 1269469626Sru 1269569626Sru@menu 1269675584Sru* Invoking ggrn:: 1269769626Sru@end menu 1269869626Sru 1269969626Sru@c --------------------------------------------------------------------- 1270069626Sru 1270169626Sru@node Invoking ggrn, , ggrn, ggrn 1270269626Sru@subsection Invoking @code{ggrn} 1270369626Sru@cindex invoking @code{ggrn} 1270469626Sru@cindex @code{ggrn}, invoking 1270569626Sru 1270669626Sru@c XXX 1270769626Sru 1270869626Sru 1270969626Sru@c ===================================================================== 1271069626Sru 1271169626Sru@node grap, grefer, ggrn, Preprocessors 1271269626Sru@section @code{grap} 12713104862Sru@cindex @code{grap}, the program 1271455839Sasmodai 1271569626SruA free implementation of @code{grap}, written by Ted Faber, 1271669626Sruis available as an extra package from the following address: 1271755839Sasmodai 1271869626Sru@display 1271969626Sru@url{http://www.lunabase.org/~faber/Vault/software/grap/} 1272069626Sru@end display 1272155839Sasmodai 1272269626Sru 1272369626Sru@c ===================================================================== 1272469626Sru 1272569626Sru@node grefer, gsoelim, grap, Preprocessors 1272669626Sru@section @code{grefer} 12727104862Sru@cindex @code{refer}, the program 12728104862Sru@cindex @code{grefer}, the program 1272955839Sasmodai 1273069626Sru@c XXX 1273155839Sasmodai 1273255839Sasmodai@menu 1273375584Sru* Invoking grefer:: 1273455839Sasmodai@end menu 1273555839Sasmodai 1273669626Sru@c --------------------------------------------------------------------- 1273769626Sru 1273855839Sasmodai@node Invoking grefer, , grefer, grefer 1273969626Sru@subsection Invoking @code{grefer} 1274055839Sasmodai@cindex invoking @code{grefer} 1274155839Sasmodai@cindex @code{grefer}, invoking 1274255839Sasmodai 1274369626Sru@c XXX 1274455839Sasmodai 1274555839Sasmodai 1274669626Sru@c ===================================================================== 1274769626Sru 1274869626Sru@node gsoelim, , grefer, Preprocessors 1274969626Sru@section @code{gsoelim} 12750104862Sru@cindex @code{soelim}, the program 12751104862Sru@cindex @code{gsoelim}, the program 1275255839Sasmodai 1275369626Sru@c XXX 1275455839Sasmodai 1275555839Sasmodai@menu 1275675584Sru* Invoking gsoelim:: 1275755839Sasmodai@end menu 1275855839Sasmodai 1275969626Sru@c --------------------------------------------------------------------- 1276069626Sru 1276155839Sasmodai@node Invoking gsoelim, , gsoelim, gsoelim 1276269626Sru@subsection Invoking @code{gsoelim} 1276355839Sasmodai@cindex invoking @code{gsoelim} 1276455839Sasmodai@cindex @code{gsoelim}, invoking 1276555839Sasmodai 1276669626Sru@c XXX 1276755839Sasmodai 1276855839Sasmodai 1276955839Sasmodai 1277069626Sru@c ===================================================================== 1277169626Sru@c ===================================================================== 1277255839Sasmodai 1277369626Sru@node Output Devices, File formats, Preprocessors, Top 1277469626Sru@chapter Output Devices 1277569626Sru@cindex output devices 1277669626Sru@cindex devices for output 1277755839Sasmodai 1277869626Sru@c XXX 1277969626Sru 1278055839Sasmodai@menu 1278175584Sru* Special Characters:: 1278275584Sru* grotty:: 1278375584Sru* grops:: 1278475584Sru* grodvi:: 1278575584Sru* grolj4:: 1278675584Sru* grolbp:: 1278775584Sru* grohtml:: 1278875584Sru* gxditview:: 1278955839Sasmodai@end menu 1279055839Sasmodai 1279169626Sru 1279269626Sru@c ===================================================================== 1279369626Sru 1279469626Sru@node Special Characters, grotty, Output Devices, Output Devices 1279555839Sasmodai@section Special Characters 1279655839Sasmodai@cindex special characters 1279755839Sasmodai@cindex characters, special 1279855839Sasmodai 1279969626Sru@c XXX 1280055839Sasmodai 1280169626Sru@xref{Font Files}. 1280255839Sasmodai 1280369626Sru 1280469626Sru@c ===================================================================== 1280569626Sru 1280669626Sru@node grotty, grops, Special Characters, Output Devices 1280755839Sasmodai@section @code{grotty} 12808104862Sru@cindex @code{grotty}, the program 1280955839Sasmodai 1281069626Sru@c XXX 1281155839Sasmodai 1281255839Sasmodai@menu 1281375584Sru* Invoking grotty:: 1281455839Sasmodai@end menu 1281555839Sasmodai 1281669626Sru@c --------------------------------------------------------------------- 1281769626Sru 1281855839Sasmodai@node Invoking grotty, , grotty, grotty 1281955839Sasmodai@subsection Invoking @code{grotty} 1282055839Sasmodai@cindex invoking @code{grotty} 1282155839Sasmodai@cindex @code{grotty}, invoking 1282255839Sasmodai 1282369626Sru@c XXX 1282455839Sasmodai 12825104862Sru@c The following is no longer true; fix and extend it. 1282655839Sasmodai 12827104862Sru@c @pindex less 12828104862Sru@c @cindex Teletype 12829104862Sru@c @cindex ISO 6249 SGR 12830104862Sru@c @cindex terminal control sequences 12831104862Sru@c @cindex control sequences, for terminals 12832104862Sru@c For TTY output devices, underlining is done by emitting sequences of 12833104862Sru@c @samp{_} and @samp{\b} (the backspace character) before the actual 12834104862Sru@c character. Literally, this is printing an underline character, then 12835104862Sru@c moving back one character position, and printing the actual character 12836104862Sru@c at the same position as the underline character (similar to a 12837104862Sru@c typewriter). Usually, a modern terminal can't interpret this (and the 12838104862Sru@c original Teletype machines for which this sequence was appropriate are 12839104862Sru@c no longer in use). You need a pager program like @code{less} which 12840104862Sru@c translates this into ISO 6429 SGR sequences to control terminals. 12841104862Sru 12842104862Sru 1284369626Sru@c ===================================================================== 1284469626Sru 1284569626Sru@node grops, grodvi, grotty, Output Devices 1284655839Sasmodai@section @code{grops} 12847104862Sru@cindex @code{grops}, the program 1284855839Sasmodai 1284969626Sru@c XXX 1285055839Sasmodai 1285155839Sasmodai@menu 1285275584Sru* Invoking grops:: 1285375584Sru* Embedding PostScript:: 1285455839Sasmodai@end menu 1285555839Sasmodai 1285669626Sru@c --------------------------------------------------------------------- 1285769626Sru 1285855839Sasmodai@node Invoking grops, Embedding PostScript, grops, grops 1285955839Sasmodai@subsection Invoking @code{grops} 1286055839Sasmodai@cindex invoking @code{grops} 1286155839Sasmodai@cindex @code{grops}, invoking 1286255839Sasmodai 1286369626Sru@c XXX 1286455839Sasmodai 1286569626Sru@c --------------------------------------------------------------------- 1286655839Sasmodai 1286755839Sasmodai@node Embedding PostScript, , Invoking grops, grops 1286869626Sru@subsection Embedding @sc{PostScript} 12869104862Sru@cindex embedding PostScript 12870104862Sru@cindex PostScript, embedding 1287155839Sasmodai 1287269626Sru@c XXX 1287355839Sasmodai 1287455839Sasmodai 1287569626Sru@c ===================================================================== 1287669626Sru 1287769626Sru@node grodvi, grolj4, grops, Output Devices 1287855839Sasmodai@section @code{grodvi} 12879104862Sru@cindex @code{grodvi}, the program 1288055839Sasmodai 1288169626Sru@c XXX 1288255839Sasmodai 1288355839Sasmodai@menu 1288475584Sru* Invoking grodvi:: 1288555839Sasmodai@end menu 1288655839Sasmodai 1288769626Sru@c --------------------------------------------------------------------- 1288869626Sru 1288955839Sasmodai@node Invoking grodvi, , grodvi, grodvi 1289055839Sasmodai@subsection Invoking @code{grodvi} 1289155839Sasmodai@cindex invoking @code{grodvi} 1289255839Sasmodai@cindex @code{grodvi}, invoking 1289355839Sasmodai 1289469626Sru@c XXX 1289555839Sasmodai 1289655839Sasmodai 1289769626Sru@c ===================================================================== 1289869626Sru 1289969626Sru@node grolj4, grolbp, grodvi, Output Devices 1290055839Sasmodai@section @code{grolj4} 12901104862Sru@cindex @code{grolj4}, the program 1290255839Sasmodai 1290369626Sru@c XXX 1290455839Sasmodai 1290555839Sasmodai@menu 1290675584Sru* Invoking grolj4:: 1290755839Sasmodai@end menu 1290855839Sasmodai 1290969626Sru@c --------------------------------------------------------------------- 1291069626Sru 1291155839Sasmodai@node Invoking grolj4, , grolj4, grolj4 1291255839Sasmodai@subsection Invoking @code{grolj4} 1291355839Sasmodai@cindex invoking @code{grolj4} 1291455839Sasmodai@cindex @code{grolj4}, invoking 1291555839Sasmodai 1291669626Sru@c XXX 1291755839Sasmodai 1291855839Sasmodai 1291969626Sru@c ===================================================================== 1292069626Sru 1292169626Sru@node grolbp, grohtml, grolj4, Output Devices 1292269626Sru@section @code{grolbp} 12923104862Sru@cindex @code{grolbp}, the program 1292469626Sru 1292569626Sru@c XXX 1292669626Sru 1292769626Sru@menu 1292875584Sru* Invoking grolbp:: 1292969626Sru@end menu 1293069626Sru 1293169626Sru@c --------------------------------------------------------------------- 1293269626Sru 1293369626Sru@node Invoking grolbp, , grolbp, grolbp 1293469626Sru@subsection Invoking @code{grolbp} 1293569626Sru@cindex invoking @code{grolbp} 1293669626Sru@cindex @code{grolbp}, invoking 1293769626Sru 1293869626Sru@c XXX 1293969626Sru 1294069626Sru 1294169626Sru@c ===================================================================== 1294269626Sru 1294369626Sru@node grohtml, gxditview, grolbp, Output Devices 1294455839Sasmodai@section @code{grohtml} 12945104862Sru@cindex @code{grohtml}, the program 1294655839Sasmodai 1294769626Sru@c XXX 1294855839Sasmodai 1294955839Sasmodai@menu 1295075584Sru* Invoking grohtml:: 12951104862Sru* grohtml specific registers and strings:: 1295255839Sasmodai@end menu 1295355839Sasmodai 1295469626Sru@c --------------------------------------------------------------------- 1295569626Sru 12956104862Sru@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml 1295755839Sasmodai@subsection Invoking @code{grohtml} 1295855839Sasmodai@cindex invoking @code{grohtml} 1295955839Sasmodai@cindex @code{grohtml}, invoking 1296055839Sasmodai 1296169626Sru@c XXX 1296255839Sasmodai 12963104862Sru@c --------------------------------------------------------------------- 1296455839Sasmodai 12965104862Sru@node grohtml specific registers and strings, , Invoking grohtml, grohtml 12966104862Sru@subsection @code{grohtml} specific registers and strings 12967104862Sru@cindex registers specific to @code{grohtml} 12968104862Sru@cindex strings specific to @code{grohtml} 12969104862Sru@cindex @code{grohtml}, registers and strings 12970104862Sru 12971104862Sru@DefmpregList {ps4html, grohtml} 12972104862Sru@DefstrListEnd {www-image-template, grohtml} 12973104862SruThe registers @code{ps4html} and @code{www-image-template} are defined 12974104862Sruby the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in 12975104862Sruthe @code{troff} input, marks up the inline equations and passes the 12976104862Sruresult firstly to 12977104862Sru 12978104862Sru@Example 12979104862Srutroff -Tps -rps4html=1 -dwww-image-template=@var{template} 12980104862Sru@endExample 12981104862Sru 12982104862Sru@noindent 12983104862Sruand secondly to 12984104862Sru 12985104862Sru@Example 12986104862Srutroff -Thtml 12987104862Sru@endExample 12988104862Sru 12989104862SruThe PostScript device is used to create all the image files, and the 12990104862Sruregister @code{ps4html} enables the macro sets to ignore floating 12991104862Srukeeps, footers, and headings. 12992104862Sru 12993104862SruThe register @code{www-image-template} is set to the user specified 12994104862Srutemplate name or the default name. 12995104862Sru@endDefmpreg 12996104862Sru 12997104862Sru 1299869626Sru@c ===================================================================== 1299969626Sru 1300069626Sru@node gxditview, , grohtml, Output Devices 1300155839Sasmodai@section @code{gxditview} 13002104862Sru@cindex @code{gxditview}, the program 1300355839Sasmodai 1300469626Sru@c XXX 1300555839Sasmodai 1300655839Sasmodai@menu 1300775584Sru* Invoking gxditview:: 1300855839Sasmodai@end menu 1300955839Sasmodai 1301069626Sru@c --------------------------------------------------------------------- 1301169626Sru 1301255839Sasmodai@node Invoking gxditview, , gxditview, gxditview 1301355839Sasmodai@subsection Invoking @code{gxditview} 1301455839Sasmodai@cindex invoking @code{gxditview} 1301555839Sasmodai@cindex @code{gxditview}, invoking 1301655839Sasmodai 1301769626Sru@c XXX 1301869626Sru@c X11's xditview 1301955839Sasmodai 1302055839Sasmodai 1302169626Sru 1302269626Sru@c ===================================================================== 1302369626Sru@c ===================================================================== 1302469626Sru 1302569626Sru@node File formats, Installation, Output Devices, Top 1302655839Sasmodai@chapter File formats 1302755839Sasmodai@cindex file formats 1302855839Sasmodai@cindex formats, file 1302955839Sasmodai 13030104862SruAll files read and written by @code{gtroff} are text files. The 13031104862Srufollowing two sections describe their format. 1303255839Sasmodai 1303355839Sasmodai@menu 1303475584Sru* gtroff Output:: 1303575584Sru* Font Files:: 1303655839Sasmodai@end menu 1303755839Sasmodai 1303869626Sru 1303969626Sru@c ===================================================================== 1304069626Sru 1304155839Sasmodai@node gtroff Output, Font Files, File formats, File formats 1304255839Sasmodai@section @code{gtroff} Output 13043104862Sru@cindex @code{gtroff}, output 1304455839Sasmodai@cindex output, @code{gtroff} 1304555839Sasmodai 13046104862SruThis section describes the intermediate output format of GNU 13047104862Sru@code{troff}. This output is produced by a run of @code{gtroff} 13048104862Srubefore it is fed into a device postprocessor program. 1304955839Sasmodai 13050104862SruAs @code{groff} is a wrapper program around @code{gtroff} that 13051104862Sruautomatically calls a postprocessor, this output does not show up 13052104862Srunormally. This is why it is called @dfn{intermediate}. 13053104862Sru@code{groff} provides the option @option{-Z} to inhibit postprocessing, 13054104862Srusuch that the produced intermediate output is sent to standard output 13055104862Srujust like calling @code{gtroff} manually. 13056104862Sru 13057104862Sru@cindex troff output 13058104862Sru@cindex output, troff 13059104862Sru@cindex intermediate output 13060104862Sru@cindex output, intermediate 13061104862SruHere, the term @dfn{troff output} describes what is output by 13062104862Sru@code{gtroff}, while @dfn{intermediate output} refers to the language 13063104862Sruthat is accepted by the parser that prepares this output for the 13064104862Srupostprocessors. This parser is smarter on whitespace and implements 13065104862Sruobsolete elements for compatibility, otherwise both formats are the 13066104862Srusame.@footnote{The parser and postprocessor for intermediate output 13067104862Srucan be found in the file@* 13068104862Sru@file{@var{groff-source-dir}/src/libs/libdriver/input.cc}.} 13069104862Sru 13070104862SruThe main purpose of the intermediate output concept is to facilitate 13071104862Sruthe development of postprocessors by providing a common programming 13072104862Sruinterface for all devices. It has a language of its own that is 13073104862Srucompletely different from the @code{gtroff} language. While the 13074104862Sru@code{gtroff} language is a high-level programming language for text 13075104862Sruprocessing, the intermediate output language is a kind of low-level 13076104862Sruassembler language by specifying all positions on the page for writing 13077104862Sruand drawing. 13078104862Sru 13079104862SruThe intermediate output produced by @code{gtroff} is fairly readable, 13080104862Sruwhile output from @acronym{AT&T} @code{troff} is rather hard to 13081104862Sruunderstand because of strange habits that are still supported, but not 13082104862Sruused any longer by @code{gtroff}. 13083104862Sru 1308469626Sru@menu 13085104862Sru* Language Concepts:: 13086104862Sru* Command Reference:: 13087104862Sru* Intermediate Output Examples:: 13088104862Sru* Output Language Compatibility:: 1308969626Sru@end menu 1309055839Sasmodai 1309169626Sru@c --------------------------------------------------------------------- 1309255839Sasmodai 13093104862Sru@node Language Concepts, Command Reference, gtroff Output, gtroff Output 13094104862Sru@subsection Language Concepts 1309569626Sru 13096104862SruDuring the run of @code{gtroff}, the input data is cracked down to the 13097104862Sruinformation on what has to be printed at what position on the intended 13098104862Srudevice. So the language of the intermediate output format can be quite 13099104862Srusmall. Its only elements are commands with and without arguments. 13100104862SruIn this section, the term @dfn{command} always refers to the intermediate 13101104862Sruoutput language, and never to the @code{gtroff} language used for document 13102104862Sruformatting. There are commands for positioning and text writing, for drawing, and 13103104862Srufor device controlling. 1310469626Sru 13105104862Sru@menu 13106104862Sru* Separation:: 13107104862Sru* Argument Units:: 13108104862Sru* Document Parts:: 13109104862Sru@end menu 1311055839Sasmodai 13111104862Sru@node Separation, Argument Units, Language Concepts, Language Concepts 13112104862Sru@subsubsection Separation 1311355839Sasmodai 13114104862Sru@acronym{AT&T} @code{troff} output has strange requirements on whitespace. 13115104862SruThe @code{gtroff} output parser, however, is smart about whitespace by 13116104862Srumaking it maximally optional. The whitespace characters, i.e., the 13117104862Srutab, space, and newline characters, always have a syntactical meaning. 13118104862SruThey are never printable because spacing within the output is always 13119104862Srudone by positioning commands. 1312055839Sasmodai 13121104862SruAny sequence of space or tab characters is treated as a single 13122104862Sru@dfn{syntactical space}. It separates commands and arguments, but is 13123104862Sruonly required when there would occur a clashing between the command code 13124104862Sruand the arguments without the space. Most often, this happens when 13125104862Sruvariable-length command names, arguments, argument lists, or command 13126104862Sruclusters meet. Commands and arguments with a known, fixed length need 13127104862Srunot be separated by syntactical space. 13128104862Sru 13129104862SruA line break is a syntactical element, too. Every command argument can be 13130104862Srufollowed by whitespace, a comment, or a newline character. Thus a 13131104862Sru@dfn{syntactical line break} is defined to consist of optional 13132104862Srusyntactical space that is optionally followed by a comment, and a 13133104862Srunewline character. 13134104862Sru 13135104862SruThe normal commands, those for positioning and text, consist of a 13136104862Srusingle letter taking a fixed number of arguments. For historical reasons, 13137104862Sruthe parser allows to stack such commands on the same line, but 13138104862Srufortunately, in @code{gtroff}'s intermediate output, every command with 13139104862Sruat least one argument is followed by a line break, thus providing 13140104862Sruexcellent readability. 13141104862Sru 13142104862SruThe other commands -- those for drawing and device controlling -- 13143104862Sruhave a more complicated structure; some recognize long command names, 13144104862Sruand some take a variable number of arguments. So all @samp{D} and 13145104862Sru@samp{x} commands were designed to request a syntactical line break 13146104862Sruafter their last argument. Only one command, @w{@samp{x X}}, 13147104862Sruhas an argument that can stretch over several lines; all other 13148104862Srucommands must have all of their arguments on the same line as the 13149104862Srucommand, i.e., the arguments may not be splitted by a line break. 13150104862Sru 13151104862SruEmpty lines (these are lines containing only space and/or a comment), can 13152104862Sruoccur everywhere. They are just ignored. 13153104862Sru 13154104862Sru@node Argument Units, Document Parts, Separation, Language Concepts 13155104862Sru@subsubsection Argument Units 13156104862Sru 13157104862SruSome commands take integer arguments that are assumed to represent 13158104862Sruvalues in a measurement unit, but the letter for the corresponding 13159104862Sruscale indicator is not written with the output command arguments. 13160104862SruMost commands assume the scale indicator @samp{u}, the basic unit of 13161104862Sruthe device, some use @samp{z}, the scaled point unit of the device, 13162104862Sruwhile others, such as the color commands, expect plain integers. 13163104862Sru 13164104862SruNote that single characters can have the eighth bit set, as can the 13165104862Srunames of fonts and special characters. The names of characters and 13166104862Srufonts can be of arbitrary length. A character that is to be printed 13167104862Sruwill always be in the current font. 13168104862Sru 13169104862SruA string argument is always terminated by the next whitespace 13170104862Srucharacter (space, tab, or newline); an embedded @samp{#} character is 13171104862Sruregarded as part of the argument, not as the beginning of a comment 13172104862Srucommand. An integer argument is already terminated by the next 13173104862Srunon-digit character, which then is regarded as the first character of 13174104862Sruthe next argument or command. 13175104862Sru 13176104862Sru@node Document Parts, , Argument Units, Language Concepts 13177104862Sru@subsubsection Document Parts 13178104862Sru 13179104862SruA correct intermediate output document consists of two parts, the 13180104862Sru@dfn{prologue} and the @dfn{body}. 13181104862Sru 13182104862SruThe task of the prologue is to set the general device parameters 13183104862Sruusing three exactly specified commands. @code{gtroff}'s prologue 13184104862Sruis guaranteed to consist of the following three lines (in that order): 13185104862Sru 13186104862Sru@Example 13187104862Srux T @var{device} 13188104862Srux res @var{n} @var{h} @var{v} 13189104862Srux init 13190104862Sru@endExample 13191104862Sru 13192104862Sru@noindent 13193104862Sruwith the arguments set as outlined in @ref{Device Control Commands}. 13194104862SruNote that the parser for the intermediate output format is able to 13195104862Sruswallow additional whitespace and comments as well even in the 13196104862Sruprologue. 13197104862Sru 13198104862SruThe body is the main section for processing the document data. 13199104862SruSyntactically, it is a sequence of any commands different from the 13200104862Sruones used in the prologue. Processing is terminated as soon as the 13201104862Srufirst @w{@samp{x stop}} command is encountered; the last line of any 13202104862Sru@code{gtroff} intermediate output always contains such a command. 13203104862Sru 13204104862SruSemantically, the body is page oriented. A new page is started by a 13205104862Sru@samp{p} command. Positioning, writing, and drawing commands are 13206104862Srualways done within the current page, so they cannot occur before the 13207104862Srufirst @samp{p} command. Absolute positioning (by the @samp{H} and 13208104862Sru@samp{V} commands) is done relative to the current page; all other 13209104862Srupositioning is done relative to the current location within this page. 13210104862Sru 13211104862Sru@c --------------------------------------------------------------------- 13212104862Sru 13213104862Sru@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output 13214104862Sru@subsection Command Reference 13215104862Sru 13216104862SruThis section describes all intermediate output commands, both from 13217104862Sru@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions. 13218104862Sru 13219104862Sru@menu 13220104862Sru* Comment Command:: 13221104862Sru* Simple Commands:: 13222104862Sru* Graphics Commands:: 13223104862Sru* Device Control Commands:: 13224104862Sru* Obsolete Command:: 13225104862Sru@end menu 13226104862Sru 13227104862Sru@node Comment Command, Simple Commands, Command Reference, Command Reference 13228104862Sru@subsubsection Comment Command 13229104862Sru 1323055839Sasmodai@table @code 13231104862Sru@item #@var{anything}@angles{end of line} 13232104862SruA comment. Ignore any characters from the @samp{#} character up to 13233104862Sruthe next newline character. 1323469626Sru 13235104862SruThis command is the only possibility for commenting in the intermediate 13236104862Sruoutput. Each comment can be preceded by arbitrary syntactical space; 13237104862Sruevery command can be terminated by a comment. 13238104862Sru@end table 1323969626Sru 13240104862Sru@node Simple Commands, Graphics Commands, Comment Command, Command Reference 13241104862Sru@subsubsection Simple Commands 1324269626Sru 13243104862SruThe commands in this subsection have a command code consisting of a 13244104862Srusingle character, taking a fixed number of arguments. Most of them 13245104862Sruare commands for positioning and text writing. These commands are 13246104862Srusmart about whitespace. Optionally, syntactical space can be inserted 13247104862Srubefore, after, and between the command letter and its arguments. 13248104862SruAll of these commands are stackable, i.e., they can be preceded by 13249104862Sruother simple commands or followed by arbitrary other commands on the 13250104862Srusame line. A separating syntactical space is only necessary when two 13251104862Sruinteger arguments would clash or if the preceding argument ends with a 13252104862Srustring argument. 1325369626Sru 13254104862Sru@table @code 13255104862Sru@ignore 13256104862Sru.if (\n[@USE_ENV_STACK] == 1) \{\ 13257104862Sru.command { 13258104862SruOpen a new environment by copying the actual device configuration data 13259104862Sruto the environment stack. 13260104862Sru. 13261104862SruThe current environment is setup by the device specification and 13262104862Srumanipulated by the setting commands. 13263104862Sru. 13264104862Sru. 13265104862Sru.command } 13266104862SruClose the actual environment (opened by a preceding 13267104862Sru.BR { \~command) 13268104862Sruand restore the previous environment from the environment 13269104862Srustack as the actual device configuration data. 13270104862Sru. 13271104862Sru\} \" endif @USE_ENV_STACK 13272104862Sru@end ignore 1327369626Sru 13274104862Sru@item C @var{xxx}@angles{whitespace} 13275104862SruPrint a special character named @var{xxx}. The trailing 13276104862Srusyntactical space or line break is necessary to allow glyph names 13277104862Sruof arbitrary length. The glyph is printed at the current print 13278104862Sruposition; the glyph's size is read from the font file. The print 13279104862Sruposition is not changed. 1328069626Sru 13281104862Sru@item c @var{g} 13282104862SruPrint glyph@w{ }@var{g} at the current print position;@footnote{@samp{c} 13283104862Sruis actually a misnomer since it outputs a glyph.} the glyph's size is 13284104862Sruread from the font file. The print position is not changed. 1328569626Sru 13286104862Sru@item f @var{n} 13287104862SruSet font to font number@w{ }@var{n} (a non-negative integer). 1328855839Sasmodai 13289104862Sru@item H @var{n} 13290104862SruMove right to the absolute vertical position@w{ }@var{n} (a 13291104862Srunon-negative integer in basic units @samp{u} relative to left edge 13292104862Sruof current page. 1329369626Sru 13294104862Sru@item h @var{n} 13295104862SruMove @var{n} (a non-negative integer) basic units @samp{u} horizontally 13296104862Sruto the right. The original @acronym{UNIX} troff manual allows negative 13297104862Sruvalues for @var{n} also, but @code{gtroff} doesn't use this. 1329855839Sasmodai 13299104862Sru@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]} 13300104862SruSet the color for text (glyphs), line drawing, and the outline of 13301104862Srugraphic objects using different color schemes; the analoguous command 13302104862Srufor the filling color of graphic objects is @samp{DF}. The color 13303104862Srucomponents are specified as integer arguments between 0 and 65536. 13304104862SruThe number of color components and their meaning vary for the 13305104862Srudifferent color schemes. These commands are generated by 13306104862Sru@code{gtroff}'s escape sequence @code{\m}. No position changing. 13307104862SruThese commands are a @code{gtroff} extension. 1330869626Sru 13309104862Sru@table @code 13310104862Sru@item mc @var{cyan} @var{magenta} @var{yellow} 13311104862SruSet color using the CMY color scheme, having the 3@w{ }color components 13312104862Sru@var{cyan}, @var{magenta}, and @var{yellow}. 1331369626Sru 13314104862Sru@item md 13315104862SruSet color to the default color value (black in most cases). 13316104862SruNo component arguments. 1331769626Sru 13318104862Sru@item mg @var{gray} 13319104862SruSet color to the shade of gray given by the argument, an integer 13320104862Srubetween 0 (black) and 65536 (white). 1332169626Sru 13322104862Sru@item mk @var{cyan} @var{magenta} @var{yellow} @var{black} 13323104862SruSet color using the CMYK color scheme, having the 4@w{ }color components 13324104862Sru@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. 1332569626Sru 13326104862Sru@item mr @var{red} @var{green} @var{blue} 13327104862SruSet color using the RGB color scheme, having the 3@w{ }color components 13328104862Sru@var{red}, @var{green}, and @var{blue}. 13329104862Sru 1333055839Sasmodai@end table 1333155839Sasmodai 13332104862Sru@item N @var{n} 13333104862SruPrint glyph with index@w{ }@var{n} (a non-negative integer) of the 13334104862Srucurrent font. This command is a @code{gtroff} extension. 1333569626Sru 13336104862Sru@item n @var{b} @var{a} 13337104862SruInform the device about a line break, but no positioning is done by 13338104862Sruthis command. In @acronym{AT&T} @code{troff}, the integer arguments 13339104862Sru@var{b} and@w{ }@var{a} informed about the space before and after the 13340104862Srucurrent line to make the intermediate output more human readable 13341104862Sruwithout performing any action. In @code{groff}, they are just ignored, but 13342104862Sruthey must be provided for compatibility reasons. 1334355839Sasmodai 13344104862Sru@item p @var{n} 13345104862SruBegin a new page in the outprint. The page number is set 13346104862Sruto@w{ }@var{n}. This page is completely independent of pages formerly 13347104862Sruprocessed even if those have the same page number. The vertical 13348104862Sruposition on the outprint is automatically set to@w{ }0. All 13349104862Srupositioning, writing, and drawing is always done relative to a page, 13350104862Sruso a @samp{p} command must be issued before any of these commands. 1335155839Sasmodai 13352104862Sru@item s @var{n} 13353104862SruSet point size to @var{n}@w{ }scaled points (this is unit @samp{z}). 13354104862Sru@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. 13355104862Sru@xref{Output Language Compatibility}. 1335655839Sasmodai 13357104862Sru@item t @var{xxx}@angles{whitespace} 13358104862Sru@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace} 13359104862SruPrint a word, i.e., a sequence of characters @var{xxx} representing 13360104862Sruoutput glyphs which names are single characters, terminated by 13361104862Srua space character or a line break; an optional second integer argument 13362104862Sruis ignored (this allows the formatter to generate an even number of 13363104862Sruarguments). The first glyph should be printed at the current 13364104862Sruposition, the current horizontal position should then be increased by 13365104862Sruthe width of the first glyph, and so on for each glyph. 13366104862SruThe widths of the glyphs are read from the font file, scaled for the 13367104862Srucurrent point size, and rounded to a multiple of the horizontal 13368104862Sruresolution. Special characters cannot be printed using this command 13369104862Sru(use the @samp{C} command for special characters). This command is a 13370104862Sru@code{gtroff} extension; it is only used for devices whose @file{DESC} 13371104862Srufile contains the @code{tcommand} keyword (@pxref{DESC File Format}). 13372104862Sru 13373104862Sru@item u @var{n} @var{xxx}@angles{whitespace} 13374104862SruPrint word with track kerning. This is the same as the @samp{t} 13375104862Srucommand except that after printing each glyph, the current 13376104862Sruhorizontal position is increased by the sum of the width of that 13377104862Sruglyph and@w{ }@var{n} (an integer in basic units @samp{u}). 13378104862SruThis command is a @code{gtroff} extension; it is only used for devices 13379104862Sruwhose @file{DESC} file contains the @code{tcommand} keyword 13380104862Sru(@pxref{DESC File Format}). 13381104862Sru 13382104862Sru@item V @var{n} 13383104862SruMove down to the absolute vertical position@w{ }@var{n} (a 13384104862Srunon-negative integer in basic units @samp{u}) relative to upper edge 13385104862Sruof current page. 13386104862Sru 13387104862Sru@item v @var{n} 13388104862SruMove @var{n}@w{ }basic units @samp{u} down (@var{n} is a non-negative 13389104862Sruinteger). The original @acronym{UNIX} troff manual allows negative 13390104862Sruvalues for @var{n} also, but @code{gtroff} doesn't use this. 13391104862Sru 13392104862Sru@item w 13393104862SruInforms about a paddable white space to increase readability. 13394104862SruThe spacing itself must be performed explicitly by a move command. 13395104862Sru 13396104862Sru@end table 13397104862Sru 13398104862Sru@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference 13399104862Sru@subsubsection Graphics Commands 13400104862Sru 13401104862SruEach graphics or drawing command in the intermediate output starts 13402104862Sruwith the letter @samp{D}, followed by one or two characters that 13403104862Sruspecify a subcommand; this is followed by a fixed or variable number 13404104862Sruof integer arguments that are separated by a single space character. 13405104862SruA @samp{D} command may not be followed by another command on the same line 13406104862Sru(apart from a comment), so each @samp{D} command is terminated by a 13407104862Srusyntactical line break. 13408104862Sru 13409104862Sru@code{gtroff} output follows the classical spacing rules (no space 13410104862Srubetween command and subcommand, all arguments are preceded by a 13411104862Srusingle space character), but the parser allows optional space between 13412104862Sruthe command letters and makes the space before the first argument 13413104862Sruoptional. As usual, each space can be any sequence of tab and space 13414104862Srucharacters. 13415104862Sru 13416104862SruSome graphics commands can take a variable number of arguments. 13417104862SruIn this case, they are integers representing a size measured in basic 13418104862Sruunits @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{}, 13419104862Sru@var{hn} stand for horizontal distances where positive means right, 13420104862Srunegative left. The arguments called @var{v1}, @var{v2}, @dots{}, 13421104862Sru@var{vn} stand for vertical distances where positive means down, 13422104862Srunegative up. All these distances are offsets relative to the current 13423104862Srulocation. 13424104862Sru 13425104862SruUnless indicated otherwise, each graphics command directly corresponds 13426104862Sruto a similar @code{gtroff} @code{\D} escape sequence. @xref{Drawing 13427104862SruRequests}. 13428104862Sru 13429104862SruUnknown @samp{D} commands are assumed to be device-specific. 13430104862SruIts arguments are parsed as strings; the whole information is then 13431104862Srusent to the postprocessor. 13432104862Sru 13433104862SruIn the following command reference, the syntax element 13434104862Sru@angles{line break} means a syntactical line break as defined above. 13435104862Sru 1343655839Sasmodai@table @code 13437104862Sru@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 13438104862SruDraw B-spline from current position to offset (@var{h1},@var{v1}), 13439104862Sruthen to offset (@var{h2},@var{v2}), if given, etc.@: up to 13440104862Sru(@var{hn},@var{vn}). This command takes a variable number of argument 13441104862Srupairs; the current position is moved to the terminal point of the drawn 13442104862Srucurve. 1344369626Sru 13444104862Sru@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break} 13445104862SruDraw arc from current position to 13446104862Sru(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at 13447104862Sru(@var{h1},@var{v1}); then move the current position to the final point 13448104862Sruof the arc. 1344969626Sru 13450104862Sru@item DC @var{d}@angles{line break} 13451104862Sru@itemx DC @var{d} @var{dummy-arg}@angles{line break} 13452104862SruDraw a solid circle using the current fill color with 13453104862Srudiameter@w{ }@var{d} (integer in basic units @samp{u}) with leftmost 13454104862Srupoint at the current position; then move the current position to the 13455104862Srurightmost point of the circle. An optional second integer argument is 13456104862Sruignored (this allows the formatter to generate an even number of 13457104862Sruarguments). This command is a @code{gtroff} extension. 1345869626Sru 13459104862Sru@item Dc @var{d}@angles{line break} 13460104862SruDraw circle line with diameter@w{ }@var{d} (integer in basic units 13461104862Sru@samp{u}) with leftmost point at the current position; then move the 13462104862Srucurrent position to the rightmost point of the circle. 13463104862Sru 13464104862Sru@item DE @var{h} @var{v}@angles{line break} 13465104862SruDraw a solid ellipse in the current fill color with a horizontal 13466104862Srudiameter of@w{ }@var{h} and a vertical diameter of@w{ }@var{v} (both 13467104862Sruintegers in basic units @samp{u}) with the leftmost point at the 13468104862Srucurrent position; then move to the rightmost point of the ellipse. 13469104862SruThis command is a @code{gtroff} extension. 13470104862Sru 13471104862Sru@item De @var{h} @var{v}@angles{line break} 13472104862SruDraw an outlined ellipse with a horizontal diameter of@w{ }@var{h} 13473104862Sruand a vertical diameter of@w{ }@var{v} (both integers in basic units 13474104862Sru@samp{u}) with the leftmost point at current position; then move to 13475104862Sruthe rightmost point of the ellipse. 13476104862Sru 13477104862Sru@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break} 13478104862SruSet fill color for solid drawing objects using different color 13479104862Sruschemes; the analoguous command for setting the color of text, line 13480104862Srugraphics, and the outline of graphic objects is @samp{m}. 13481104862SruThe color components are specified as integer arguments between 0 and 13482104862Sru65536. The number of color components and their meaning vary for the 13483104862Srudifferent color schemes. These commands are generated by @code{gtroff}'s 13484104862Sruescape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other 13485104862Srucorresponding graphics commands). No position changing. This command 13486104862Sruis a @code{gtroff} extension. 13487104862Sru 13488104862Sru@table @code 13489104862Sru@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} 13490104862SruSet fill color for solid drawing objects using the CMY color scheme, 13491104862Sruhaving the 3@w{ }color components @var{cyan}, @var{magenta}, and 13492104862Sru@var{yellow}. 13493104862Sru 13494104862Sru@item DFd@angles{line break} 13495104862SruSet fill color for solid drawing objects to the default fill color value 13496104862Sru(black in most cases). No component arguments. 13497104862Sru 13498104862Sru@item DFg @var{gray}@angles{line break} 13499104862SruSet fill color for solid drawing objects to the shade of gray given by 13500104862Sruthe argument, an integer between 0 (black) and 65536 (white). 13501104862Sru 13502104862Sru@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} 13503104862SruSet fill color for solid drawing objects using the CMYK color scheme, 13504104862Sruhaving the 4@w{ }color components @var{cyan}, @var{magenta}, @var{yellow}, 13505104862Sruand @var{black}. 13506104862Sru 13507104862Sru@item DFr @var{red} @var{green} @var{blue}@angles{line break} 13508104862SruSet fill color for solid drawing objects using the RGB color scheme, 13509104862Sruhaving the 3@w{ }color components @var{red}, @var{green}, and @var{blue}. 13510104862Sru 1351155839Sasmodai@end table 1351255839Sasmodai 13513104862Sru@item Df @var{n}@angles{line break} 13514104862SruThe argument@w{ }@var{n} must be an integer in the range @math{-32767} 13515104862Sruto 32767. 1351655839Sasmodai 13517104862Sru@table @asis 13518104862Sru@item @math{0 @LE @var{n} @LE 1000} 13519104862SruSet the color for filling solid drawing objects to a shade of gray, 13520104862Sruwhere 0 corresponds to solid white, 1000 (the default) to solid black, 13521104862Sruand values in between to intermediate shades of gray; this is 13522104862Sruobsoleted by command @samp{DFg}. 13523104862Sru 13524104862Sru@item @math{@var{n} @LT 0} or @math{@var{n} @LT 1000} 13525104862SruSet the filling color to the color that is currently being used for 13526104862Sruthe text and the outline, see command @samp{m}. For example, the 13527104862Srucommand sequence 13528104862Sru 1352975584Sru@Example 13530104862Srumg 0 0 65536 13531104862SruDf -1 1353275584Sru@endExample 1353355839Sasmodai 1353469626Sru@noindent 13535104862Srusets all colors to blue. 1353655839Sasmodai 13537104862Sru@end table 1353869626Sru 1353969626Sru@noindent 13540104862SruNo position changing. This command is a @code{gtroff} extension. 1354169626Sru 13542104862Sru@item Dl @var{h} @var{v}@angles{line break} 13543104862SruDraw line from current position to offset (@var{h},@var{v}) (integers 13544104862Sruin basic units @samp{u}); then set current position to the end of the 13545104862Srudrawn line. 1354669626Sru 13547104862Sru@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 13548104862SruDraw a polygon line from current position to offset (@var{h1},@var{v1}), 13549104862Srufrom there to offset (@var{h2},@var{v2}), etc.@: up to offset 13550104862Sru(@var{hn},@var{vn}), and from there back to the starting position. 13551104862SruFor historical reasons, the position is changed by adding the sum of 13552104862Sruall arguments with odd index to the actual horizontal position and the 13553104862Srueven ones to the vertical position. Although this doesn't make sense 13554104862Sruit is kept for compatibility. 1355569626Sru@ignore 13556104862SruAs the polygon is closed, the end of drawing is the starting point, so 13557104862Sruthe position doesn't change. 1355869626Sru@end ignore 13559104862SruThis command is a @code{gtroff} extension. 1356055839Sasmodai 13561104862Sru@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 13562104862SruDraw a solid polygon in the current fill color rather than an outlined 13563104862Srupolygon, using the same arguments and positioning as the corresponding 13564104862Sru@samp{Dp} command. 13565104862Sru@ignore 13566104862SruNo position changing. 13567104862Sru@end ignore 13568104862SruThis command is a @code{gtroff} extension. 1356969626Sru 13570104862Sru@item Dt @var{n}@angles{line break} 13571104862SruSet the current line thickness to@w{ }@var{n} (an integer in basic 13572104862Sruunits @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the 13573104862Srusmallest available line thickness; if @math{@var{n}<0} set the line 13574104862Sruthickness proportional to the point size (this is the default before 13575104862Sruthe first @samp{Dt} command was specified). For historical reasons, 13576104862Sruthe horizontal position is changed by adding the argument to the actual 13577104862Sruhorizontal position, while the vertical position is not changed. 13578104862SruAlthough this doesn't make sense it is kept for compatibility. 13579104862Sru@ignore 13580104862SruNo position changing. 13581104862Sru@end ignore 13582104862SruThis command is a @code{gtroff} extension. 1358355839Sasmodai 13584104862Sru@end table 1358555839Sasmodai 13586104862Sru@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference 13587104862Sru@subsubsection Device Control Commands 1358869626Sru 13589104862SruEach device control command starts with the letter @samp{x}, 13590104862Srufollowed by a space character (optional or arbitrary space or tab in 13591104862Sru@code{gtroff}) and a subcommand letter or word; each argument (if any) 13592104862Srumust be preceded by a syntactical space. All @samp{x} commands are 13593104862Sruterminated by a syntactical line break; no device control command can 13594104862Srube followed by another command on the same line (except a comment). 13595104862Sru 13596104862SruThe subcommand is basically a single letter, but to increase 13597104862Srureadability, it can be written as a word, i.e., an arbitrary sequence 13598104862Sruof characters terminated by the next tab, space, or newline character. 13599104862SruAll characters of the subcommand word but the first are simply ignored. 13600104862SruFor example, @code{gtroff} outputs the initialization command 13601104862Sru@w{@samp{x i}} as @w{@samp{x init}} and the resolution command 13602104862Sru@w{@samp{x r}} as @w{@samp{x res}}. 13603104862Sru 13604104862SruIn the following, the syntax element @angles{line break} means a 13605104862Srusyntactical line break (@pxref{Separation}). 13606104862Sru 1360755839Sasmodai@table @code 13608104862Sru@item xF @var{name}@angles{line break} 13609104862SruThe @samp{F} stands for @var{Filename}. 1361069626Sru 13611104862SruUse @var{name} as the intended name for the current file in error 13612104862Srureports. This is useful for remembering the original file name when 13613104862Sru@code{gtroff} uses an internal piping mechanism. The input file is 13614104862Srunot changed by this command. This command is a @code{gtroff} extension. 1361569626Sru 13616104862Sru@item xf @var{n} @var{s}@angles{line break} 13617104862SruThe @samp{f} stands for @var{font}. 1361869626Sru 13619104862SruMount font position@w{ }@var{n} (a non-negative integer) with font 13620104862Srunamed@w{ }@var{s} (a text word). @xref{Font Positions}. 1362169626Sru 13622104862Sru@item xH @var{n}@angles{line break} 13623104862SruThe @samp{H} stands for @var{Height}. 1362469626Sru 13625104862SruSet glyph height to@w{ }@var{n} (a positive integer in scaled 13626104862Srupoints @samp{z}). @acronym{AT&T} @code{troff} uses the unit points 13627104862Sru(@samp{p}) instead. @xref{Output Language Compatibility}. 13628104862Sru 13629104862Sru@item xi@angles{line break} 13630104862SruThe @samp{i} stands for @var{init}. 13631104862Sru 13632104862SruInitialize device. This is the third command of the prologue. 13633104862Sru 13634104862Sru@item xp@angles{line break} 13635104862SruThe @samp{p} stands for @var{pause}. 13636104862Sru 13637104862SruParsed but ignored. The original @acronym{UNIX} troff manual writes 13638104862Sru 13639104862Sru@display 13640104862Srupause device, can be restarted 13641104862Sru@end display 13642104862Sru 13643104862Sru@item xr @var{n} @var{h} @var{v}@angles{line break} 13644104862SruThe @samp{r} stands for @var{resolution}. 13645104862Sru 13646104862SruResolution is@w{ }@var{n}, while @var{h} is the minimal horizontal 13647104862Srumotion, and @var{v} the minimal vertical motion possible with this 13648104862Srudevice; all arguments are positive integers in basic units @samp{u} 13649104862Sruper inch. This is the second command of the prologue. 13650104862Sru 13651104862Sru@item xS @var{n}@angles{line break} 13652104862SruThe @samp{S} stands for @var{Slant}. 13653104862Sru 13654104862SruSet slant to@w{ }@var{n} (an integer in basic units @samp{u}). 13655104862Sru 13656104862Sru@item xs@angles{line break} 13657104862SruThe @samp{s} stands for @var{stop}. 13658104862Sru 13659104862SruTerminates the processing of the current file; issued as the last 13660104862Srucommand of any intermediate troff output. 13661104862Sru 13662104862Sru@item xt@angles{line break} 13663104862SruThe @samp{t} stands for @var{trailer}. 13664104862Sru 13665104862SruGenerate trailer information, if any. In @var{gtroff}, this is 13666104862Sruactually just ignored. 13667104862Sru 13668104862Sru@item xT @var{xxx}@angles{line break} 13669104862SruThe @samp{T} stands for @var{Typesetter}. 13670104862Sru 13671104862SruSet name of device to word @var{xxx}, a sequence of characters ended 13672104862Sruby the next white space character. The possible device names coincide 13673104862Sruwith those from the @code{groff} @option{-T} option. This is the first 13674104862Srucommand of the prologue. 13675104862Sru 13676104862Sru@item xu @var{n}@angles{line break} 13677104862SruThe @samp{u} stands for @var{underline}. 13678104862Sru 13679104862SruConfigure underlining of spaces. If @var{n} is@w{ }1, start 13680104862Sruunderlining of spaces; if @var{n} is@w{ }0, stop underlining of spaces. 13681104862SruThis is needed for the @code{cu} request in nroff mode and is ignored 13682104862Sruotherwise. This command is a @code{gtroff} extension. 13683104862Sru 13684104862Sru@item xX @var{anything}@angles{line break} 13685104862SruThe @samp{x} stands for @var{X-escape}. 13686104862Sru 13687104862SruSend string @var{anything} uninterpreted to the device. If the line 13688104862Srufollowing this command starts with a @samp{+} character this line is 13689104862Sruinterpreted as a continuation line in the following sense. The 13690104862Sru@samp{+} is ignored, but a newline character is sent instead to the 13691104862Srudevice, the rest of the line is sent uninterpreted. The same applies 13692104862Sruto all following lines until the first character of a line is not a 13693104862Sru@samp{+} character. This command is generated by the @code{gtroff} 13694104862Sruescape sequence @code{\X}. The line-continuing feature is a 13695104862Sru@code{gtroff} extension. 13696104862Sru 1369755839Sasmodai@end table 1369855839Sasmodai 13699104862Sru@node Obsolete Command, , Device Control Commands, Command Reference 13700104862Sru@subsubsection Obsolete Command 13701104862SruIn @acronym{AT&T} @code{troff} output, the writing of a single 13702104862Sruglyph is mostly done by a very strange command that combines a 13703104862Sruhorizontal move and a single character giving the glyph name. It 13704104862Srudoesn't have a command code, but is represented by a 3-character 13705104862Sruargument consisting of exactly 2@w{ }digits and a character. 1370655839Sasmodai 13707104862Sru@table @asis 13708104862Sru@item @var{dd}@var{g} 13709104862SruMove right @var{dd} (exactly two decimal digits) basic units @samp{u}, 13710104862Sruthen print glyph@w{ }@var{g} (represented as a single character). 1371155839Sasmodai 13712104862SruIn @code{gtroff}, arbitrary syntactical space around and within this 13713104862Srucommand is allowed to be added. Only when a preceding command on the 13714104862Srusame line ends with an argument of variable length a separating space 13715104862Sruis obligatory. In @acronym{AT&T} @code{troff}, large clusters of these 13716104862Sruand other commands are used, mostly without spaces; this made such output 13717104862Srualmost unreadable. 13718104862Sru 13719104862Sru@end table 13720104862Sru 13721104862SruFor modern high-resolution devices, this command does not make sense 13722104862Srubecause the width of the glyphs can become much larger than two 13723104862Srudecimal digits. In @code{gtroff}, this is only used for the devices 13724104862Sru@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other 13725104862Srudevices, the commands @samp{t} and @samp{u} provide a better 13726104862Srufunctionality. 13727104862Sru 13728104862Sru@c --------------------------------------------------------------------- 13729104862Sru 13730104862Sru@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output 13731104862Sru@subsection Intermediate Output Examples 13732104862Sru 13733104862SruThis section presents the intermediate output generated from the same 13734104862Sruinput for three different devices. The input is the sentence 13735104862Sru@samp{hell world} fed into @code{gtroff} on the command line. 13736104862Sru 13737104862Sru@table @asis 13738104862Sru@item High-resolution device @code{ps} 13739104862Sru 13740104862SruThis is the standard output of @code{gtroff} if no @option{-T} option 13741104862Sruis given. 13742104862Sru 13743104862Sru@example 13744104862Sru@group 13745104862Srushell> echo "hell world" | groff -Z -T ps 13746104862Sru 13747104862Srux T ps 13748104862Srux res 72000 1 1 13749104862Srux init 13750104862Sru@end group 13751104862Srup1 13752104862Srux font 5 TR 13753104862Sruf5 13754104862Srus10000 13755104862SruV12000 13756104862SruH72000 13757104862Sruthell 13758104862Sruwh2500 13759104862Srutw 13760104862SruH96620 13761104862Srutorld 13762104862Srun12000 0 13763104862Sru@group 13764104862Srux trailer 13765104862SruV792000 13766104862Srux stop 13767104862Sru@end group 13768104862Sru@end example 13769104862Sru 1377069626Sru@noindent 13771104862SruThis output can be fed into @code{grops} to get its representation as 13772104862Srua PostScript file. 1377355839Sasmodai 13774104862Sru@item Low-resolution device @code{latin1} 1377555839Sasmodai 13776104862SruThis is similar to the high-resolution device except that the 13777104862Srupositioning is done at a minor scale. Some comments (lines starting 13778104862Sruwith @samp{#}) were added for clarification; they were not generated 13779104862Sruby the formatter. 13780104862Sru 13781104862Sru@example 13782104862Sru@group 13783104862Srushell> echo "hell world" | groff -Z -T latin1 13784104862Sru 13785104862Sru# prologue 13786104862Srux T latin1 13787104862Srux res 240 24 40 13788104862Srux init 13789104862Sru@end group 13790104862Sru# begin a new page 13791104862Srup1 13792104862Sru# font setup 13793104862Srux font 1 R 13794104862Sruf1 13795104862Srus10 13796104862Sru# initial positioning on the page 13797104862SruV40 13798104862SruH0 13799104862Sru# write text `hell' 13800104862Sruthell 13801104862Sru# inform about space, and issue a horizontal jump 13802104862Sruwh24 13803104862Sru# write text `world' 13804104862Srutworld 13805104862Sru# announce line break, but do nothing because ... 13806104862Srun40 0 13807104862Sru@group 13808104862Sru# ... the end of the document has been reached 13809104862Srux trailer 13810104862SruV2640 13811104862Srux stop 13812104862Sru@end group 13813104862Sru@end example 13814104862Sru 1381569626Sru@noindent 13816104862SruThis output can be fed into @code{grotty} to get a formatted text 13817104862Srudocument. 1381855839Sasmodai 13819104862Sru@item @acronym{AT&T} @code{troff} output 13820104862SruSince a computer monitor has a very low resolution compared to modern 13821104862Sruprinters the intermediate output for the X@w{ }Window devices can use 13822104862Sruthe jump-and-write command with its 2-digit displacements. 13823104862Sru 13824104862Sru@example 13825104862Sru@group 13826104862Srushell> echo "hell world" | groff -Z -T X100 13827104862Sru 13828104862Srux T X100 13829104862Srux res 100 1 1 13830104862Srux init 13831104862Sru@end group 13832104862Srup1 13833104862Srux font 5 TR 13834104862Sruf5 13835104862Srus10 13836104862SruV16 13837104862SruH100 13838104862Sru# write text with jump-and-write commands 13839104862Sruch07e07l03lw06w11o07r05l03dh7 13840104862Srun16 0 13841104862Sru@group 13842104862Srux trailer 13843104862SruV1100 13844104862Srux stop 13845104862Sru@end group 13846104862Sru@end example 13847104862Sru 13848104862Sru@noindent 13849104862SruThis output can be fed into @code{xditview} or @code{gxditview} 13850104862Srufor displaying in@w{ }X. 13851104862Sru 13852104862SruDue to the obsolete jump-and-write command, the text clusters in the 13853104862Sru@acronym{AT&T} @code{troff} output are almost unreadable. 13854104862Sru 13855104862Sru@end table 13856104862Sru 1385769626Sru@c --------------------------------------------------------------------- 1385869626Sru 13859104862Sru@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output 13860104862Sru@subsection Output Language Compatibility 1386155839Sasmodai 13862104862SruThe intermediate output language of @acronym{AT&T} @code{troff} 13863104862Sruwas first documented in the @acronym{UNIX} troff manual, with later 13864104862Sruadditions documented in @cite{A Typesetter-indenpendent TROFF}, 13865104862Sruwritten by Brian Kernighan. 1386655839Sasmodai 13867104862SruThe @code{gtroff} intermediate output format is compatible with this 13868104862Sruspecification except for the following features. 1386955839Sasmodai 13870104862Sru@itemize @bullet 13871104862Sru@item 13872104862SruThe classical quasi device independence is not yet implemented. 13873104862Sru 13874104862Sru@item 13875104862SruThe old hardware was very different from what we use today. So the 13876104862Sru@code{groff} devices are also fundamentally different from the ones in 13877104862Sru@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T} 13878104862SruPostScript device is called @code{post} and has a resolution of only 13879104862Sru720 units per inch, suitable for printers 20 years ago, while 13880104862Sru@code{groff}'s @code{ps} device has a resolution of 13881104862Sru72000 units per inch. Maybe, by implementing some rescaling 13882104862Srumechanism similar to the classical quasi device independence, 13883104862Sru@code{groff} could emulate @acronym{AT&T}'s @code{post} device. 13884104862Sru 13885104862Sru@item 13886104862SruThe B-spline command @samp{D~} is correctly handled by the 13887104862Sruintermediate output parser, but the drawing routines aren't 13888104862Sruimplemented in some of the postprocessor programs. 13889104862Sru 13890104862Sru@item 13891104862SruThe argument of the commands @samp{s} and @w{@samp{x H}} has the 13892104862Sruimplicit unit scaled point @samp{z} in @code{gtroff}, while 13893104862Sru@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an 13894104862Sruincompatibility but a compatible extension, for both units coincide 13895104862Srufor all devices without a @code{sizescale} parameter in the @file{DESC} 13896104862Srufile, including all postprocessors from @acronym{AT&T} and 13897104862Sru@code{groff}'s text devices. The few @code{groff} devices with 13898104862Srua @code{sizescale} parameter either do not exist for @acronym{AT&T} 13899104862Sru@code{troff}, have a different name, or seem to have a different 13900104862Sruresolution. So conflicts are very unlikely. 13901104862Sru 13902104862Sru@item 13903104862SruThe position changing after the commands @samp{Dp}, @samp{DP}, and 13904104862Sru@samp{Dt} is illogical, but as old versions of @code{gtroff} used this 13905104862Srufeature it is kept for compatibility reasons. 13906104862Sru 13907104862Sru@ignore 13908104862SruTemporarily, there existed some confusion on the positioning after the 13909104862Sru@samp{D} commands that are groff extensions. This has been clarified 13910104862Sruby establishing the classical rule for all @code{groff} drawing commands: 13911104862Sru 13912104862Sru@itemize 13913104862Sru@item 13914104862SruThe position after a graphic object has been drawn is at its end; 13915104862Srufor circles and ellipses, the `end' is at the right side. 13916104862Sru 13917104862Sru@item 13918104862SruFrom this, the positionings specified for the drawing commands above 13919104862Srufollow quite naturally. 13920104862Sru@end itemize 13921104862Sru@end ignore 13922104862Sru 13923104862Sru@end itemize 13924104862Sru 13925104862Sru 1392669626Sru@c ===================================================================== 1392755839Sasmodai 1392855839Sasmodai@node Font Files, , gtroff Output, File formats 1392955839Sasmodai@section Font Files 1393055839Sasmodai@cindex font files 1393155839Sasmodai@cindex files, font 1393255839Sasmodai 1393369626SruThe @code{gtroff} font format is roughly a superset of the 13934104862Sru@code{ditroff} font format (as used in later versions of @acronym{AT&T} 13935104862Sru@code{troff} and its descendants). Unlike the @code{ditroff} font 13936104862Sruformat, there is no associated binary format; all files are text 13937104862Srufiles.@footnote{Plan@w{ }9 @code{troff} has also abandoned the binary 13938104862Sruformat.} The font files for device @var{name} are stored in a directory 1393969626Sru@file{dev@var{name}}. There are two types of file: a device description 1394069626Srufile called @file{DESC} and for each font@w{ }@var{f} a font file 1394169626Srucalled@w{ }@file{@var{f}}. 1394255839Sasmodai 1394369626Sru@menu 1394475584Sru* DESC File Format:: 1394575584Sru* Font File Format:: 1394669626Sru@end menu 1394755839Sasmodai 1394869626Sru@c --------------------------------------------------------------------- 1394969626Sru 1395075584Sru@node DESC File Format, Font File Format, Font Files, Font Files 1395175584Sru@subsection @file{DESC} File Format 13952104862Sru@cindex @file{DESC} file, format 13953104862Sru@cindex font description file, format 1395469626Sru@cindex format of font description file 1395569626Sru@pindex DESC@r{ file format} 1395655839Sasmodai 13957104862SruThe @file{DESC} file can contain the following types of line. Except 13958104862Srufor the @code{charset} keyword which must comes last (if at all), the 13959104862Sruorder of the lines is not important. 1396055839Sasmodai 1396155839Sasmodai@table @code 1396255839Sasmodai@item res @var{n} 1396369626Sru@kindex res 13964104862SruThere are @var{n}@w{ }machine units per inch. 1396569626Sru 1396655839Sasmodai@item hor @var{n} 1396769626Sru@kindex hor 13968104862SruThe horizontal resolution is @var{n}@w{ }machine units. 1396969626Sru 1397055839Sasmodai@item vert @var{n} 1397169626Sru@kindex vert 13972104862SruThe vertical resolution is @var{n}@w{ }machine units. 1397369626Sru 1397455839Sasmodai@item sizescale @var{n} 1397569626Sru@kindex sizescale 1397669626SruThe scale factor for point sizes. By default this has a value of@w{ }1. 1397769626SruOne scaled point is equal to one point/@var{n}. The arguments to the 1397855839Sasmodai@code{unitwidth} and @code{sizes} commands are given in scaled points. 1397955839Sasmodai@xref{Fractional Type Sizes}, for more information. 1398069626Sru 1398155839Sasmodai@item unitwidth @var{n} 1398269626Sru@kindex unitwidth 1398369626SruQuantities in the font files are given in machine units for fonts whose 1398469626Srupoint size is @var{n}@w{ }scaled points. 1398569626Sru 13986104862Sru@item prepro @var{program} 13987104862Sru@kindex prepro 13988104862SruCall @var{program} as a preprocessor. Currently, this keyword is used 13989104862Sruby @code{groff} with option @option{-Thtml} only. 13990104862Sru 13991104862Sru@item postpro @var{program} 13992104862Sru@kindex postpro 13993104862SruCall @var{program} as a postprocessor. For example, the line 13994104862Sru 13995104862Sru@Example 13996104862Srupostpro grodvi 13997104862Sru@endExample 13998104862Sru 13999104862Sru@noindent 14000104862Sruin the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} 14001104862Sruif option @option{-Tdvi} is given (and @option{-Z} isn't used). 14002104862Sru 1400355839Sasmodai@item tcommand 1400469626Sru@kindex tcommand 1400569626SruThis means that the postprocessor can handle the @samp{t} and @samp{u} 14006104862Sruintermediate output commands. 1400769626Sru 1400869626Sru@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 1400969626Sru@kindex sizes 1401069626SruThis means that the device has fonts at @var{s1}, @var{s2}, @dots{} 14011104862Sru@var{sn} scaled points. The list of sizes must be terminated by@w{ }0 14012104862Sru(this is digit zero). Each @var{si} can also be a range of sizes 14013104862Sru@var{m}-@var{n}. The list can extend over more than one line. 1401469626Sru 1401569626Sru@item styles @var{S1} @var{S2} @dots{} @var{Sm} 1401669626Sru@kindex styles 1401775584SruThe first @var{m}@w{ }font positions are associated with styles 1401869626Sru@var{S1} @dots{} @var{Sm}. 1401969626Sru 1402069626Sru@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 1402169626Sru@kindex fonts 1402275584SruFonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 1402369626Sru@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 1402469626Srustyles. This command may extend over more than one line. A font name 14025104862Sruof@w{ }0 means no font is mounted on the corresponding font position. 1402669626Sru 1402755839Sasmodai@item family @var{fam} 1402869626Sru@kindex family 1402955839SasmodaiThe default font family is @var{fam}. 1403069626Sru 14031104862Sru@item use_charnames_in_special 14032104862Sru@kindex use_charnames_in_special 14033104862SruThis command indicates that @code{gtroff} should encode special 14034104862Srucharacters inside special commands. Currently, this is only used 14035104862Sruby the @acronym{HTML} output device. @xref{Postprocessor Access}. 14036104862Sru 14037104862Sru@item papersize @var{string} @dots{} 14038104862Sru@kindex papersize 14039104862SruSelect a paper size. Valid values for @var{string} are the ISO paper 14040104862Srutypes @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7}, 14041104862Sru@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter}, 14042104862Sru@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, 14043104862Sru@code{executive}, @code{com10}, and @code{monarch}. Case is not significant 14044104862Srufor @var{string} if it holds predefined paper types. Alternatively, 14045104862Sru@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file 14046104862Srucan be opened, @code{groff} reads the first line and tests for the above 14047104862Srupaper sizes. Finally, @var{string} can be a custom paper size in the format 14048104862Sru@code{@var{length},@var{width}} (no spaces before and after the comma). 14049104862SruBoth @var{length} and @var{width} must have a unit appended; valid values 14050104862Sruare @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and 14051104862Sru@samp{P} for picas. Example: @code{12c,235p}. An argument which starts 14052104862Sruwith a digit is always treated as a custom paper format. @code{papersize} 14053104862Srusets both the vertical and horizontal dimension of the output medium. 14054104862Sru 14055104862SruMore than one argument can be specified; @code{groff} scans from left to 14056104862Sruright and uses the first valid paper specification. 14057104862Sru 14058104862Sru@item pass_filenames 14059104862Sru@kindex pass_filenames 14060104862SruTell @code{gtroff} to emit the name of the source file currently 14061104862Srubeing processed. This is achieved by the intermediate output command 14062104862Sru@samp{F}. Currently, this is only used by the @acronym{HTML} output 14063104862Srudevice. 14064104862Sru 14065104862Sru@item print @var{program} 14066104862Sru@kindex print 14067104862SruUse @var{program} as a spooler program for printing. If omitted, 14068104862Sruthe @option{-l} and @option{-L} options of @code{groff} are ignored. 14069104862Sru 1407055839Sasmodai@item charset 1407169626Sru@kindex charset 1407255839SasmodaiThis line and everything following in the file are ignored. It is 1407355839Sasmodaiallowed for the sake of backwards compatibility. 1407455839Sasmodai@end table 1407555839Sasmodai 14076104862SruThe @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines 1407769626Sruare mandatory. Other commands are ignored by @code{gtroff} but may be 1407869626Sruused by postprocessors to store arbitrary information about the device 1407969626Sruin the @file{DESC} file. 1408055839Sasmodai 14081104862Sru@kindex spare1 14082104862Sru@kindex spare2 14083104862Sru@kindex biggestfont 14084104862SruHere a list of obsolete keywords which are recognized by @code{groff} 14085104862Srubut completely ignored: @code{spare1}, @code{spare2}, 14086104862Sru@code{biggestfont}. 1408755839Sasmodai 14088104862Sru 1408969626Sru@c --------------------------------------------------------------------- 1409069626Sru 1409175584Sru@node Font File Format, , DESC File Format, Font Files 1409275584Sru@subsection Font File Format 14093104862Sru@cindex font file, format 14094104862Sru@cindex font description file, format 1409569626Sru@cindex format of font files 14096104862Sru@cindex format of font description files 1409755839Sasmodai 14098104862SruA @dfn{font file}, also (and probably better) called a @dfn{font 14099104862Srudescription file}, has two sections. The first section is a sequence 14100104862Sruof lines each containing a sequence of blank delimited words; the first 14101104862Sruword in the line is a key, and subsequent words give a value for that 14102104862Srukey. 1410355839Sasmodai 1410455839Sasmodai@table @code 1410569626Sru@item name @var{f} 1410669626Sru@kindex name 1410769626SruThe name of the font is@w{ }@var{f}. 1410869626Sru 1410955839Sasmodai@item spacewidth @var{n} 1411069626Sru@kindex spacewidth 1411169626SruThe normal width of a space is@w{ }@var{n}. 1411269626Sru 1411355839Sasmodai@item slant @var{n} 1411469626Sru@kindex slant 14115104862SruThe glyphs of the font have a slant of @var{n}@w{ }degrees. 1411655839Sasmodai(Positive means forward.) 1411769626Sru 1411869626Sru@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 1411969626Sru@kindex ligatures 14120104862SruGlyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 1412169626Srupossible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 1412269626Sru@samp{ffl}. For backwards compatibility, the list of ligatures may be 1412369626Sruterminated with a@w{ }0. The list of ligatures may not extend over more 1412469626Sruthan one line. 1412569626Sru 1412655839Sasmodai@item special 14127104862Sru@cindex special fonts 1412869626Sru@kindex special 14129104862SruThe font is @dfn{special}; this means that when a glyph is requested 14130104862Sruthat is not present in the current font, it is searched for in any 1413155839Sasmodaispecial fonts that are mounted. 1413255839Sasmodai@end table 1413355839Sasmodai 1413469626SruOther commands are ignored by @code{gtroff} but may be used by 1413569626Srupostprocessors to store arbitrary information about the font in the font 1413669626Srufile. 1413755839Sasmodai 1413869626Sru@cindex comments in font files 1413969626Sru@cindex font files, comments 1414069626Sru@kindex # 1414169626SruThe first section can contain comments which start with the @samp{#} 1414269626Srucharacter and extend to the end of a line. 1414355839Sasmodai 1414455839SasmodaiThe second section contains one or two subsections. It must contain a 1414555839Sasmodai@code{charset} subsection and it may also contain a @code{kernpairs} 1414655839Sasmodaisubsection. These subsections can appear in any order. Each 1414755839Sasmodaisubsection starts with a word on a line by itself. 1414855839Sasmodai 1414969626Sru@kindex charset 14150104862SruThe word @code{charset} starts the character set 14151104862Srusubsection.@footnote{This keyword is misnamed since it starts a list 14152104862Sruof ordered glyphs, not characters.} The @code{charset} line is 14153104862Srufollowed by a sequence of lines. Each line gives information for one 14154104862Sruglyph. A line comprises a number of fields separated by blanks or 14155104862Srutabs. The format is 1415655839Sasmodai 14157104862Sru@quotation 14158104862Sru@var{name} @var{metrics} @var{type} @var{code} 14159104862Sru[@var{entity-name}] [@code{--} @var{comment}] 14160104862Sru@end quotation 1416169626Sru 1416269626Sru@cindex 8-bit input 1416369626Sru@cindex input, 8-bit 14164104862Sru@cindex accessing unnamed glyphs with @code{\N} 14165104862Sru@cindex unnamed glyphs, accessing with @code{\N} 14166104862Sru@cindex characters, unnamed, accessing with @code{\N} 14167104862Sru@cindex glyphs, unnamed, accessing with @code{\N} 1416869626Sru@kindex --- 1416969626Sru@noindent 14170104862Sru@var{name} identifies the glyph name@footnote{The distinction between 14171104862Sruinput, characters, and output, glyphs, is not clearly separated in the 14172104862Sruterminology of @code{groff}; for example, the @code{char} request 14173104862Srushould be called @code{glyph} since it defines an output entity.}: 14174104862SruIf @var{name} is a single character@w{ }@var{c} then it corresponds 14175104862Sruto the @code{gtroff} input character@w{ }@var{c}; if it is of the form 14176104862Sru@samp{\@var{c}} where @var{c} is a single character, then it 14177104862Srucorresponds to the special character @code{\[@var{c}]}; otherwise it 14178104862Srucorresponds to the special character @samp{\[@var{name}]}. If it 14179104862Sruis exactly two characters @var{xx} it can be entered as 14180104862Sru@samp{\(@var{xx}}. Note that single-letter special characters can't 14181104862Srube accessed as @samp{\@var{c}}; the only exception is @samp{\-} which 14182104862Sruis identical to @code{\[-]}. 1418355839Sasmodai 14184104862Sru@code{gtroff} supports 8-bit input characters; however some utilities 14185104862Sruhave difficulties with eight-bit characters. For this reason, there is 14186104862Srua convention that the entity name @samp{char@var{n}} is equivalent to 14187104862Sruthe single input character whose code is@w{ }@var{n}. For example, 14188104862Sru@samp{char163} would be equivalent to the character with code@w{ }163 14189104862Sruwhich is the pounds sterling sign in the @w{ISO Latin-1} character set. 14190104862SruYou shouldn't use @samp{char@var{n}} entities in font description files 14191104862Srusince they are related to input, not output. Otherwise, you get 14192104862Sruhard-coded connections between input and output encoding which 14193104862Sruprevents use of different (input) character sets. 1419469626Sru 14195104862SruThe name @samp{---} is special and indicates that the glyph is 14196104862Sruunnamed; such glyphs can only be used by means of the @code{\N} 14197104862Sruescape sequence in @code{gtroff}. 1419855839Sasmodai 14199104862SruThe @var{type} field gives the glyph type: 14200104862Sru 1420155839Sasmodai@table @code 1420255839Sasmodai@item 1 14203104862Sruthe glyph has a descender, for example, @samp{p}; 1420469626Sru 1420555839Sasmodai@item 2 14206104862Sruthe glyph has an ascender, for example, @samp{b}; 1420769626Sru 1420855839Sasmodai@item 3 14209104862Sruthe glyph has both an ascender and a descender, for example, @samp{(}. 1421055839Sasmodai@end table 1421155839Sasmodai 1421255839SasmodaiThe @var{code} field gives the code which the postprocessor uses to 14213104862Sruprint the glyph. The glyph can also be input to @code{gtroff} 14214104862Sruusing this code by means of the @code{\N} escape sequence. @var{code} 14215104862Srucan be any integer. If it starts with @samp{0} it is interpreted as 1421675584Sruoctal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 14217104862Sruhexadecimal. Note, however, that the @code{\N} escape sequence only 14218104862Sruaccepts a decimal integer. 1421955839Sasmodai 14220104862SruThe @var{entity-name} field gives an @acronym{ASCII} string 14221104862Sruidentifying the glyph which the postprocessor uses to print the 14222104862Sru@code{gtroff} glyph @var{name}. This field is optional and has been 14223104862Sruintroduced so that the @acronym{HTML} device driver can encode its 14224104862Srucharacter set. For example, the glyph @samp{\[Po]} is 14225104862Srurepresented as @samp{£} in @acronym{HTML} 4.0. 1422655839Sasmodai 14227104862SruAnything on the line after the @var{entity-name} field resp.@: after 14228104862Sru@samp{--} will be ignored. 14229104862Sru 1423055839SasmodaiThe @var{metrics} field has the form: 1423155839Sasmodai 14232104862Sru@display 14233104862Sru@group 14234104862Sru@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction} 14235104862Sru [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]] 14236104862Sru@end group 14237104862Sru@end display 1423855839Sasmodai 1423969626Sru@noindent 1424069626SruThere must not be any spaces between these subfields (it has been split 1424169626Sruhere into two lines for better legibility only). Missing subfields are 1424269626Sruassumed to be@w{ }0. The subfields are all decimal integers. Since 1424369626Sruthere is no associated binary format, these values are not required to 1424469626Srufit into a variable of type @samp{char} as they are in @code{ditroff}. 14245104862SruThe @var{width} subfield gives the width of the glyph. The @var{height} 14246104862Srusubfield gives the height of the glyph (upwards is positive); if a 14247104862Sruglyph does not extend above the baseline, it should be given a zero 14248104862Sruheight, rather than a negative height. The @var{depth} subfield gives 14249104862Sruthe depth of the glyph, that is, the distance from the baseline to the 14250104862Srulowest point below the baseline to which the glyph extends (downwards is 14251104862Srupositive); if a glyph does not extend below the baseline, it should be 14252104862Srugiven a zero depth, rather than a negative depth. The 14253104862Sru@var{italic-correction} subfield gives the amount of space that should 14254104862Srube added after the glyph when it is immediately to be followed by a 14255104862Sruglyph from a roman font. The @var{left-italic-correction} subfield 14256104862Srugives the amount of space that should be added before the glyph when it 14257104862Sruis immediately to be preceded by a glyph from a roman font. The 14258104862Sru@var{subscript-correction} gives the amount of space that should be 14259104862Sruadded after a glyph before adding a subscript. This should be less 1426055839Sasmodaithan the italic correction. 1426155839Sasmodai 1426255839SasmodaiA line in the @code{charset} section can also have the format 1426355839Sasmodai 1426475584Sru@Example 1426555839Sasmodai@var{name} " 1426675584Sru@endExample 1426755839Sasmodai 1426869626Sru@noindent 14269104862SruThis indicates that @var{name} is just another name for the glyph 1427055839Sasmodaimentioned in the preceding line. 1427155839Sasmodai 1427269626Sru@kindex kernpairs 1427355839SasmodaiThe word @code{kernpairs} starts the kernpairs section. This contains a 1427455839Sasmodaisequence of lines of the form: 1427555839Sasmodai 1427675584Sru@Example 1427769626Sru@var{c1} @var{c2} @var{n} 1427875584Sru@endExample 1427955839Sasmodai 1428075584Sru@noindent 14281104862SruThis means that when glyph @var{c1} appears next to glyph @var{c2} 14282104862Sruthe space between them should be increased by@w{ }@var{n}. Most 14283104862Sruentries in the kernpairs section have a negative value for@w{ }@var{n}. 1428455839Sasmodai 1428555839Sasmodai 1428655839Sasmodai 1428769626Sru@c ===================================================================== 1428869626Sru@c ===================================================================== 1428969626Sru 14290104862Sru@node Installation, Copying This Manual, File formats, Top 1429155839Sasmodai@chapter Installation 1429255839Sasmodai@cindex installation 1429355839Sasmodai 1429469626Sru@c XXX 1429555839Sasmodai 1429655839Sasmodai 1429755839Sasmodai 1429869626Sru@c ===================================================================== 1429969626Sru@c ===================================================================== 1430069626Sru 14301104862Sru@node Copying This Manual, Request Index, Installation, Top 14302104862Sru@appendix Copying This Manual 1430369626Sru 14304104862Sru@menu 14305104862Sru* GNU Free Documentation License:: License for copying this manual. 14306104862Sru@end menu 14307104862Sru 14308104862Sru@include fdl.texi 14309104862Sru 14310104862Sru 14311104862Sru 14312104862Sru@c ===================================================================== 14313104862Sru@c ===================================================================== 14314104862Sru 14315104862Sru@node Request Index, Escape Index, Copying This Manual, Top 14316104862Sru@appendix Request Index 14317104862Sru 1431875584SruRequests appear without the leading control character (normally either 1431975584Sru@samp{.} or @samp{'}). 1432069626Sru 1432175584Sru@printindex rq 1432255839Sasmodai 1432355839Sasmodai 1432469626Sru 1432569626Sru@c ===================================================================== 1432669626Sru@c ===================================================================== 1432769626Sru 1432875584Sru@node Escape Index, Operator Index, Request Index, Top 14329104862Sru@appendix Escape Index 1433075584Sru 14331104862SruAny escape sequence @code{\@var{X}} with @var{X} not in the list below 14332104862Sruemits a warning, printing glyph @var{X}. 14333104862Sru 1433475584Sru@printindex es 1433575584Sru 1433675584Sru 1433775584Sru 1433875584Sru@c ===================================================================== 1433975584Sru@c ===================================================================== 1434075584Sru 1434175584Sru@node Operator Index, Register Index, Escape Index, Top 14342104862Sru@appendix Operator Index 1434369626Sru 1434469626Sru@printindex op 1434569626Sru 1434669626Sru 1434769626Sru 1434869626Sru@c ===================================================================== 1434969626Sru@c ===================================================================== 1435069626Sru 1435175584Sru@node Register Index, Macro Index, Operator Index, Top 14352104862Sru@appendix Register Index 1435355839Sasmodai 14354104862SruThe macro package or program a specific register belongs to is appended in 14355104862Srubrackets. 14356104862Sru 14357104862SruA register name@w{ }@code{x} consisting of exactly one character can be 14358104862Sruaccessed as @samp{\nx}. A register name @code{xx} consisting of exactly 14359104862Srutwo characters can be accessed as @samp{\n(xx}. Register names @code{xxx} 14360104862Sruof any length can be accessed as @samp{\n[xxx]}. 14361104862Sru 1436255839Sasmodai@printindex vr 1436355839Sasmodai 1436455839Sasmodai 1436555839Sasmodai 1436669626Sru@c ===================================================================== 1436769626Sru@c ===================================================================== 1436855839Sasmodai 1436975584Sru@node Macro Index, String Index, Register Index, Top 14370104862Sru@appendix Macro Index 1437155839Sasmodai 14372104862SruThe macro package a specific macro belongs to is appended in brackets. 14373104862SruThey appear without the leading control character (normally @samp{.}). 14374104862Sru 1437569626Sru@printindex ma 1437655839Sasmodai 1437755839Sasmodai 1437855839Sasmodai 1437969626Sru@c ===================================================================== 1438069626Sru@c ===================================================================== 1438169626Sru 1438275584Sru@node String Index, Glyph Name Index, Macro Index, Top 14383104862Sru@appendix String Index 1438475584Sru 14385104862SruThe macro package or program a specific string belongs to is appended in 14386104862Srubrackets. 14387104862Sru 14388104862SruA string name@w{ }@code{x} consisting of exactly one character can be 14389104862Sruaccessed as @samp{\*x}. A string name @code{xx} consisting of exactly 14390104862Srutwo characters can be accessed as @samp{\*(xx}. String names @code{xxx} 14391104862Sruof any length can be accessed as @samp{\*[xxx]}. 14392104862Sru 14393104862Sru 1439475584Sru@printindex st 1439575584Sru 1439675584Sru 1439775584Sru 1439875584Sru@c ===================================================================== 1439975584Sru@c ===================================================================== 1440075584Sru 1440175584Sru@node Glyph Name Index, Font File Keyword Index, String Index, Top 14402104862Sru@appendix Glyph Name Index 1440369626Sru 1440469626SruA glyph name @code{xx} consisting of exactly two characters can be 1440569626Sruaccessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 1440669626Sruaccessed as @samp{\[xxx]}. 1440769626Sru 14408104862Sru@c XXX 1440969626Sru 1441069626Sru 1441169626Sru 1441269626Sru@c ===================================================================== 1441369626Sru@c ===================================================================== 1441469626Sru 1441569626Sru@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 14416104862Sru@appendix Font File Keyword Index 1441769626Sru 1441869626Sru@printindex ky 1441969626Sru 1442069626Sru 1442169626Sru 1442269626Sru@c ===================================================================== 1442369626Sru@c ===================================================================== 1442469626Sru 1442569626Sru@node Program and File Index, Concept Index, Font File Keyword Index, Top 14426104862Sru@appendix Program and File Index 1442769626Sru 1442855839Sasmodai@printindex pg 1442955839Sasmodai 1443055839Sasmodai 1443155839Sasmodai 1443269626Sru@c ===================================================================== 1443369626Sru@c ===================================================================== 1443469626Sru 1443569626Sru@node Concept Index, , Program and File Index, Top 14436104862Sru@appendix Concept Index 1443755839Sasmodai 1443855839Sasmodai@printindex cp 1443955839Sasmodai 1444055839Sasmodai 1444155839Sasmodai@bye 14442