groff.texinfo revision 114402
155839Sasmodai\input texinfo @c -*-texinfo-*- 269626Sru 369626Sru@c 4114402Sru@c Please convert this manual with `texi2dvi -e groff.texinfo' due to 5114402Sru@c problems in texinfo regarding expansion of user-defined macros. 669626Sru@c 7114402Sru@c You need texinfo 4.3 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 24114402SruThis manual documents GNU @code{troff} version 1.19. 25104862Sru 26114402SruCopyright @copyright{} 1994-2000, 2001, 2002, 2003 27114402SruFree Software Foundation, Inc. 28104862Sru 29104862Sru@quotation 30104862SruPermission is granted to copy, distribute and/or modify this document 31104862Sruunder the terms of the GNU Free Documentation License, Version 1.1 or 32104862Sruany later version published by the Free Software Foundation; with no 33104862SruInvariant Sections, with the Front-Cover texts being `A GNU Manual,'' 34104862Sruand with the Back-Cover Texts as in (a) below. A copy of the 35104862Srulicense is included in the section entitled `GNU Free Documentation 36104862SruLicense.'' 37104862Sru 38104862Sru(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 39104862Sruthis GNU Manual, like GNU software. Copies published by the Free 40104862SruSoftware Foundation raise funds for GNU development.'' 41104862Sru@end quotation 42104862Sru@end copying 43104862Sru 44104862Sru 4569626Sru@c We use the following indices: 4669626Sru@c 4769626Sru@c cindex: concepts 4875584Sru@c rqindex: requests 4975584Sru@c esindex: escapes 5069626Sru@c vindex: registers 5169626Sru@c kindex: commands in font files 5269626Sru@c pindex: programs and files 5369626Sru@c tindex: environment variables 5475584Sru@c maindex: macros 5575584Sru@c stindex: strings 5669626Sru@c opindex: operators 5769626Sru@c 5869626Sru@c tindex and cindex are merged. 5969626Sru 6075584Sru@defcodeindex rq 6175584Sru@defcodeindex es 6269626Sru@defcodeindex ma 6375584Sru@defcodeindex st 6469626Sru@defcodeindex op 6569626Sru@syncodeindex tp cp 6669626Sru 6769626Sru 68114402Sru@c To avoid uppercasing in @deffn while converting to info, we define 69114402Sru@c our special @Var{}. 7075584Sru@c 71114402Sru@c Due to a (not officially documented) `feature' in makeinfo 4.0, 7275584Sru@c macros are not expanded in @deffn (but the macro definition is 73114402Sru@c properly removed), so we have to define @Var{} directly in TeX also. 7475584Sru 7575584Sru@macro Var{arg} 7675584Sru\arg\ 7769626Sru@end macro 7875584Sru@tex 7975584Sru\gdef\Var#1{\var{#1}} 8075584Sru@end tex 8169626Sru 8275584Sru 83104862Sru@c To assure correct HTML translation, some ugly hacks are necessary. 84104862Sru@c While processing a @def... request, the HTML translator looks at the 85104862Sru@c next line to decide whether it should start indentation or not. If 86104862Sru@c it is something starting with @def... (e.g. @deffnx), it doesn't. 87104862Sru@c So we must assure during macro expansion that a @def... is seen. 88104862Sru@c 89104862Sru@c The following macros have to be used: 90104862Sru@c 91104862Sru@c One item: 92104862Sru@c 93104862Sru@c @Def... 94104862Sru@c 95104862Sru@c Two items: 96104862Sru@c 97104862Sru@c @Def...List 98104862Sru@c @Def...ListEnd 99104862Sru@c 100104862Sru@c More than two: 101104862Sru@c 102104862Sru@c @Def...List 103104862Sru@c @Def...Item 104104862Sru@c @Def...Item 105104862Sru@c ... 106104862Sru@c @Def...ListEnd 107104862Sru@c 108104862Sru@c The definition block must end with 109104862Sru@c 110104862Sru@c @endDef... 111104862Sru@c 112114402Sru@c The above is valid for texinfo 4.0f and above. 113104862Sru 114104862Sru 115104862Sru@c a dummy macro to assure the `@def...' 116104862Sru 117104862Sru@macro defdummy 118104862Sru@end macro 119104862Sru 120104862Sru 12175584Sru@c definition of requests 12275584Sru 12375584Sru@macro Defreq{name, arg} 124104862Sru@deffn Request @t{.\name\} \arg\ 12575584Sru@rqindex \name\ 126104862Sru@end macro 127104862Sru 128104862Sru@macro DefreqList{name, arg} 12975584Sru@deffn Request @t{.\name\} \arg\ 130104862Sru@defdummy 131104862Sru@rqindex \name\ 13275584Sru@end macro 13375584Sru 134104862Sru@macro DefreqItem{name, arg} 135104862Sru@deffnx Request @t{.\name\} \arg\ 136104862Sru@defdummy 13775584Sru@rqindex \name\ 138104862Sru@end macro 139104862Sru 140104862Sru@macro DefreqListEnd{name, arg} 14175584Sru@deffnx Request @t{.\name\} \arg\ 142104862Sru@rqindex \name\ 14375584Sru@end macro 14475584Sru 14575584Sru@macro endDefreq 14669626Sru@end deffn 14769626Sru@end macro 14869626Sru 14975584Sru 15075584Sru@c definition of escapes 15175584Sru 15275584Sru@macro Defesc{name, delimI, arg, delimII} 153114402Sru@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 15475584Sru@esindex \name\ 155104862Sru@end macro 156104862Sru 157104862Sru@macro DefescList{name, delimI, arg, delimII} 158114402Sru@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 159104862Sru@defdummy 160104862Sru@esindex \name\ 16169626Sru@end macro 16269626Sru 163104862Sru@macro DefescItem{name, delimI, arg, delimII} 164114402Sru@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 165104862Sru@defdummy 16675584Sru@esindex \name\ 167104862Sru@end macro 168104862Sru 169104862Sru@macro DefescListEnd{name, delimI, arg, delimII} 170114402Sru@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 171104862Sru@esindex \name\ 17269626Sru@end macro 17369626Sru 17475584Sru@macro endDefesc 17575584Sru@end deffn 17675584Sru@end macro 17775584Sru 17875584Sru 17975584Sru@c definition of registers 18075584Sru 18175584Sru@macro Defreg{name} 182104862Sru@deffn Register @t{\\n[\name\]} 18375584Sru@vindex \name\ 184104862Sru@end macro 185104862Sru 186104862Sru@macro DefregList{name} 18775584Sru@deffn Register @t{\\n[\name\]} 188104862Sru@defdummy 189104862Sru@vindex \name\ 19075584Sru@end macro 19175584Sru 192104862Sru@macro DefregItem{name} 193104862Sru@deffnx Register @t{\\n[\name\]} 194104862Sru@defdummy 19575584Sru@vindex \name\ 196104862Sru@end macro 197104862Sru 198104862Sru@macro DefregListEnd{name} 19975584Sru@deffnx Register @t{\\n[\name\]} 200104862Sru@vindex \name\ 20175584Sru@end macro 20275584Sru 20375584Sru@macro endDefreg 20475584Sru@end deffn 20575584Sru@end macro 20675584Sru 20775584Sru 208104862Sru@c definition of registers specific to macro packages, preprocessors, etc. 209104862Sru 210104862Sru@macro Defmpreg{name, package} 211104862Sru@deffn Register @t{\\n[\name\]} 212104862Sru@vindex \name\ @r{[}\package\@r{]} 213104862Sru@end macro 214104862Sru 215104862Sru@macro DefmpregList{name, package} 216104862Sru@deffn Register @t{\\n[\name\]} 217104862Sru@defdummy 218104862Sru@vindex \name\ @r{[}\package\@r{]} 219104862Sru@end macro 220104862Sru 221104862Sru@macro DefmpregItem{name, package} 222104862Sru@deffnx Register @t{\\n[\name\]} 223104862Sru@defdummy 224104862Sru@vindex \name\ @r{[}\package\@r{]} 225104862Sru@end macro 226104862Sru 227104862Sru@macro DefmpregListEnd{name, package} 228104862Sru@deffnx Register @t{\\n[\name\]} 229104862Sru@vindex \name\ @r{[}\package\@r{]} 230104862Sru@end macro 231104862Sru 232104862Sru@macro endDefmpreg 233104862Sru@end deffn 234104862Sru@end macro 235104862Sru 236104862Sru 23775584Sru@c definition of macros 23875584Sru 239104862Sru@macro Defmac{name, arg, package} 24075584Sru@defmac @t{.\name\} \arg\ 241104862Sru@maindex \name\ @r{[}\package\@r{]} 24269626Sru@end macro 24369626Sru 244104862Sru@macro DefmacList{name, arg, package} 245104862Sru@defmac @t{.\name\} \arg\ 246104862Sru@defdummy 247104862Sru@maindex \name\ @r{[}\package\@r{]} 248104862Sru@end macro 249104862Sru 250104862Sru@macro DefmacItem{name, arg, package} 25175584Sru@defmacx @t{.\name\} \arg\ 252104862Sru@defdummy 253104862Sru@maindex \name\ @r{[}\package\@r{]} 25475584Sru@end macro 25575584Sru 256104862Sru@macro DefmacListEnd{name, arg, package} 257104862Sru@defmacx @t{.\name\} \arg\ 258104862Sru@maindex \name\ @r{[}\package\@r{]} 259104862Sru@end macro 260104862Sru 26175584Sru@macro endDefmac 26269626Sru@end defmac 26369626Sru@end macro 26469626Sru 26575584Sru 26675584Sru@c definition of strings 26775584Sru 268104862Sru@macro Defstr{name, package} 269104862Sru@deffn String @t{\\*[\name\]} 270104862Sru@stindex \name\ @r{[}\package\@r{]} 27169626Sru@end macro 27269626Sru 273104862Sru@macro DefstrList{name, package} 274104862Sru@deffn String @t{\\*[\name\]} 275104862Sru@defdummy 276104862Sru@stindex \name\ @r{[}\package\@r{]} 27769626Sru@end macro 27869626Sru 279104862Sru@macro DefstrItem{name, package} 280104862Sru@deffnx String @t{\\*[\name\]} 281104862Sru@defdummy 282104862Sru@stindex \name\ @r{[}\package\@r{]} 283104862Sru@end macro 284104862Sru 285104862Sru@macro DefstrListEnd{name, package} 286104862Sru@deffnx String @t{\\*[\name\]} 287104862Sru@stindex \name\ @r{[}\package\@r{]} 288104862Sru@end macro 289104862Sru 29075584Sru@macro endDefstr 29175584Sru@end deffn 29275584Sru@end macro 29369626Sru 29475584Sru 29575584Sru@c our example macro 29675584Sru 29775584Sru@macro Example 29875584Sru@example 29975584Sru@group 30075584Sru@end macro 30175584Sru 30275584Sru@macro endExample 30375584Sru@end group 30475584Sru@end example 30575584Sru@end macro 30675584Sru 30775584Sru 308104862Sru@c <text> 309104862Sru 310104862Sru@tex 311104862Sru\gdef\angles#1{\angleleft{}\r{#1}\angleright{}} 312104862Sru@end tex 313104862Sru 314104862Sru@macro angles{text} 315104862Sru<\text\> 316104862Sru@end macro 317104862Sru 318104862Sru 319104862Sru@c a <= sign 320104862Sru 321104862Sru@tex 322104862Sru\gdef\LE{\le} 323104862Sru@end tex 324104862Sru 325104862Sru@macro LE 326104862Sru<= 327104862Sru@end macro 328104862Sru 329104862Sru 33075584Sru@c We need special parentheses and brackets: 33175584Sru@c 33275584Sru@c . Real parentheses in @deffn produce an error while compiling with 333114402Sru@c TeX. 33475584Sru@c . Real brackets use the wrong font in @deffn, overriding @t{}. 33575584Sru@c 336104862Sru@c Since macros aren't expanded in @deffn during -E, the following 337104862Sru@c definitions are for non-TeX only. 338104862Sru@c 33975584Sru@c This is true for texinfo 4.0. 34075584Sru 34175584Sru@macro lparen 34275584Sru( 34375584Sru@end macro 34475584Sru@macro rparen 34575584Sru) 34675584Sru@end macro 34775584Sru@macro lbrack 34875584Sru[ 34975584Sru@end macro 35075584Sru@macro rbrack 35175584Sru] 35275584Sru@end macro 35375584Sru 35475584Sru 355104862Sru@tex 356104862Sru\gdef\gobblefirst#1#2{#2} 357104862Sru\gdef\putwordAppendix{\gobblefirst} 358104862Sru@end tex 35975584Sru 360104862Sru 36175584Sru@c Note: We say `Roman numerals' but `roman font'. 36275584Sru 36375584Sru 364114402Sru@dircategory Typesetting 36555839Sasmodai@direntry 366104862Sru* Groff: (groff). The GNU troff document formatting system. 36755839Sasmodai@end direntry 36855839Sasmodai 36955839Sasmodai 37055839Sasmodai@titlepage 37155839Sasmodai@title groff 37269626Sru@subtitle The GNU implementation of @code{troff} 373114402Sru@subtitle Edition 1.19 374114402Sru@subtitle Spring 2003 375114402Sru@author by Trent A.@tie{}Fisher 376104862Sru@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 37755839Sasmodai 37855839Sasmodai@page 37955839Sasmodai@vskip 0pt plus 1filll 380104862Sru@insertcopying 38155839Sasmodai@end titlepage 38255839Sasmodai 38355839Sasmodai 384104862Sru@contents 38555839Sasmodai 38655839Sasmodai@ifinfo 387104862Sru@node Top, Introduction, (dir), (dir) 388104862Sru@top GNU troff 38955839Sasmodai 390104862Sru@insertcopying 39155839Sasmodai@end ifinfo 39255839Sasmodai 393104862Sru@ifhtml 394104862Sru@node Top, Introduction, (dir), (dir) 395104862Sru@top GNU troff 396104862Sru 397104862Sru@insertcopying 398104862Sru@end ifhtml 399104862Sru 40055839Sasmodai@menu 40175584Sru* Introduction:: 40275584Sru* Invoking groff:: 40375584Sru* Tutorial for Macro Users:: 40475584Sru* Macro Packages:: 40575584Sru* gtroff Reference:: 40675584Sru* Preprocessors:: 40775584Sru* Output Devices:: 40875584Sru* File formats:: 40975584Sru* Installation:: 410104862Sru* Copying This Manual:: 41175584Sru* Request Index:: 41275584Sru* Escape Index:: 41375584Sru* Operator Index:: 41475584Sru* Register Index:: 41575584Sru* Macro Index:: 41675584Sru* String Index:: 41775584Sru* Glyph Name Index:: 41875584Sru* Font File Keyword Index:: 41975584Sru* Program and File Index:: 42075584Sru* Concept Index:: 42155839Sasmodai@end menu 42255839Sasmodai 42355839Sasmodai 42455839Sasmodai 42569626Sru@c ===================================================================== 42669626Sru@c ===================================================================== 42769626Sru 428104862Sru@node Introduction, Invoking groff, Top, Top 42955839Sasmodai@chapter Introduction 43055839Sasmodai@cindex introduction 43155839Sasmodai 43255839SasmodaiGNU @code{troff} (or @code{groff}) is a system for typesetting 43355839Sasmodaidocuments. @code{troff} is very flexible and has been in existence (and 434114402Sruuse) for about 3@tie{}decades. It is quite widespread and firmly 43569626Sruentrenched in the @acronym{UNIX} community. 43655839Sasmodai 43755839Sasmodai@menu 43875584Sru* What Is groff?:: 43975584Sru* History:: 44075584Sru* groff Capabilities:: 44175584Sru* Macro Package Intro:: 44275584Sru* Preprocessor Intro:: 44375584Sru* Output device intro:: 44475584Sru* Credits:: 44555839Sasmodai@end menu 44655839Sasmodai 44769626Sru 44869626Sru@c ===================================================================== 44969626Sru 45055839Sasmodai@node What Is groff?, History, Introduction, Introduction 45155839Sasmodai@section What Is @code{groff}? 45255839Sasmodai@cindex what is @code{groff}? 45355839Sasmodai@cindex @code{groff} -- what is it? 45455839Sasmodai 45569626Sru@code{groff} belongs to an older generation of document preparation 45669626Srusystems, which operate more like compilers than the more recent 45769626Sruinteractive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 45869626Srusystems. @code{groff} and its contemporary counterpart, @TeX{}, both 45969626Sruwork using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 46069626Srunormal text files with embedded formatting commands. These files can 46169626Sruthen be processed by @code{groff} to produce a typeset document on a 46269626Sruvariety of devices. 46355839Sasmodai 46455839SasmodaiLikewise, @code{groff} should not be confused with a @dfn{word 46575584Sruprocessor}, since that term connotes an integrated system that includes 46655839Sasmodaian editor and a text formatter. Also, many word processors follow the 46775584Sru@acronym{WYSIWYG} paradigm discussed earlier. 46855839Sasmodai 46969626SruAlthough @acronym{WYSIWYG} systems may be easier to use, they have a 47069626Srunumber of disadvantages compared to @code{troff}: 47155839Sasmodai 47269626Sru@itemize @bullet 47355839Sasmodai@item 47475584SruThey must be used on a graphics display to work on a document. 47569626Sru 47655839Sasmodai@item 47769626SruMost of the @acronym{WYSIWYG} systems are either non-free or are not 47869626Sruvery portable. 47969626Sru 48055839Sasmodai@item 48169626Sru@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 48269626Sru 48355839Sasmodai@item 48455839SasmodaiIt is difficult to have a wide range of capabilities available within 48555839Sasmodaithe confines of a GUI/window system. 48669626Sru 48755839Sasmodai@item 48855839SasmodaiIt is more difficult to make global changes to a document. 48955839Sasmodai@end itemize 49055839Sasmodai 49155839Sasmodai@quotation 49255839Sasmodai``GUIs normally make it simple to accomplish simple actions and 49355839Sasmodaiimpossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 49455839Sasmodai@code{comp.unix.wizards}) 49555839Sasmodai@end quotation 49655839Sasmodai 49755839Sasmodai 49869626Sru@c ===================================================================== 49955839Sasmodai 50055839Sasmodai@node History, groff Capabilities, What Is groff?, Introduction 50155839Sasmodai@section History 50255839Sasmodai@cindex history 50355839Sasmodai 504104862Sru@cindex @code{runoff}, the program 505104862Sru@cindex @code{rf}, the program 50655839Sasmodai@code{troff} can trace its origins back to a formatting program called 507114402Sru@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS 50869626Sruoperating system in the mid-sixties. This name came from the common 50969626Sruphrase of the time ``I'll run off a document.'' Bob Morris ported it to 51069626Sruthe 635 architecture and called the program @code{roff} (an abbreviation 51175584Sruof @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 51275584Sru(before having @acronym{UNIX}), and at the same time (1969), Doug 51369626SruMcIllroy rewrote an extended and simplified version of @code{roff} in 51469626Sruthe @acronym{BCPL} programming language. 51555839Sasmodai 516104862Sru@cindex @code{roff}, the program 51775584SruThe first version of @acronym{UNIX} was developed on a @w{PDP-7} which 51875584Sruwas sitting around Bell Labs. In 1971 the developers wanted to get a 51975584Sru@w{PDP-11} for further work on the operating system. In order to 52075584Srujustify the cost for this system, they proposed that they would 521104862Sruimplement a document formatting system for the @acronym{AT&T} patents 522104862Srudivision. This first formatting program was a reimplementation of 523114402SruMcIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna. 52455839Sasmodai 525104862Sru@cindex @code{nroff}, the program 52655839SasmodaiWhen they needed a more flexible language, a new version of @code{roff} 52769626Srucalled @code{nroff} (``Newer @code{roff}'') was written. It had a much 52869626Srumore complicated syntax, but provided the basis for all future versions. 52969626SruWhen they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 53075584Sruversion of @code{nroff} that would drive it. It was dubbed 53169626Sru@code{troff}, for ``typesetter @code{roff}'', although many people have 53269626Sruspeculated that it actually means ``Times @code{roff}'' because of the 53369626Sruuse of the Times font family in @code{troff} by default. As such, the 53469626Sruname @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 53555839Sasmodai 53655839SasmodaiWith @code{troff} came @code{nroff} (they were actually the same program 53769626Sruexcept for some @samp{#ifdef}s), which was for producing output for line 53869626Sruprinters and character terminals. It understood everything @code{troff} 53969626Srudid, and ignored the commands which were not applicable (e.g.@: font 54055839Sasmodaichanges). 54155839Sasmodai 54255839SasmodaiSince there are several things which cannot be done easily in 54355839Sasmodai@code{troff}, work on several preprocessors began. These programs would 54455839Sasmodaitransform certain parts of a document into @code{troff}, which made a 54569626Sruvery natural use of pipes in @acronym{UNIX}. 54655839Sasmodai 54755839SasmodaiThe @code{eqn} preprocessor allowed mathematical formul@ae{} to be 54855839Sasmodaispecified in a much simpler and more intuitive manner. @code{tbl} is a 54955839Sasmodaipreprocessor for formatting tables. The @code{refer} preprocessor (and 55055839Sasmodaithe similar program, @code{bib}) processes citations in a document 55155839Sasmodaiaccording to a bibliographic database. 55255839Sasmodai 55375584SruUnfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 55455839Sasmodailanguage and produced output specifically for the CAT phototypesetter. 555114402SruHe rewrote it in C, although it was now 7000@tie{}lines of uncommented 55655839Sasmodaicode and still dependent on the CAT. As the CAT became less common, and 55755839Sasmodaiwas no longer supported by the manufacturer, the need to make it support 55869626Sruother devices became a priority. However, before this could be done, 559104862SruOssanna was killed in a car accident. 56055839Sasmodai 56155839Sasmodai@pindex ditroff 562104862Sru@cindex @code{ditroff}, the program 56355839SasmodaiSo, Brian Kernighan took on the task of rewriting @code{troff}. The 564104862Srunewly rewritten version produced device independent code which was 56555839Sasmodaivery easy for postprocessors to read and translate to the appropriate 56655839Sasmodaiprinter codes. Also, this new version of @code{troff} (called 56769626Sru@code{ditroff} for ``device independent @code{troff}'') had several 56869626Sruextensions, which included drawing functions. 56955839Sasmodai 57055839SasmodaiDue to the additional abilities of the new version of @code{troff}, 57155839Sasmodaiseveral new preprocessors appeared. The @code{pic} preprocessor 57255839Sasmodaiprovides a wide range of drawing functions. Likewise the @code{ideal} 57355839Sasmodaipreprocessor did the same, although via a much different paradigm. The 57455839Sasmodai@code{grap} preprocessor took specifications for graphs, but, unlike 57555839Sasmodaiother preprocessors, produced @code{pic} code. 57655839Sasmodai 57755839SasmodaiJames Clark began work on a GNU implementation of @code{ditroff} in 578114402Sruearly@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released 579114402SruJune@tie{}1990. @code{groff} included: 58055839Sasmodai 58169626Sru@itemize @bullet 58255839Sasmodai@item 58369626SruA replacement for @code{ditroff} with many extensions. 58469626Sru 58555839Sasmodai@item 58655839SasmodaiThe @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 58769626Sru 58855839Sasmodai@item 58975584SruPostprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 590114402SruX@tie{}Windows. GNU @code{troff} also eliminated the need for a 59169626Sruseparate @code{nroff} program with a postprocessor which would produce 59269626Sru@acronym{ASCII} output. 59369626Sru 59455839Sasmodai@item 59569626SruA version of the @file{me} macros and an implementation of the 59669626Sru@file{man} macros. 59755839Sasmodai@end itemize 59855839Sasmodai 59955839SasmodaiAlso, a front-end was included which could construct the, sometimes 60055839Sasmodaipainfully long, pipelines required for all the post- and preprocessors. 60155839Sasmodai 60255839SasmodaiDevelopment of GNU @code{troff} progressed rapidly, and saw the 60355839Sasmodaiadditions of a replacement for @code{refer}, an implementation of the 60469626Sru@file{ms} and @file{mm} macros, and a program to deduce how to format a 60569626Srudocument (@code{grog}). 60655839Sasmodai 60769626SruIt was declared a stable (i.e.@: non-beta) package with the release of 608114402Sruversion@tie{}1.04 around November@tie{}1991. 60955839Sasmodai 610114402SruBeginning in@tie{}1999, @code{groff} has new maintainers (the package was 61169626Sruan orphan for a few years). As a result, new features and programs like 61275584Sru@code{grn}, a preprocessor for gremlin images, and an output device to 61375584Sruproduce @acronym{HTML} output have been added. 61455839Sasmodai 61555839Sasmodai 61669626Sru@c ===================================================================== 61769626Sru 61869626Sru@node groff Capabilities, Macro Package Intro, History, Introduction 61955839Sasmodai@section @code{groff} Capabilities 62055839Sasmodai@cindex @code{groff} capabilities 62155839Sasmodai@cindex capabilities of @code{groff} 62255839Sasmodai 62355839SasmodaiSo what exactly is @code{groff} capable of doing? @code{groff} provides 62469626Srua wide range of low-level text formatting operations. Using these, it 62569626Sruis possible to perform a wide range of formatting tasks, such as 62669626Srufootnotes, table of contents, multiple columns, etc. Here's a list of 62769626Sruthe most important operations supported by @code{groff}: 62855839Sasmodai 62969626Sru@itemize @bullet 63055839Sasmodai@item 63169626Srutext filling, adjusting, and centering 63269626Sru 63355839Sasmodai@item 63469626Sruhyphenation 63569626Sru 63655839Sasmodai@item 63769626Srupage control 63869626Sru 63955839Sasmodai@item 640104862Srufont and glyph size control 64169626Sru 64255839Sasmodai@item 643104862Sruvertical spacing (e.g.@: double-spacing) 64469626Sru 64555839Sasmodai@item 64669626Sruline length and indenting 64769626Sru 64855839Sasmodai@item 64969626Srumacros, strings, diversions, and traps 65069626Sru 65155839Sasmodai@item 65269626Srunumber registers 65369626Sru 65455839Sasmodai@item 65569626Srutabs, leaders, and fields 65669626Sru 65755839Sasmodai@item 65869626Sruinput and output conventions and character translation 65969626Sru 66055839Sasmodai@item 66169626Sruoverstrike, bracket, line drawing, and zero-width functions 66269626Sru 66355839Sasmodai@item 66469626Srulocal horizontal and vertical motions and the width function 66569626Sru 66655839Sasmodai@item 66769626Sruthree-part titles 66869626Sru 66955839Sasmodai@item 67069626Sruoutput line numbering 67169626Sru 67255839Sasmodai@item 67369626Sruconditional acceptance of input 67469626Sru 67555839Sasmodai@item 67669626Sruenvironment switching 67769626Sru 67855839Sasmodai@item 67969626Sruinsertions from the standard input 68069626Sru 68155839Sasmodai@item 68269626Sruinput/output file switching 68369626Sru 68455839Sasmodai@item 68569626Sruoutput and error messages 68655839Sasmodai@end itemize 68755839Sasmodai 68855839Sasmodai 68969626Sru@c ===================================================================== 69069626Sru 69169626Sru@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 69255839Sasmodai@section Macro Packages 69355839Sasmodai@cindex macro packages 69455839Sasmodai 69569626SruSince @code{groff} provides such low-level facilities, it can be quite 69655839Sasmodaidifficult to use by itself. However, @code{groff} provides a 697114402Sru@dfn{macro} facility to specify how certain routine operations 698114402Sru(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@: 699114402Srushould be done. These macros can be collected together into a @dfn{macro 70069626Srupackage}. There are a number of macro packages available; the most 70169626Srucommon (and the ones described in this manual) are @file{man}, 70269626Sru@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 70355839Sasmodai 70455839Sasmodai 70569626Sru@c ===================================================================== 70669626Sru 70769626Sru@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 70855839Sasmodai@section Preprocessors 70955839Sasmodai@cindex preprocessors 71055839Sasmodai 71155839SasmodaiAlthough @code{groff} provides most functions needed to format a 71269626Srudocument, some operations would be unwieldy (e.g.@: to draw pictures). 713104862SruTherefore, programs called @dfn{preprocessors} were written which 714104862Sruunderstand their own language and produce the necessary @code{groff} 715104862Sruoperations. These preprocessors are able to differentiate their own 716104862Sruinput from the rest of the document via markers. 71755839Sasmodai 71869626SruTo use a preprocessor, @acronym{UNIX} pipes are used to feed the output 71969626Srufrom the preprocessor into @code{groff}. Any number of preprocessors 72069626Srumay be used on a given document; in this case, the preprocessors are 721104862Srulinked together into one pipeline. However, with @code{groff}, the user 72269626Srudoes not need to construct the pipe, but only tell @code{groff} what 72355839Sasmodaipreprocessors to use. 72455839Sasmodai 72555839Sasmodai@code{groff} currently has preprocessors for producing tables 72655839Sasmodai(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 72769626Sru(@code{pic} and @code{grn}), and for processing bibliographies 72869626Sru(@code{refer}). An associated program which is useful when dealing with 72969626Srupreprocessors is @code{soelim}. 73055839Sasmodai 73169626SruA free implementation of @code{grap}, a preprocessor for drawing graphs, 73269626Srucan be obtained as an extra package; @code{groff} can use @code{grap} 73369626Srualso. 73455839Sasmodai 73569626SruThere are other preprocessors in existence, but, unfortunately, no free 73669626Sruimplementations are available. Among them are preprocessors for drawing 73769626Srumathematical pictures (@code{ideal}) and chemical structures 73869626Sru(@code{chem}). 73955839Sasmodai 74069626Sru 74169626Sru@c ===================================================================== 74269626Sru 74369626Sru@node Output device intro, Credits, Preprocessor Intro, Introduction 74469626Sru@section Output Devices 74555839Sasmodai@cindex postprocessors 74669626Sru@cindex output devices 74769626Sru@cindex devices for output 74855839Sasmodai 74975584Sru@code{groff} actually produces device independent code which may be 75075584Srufed into a postprocessor to produce output for a particular device. 75175584SruCurrently, @code{groff} has postprocessors for @sc{PostScript} 752114402Srudevices, character terminals, X@tie{}Windows (for previewing), @TeX{} 753114402SruDVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use 75469626Sru@acronym{CAPSL}), and @acronym{HTML}. 75555839Sasmodai 75655839Sasmodai 75769626Sru@c ===================================================================== 75869626Sru 75969626Sru@node Credits, , Output device intro, Introduction 76055839Sasmodai@section Credits 76155839Sasmodai@cindex credits 76255839Sasmodai 76355839SasmodaiLarge portions of this manual were taken from existing documents, most 76455839Sasmodainotably, the manual pages for the @code{groff} package by James Clark, 76569626Sruand Eric Allman's papers on the @file{me} macro package. 76655839Sasmodai 767114402SruThe section on the @file{man} macro package is partly based on 768114402SruSusan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the 769114402SruDebian GNU/Linux system. 77055839Sasmodai 771104862SruLarry Kollar contributed the section in the @file{ms} macro package. 77255839Sasmodai 77369626Sru 77475584Sru 77569626Sru@c ===================================================================== 77669626Sru@c ===================================================================== 77769626Sru 77855839Sasmodai@node Invoking groff, Tutorial for Macro Users, Introduction, Top 77955839Sasmodai@chapter Invoking @code{groff} 78055839Sasmodai@cindex invoking @code{groff} 78155839Sasmodai@cindex @code{groff} invocation 78255839Sasmodai 78355839SasmodaiThis section focuses on how to invoke the @code{groff} front end. This 78455839Sasmodaifront end takes care of the details of constructing the pipeline among 78555839Sasmodaithe preprocessors, @code{gtroff} and the postprocessor. 78655839Sasmodai 78769626SruIt has become a tradition that GNU programs get the prefix @samp{g} to 78869626Srudistinguish it from its original counterparts provided by the host (see 78969626Sru@ref{Environment}, for more details). Thus, for example, @code{geqn} is 790104862SruGNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 791104862Srudon't contain proprietary versions of @code{troff}, and on 792104862SruMS-DOS/MS-Windows, where @code{troff} and associated programs are not 793104862Sruavailable at all, this prefix is omitted since GNU @code{troff} is the 794104862Sruonly used incarnation of @code{troff}. Exception: @samp{groff} is never 795104862Srureplaced by @samp{roff}. 79655839Sasmodai 797104862SruIn this document, we consequently say @samp{gtroff} when talking about 798104862Sruthe GNU @code{troff} program. All other implementations of @code{troff} 799104862Sruare called @acronym{AT&T} @code{troff} which is the common origin of 800104862Sruall @code{troff} derivates (with more or less compatible changes). 801104862SruSimilarly, we say @samp{gpic}, @samp{geqn}, etc. 802104862Sru 80355839Sasmodai@menu 80475584Sru* Groff Options:: 80575584Sru* Environment:: 806104862Sru* Macro Directories:: 807104862Sru* Font Directories:: 808114402Sru* Paper Size:: 80975584Sru* Invocation Examples:: 81055839Sasmodai@end menu 81155839Sasmodai 81269626Sru 81369626Sru@c ===================================================================== 81469626Sru 81569626Sru@node Groff Options, Environment, Invoking groff, Invoking groff 81655839Sasmodai@section Options 81755839Sasmodai@cindex options 81855839Sasmodai 81955839Sasmodai@pindex groff 82055839Sasmodai@pindex gtroff 82155839Sasmodai@pindex gpic 82255839Sasmodai@pindex geqn 82369626Sru@pindex ggrn 82469626Sru@pindex grap 82555839Sasmodai@pindex gtbl 82655839Sasmodai@pindex grefer 82755839Sasmodai@pindex gsoelim 82869626Sru@code{groff} normally runs the @code{gtroff} program and a postprocessor 82969626Sruappropriate for the selected device. The default device is @samp{ps} 83069626Sru(but it can be changed when @code{groff} is configured and built). It 83169626Srucan optionally preprocess with any of @code{gpic}, @code{geqn}, 83269626Sru@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 83355839Sasmodai 83455839SasmodaiThis section only documents options to the @code{groff} front end. Many 83555839Sasmodaiof the arguments to @code{groff} are passed on to @code{gtroff}, 83655839Sasmodaitherefore those are also included. Arguments to pre- or postprocessors 83755839Sasmodaican be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 83869626Srugtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 83969626Srugsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 84069626Srugrohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 84169626Srugrolbp}, and @ref{Invoking gxditview}. 84255839Sasmodai 84355839SasmodaiThe command line format for @code{groff} is: 84455839Sasmodai 84575584Sru@Example 846104862Srugroff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 84755839Sasmodai [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 84855839Sasmodai [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 84969626Sru [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 85055839Sasmodai [ @var{files}@dots{} ] 85175584Sru@endExample 85255839Sasmodai 85369626SruThe command line format for @code{gtroff} is as follows. 85455839Sasmodai 85575584Sru@Example 856104862Srugtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 85755839Sasmodai [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 85855839Sasmodai [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 85955839Sasmodai [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 86075584Sru@endExample 86155839Sasmodai 86269626Sru@noindent 86375584SruObviously, many of the options to @code{groff} are actually passed on to 86475584Sru@code{gtroff}. 86555839Sasmodai 866114402SruOptions without an argument can be grouped behind a single@tie{}@option{-}. 867114402SruA filename of@tie{}@file{-} denotes the standard input. It is possible to 86869626Sruhave whitespace between an option and its parameter. 86969626Sru 87055839SasmodaiThe @code{grog} command can be used to guess the correct @code{groff} 87169626Srucommand to format a file. 87255839Sasmodai 87369626SruHere's the description of the command-line options: 87469626Sru 87569626Sru@cindex command-line options 87655839Sasmodai@table @samp 87755839Sasmodai@item -h 87855839SasmodaiPrint a help message. 87969626Sru 88055839Sasmodai@item -e 88155839SasmodaiPreprocess with @code{geqn}. 88269626Sru 88355839Sasmodai@item -t 88455839SasmodaiPreprocess with @code{gtbl}. 88569626Sru 88669626Sru@item -g 88769626SruPreprocess with @code{ggrn}. 88869626Sru 88969626Sru@item -G 89069626SruPreprocess with @code{grap}. 89169626Sru 89255839Sasmodai@item -p 89355839SasmodaiPreprocess with @code{gpic}. 89469626Sru 89555839Sasmodai@item -s 89655839SasmodaiPreprocess with @code{gsoelim}. 89769626Sru 898104862Sru@item -c 899104862SruSuppress color output. 900104862Sru 90155839Sasmodai@item -R 90255839SasmodaiPreprocess with @code{grefer}. No mechanism is provided for passing 90355839Sasmodaiarguments to @code{grefer} because most @code{grefer} options have 90455839Sasmodaiequivalent commands which can be included in the file. @xref{grefer}, 90555839Sasmodaifor more details. 90655839Sasmodai 90755839Sasmodai@pindex troffrc 90869626Sru@pindex troffrc-end 90969626SruNote that @code{gtroff} also accepts a @option{-R} option, which is not 91055839Sasmodaiaccessible via @code{groff}. This option prevents the loading of the 91169626Sru@file{troffrc} and @file{troffrc-end} files. 91269626Sru 91355839Sasmodai@item -v 91455839SasmodaiMake programs run by @code{groff} print out their version number. 91569626Sru 91655839Sasmodai@item -V 91775584SruPrint the pipeline on @code{stdout} instead of executing it. 91869626Sru 91955839Sasmodai@item -z 92075584SruSuppress output from @code{gtroff}. Only error messages are printed. 92169626Sru 92255839Sasmodai@item -Z 92355839SasmodaiDo not postprocess the output of @code{gtroff}. Normally @code{groff} 92475584Sruautomatically runs the appropriate postprocessor. 92569626Sru 92655839Sasmodai@item -P@var{arg} 92755839SasmodaiPass @var{arg} to the postprocessor. Each argument should be passed 92869626Sruwith a separate @option{-P} option. Note that @code{groff} does not 92969626Sruprepend @samp{-} to @var{arg} before passing it to the postprocessor. 93069626Sru 93155839Sasmodai@item -l 93275584SruSend the output to a spooler for printing. The command used for this is 93375584Sruspecified by the @code{print} command in the device description file 93475584Sru(see @ref{Font Files}, for more info). If not present, @option{-l} is 93575584Sruignored. 93669626Sru 93755839Sasmodai@item -L@var{arg} 93855839SasmodaiPass @var{arg} to the spooler. Each argument should be passed with a 939104862Sruseparate @option{-L} option. Note that @code{groff} does not prepend 940104862Srua @samp{-} to @var{arg} before passing it to the postprocessor. 941104862SruIf the @code{print} keyword in the device description file is missing, 94275584Sru@option{-L} is ignored. 94369626Sru 94455839Sasmodai@item -T@var{dev} 94569626SruPrepare output for device @var{dev}. The default device is @samp{ps}, 94669626Sruunless changed when @code{groff} was configured and built. The 94769626Srufollowing are the output devices currently available: 94869626Sru 94969626Sru@table @code 95055839Sasmodai@item ps 95175584SruFor @sc{PostScript} printers and previewers. 95269626Sru 95355839Sasmodai@item dvi 95469626SruFor @TeX{} DVI format. 95569626Sru 95655839Sasmodai@item X75 95769626SruFor a 75@dmn{dpi} X11 previewer. 95869626Sru 959104862Sru@item X75-12 960104862SruFor a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 961104862Srudocument. 962104862Sru 96355839Sasmodai@item X100 96469626SruFor a 100@dmn{dpi} X11 previewer. 96569626Sru 966104862Sru@item X100-12 967104862SruFor a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 968104862Srudocument. 969104862Sru 97055839Sasmodai@item ascii 971114402Sru@cindex encoding, output, @acronym{ASCII} 972114402Sru@cindex @acronym{ASCII}, output encoding 973114402Sru@cindex output encoding, @acronym{ASCII} 974104862SruFor typewriter-like devices using the (7-bit) @acronym{ASCII} 975104862Srucharacter set. 97669626Sru 97755839Sasmodai@item latin1 978114402Sru@cindex encoding, output, @w{latin-1} (ISO @w{8859-1}) 979114402Sru@cindex @w{latin-1} (ISO @w{8859-1}), output encoding 980114402Sru@cindex ISO @w{8859-1} (@w{latin-1}), output encoding 981114402Sru@cindex output encoding, @w{latin-1} (ISO @w{8859-1}) 982114402SruFor typewriter-like devices that support the @w{Latin-1} 983114402Sru(ISO@tie{}@w{8859-1}) character set. 98469626Sru 98569626Sru@item utf8 986114402Sru@cindex encoding, output, @w{utf-8} 987114402Sru@cindex @w{utf-8}, output encoding 988114402Sru@cindex output encoding, @w{utf-8} 989114402SruFor typewriter-like devices which use the Unicode (ISO@tie{}10646) 99069626Srucharacter set with @w{UTF-8} encoding. 99169626Sru 99269626Sru@item cp1047 993114402Sru@cindex encoding, output, @acronym{EBCDIC} 994114402Sru@cindex @acronym{EBCDIC}, output encoding 995114402Sru@cindex output encoding, @acronym{EBCDIC} 996114402Sru@cindex encoding, output, cp1047 997114402Sru@cindex cp1047, output encoding 998114402Sru@cindex output encoding, cp1047 999114402Sru@cindex IBM cp1047 output encoding 100069626SruFor typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 100169626Srucp1047. 100269626Sru 100355839Sasmodai@item lj4 1004104862SruFor HP LaserJet4-compatible (or other PCL5-compatible) printers. 100569626Sru 100669626Sru@item lbp 100769626SruFor Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 100869626Sruprinters). 100969626Sru 101075584Sru@pindex pre-grohtml 101175584Sru@pindex post-grohtml 1012104862Sru@cindex @code{grohtml}, the program 101355839Sasmodai@item html 101475584SruTo produce @acronym{HTML} output. Note that the @acronym{HTML} driver 101575584Sruconsists of two parts, a preprocessor (@code{pre-grohtml}) and a 101675584Srupostprocessor (@code{post-grohtml}). 101755839Sasmodai@end table 101855839Sasmodai 1019104862Sru@cindex output device name string register (@code{.T}) 1020104862Sru@cindex output device usage number register (@code{.T}) 102169626SruThe predefined @code{gtroff} string register @code{.T} contains the 102269626Srucurrent output device; the read-only number register @code{.T} is set 1023114402Sruto@tie{}1 if this option is used (which is always true if @code{groff} is 102469626Sruused to call @code{gtroff}). @xref{Built-in Registers}. 102569626Sru 102655839SasmodaiThe postprocessor to be used for a device is specified by the 102755839Sasmodai@code{postpro} command in the device description file. (@xref{Font 102869626SruFiles}, for more info.) This can be overridden with the @option{-X} 102955839Sasmodaioption. 103069626Sru 103155839Sasmodai@item -X 103255839SasmodaiPreview with @code{gxditview} instead of using the usual postprocessor. 103369626SruThis is unlikely to produce good results except with @option{-Tps}. 103469626Sru 103569626SruNote that this is not the same as using @option{-TX75} or 103669626Sru@option{-TX100} to view a document with @code{gxditview}: The former 103775584Sruuses the metrics of the specified device, whereas the latter uses 103875584SruX-specific fonts and metrics. 103969626Sru 104055839Sasmodai@item -N 104155839SasmodaiDon't allow newlines with @code{eqn} delimiters. This is the same as 104269626Sruthe @option{-N} option in @code{geqn}. 104369626Sru 104455839Sasmodai@item -S 1045104862Sru@cindex @code{open} request, and safer mode 1046104862Sru@cindex @code{opena} request, and safer mode 1047104862Sru@cindex @code{pso} request, and safer mode 1048104862Sru@cindex @code{sy} request, and safer mode 1049104862Sru@cindex @code{pi} request, and safer mode 1050104862Sru@cindex safer mode 1051104862Sru@cindex mode, safer 105275584SruSafer mode. Pass the @option{-S} option to @code{gpic} and disable the 105375584Sru@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 105475584Srurequests. For security reasons, this is enabled by default. 105569626Sru 105669626Sru@item -U 1057104862Sru@cindex mode, unsafe 1058104862Sru@cindex unsafe mode 1059104862SruUnsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1060104862Sru@code{sy}, and @code{pi} requests. 106169626Sru 106255839Sasmodai@item -a 1063104862Sru@cindex @acronym{ASCII} approximation output register (@code{.A}) 106469626SruGenerate an @acronym{ASCII} approximation of the typeset output. The 1065114402Sruread-only register @code{.A} is then set to@tie{}1. @xref{Built-in 106675584SruRegisters}. A typical example is 106769626Sru 106875584Sru@Example 106975584Srugroff -a -man -Tdvi troff.man | less 107075584Sru@endExample 107175584Sru 107275584Sru@noindent 107375584Sruwhich shows how lines are broken for the DVI device. Note that this 107475584Sruoption is rather useless today since graphic output devices are 107575584Sruavailable virtually everywhere. 107675584Sru 107755839Sasmodai@item -b 107855839SasmodaiPrint a backtrace with each warning or error message. This backtrace 107955839Sasmodaishould help track down the cause of the error. The line numbers given 108069626Sruin the backtrace may not always be correct: @code{gtroff} can get 108169626Sruconfused by @code{as} or @code{am} requests while counting line numbers. 108269626Sru 108355839Sasmodai@item -i 108455839SasmodaiRead the standard input after all the named input files have been 108555839Sasmodaiprocessed. 108669626Sru 108755839Sasmodai@item -w@var{name} 108855839SasmodaiEnable warning @var{name}. Available warnings are described in 108969626Sru@ref{Debugging}. Multiple @option{-w} options are allowed. 109069626Sru 109155839Sasmodai@item -W@var{name} 109269626SruInhibit warning @var{name}. Multiple @option{-W} options are allowed. 109369626Sru 109455839Sasmodai@item -E 109555839SasmodaiInhibit all error messages. 109669626Sru 109755839Sasmodai@item -C 109869626SruEnable compatibility mode. @xref{Implementation Differences}, for the 1099104862Srulist of incompatibilities between @code{groff} and @acronym{AT&T} 110069626Sru@code{troff}. 110169626Sru 1102104862Sru@item -d@var{c}@var{s} 1103104862Sru@itemx -d@var{name}=@var{s} 1104114402SruDefine @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must 1105104862Srube a one-letter name; @var{name} can be of arbitrary length. All string 110675584Sruassignments happen before loading any macro file (including the start-up 110775584Srufile). 110869626Sru 110955839Sasmodai@item -f@var{fam} 111075584SruUse @var{fam} as the default font family. @xref{Font Families}. 111169626Sru 111255839Sasmodai@item -m@var{name} 111375584SruRead in the file @file{@var{name}.tmac}. Normally @code{groff} searches 111475584Srufor this in its macro directories. If it isn't found, it tries 1115104862Sru@file{tmac.@var{name}} (searching in the same directories). 111669626Sru 111755839Sasmodai@item -n@var{num} 111855839SasmodaiNumber the first page @var{num}. 111969626Sru 112055839Sasmodai@item -o@var{list} 1121104862Sru@cindex print current page register (@code{.P}) 112255839SasmodaiOutput only pages in @var{list}, which is a comma-separated list of page 1123114402Sruranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}} 1124114402Srumeans print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} 1125114402Srumeans print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every 1126114402Srupage beginning with@tie{}@var{n}. @code{gtroff} exits after printing the 112769626Srulast page in the list. All the ranges are inclusive on both ends. 112869626Sru 112969626SruWithin @code{gtroff}, this information can be extracted with the 113069626Sru@samp{.P} register. @xref{Built-in Registers}. 113169626Sru 113275584SruIf your document restarts page numbering at the beginning of each 113375584Sruchapter, then @code{gtroff} prints the specified page range for each 113475584Sruchapter. 113575584Sru 1136104862Sru@item -r@var{c}@var{n} 113755839Sasmodai@itemx -r@var{name}=@var{n} 1138114402SruSet number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. 1139114402Sru@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary 1140114402Srulength. @var{n}@tie{}can be any @code{gtroff} numeric expression. All 1141114402Sruregister assignments happen before loading any macro file (including 1142104862Sruthe start-up file). 114369626Sru 114455839Sasmodai@item -F@var{dir} 114569626SruSearch @file{@var{dir}} for subdirectories @file{dev@var{name}} 114669626Sru(@var{name} is the name of the device), for the @file{DESC} file, and 1147104862Srufor font files before looking in the standard directories (@pxref{Font 1148104862SruDirectories}). This option is passed to all pre- and postprocessors 1149104862Sruusing the @env{GROFF_FONT_PATH} environment variable. 115069626Sru 115155839Sasmodai@item -M@var{dir} 115269626SruSearch directory @file{@var{dir}} for macro files before the standard 1153104862Srudirectories (@pxref{Macro Directories}). 115469626Sru 115569626Sru@item -I@var{dir} 115669626SruThis option is as described in @ref{gsoelim}. It implies the 115769626Sru@option{-s} option. 115855839Sasmodai@end table 115955839Sasmodai 116055839Sasmodai 116169626Sru@c ===================================================================== 116255839Sasmodai 1163104862Sru@node Environment, Macro Directories, Groff Options, Invoking groff 116455839Sasmodai@section Environment 116569626Sru@cindex environment variables 116669626Sru@cindex variables in environment 116755839Sasmodai 116869626SruThere are also several environment variables (of the operating system, 116969626Srunot within @code{gtroff}) which can modify the behavior of @code{groff}. 117055839Sasmodai 117155839Sasmodai@table @code 117255839Sasmodai@item GROFF_COMMAND_PREFIX 1173104862Sru@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1174104862Sru@cindex command prefix 1175104862Sru@cindex prefix, for commands 1176114402SruIf this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff} 117775584Sruinstead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 117875584Sru@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 117975584Sruapply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 118075584Sru@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 118169626Sru 1182104862SruThe default command prefix is determined during the installation process. 1183104862SruIf a non-GNU troff system is found, prefix @samp{g} is used, none 1184104862Sruotherwise. 118575584Sru 118655839Sasmodai@item GROFF_TMAC_PATH 1187104862Sru@tindex GROFF_TMAC_PATH@r{, environment variable} 118875584SruA colon-separated list of directories in which to search for macro files 1189104862Sru(before the default directories are tried). @xref{Macro Directories}. 119069626Sru 119155839Sasmodai@item GROFF_TYPESETTER 1192104862Sru@tindex GROFF_TYPESETTER@r{, environment variable} 119369626SruThe default output device. 119469626Sru 119555839Sasmodai@item GROFF_FONT_PATH 1196104862Sru@tindex GROFF_FONT_PATH@r{, environment variable} 119769626SruA colon-separated list of directories in which to search for the 119875584Sru@code{dev}@var{name} directory (before the default directories are 1199104862Srutried). @xref{Font Directories}. 120069626Sru 120175584Sru@item GROFF_BIN_PATH 1202104862Sru@tindex GROFF_BIN_PATH@r{, environment variable} 120375584SruThis search path, followed by @code{PATH}, is used for commands executed 120475584Sruby @code{groff}. 120569626Sru 120655839Sasmodai@item GROFF_TMPDIR 1207104862Sru@tindex GROFF_TMPDIR@r{, environment variable} 1208104862Sru@tindex TMPDIR@r{, environment variable} 120975584SruThe directory in which @code{groff} creates temporary files. If this is 121075584Srunot set and @env{TMPDIR} is set, temporary files are created in that 121175584Srudirectory. Otherwise temporary files are created in a system-dependent 121275584Srudefault directory (on Unix and GNU/Linux systems, this is usually 121375584Sru@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 121475584Sru@code{post-grohtml} can create temporary files in this directory. 121555839Sasmodai@end table 121655839Sasmodai 121769626SruNote that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 121869626Srurather than colons, to separate the directories in the lists described 121969626Sruabove. 122055839Sasmodai 122169626Sru 122269626Sru@c ===================================================================== 122369626Sru 1224104862Sru@node Macro Directories, Font Directories, Environment, Invoking groff 1225104862Sru@section Macro Directories 1226104862Sru@cindex macro directories 1227104862Sru@cindex directories for macros 1228104862Sru@cindex searching macros 1229104862Sru@cindex macros, searching 1230104862Sru 1231104862SruAll macro file names must be named @code{@var{name}.tmac} or 1232104862Sru@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1233104862Sruoption work. The @code{mso} request doesn't have this restriction; any 1234104862Srufile name can be used, and @code{gtroff} won't try to append or prepend 1235104862Sruthe @samp{tmac} string. 1236104862Sru 1237104862Sru@cindex tmac, directory 1238104862Sru@cindex directory, for tmac files 1239104862Sru@cindex tmac, path 1240104862Sru@cindex path, for tmac files 1241104862Sru@cindex searching macro files 1242104862Sru@cindex macro files, searching 1243104862Sru@cindex files, macro, searching 1244104862SruMacro files are kept in the @dfn{tmac directories}, all of which 1245104862Sruconstitute the @dfn{tmac path}. The elements of the search path for 1246104862Srumacro files are (in that order): 1247104862Sru 1248104862Sru@itemize @bullet 1249104862Sru@item 1250104862SruThe directories specified with @code{gtroff}'s or @code{groff}'s 1251104862Sru@option{-M} command line option. 1252104862Sru 1253104862Sru@item 1254104862Sru@tindex GROFF_TMAC_PATH@r{, environment variable} 1255104862SruThe directories given in the @env{GROFF_TMAC_PATH} environment 1256104862Sruvariable. 1257104862Sru 1258104862Sru@item 1259104862Sru@cindex safer mode 1260104862Sru@cindex mode, safer 1261104862Sru@cindex unsafe mode 1262104862Sru@cindex mode, unsafe 1263104862Sru@cindex current directory 1264104862Sru@cindex directory, current 1265104862SruThe current directory (only if in unsafe mode using the @option{-U} 1266104862Srucommand line switch). 1267104862Sru 1268104862Sru@item 1269104862Sru@cindex home directory 1270104862Sru@cindex directory, home 1271104862SruThe home directory. 1272104862Sru 1273104862Sru@item 1274104862Sru@cindex site-specific directory 1275104862Sru@cindex directory, site-specific 1276104862Sru@cindex platform-specific directory 1277104862Sru@cindex directory, platform-specific 1278104862SruA platform-dependent directory, a site-specific (platform-independent) 1279104862Srudirectory, and the main tmac directory; the default locations are 1280104862Sru 1281104862Sru@Example 1282104862Sru/usr/local/lib/groff/site-tmac 1283104862Sru/usr/local/share/groff/site-tmac 1284114402Sru/usr/local/share/groff/1.18.2/tmac 1285104862Sru@endExample 1286104862Sru 1287104862Sru@noindent 1288114402Sruassuming that the version of @code{groff} is 1.18.2, and the installation 1289104862Sruprefix was @file{/usr/local}. It is possible to fine-tune those 1290104862Srudirectories during the installation process. 1291104862Sru@end itemize 1292104862Sru 1293104862Sru 1294104862Sru@c ===================================================================== 1295104862Sru 1296114402Sru@node Font Directories, Paper Size, Macro Directories, Invoking groff 1297104862Sru@section Font Directories 1298104862Sru@cindex font directories 1299104862Sru@cindex directories for fonts 1300104862Sru@cindex searching fonts 1301104862Sru@cindex fonts, searching 1302104862Sru 1303104862SruBasically, there is no restriction how font files for @code{groff} are 1304104862Srunamed and how long font names are; however, to make the font family 1305104862Srumechanism work (@pxref{Font Families}), fonts within a family should 1306104862Srustart with the family name, followed by the shape. For example, the 1307104862SruTimes family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1308104862Sru@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1309104862Sru`italic', and `bold italic', respectively. Thus the final font names 1310104862Sruare @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1311104862Sru 1312104862Sru@cindex font path 1313104862Sru@cindex path, for font files 1314104862SruAll font files are kept in the @dfn{font directories} which constitute 1315104862Sruthe @dfn{font path}. The file search functions will always append the 1316104862Srudirectory @code{dev}@var{name}, where @var{name} is the name of the 1317104862Sruoutput device. Assuming, say, DVI output, and @file{/foo/bar} as a 1318104862Srufont directory, the font files for @code{grodvi} must be in 1319104862Sru@file{/foo/bar/devdvi}. 1320104862Sru 1321104862SruThe elements of the search path for font files are (in that order): 1322104862Sru 1323104862Sru@itemize @bullet 1324104862Sru@item 1325104862SruThe directories specified with @code{gtroff}'s or @code{groff}'s 1326104862Sru@option{-F} command line option. All device drivers and some 1327104862Srupreprocessors also have this option. 1328104862Sru 1329104862Sru@item 1330104862Sru@tindex GROFF_FONT_PATH@r{, environment variable} 1331104862SruThe directories given in the @env{GROFF_FONT_PATH} environment 1332104862Sruvariable. 1333104862Sru 1334104862Sru@item 1335104862Sru@cindex site-specific directory 1336104862Sru@cindex directory, site-specific 1337104862SruA site-specific directory and the main font directory; the default 1338104862Srulocations are 1339104862Sru 1340104862Sru@Example 1341104862Sru/usr/local/share/groff/site-font 1342114402Sru/usr/local/share/groff/1.18.2/font 1343104862Sru@endExample 1344104862Sru 1345104862Sru@noindent 1346114402Sruassuming that the version of @code{groff} is 1.18.2, and the installation 1347104862Sruprefix was @file{/usr/local}. It is possible to fine-tune those 1348104862Srudirectories during the installation process. 1349104862Sru@end itemize 1350104862Sru 1351104862Sru 1352104862Sru@c ===================================================================== 1353104862Sru 1354114402Sru@node Paper Size, Invocation Examples, Font Directories, Invoking groff 1355114402Sru@section Paper Size 1356114402Sru@cindex paper size 1357114402Sru@cindex size, paper 1358114402Sru@cindex landscape page orientation 1359114402Sru@cindex orientation, landscape 1360114402Sru@cindex page orientation, landscape 1361114402Sru 1362114402SruIn groff, the page size for @code{gtroff} and for output devices are 1363114402Sruhandled separately. @xref{Page Layout}, for vertical manipulation of 1364114402Sruthe page size. @xref{Line Layout}, for horizontal changes. 1365114402Sru 1366114402SruA default paper size can be set in the device's @file{DESC} file. Most 1367114402Sruoutput devices also have a command line option @option{-p} to override 1368114402Sruthe default paper size and option @option{-l} to use landscape 1369114402Sruorientation. @xref{DESC File Format}, for a description of the 1370114402Sru@code{papersize} keyword which takes the same argument as @option{-p}. 1371114402Sru 1372114402Sru@pindex papersize.tmac 1373114402Sru@pindex troffrc 1374114402SruA convenient shorthand to set a particular paper size for @code{gtroff} 1375114402Sruis command line option @option{-dpaper=@var{size}}. This defines string 1376114402Sru@code{paper} which is processed in file @file{papersize.tmac} (loaded in 1377114402Sruthe start-up file @file{troffrc} by default). Possible values for 1378114402Sru@var{size} are the same as the predefined values for the 1379114402Sru@code{papersize} keyword (but only in lowercase) except 1380114402Sru@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes 1381114402Srulandscape orientation. 1382114402Sru 1383114402SruFor example, use the following for PS output on A4 paper in landscape 1384114402Sruorientation: 1385114402Sru 1386114402Sru@Example 1387114402Srugroff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 1388114402Sru@endExample 1389114402Sru 1390114402SruNote that it is up to the particular macro package to respect default 1391114402Srupage dimensions set in this way (most do). 1392114402Sru 1393114402Sru 1394114402Sru@c ===================================================================== 1395114402Sru 1396114402Sru@node Invocation Examples, , Paper Size, Invoking groff 139755839Sasmodai@section Invocation Examples 139855839Sasmodai@cindex invocation examples 139955839Sasmodai@cindex examples of invocation 140055839Sasmodai 140175584SruThis section lists several common uses of @code{groff} and the 140275584Srucorresponding command lines. 140355839Sasmodai 140475584Sru@Example 140555839Sasmodaigroff file 140675584Sru@endExample 140755839Sasmodai 140869626Sru@noindent 140969626SruThis command processes @file{file} without a macro package or a 141069626Srupreprocessor. The output device is the default, @samp{ps}, and the 141175584Sruoutput is sent to @code{stdout}. 141269626Sru 141375584Sru@Example 141469626Srugroff -t -mandoc -Tascii file | less 141575584Sru@endExample 141669626Sru 141769626Sru@noindent 141875584SruThis is basically what a call to the @code{man} program does. 141975584Sru@code{gtroff} processes the manual page @file{file} with the 142075584Sru@file{mandoc} macro file (which in turn either calls the @file{man} or 142175584Sruthe @file{mdoc} macro package), using the @code{tbl} preprocessor and 142275584Sruthe @acronym{ASCII} output device. Finally, the @code{less} pager 142375584Srudisplays the result. 142469626Sru 142575584Sru@Example 142669626Srugroff -X -m me file 142775584Sru@endExample 142869626Sru 142969626Sru@noindent 143069626SruPreview @file{file} with @code{gxditview}, using the @file{me} macro 143169626Srupackage. Since no @option{-T} option is specified, use the default 143269626Srudevice (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 143369626Sru@w{@samp{-me}}; the latter is an anachronism from the early days of 143469626Sru@acronym{UNIX}.@footnote{The same is true for the other main macro 143569626Srupackages that come with @code{groff}: @file{man}, @file{mdoc}, 143669626Sru@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 143775584Srufor example, to load @file{trace.tmac}, either @samp{-mtrace} or 143875584Sru@w{@samp{-m trace}} must be used.} 143969626Sru 144075584Sru@Example 144169626Srugroff -man -rD1 -z file 144275584Sru@endExample 144369626Sru 144469626Sru@noindent 144569626SruCheck @file{file} with the @file{man} macro package, forcing 144669626Srudouble-sided printing -- don't produce any output. 144769626Sru 144869626Sru@menu 144975584Sru* grog:: 145069626Sru@end menu 145169626Sru 145275584Sru@c --------------------------------------------------------------------- 145375584Sru 145469626Sru@node grog, , Invocation Examples, Invocation Examples 145555839Sasmodai@subsection @code{grog} 145655839Sasmodai 145769626Sru@pindex grog 145869626Sru@code{grog} reads files, guesses which of the @code{groff} preprocessors 145969626Sruand/or macro packages are required for formatting them, and prints the 146075584Sru@code{groff} command including those options on the standard output. It 146175584Srugenerates one or more of the options @option{-e}, @option{-man}, 1462104862Sru@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 146375584Sru@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 146475584Sru@option{-s}, and @option{-t}. 146555839Sasmodai 1466114402SruA special file name@tie{}@file{-} refers to the standard input. Specifying 146775584Sruno files also means to read the standard input. Any specified options 146875584Sruare included in the printed command. No space is allowed between 146975584Sruoptions and their arguments. The only options recognized are 147075584Sru@option{-C} (which is also passed on) to enable compatibility mode, and 1471104862Sru@option{-v} to print the version number and exit. 147255839Sasmodai 147375584SruFor example, 147475584Sru 147575584Sru@Example 147655839Sasmodaigrog -Tdvi paper.ms 147775584Sru@endExample 147855839Sasmodai 147969626Sru@noindent 148075584Sruguesses the appropriate command to print @file{paper.ms} and then prints 148175584Sruit to the command line after adding the @option{-Tdvi} option. For 148275584Srudirect execution, enclose the call to @code{grog} in backquotes at the 148375584Sru@acronym{UNIX} shell prompt: 148455839Sasmodai 148575584Sru@Example 148669626Sru`grog -Tdvi paper.ms` > paper.dvi 148775584Sru@endExample 148855839Sasmodai 148969626Sru@noindent 149069626SruAs seen in the example, it is still necessary to redirect the output to 149169626Srusomething meaningful (i.e.@: either a file or a pager program like 149269626Sru@code{less}). 149369626Sru 149469626Sru 149569626Sru 149669626Sru@c ===================================================================== 149769626Sru@c ===================================================================== 149869626Sru 149969626Sru@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 150055839Sasmodai@chapter Tutorial for Macro Users 150155839Sasmodai@cindex tutorial for macro users 150269626Sru@cindex macros, tutorial for users 150355839Sasmodai@cindex user's tutorial for macros 150455839Sasmodai@cindex user's macro tutorial 150555839Sasmodai 150655839SasmodaiMost users tend to use a macro package to format their papers. This 150769626Srumeans that the whole breadth of @code{groff} is not necessary for most 150855839Sasmodaipeople. This chapter covers the material needed to efficiently use a 150955839Sasmodaimacro package. 151055839Sasmodai 151155839Sasmodai@menu 151275584Sru* Basics:: 151375584Sru* Common Features:: 151455839Sasmodai@end menu 151555839Sasmodai 151669626Sru 151769626Sru@c ===================================================================== 151869626Sru 151955839Sasmodai@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 152055839Sasmodai@section Basics 152169626Sru@cindex basics of macros 152269626Sru@cindex macro basics 152355839Sasmodai 152469626SruThis section covers some of the basic concepts necessary to understand 152569626Sruhow to use a macro package.@footnote{This section is derived from 1526114402Sru@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.} 152755839SasmodaiReferences are made throughout to more detailed information, if desired. 152855839Sasmodai 152969626Sru@code{gtroff} reads an input file prepared by the user and outputs a 153069626Sruformatted document suitable for publication or framing. The input 153169626Sruconsists of text, or words to be printed, and embedded commands 153269626Sru(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 153369626Sruformat the output. For more detail on this, see @ref{Embedded 153469626SruCommands}. 153555839Sasmodai 153669626SruThe word @dfn{argument} is used in this chapter to mean a word or number 153769626Sruwhich appears on the same line as a request, and which modifies the 153869626Srumeaning of that request. For example, the request 153955839Sasmodai 154075584Sru@Example 154155839Sasmodai.sp 154275584Sru@endExample 154355839Sasmodai 154455839Sasmodai@noindent 154555839Sasmodaispaces one line, but 154655839Sasmodai 154775584Sru@Example 154855839Sasmodai.sp 4 154975584Sru@endExample 155055839Sasmodai 155155839Sasmodai@noindent 1552114402Sruspaces four lines. The number@tie{}4 is an argument to the @code{sp} 155355839Sasmodairequest which says to space four lines instead of one. Arguments are 155475584Sruseparated from the request and from each other by spaces (@emph{no} 1555114402Srutabs). More details on this can be found in @ref{Request and Macro 1556114402SruArguments}. 155755839Sasmodai 155869626SruThe primary function of @code{gtroff} is to collect words from input 155969626Srulines, fill output lines with those words, justify the right-hand margin 156055839Sasmodaiby inserting extra spaces in the line, and output the result. For 156155839Sasmodaiexample, the input: 156255839Sasmodai 156375584Sru@Example 156455839SasmodaiNow is the time 156555839Sasmodaifor all good men 156655839Sasmodaito come to the aid 156755839Sasmodaiof their party. 156855839SasmodaiFour score and seven 1569104862Sruyears ago, etc. 157075584Sru@endExample 157155839Sasmodai 157255839Sasmodai@noindent 157375584Sruis read, packed onto output lines, and justified to produce: 157455839Sasmodai 157555839Sasmodai@quotation 157655839SasmodaiNow is the time for all good men to come to the aid of their party. 1577104862SruFour score and seven years ago, etc. 157855839Sasmodai@end quotation 157955839Sasmodai 158055839Sasmodai@cindex break 158155839Sasmodai@cindex line break 158269626SruSometimes a new output line should be started even though the current 158369626Sruline is not yet full; for example, at the end of a paragraph. To do 158469626Sruthis it is possible to cause a @dfn{break}, which starts a new output 158575584Sruline. Some requests cause a break automatically, as normally do blank 158675584Sruinput lines and input lines beginning with a space. 158755839Sasmodai 158875584SruNot all input lines are text to be formatted. Some input lines are 158975584Srurequests which describe how to format the text. Requests always have a 159075584Sruperiod (@samp{.}) or an apostrophe (@samp{'}) as the first character of 159175584Sruthe input line. 159255839Sasmodai 159355839SasmodaiThe text formatter also does more complex things, such as automatically 159469626Srunumbering pages, skipping over page boundaries, putting footnotes in the 159555839Sasmodaicorrect place, and so forth. 159655839Sasmodai 159769626SruHere are a few hints for preparing text for input to @code{gtroff}. 159875584Sru 159975584Sru@itemize @bullet 160075584Sru@item 160169626SruFirst, keep the input lines short. Short input lines are easier to 160275584Sruedit, and @code{gtroff} packs words onto longer lines anyhow. 160355839Sasmodai 160475584Sru@item 160575584SruIn keeping with this, it is helpful to begin a new line after every 160675584Srucomma or phrase, since common corrections are to add or delete sentences 160775584Sruor phrases. 160875584Sru 160975584Sru@item 161075584SruEnd each sentence with two spaces -- or better, start each sentence on a 161175584Srunew line. @code{gtroff} recognizes characters that usually end a 161275584Srusentence, and inserts sentence space accordingly. 161375584Sru 161475584Sru@item 161575584SruDo not hyphenate words at the end of lines -- @code{gtroff} is smart 161675584Sruenough to hyphenate words as needed, but is not smart enough to take 161775584Sruhyphens out and join a word back together. Also, words such as 161875584Sru``mother-in-law'' should not be broken over a line, since then a space 161975584Srucan occur where not wanted, such as ``@w{mother- in}-law''. 162075584Sru@end itemize 162175584Sru 1622104862Sru@cindex double-spacing (@code{ls}) 162355839Sasmodai@cindex spacing 1624104862Sru@code{gtroff} double-spaces output text automatically if you use the 1625104862Srurequest @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing 1626104862Sru@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the 1627104862Sruvertical space, use the @code{pvs} request (@pxref{Changing Type 1628104862SruSizes}).} 162955839Sasmodai 163075584SruA number of requests allow to change the way the output looks, 163175584Srusometimes called the @dfn{layout} of the output page. Most of these 1632104862Srurequests adjust the placing of @dfn{whitespace} (blank lines or 163375584Sruspaces). 163455839Sasmodai 1635104862Sru@cindex new page (@code{bp}) 1636104862SruThe @code{bp} request starts a new page, causing a line break. 163755839Sasmodai 1638104862Sru@cindex blank line (@code{sp}) 1639104862Sru@cindex empty line (@code{sp}) 1640104862Sru@cindex line, empty (@code{sp}) 1641114402SruThe request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank 1642114402Sruspace. @var{N}@tie{}can be omitted (meaning skip a single line) or can 1643114402Srube of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for 1644114402Sru@var{N}@tie{}centimeters). For example, the input: 164555839Sasmodai 164675584Sru@Example 164755839Sasmodai.sp 1.5i 164855839SasmodaiMy thoughts on the subject 164955839Sasmodai.sp 165075584Sru@endExample 165155839Sasmodai 165255839Sasmodai@noindent 165355839Sasmodaileaves one and a half inches of space, followed by the line ``My 165475584Sruthoughts on the subject'', followed by a single blank line (more 165575584Srumeasurement units are available, see @ref{Measurements}). 165655839Sasmodai 1657104862Sru@cindex centering lines (@code{ce}) 1658104862Sru@cindex lines, centering (@code{ce}) 165969626SruText lines can be centered by using the @code{ce} request. The line 166069626Sruafter @code{ce} is centered (horizontally) on the page. To center more 166169626Sruthan one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1662114402Sruof lines to center), followed by the @var{N}@tie{}lines. To center many 166369626Srulines without counting them, type: 166455839Sasmodai 166575584Sru@Example 166655839Sasmodai.ce 1000 166755839Sasmodailines to center 166855839Sasmodai.ce 0 166975584Sru@endExample 167055839Sasmodai 167155839Sasmodai@noindent 167269626SruThe @w{@samp{.ce 0}} request tells @code{groff} to center zero more 167369626Srulines, in other words, stop centering. 167455839Sasmodai 1675104862Sru@cindex line break (@code{br}) 1676104862Sru@cindex break (@code{br}) 167755839SasmodaiAll of these requests cause a break; that is, they always start a new 167869626Sruline. To start a new line without performing any other action, use 167969626Sru@code{br}. 168055839Sasmodai 168155839Sasmodai 168269626Sru@c ===================================================================== 168369626Sru 168455839Sasmodai@node Common Features, , Basics, Tutorial for Macro Users 168555839Sasmodai@section Common Features 168655839Sasmodai@cindex common features 168755839Sasmodai@cindex features, common 168855839Sasmodai 168975584Sru@code{gtroff} provides very low-level operations for formatting a 169069626Srudocument. There are many common routine operations which are done in 169169626Sruall documents. These common operations are written into @dfn{macros} 169269626Sruand collected into a @dfn{macro package}. 169355839Sasmodai 169469626SruAll macro packages provide certain common capabilities which fall into 169569626Sruthe following categories. 169655839Sasmodai 169769626Sru@menu 169875584Sru* Paragraphs:: 169975584Sru* Sections and Chapters:: 170075584Sru* Headers and Footers:: 170175584Sru* Page Layout Adjustment:: 170275584Sru* Displays:: 170375584Sru* Footnotes and Annotations:: 170475584Sru* Table of Contents:: 170575584Sru* Indices:: 170675584Sru* Paper Formats:: 170775584Sru* Multiple Columns:: 170875584Sru* Font and Size Changes:: 170975584Sru* Predefined Strings:: 171075584Sru* Preprocessor Support:: 171175584Sru* Configuration and Customization:: 171269626Sru@end menu 171369626Sru 171475584Sru@c --------------------------------------------------------------------- 171575584Sru 171669626Sru@node Paragraphs, Sections and Chapters, Common Features, Common Features 171755839Sasmodai@subsection Paragraphs 171855839Sasmodai@cindex paragraphs 171955839Sasmodai 172075584SruOne of the most common and most used capability is starting a 172175584Sruparagraph. There are a number of different types of paragraphs, any 172275584Sruof which can be initiated with macros supplied by the macro package. 172375584SruNormally, paragraphs start with a blank line and the first line 172475584Sruindented, like the text in this manual. There are also block style 172575584Sruparagraphs, which omit the indentation: 172655839Sasmodai 172775584Sru@Example 172855839SasmodaiSome men look at constitutions with sanctimonious 172955839Sasmodaireverence, and deem them like the ark of the covenant, too 173055839Sasmodaisacred to be touched. 173175584Sru@endExample 173255839Sasmodai 173369626Sru@noindent 173455839SasmodaiAnd there are also indented paragraphs which begin with a tag or label 173555839Sasmodaiat the margin and the remaining text indented. 173655839Sasmodai 1737104862Sru@Example 173855839Sasmodaione This is the first paragraph. Notice how the first 173955839Sasmodai line of the resulting paragraph lines up with the 174055839Sasmodai other lines in the paragraph. 1741104862Sru@endExample 1742104862Sru@Example 174355839Sasmodailonglabel 174455839Sasmodai This paragraph had a long label. The first 174575584Sru character of text on the first line does not line up 174655839Sasmodai with the text on second and subsequent lines, 174775584Sru although they line up with each other. 1748104862Sru@endExample 174955839Sasmodai 175069626SruA variation of this is a bulleted list. 175155839Sasmodai 1752104862Sru@Example 1753104862Sru. Bulleted lists start with a bullet. It is possible 1754104862Sru to use other glyphs instead of the bullet. In nroff 1755104862Sru mode using the ASCII character set for output, a dot 1756104862Sru is used instead of a real bullet. 1757104862Sru@endExample 175869626Sru 175969626Sru@c --------------------------------------------------------------------- 176069626Sru 176169626Sru@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 176255839Sasmodai@subsection Sections and Chapters 176355839Sasmodai 176469626SruMost macro packages supply some form of section headers. The simplest 176569626Srukind is simply the heading on a line by itself in bold type. Others 176669626Srusupply automatically numbered section heading or different heading 176769626Srustyles at different levels. Some, more sophisticated, macro packages 176869626Srusupply macros for starting chapters and appendices. 176955839Sasmodai 177069626Sru@c --------------------------------------------------------------------- 177169626Sru 177269626Sru@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 177355839Sasmodai@subsection Headers and Footers 177455839Sasmodai 1775104862SruEvery macro package gives some way to manipulate the @dfn{headers} and 1776104862Sru@dfn{footers} (also called @dfn{titles}) on each page. This is text 1777104862Sruput at the top and bottom of each page, respectively, which contain 1778104862Srudata like the current page number, the current chapter title, and so 1779104862Sruon. Its appearance is not affected by the running text. Some packages 1780104862Sruallow for different ones on the even and odd pages (for material printed 1781104862Sruin a book form). 178269626Sru 1783104862SruThe titles are called @dfn{three-part titles}, that is, there is a 178469626Sruleft-justified part, a centered part, and a right-justified part. An 178569626Sruautomatically generated page number may be put in any of these fields 178669626Sruwith the @samp{%} character (see @ref{Page Layout}, for more details). 178755839Sasmodai 178869626Sru@c --------------------------------------------------------------------- 178969626Sru 179069626Sru@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 179155839Sasmodai@subsection Page Layout 179255839Sasmodai 179369626SruMost macro packages let the user specify top and bottom margins and 179469626Sruother details about the appearance of the printed pages. 179555839Sasmodai 179669626Sru@c --------------------------------------------------------------------- 179769626Sru 179869626Sru@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 179955839Sasmodai@subsection Displays 180055839Sasmodai@cindex displays 180155839Sasmodai 1802104862Sru@dfn{Displays} are sections of text to be set off from the body of 1803104862Sruthe paper. Major quotes, tables, and figures are types of displays, as 1804104862Sruare all the examples used in this document. 180555839Sasmodai 180655839Sasmodai@cindex quotes, major 180755839Sasmodai@cindex major quotes 180869626Sru@dfn{Major quotes} are quotes which are several lines long, and hence 180969626Sruare set in from the rest of the text without quote marks around them. 181055839Sasmodai 181155839Sasmodai@cindex list 1812104862SruA @dfn{list} is an indented, single-spaced, unfilled display. Lists 181369626Srushould be used when the material to be printed should not be filled and 181469626Srujustified like normal text, such as columns of figures or the examples 181569626Sruused in this paper. 181655839Sasmodai 181755839Sasmodai@cindex keep 181869626SruA @dfn{keep} is a display of lines which are kept on a single page if 181969626Srupossible. An example for a keep might be a diagram. Keeps differ from 182075584Srulists in that lists may be broken over a page boundary whereas keeps are 182175584Srunot. 182255839Sasmodai 182355839Sasmodai@cindex keep, floating 182455839Sasmodai@cindex floating keep 1825104862Sru@dfn{Floating keeps} move relative to the text. Hence, they are good for 1826114402Sruthings which are referred to by name, such as ``See figure@tie{}3''. A 182775584Srufloating keep appears at the bottom of the current page if it fits; 182875584Sruotherwise, it appears at the top of the next page. Meanwhile, the 182975584Srusurrounding text `flows' around the keep, thus leaving no blank areas. 183055839Sasmodai 183169626Sru@c --------------------------------------------------------------------- 183269626Sru 183369626Sru@node Footnotes and Annotations, Table of Contents, Displays, Common Features 183469626Sru@subsection Footnotes and Annotations 183555839Sasmodai@cindex footnotes 183655839Sasmodai@cindex annotations 183755839Sasmodai 183869626SruThere are a number of requests to save text for later printing. 183955839Sasmodai 184069626Sru@dfn{Footnotes} are printed at the bottom of the current page. 184155839Sasmodai 184269626Sru@cindex delayed text 184369626Sru@dfn{Delayed text} is very similar to a footnote except that it is 184469626Sruprinted when called for explicitly. This allows a list of references to 184569626Sruappear (for example) at the end of each chapter, as is the convention in 184669626Srusome disciplines. 184755839Sasmodai 184869626SruMost macro packages which supply this functionality also supply a means 184969626Sruof automatically numbering either type of annotation. 185069626Sru 185169626Sru@c --------------------------------------------------------------------- 185269626Sru 185369626Sru@node Table of Contents, Indices, Footnotes and Annotations, Common Features 185455839Sasmodai@subsection Table of Contents 185569626Sru@cindex table of contents 185669626Sru@cindex contents, table of 185755839Sasmodai 185869626Sru@dfn{Tables of contents} are a type of delayed text having a tag 185969626Sru(usually the page number) attached to each entry after a row of dots. 186069626SruThe table accumulates throughout the paper until printed, usually after 186175584Sruthe paper has ended. Many macro packages provide the ability to have 186275584Sruseveral tables of contents (e.g.@: a standard table of contents, a list 186375584Sruof tables, etc). 186455839Sasmodai 186569626Sru@c --------------------------------------------------------------------- 186655839Sasmodai 186769626Sru@node Indices, Paper Formats, Table of Contents, Common Features 186869626Sru@subsection Indices 186969626Sru@cindex index, in macro package 187055839Sasmodai 187175584SruWhile some macro packages use the term @dfn{index}, none actually 187269626Sruprovide that functionality. The facilities they call indices are 187369626Sruactually more appropriate for tables of contents. 187455839Sasmodai 1875104862Sru@pindex makeindex 1876104862SruTo produce a real index in a document, external tools like the 1877104862Sru@code{makeindex} program are necessary. 1878104862Sru 187969626Sru@c --------------------------------------------------------------------- 188069626Sru 188169626Sru@node Paper Formats, Multiple Columns, Indices, Common Features 188269626Sru@subsection Paper Formats 188369626Sru@cindex paper formats 188469626Sru 188555839SasmodaiSome macro packages provide stock formats for various kinds of 188655839Sasmodaidocuments. Many of them provide a common format for the title and 188769626Sruopening pages of a technical paper. The @file{mm} macros in particular 188869626Sruprovide formats for letters and memoranda. 188955839Sasmodai 189069626Sru@c --------------------------------------------------------------------- 189169626Sru 189269626Sru@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 189355839Sasmodai@subsection Multiple Columns 189455839Sasmodai 189569626SruSome macro packages (but not @file{man}) provide the ability to have two 189669626Sruor more columns on a page. 189755839Sasmodai 189869626Sru@c --------------------------------------------------------------------- 189955839Sasmodai 190069626Sru@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 190169626Sru@subsection Font and Size Changes 190269626Sru 190369626SruThe built-in font and size functions are not always intuitive, so all 190455839Sasmodaimacro packages provide macros to make these operations simpler. 190555839Sasmodai 190669626Sru@c --------------------------------------------------------------------- 190769626Sru 190869626Sru@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 190955839Sasmodai@subsection Predefined Strings 191055839Sasmodai 191169626SruMost macro packages provide various predefined strings for a variety of 191269626Sruuses; examples are sub- and superscripts, printable dates, quotes and 191369626Sruvarious special characters. 191455839Sasmodai 191569626Sru@c --------------------------------------------------------------------- 191669626Sru 191769626Sru@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 191855839Sasmodai@subsection Preprocessor Support 191955839Sasmodai 1920104862SruAll macro packages provide support for various preprocessors and may 192175584Sruextend their functionality. 192255839Sasmodai 192375584SruFor example, all macro packages mark tables (which are processed with 1924104862Sru@code{gtbl}) by placing them between @code{TS} and @code{TE} macros. 1925114402SruThe @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints 192675584Srua caption at the top of a new page (when the table is too long to fit on 192775584Srua single page). 192875584Sru 192969626Sru@c --------------------------------------------------------------------- 193069626Sru 193169626Sru@node Configuration and Customization, , Preprocessor Support, Common Features 193255839Sasmodai@subsection Configuration and Customization 193355839Sasmodai 193475584SruSome macro packages provide means of customizing many of the details of 193575584Sruhow the package behaves. This ranges from setting the default type size 193675584Sruto changing the appearance of section headers. 193755839Sasmodai 193855839Sasmodai 193955839Sasmodai 194069626Sru@c ===================================================================== 194169626Sru@c ===================================================================== 194255839Sasmodai 194375584Sru@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 194469626Sru@chapter Macro Packages 194569626Sru@cindex macro packages 194669626Sru@cindex packages, macros 194755839Sasmodai 194869626SruThis chapter documents the main macro packages that come with 194969626Sru@code{groff}. 195055839Sasmodai 1951114402SruDifferent main macro packages can't be used at the same time; for example 1952114402Sru 1953114402Sru@Example 1954114402Srugroff -m man foo.man -m ms bar.doc 1955114402Sru@endExample 1956114402Sru 1957114402Sru@noindent 1958114402Srudoesn't work. Note that option arguments are processed before non-option 1959114402Sruarguments; the above (failing) sample is thus reordered to 1960114402Sru 1961114402Sru@Example 1962114402Srugroff -m man -m ms foo.man bar.doc 1963114402Sru@endExample 1964114402Sru 196569626Sru@menu 196675584Sru* man:: 196775584Sru* mdoc:: 196875584Sru* ms:: 196975584Sru* me:: 197075584Sru* mm:: 197169626Sru@end menu 197255839Sasmodai 197355839Sasmodai 197469626Sru@c ===================================================================== 197555839Sasmodai 197669626Sru@node man, mdoc, Macro Packages, Macro Packages 197769626Sru@section @file{man} 197869626Sru@cindex manual pages 1979104862Sru@cindex man pages 198075584Sru@pindex an.tmac 198175584Sru@pindex man.tmac 198275584Sru@pindex man-old.tmac 198355839Sasmodai 198469626SruThis is the most popular and probably the most important macro package 198569626Sruof @code{groff}. It is easy to use, and a vast majority of manual pages 198669626Sruare based on it. 198755839Sasmodai 198869626Sru@menu 198975584Sru* Man options:: 199075584Sru* Man usage:: 199175584Sru* Man font macros:: 199275584Sru* Miscellaneous man macros:: 199375584Sru* Predefined man strings:: 199475584Sru* Preprocessors in man pages:: 1995114402Sru* Optional man extensions:: 199669626Sru@end menu 199755839Sasmodai 199869626Sru@c --------------------------------------------------------------------- 199955839Sasmodai 200069626Sru@node Man options, Man usage, man, man 200169626Sru@subsection Options 200255839Sasmodai 200369626SruThe command line format for using the @file{man} macros with 200469626Sru@code{groff} is: 200569626Sru 200675584Sru@Example 2007114402Srugroff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ] 2008114402Sru [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ] 2009114402Sru [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ] 2010114402Sru [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ] 201175584Sru@endExample 201269626Sru 201375584Sru@noindent 201469626SruIt is possible to use @samp{-man} instead of @w{@samp{-m man}}. 201569626Sru 201669626Sru@table @code 201775584Sru@item -rcR=1 2018104862SruThis option (the default if a TTY output device is used) creates a 201975584Srusingle, very long page instead of multiple pages. Use @code{-rcR=0} 202075584Sruto disable it. 202175584Sru 202269626Sru@item -rC1 202369626SruIf more than one manual page is given on the command line, number the 2024114402Srupages continuously, rather than starting each at@tie{}1. 202569626Sru 202669626Sru@item -rD1 202769626SruDouble-sided printing. Footers for even and odd pages are formatted 202869626Srudifferently. 202969626Sru 2030114402Sru@item -rFT=@var{dist} 2031114402SruSet the position of the footer text to @var{dist}. If positive, the 2032114402Srudistance is measured relative to the top of the page, otherwise it is 2033114402Srurelative to the bottom. The default is @minus{}0.5@dmn{i}. 2034114402Sru 2035114402Sru@item -rHY=@var{flags} 2036114402SruSet hyphenation flags. Possible values are 1@tie{}to hyphenate without 2037114402Srurestrictions, 2@tie{} to not hyphenate the last word on a page, 2038114402Sru4@tie{}to not hyphenate the last two characters of a word, and 2039114402Sru8@tie{}to not hyphenate the first two characters of a word. These 2040114402Sruvalues are additive; the default is@tie{}14. 2041114402Sru 2042114402Sru@item -rIN=@var{length} 2043114402SruSet the body text indent to @var{length}. 2044114402SruIf not specified, the indent defaults to 7@dmn{n} 2045114402Sru(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. 2046114402SruFor nroff, this value should always be an integer multiple of unit @samp{n} 2047114402Sruto get consistent indentation. 2048114402Sru 2049114402Sru@item -rLL=@var{length} 2050114402SruSet line length to @var{length}. If not specified, the line length 2051114402Srudefaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per 2052114402Sruline) and 6.5@tie{}inch otherwise. 2053114402Sru 2054114402Sru@item -rLT=@var{length} 2055114402SruSet title length to @var{length}. If not specified, the title length 2056114402Srudefaults to the line length. 2057114402Sru 205869626Sru@item -rP@var{nnn} 2059114402SruPage numbering starts with @var{nnn} rather than with@tie{}1. 206069626Sru 206169626Sru@item -rS@var{xx} 2062114402SruUse @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base 2063114402Srudocument font size instead of the default value of@tie{}10@dmn{pt}. 206469626Sru 2065114402Sru@item -rSN=@var{length} 2066114402SruSet the indent for sub-subheadings to @var{length}. 2067114402SruIf not specified, the indent defaults to 3@dmn{n}. 2068114402Sru 206969626Sru@item -rX@var{nnn} 207069626SruAfter page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 207175584Sru@var{nnn}c, etc. For example, the option @option{-rX2} produces the 207269626Srufollowing page numbers: 1, 2, 2a, 2b, 2c, etc. 207369626Sru@end table 207469626Sru 207569626Sru@c --------------------------------------------------------------------- 207669626Sru 207769626Sru@node Man usage, Man font macros, Man options, man 207869626Sru@subsection Usage 207969626Sru@cindex @code{man} macros 2080104862Sru@cindex macros for manual pages [@code{man}] 208169626Sru 208269626Sru@pindex man.local 208369626SruThis section describes the available macros for manual pages. For 208469626Srufurther customization, put additional macros and requests into the file 208575584Sru@file{man.local} which is loaded immediately after the @file{man} 208675584Srupackage. 208769626Sru 2088104862Sru@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} 208975584SruSet the title of the man page to @var{title} and the section to 2090114402Sru@var{section}, which must have a value between 1 and@tie{}8. The value 209175584Sruof @var{section} may also have a string appended, e.g.@: @samp{.pm}, 209275584Sruto indicate a specific subsection of the man pages. 209369626Sru 209469626SruBoth @var{title} and @var{section} are positioned at the left and right 209569626Sruin the header line (with @var{section} in parentheses immediately 209675584Sruappended to @var{title}. @var{extra1} is positioned in the middle of 209775584Sruthe footer line. @var{extra2} is positioned at the left in the footer 209875584Sruline (or at the left on even pages and at the right on odd pages if 209975584Srudouble-sided printing is active). @var{extra3} is centered in the 210075584Sruheader line. 210169626Sru 210269626SruFor @acronym{HTML} output, headers and footers are completely suppressed. 210369626Sru 2104114402SruAdditionally, this macro starts a new page; the new line number is@tie{}1 210569626Sruagain (except if the @option{-rC1} option is given on the command line) 210669626Sru-- this feature is intended only for formatting multiple man pages; a 210769626Srusingle man page should contain exactly one @code{TH} macro at the 210869626Srubeginning of the file. 210975584Sru@endDefmac 211069626Sru 2111104862Sru@Defmac {SH, [@Var{heading}], man} 211275584SruSet up an unnumbered section heading sticking out to the left. Prints 211375584Sruout all the text following @code{SH} up to the end of the line (or the 211475584Srutext in the next line if there is no argument to @code{SH}) in bold 2115114402Sruface (or the font specified by the string @code{HF}), one size larger than 2116114402Sruthe base document size. Additionally, the left margin and the indentation 2117114402Srufor the following text is reset to its default value. 211875584Sru@endDefmac 211969626Sru 2120104862Sru@Defmac {SS, [@Var{heading}], man} 212175584SruSet up an unnumbered (sub)section heading. Prints out all the text 212275584Srufollowing @code{SS} up to the end of the line (or the text in the next 2123114402Sruline if there is no argument to @code{SS}) in bold face (or the font 2124114402Sruspecified by the string @code{HF}), at the same size as the base document 2125114402Srusize. Additionally, the left margin and the indentation for the 212675584Srufollowing text is reset to its default value. 212775584Sru@endDefmac 212869626Sru 2129104862Sru@Defmac {TP, [@Var{nnn}], man} 213075584SruSet up an indented paragraph with label. The indentation is set to 213175584Sru@var{nnn} if that argument is supplied (the default unit is @samp{n} 2132114402Sruif omitted), otherwise it is set to the previous indentation value 2133114402Sruspecified with @code{TP}, @code{IP}, or @code{HP} (or to the default 2134114402Sruvalue if none of them have been used yet). 213569626Sru 213669626SruThe first line of text following this macro is interpreted as a string 213769626Sruto be printed flush-left, as it is appropriate for a label. It is not 213869626Sruinterpreted as part of a paragraph, so there is no attempt to fill the 213969626Srufirst line with text from the following input lines. Nevertheless, if 2140114402Sruthe label is not as wide as the indentation the paragraph starts 214175584Sruat the same line (but indented), continuing on the following lines. 2142114402SruIf the label is wider than the indentation the descriptive part 214375584Sruof the paragraph begins on the line following the label, entirely 214475584Sruindented. Note that neither font shape nor font size of the label is 214575584Sruset to a default value; on the other hand, the rest of the text has 214675584Srudefault font settings. 214775584Sru@endDefmac 214869626Sru 2149104862Sru@DefmacList {LP, , man} 2150104862Sru@DefmacItem {PP, , man} 2151104862Sru@DefmacListEnd {P, , man} 215275584SruThese macros are mutual aliases. Any of them causes a line break at 215375584Sruthe current position, followed by a vertical space downwards by the 215475584Sruamount specified by the @code{PD} macro. The font size and shape are 2155104862Srureset to the default value (10@dmn{pt} roman if no @option{-rS} option 2156114402Sruis given on the command line). Finally, the current left margin and the 2157114402Sruindentation is restored. 215875584Sru@endDefmac 215969626Sru 2160104862Sru@Defmac {IP, [@Var{designator} [@Var{nnn}]], man} 216175584SruSet up an indented paragraph, using @var{designator} as a tag to mark 216275584Sruits beginning. The indentation is set to @var{nnn} if that argument 2163114402Sruis supplied (default unit is @samp{n}), otherwise it is set to the 2164114402Sruprevious indentation value specified with @code{TP}, @code{IP}, or 2165114402Sru@code{HP} (or the default value if none of them have been used yet). 2166114402SruFont size and face of the paragraph (but not the designator) are reset 2167114402Sruto their default values. 2168114402Sru 2169114402SruTo start an indented paragraph with a particular indentation but without 2170114402Srua designator, use @samp{""} (two double quotes) as the first argument of 217175584Sru@code{IP}. 217269626Sru 217369626SruFor example, to start a paragraph with bullets as the designator and 2174114402Sru4@tie{}en indentation, write 217569626Sru 217675584Sru@Example 217769626Sru.IP \(bu 4 217875584Sru@endExample 217975584Sru@endDefmac 218069626Sru 2181104862Sru@Defmac {HP, [@Var{nnn}], man} 2182104862Sru@cindex hanging indentation [@code{man}] 2183104862Sru@cindex @code{man} macros, hanging indentation 218475584SruSet up a paragraph with hanging left indentation. The indentation is 218569626Sruset to @var{nnn} if that argument is supplied (default unit is 2186114402Sru@samp{n}), otherwise it is set to the previous indentation value 2187114402Sruspecified with @code{TP}, @code{IP}, or @code{HP} (or the default 2188114402Sruvalue if non of them have been used yet). Font size and face are reset 2189114402Sruto their default values. 219075584Sru@endDefmac 219169626Sru 2192104862Sru@Defmac {RS, [@Var{nnn}], man} 2193104862Sru@cindex left margin, how to move [@code{man}] 2194104862Sru@cindex @code{man} macros, moving left margin 219575584SruMove the left margin to the right by the value @var{nnn} if specified 2196114402Sru(default unit is @samp{n}); otherwise it is set to the previous 2197114402Sruindentation value specified with @code{TP}, @code{IP}, or @code{HP} 2198114402Sru(or to the default value if none of them have been used yet). The 2199114402Sruindentation value is then set to the default. 2200114402Sru 2201114402SruCalls to the @code{RS} macro can be nested. 220275584Sru@endDefmac 220369626Sru 2204104862Sru@Defmac {RE, [@Var{nnn}], man} 2205114402SruMove the left margin back to level @var{nnn}, restoring the previous left 2206114402Srumargin. If no argument is given, it moves one level back. The first 2207114402Srulevel (i.e., no call to @code{RS} yet) has number@tie{}1, and each call 2208114402Sruto @code{RS} increases the level by@tie{}1. 220975584Sru@endDefmac 221069626Sru 2211104862Sru@cindex line breaks, with vertical space [@code{man}] 2212104862Sru@cindex @code{man} macros, line breaks with vertical space 221369626SruTo summarize, the following macros cause a line break with the insertion 221469626Sruof vertical space (which amount can be changed with the @code{PD} 221569626Srumacro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 221669626Sru@code{P}), @code{IP}, and @code{HP}. 221769626Sru 2218104862Sru@cindex line breaks, without vertical space [@code{man}] 2219104862Sru@cindex @code{man} macros, line breaks without vertical space 222069626SruThe macros @code{RS} and @code{RE} also cause a break but do not insert 222169626Sruvertical space. 222269626Sru 2223104862Sru@cindex default indentation, resetting [@code{man}] 2224104862Sru@cindex indentaion, resetting to default [@code{man}] 2225104862Sru@cindex @code{man} macros, resetting default indentation 2226104862SruFinally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}), 2227104862Sruand @code{RS} reset the indentation to its default value. 2228104862Sru 222969626Sru@c --------------------------------------------------------------------- 223069626Sru 223175584Sru@node Man font macros, Miscellaneous man macros, Man usage, man 223269626Sru@subsection Macros to set fonts 2233104862Sru@cindex font selection [@code{man}] 2234104862Sru@cindex @code{man} macros, how to set fonts 223569626Sru 2236114402SruThe standard font is roman; the default text size is 10@tie{}point. 2237104862SruIf command line option @option{-rS=@var{n}} is given, use 2238104862Sru@var{n}@dmn{pt} as the default text size. 223969626Sru 2240104862Sru@Defmac {SM, [@Var{text}], man} 224175584SruSet the text on the same line or the text on the next line in a font 224275584Sruthat is one point size smaller than the default font. 224375584Sru@endDefmac 224469626Sru 2245104862Sru@Defmac {SB, [@Var{text}], man} 2246104862Sru@cindex bold face [@code{man}] 2247104862Sru@cindex @code{man} macros, bold face 2248104862SruSet the text on the same line or the text on the next line in bold face 224975584Srufont, one point size smaller than the default font. 225075584Sru@endDefmac 225169626Sru 2252104862Sru@Defmac {BI, text, man} 2253114402SruSet its arguments alternately in bold face and italic, without a space 2254114402Srubetween the arguments. Thus, 225569626Sru 225675584Sru@Example 225769626Sru.BI this "word and" that 225875584Sru@endExample 225969626Sru 226069626Sru@noindent 2261114402Sruproduces ``thisword andthat'' with ``this'' and ``that'' in bold face, 2262114402Sruand ``word and'' in italics. 226375584Sru@endDefmac 226469626Sru 2265104862Sru@Defmac {IB, text, man} 2266114402SruSet its arguments alternately in italic and bold face, without a space 2267114402Srubetween the arguments. 226875584Sru@endDefmac 226969626Sru 2270104862Sru@Defmac {RI, text, man} 2271114402SruSet its arguments alternately in roman and italic, without a space between 2272114402Sruthe arguments. 227375584Sru@endDefmac 227469626Sru 2275104862Sru@Defmac {IR, text, man} 2276114402SruSet its arguments alternately in italic and roman, without a space between 2277114402Sruthe arguments. 227875584Sru@endDefmac 227969626Sru 2280104862Sru@Defmac {BR, text, man} 2281114402SruSet its arguments alternately in bold face and roman, without a space 2282114402Srubetween the arguments. 228375584Sru@endDefmac 228469626Sru 2285104862Sru@Defmac {RB, text, man} 2286114402SruSet its arguments alternately in roman and bold face, without a space 2287114402Srubetween the arguments. 228875584Sru@endDefmac 228969626Sru 2290104862Sru@Defmac {B, [@Var{text}], man} 229175584SruSet @var{text} in bold face. If no text is present on the line where 229275584Sruthe macro is called, then the text of the next line appears in bold 229375584Sruface. 229475584Sru@endDefmac 229569626Sru 2296104862Sru@Defmac {I, [@Var{text}], man} 2297104862Sru@cindex italic fonts [@code{man}] 2298104862Sru@cindex @code{man} macros, italic fonts 229975584SruSet @var{text} in italic. If no text is present on the line where the 230075584Srumacro is called, then the text of the next line appears in italic. 230175584Sru@endDefmac 230269626Sru 230369626Sru@c --------------------------------------------------------------------- 230469626Sru 230575584Sru@node Miscellaneous man macros, Predefined man strings, Man font macros, man 230675584Sru@subsection Miscellaneous macros 230769626Sru 230869626Sru@pindex grohtml 2309104862Sru@cindex @code{man} macros, default indentation 2310104862Sru@cindex default indentation [@code{man}] 2311114402SruThe default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in 2312114402Srunroff mode except for @code{grohtml} which ignores indentation. 231369626Sru 2314104862Sru@Defmac {DT, , man} 2315104862Sru@cindex tab stops [@code{man}] 2316104862Sru@cindex @code{man} macros, tab stops 2317114402SruSet tabs every 0.5@tie{}inches. Since this macro is always executed 2318104862Sruduring a call to the @code{TH} macro, it makes sense to call it only if 2319104862Sruthe tab positions have been changed. 232075584Sru@endDefmac 232169626Sru 2322104862Sru@Defmac {PD, [@Var{nnn}], man} 2323104862Sru@cindex empty space before a paragraph [@code{man}] 2324104862Sru@cindex @code{man} macros, empty space before a paragraph 232575584SruAdjust the empty space before a new paragraph (or section). The 232675584Sruoptional argument gives the amount of space (default unit is 232769626Sru@samp{v}); without parameter, the value is reset to its default value 2328114402Sru(1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise). 232969626Sru 233075584SruThis affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 233175584Sruwell as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2332114402Sru@endDefmac 233369626Sru 2334114402SruThe following two macros are included for 2335114402SruBSD compatibility. 2336114402Sru 2337114402Sru@Defmac {AT, [@Var{system} [@Var{release}]], man} 2338114402Sru@cindex @code{man}macros, BSD compatibility 2339114402SruAlter the footer for use with @acronym{AT&T} manpages. 2340114402SruThis command exists only for compatibility; don't use it. 2341114402SruThe first argument @var{system} can be: 2342114402Sru 2343114402Sru@table @code 2344114402Sru@item 3 2345114402Sru7th Edition (the default) 2346114402Sru 2347114402Sru@item 4 2348114402SruSystem III 2349114402Sru 2350114402Sru@item 5 2351114402SruSystem V 2352114402Sru@end table 2353114402Sru 2354114402SruAn optional second argument @var{release} to @code{AT} specifies the 2355114402Srurelease number (such as ``System V Release 3''). 2356114402Sru@endDefmac 2357114402Sru 2358114402Sru@Defmac {UC, [@Var{version}], man} 2359114402Sru@cindex @code{man}macros, BSD compatibility 2360114402SruAlters the footer for use with @acronym{BSD} manpages. 2361114402SruThis command exists only for compatibility; don't use it. 2362114402SruThe argument can be: 2363114402Sru 2364114402Sru@table @code 2365114402Sru@item 3 2366114402Sru3rd Berkeley Distribution (the default) 2367114402Sru 2368114402Sru@item 4 2369114402Sru4th Berkeley Distribution 2370114402Sru 2371114402Sru@item 5 2372114402Sru4.2 Berkeley Distribution 2373114402Sru 2374114402Sru@item 6 2375114402Sru4.3 Berkeley Distribution 2376114402Sru 2377114402Sru@item 7 2378114402Sru4.4 Berkeley Distribution 2379114402Sru@end table 2380114402Sru@endDefmac 2381114402Sru 238275584Sru@c --------------------------------------------------------------------- 238375584Sru 238475584Sru@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 238575584Sru@subsection Predefined strings 238675584Sru 238769626SruThe following strings are defined: 238869626Sru 2389104862Sru@Defstr {S, man} 239069626SruSwitch back to the default font size. 239175584Sru@endDefstr 239269626Sru 2393114402Sru@Defstr {HF, man} 2394114402SruThe typeface used for headings. 2395114402SruThe default is @samp{B}. 2396114402Sru@endDefstr 2397114402Sru 2398104862Sru@Defstr {R, man} 239969626SruThe `registered' sign. 240075584Sru@endDefstr 240169626Sru 2402104862Sru@Defstr {Tm, man} 240369626SruThe `trademark' sign. 240475584Sru@endDefstr 240569626Sru 2406104862Sru@DefstrList {lq, man} 2407104862Sru@DefstrListEnd {rq, man} 2408104862Sru@cindex @code{lq} glyph, and @code{lq} string [@code{man}] 2409104862Sru@cindex @code{rq} glyph, and @code{rq} string [@code{man}] 241075584SruLeft and right quote. This is equal to @code{\(lq} and @code{\(rq}, 241175584Srurespectively. 241275584Sru@endDefstr 241369626Sru 241475584Sru@c --------------------------------------------------------------------- 241575584Sru 2416114402Sru@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man 241775584Sru@subsection Preprocessors in @file{man} pages 241875584Sru 241969626Sru@cindex preprocessor, calling convention 242069626Sru@cindex calling convention of preprocessors 242169626SruIf a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 242269626Srubecome common usage to make the first line of the man page look like 242369626Sruthis: 242469626Sru 242575584Sru@Example 2426104862Sru'\" @var{word} 242775584Sru@endExample 242869626Sru 242969626Sru@pindex geqn@r{, invocation in manual pages} 243069626Sru@pindex grefer@r{, invocation in manual pages} 243169626Sru@pindex gtbl@r{, invocation in manual pages} 243269626Sru@pindex man@r{, invocation of preprocessors} 243375584Sru@noindent 243469626SruNote the single space character after the double quote. @var{word} 243569626Sruconsists of letters for the needed preprocessors: @samp{e} for 243669626Sru@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 243769626SruModern implementations of the @code{man} program read this first line 243869626Sruand automatically call the right preprocessor(s). 243969626Sru 2440114402Sru@c --------------------------------------------------------------------- 244169626Sru 2442114402Sru@node Optional man extensions, , Preprocessors in man pages, man 2443114402Sru@subsection Optional @file{man} extensions 2444114402Sru 2445114402Sru@pindex man.local 2446114402SruUse the file @file{man.local} for local extensions 2447114402Sruto the @code{man} macros or for style changes. 2448114402Sru 2449114402Sru@unnumberedsubsubsec Custom headers and footers 2450114402Sru@cindex @code{man} macros, custom headers and footers 2451114402Sru 2452114402SruIn groff versions 1.18.2 and later, you can specify custom 2453114402Sruheaders and footers by redefining the following macros in 2454114402Sru@file{man.local}. 2455114402Sru 2456114402Sru@Defmac {PT, , man} 2457114402SruControl the content of the headers. 2458114402SruNormally, the header prints the command name 2459114402Sruand section number on either side, and the 2460114402Sruoptional fifth argument to @code{TH} in the center. 2461114402Sru@endDefmac 2462114402Sru 2463114402Sru@Defmac {BT, , man} 2464114402SruControl the content of the footers. 2465114402SruNormally, the footer prints the page number 2466114402Sruand the third and fourth arguments to @code{TH}. 2467114402Sru 2468114402SruUse the @code{FT} number register to specify the 2469114402Srufooter position. 2470114402SruThe default is @minus{}0.5@dmn{i}. 2471114402Sru@endDefmac 2472114402Sru 2473114402Sru@unnumberedsubsubsec Ultrix-specific man macros 2474114402Sru@cindex Ultrix-specific @code{man} macros 2475114402Sru@cindex @code{man} macros, Ultrix-specific 2476114402Sru 2477114402Sru@pindex man.ultrix 2478114402SruThe @code{groff} source distribution includes 2479114402Srua file named @file{man.ultrix}, containing 2480114402Srumacros compatible with the Ultrix variant of 2481114402Sru@code{man}. 2482114402SruCopy this file into @file{man.local} (or use the @code{mso} request to 2483114402Sruload it) to enable the following macros. 2484114402Sru 2485114402Sru@Defmac {CT, @Var{key}, man} 2486114402SruPrint @samp{<CTRL/@var{key}>}. 2487114402Sru@endDefmac 2488114402Sru 2489114402Sru@Defmac {CW, , man} 2490114402SruPrint subsequent text using the constant width (Courier) typeface. 2491114402Sru@endDefmac 2492114402Sru 2493114402Sru@Defmac {Ds, , man} 2494114402SruBegin a non-filled display. 2495114402Sru@endDefmac 2496114402Sru 2497114402Sru@Defmac {De, , man} 2498114402SruEnd a non-filled display started with @code{Ds}. 2499114402Sru@endDefmac 2500114402Sru 2501114402Sru@Defmac {EX, [@Var{indent}], man} 2502114402SruBegins a non-filled display 2503114402Sruusing the constant width (Courier) typeface. 2504114402SruUse the optional @var{indent} argument to 2505114402Sruindent the display. 2506114402Sru@endDefmac 2507114402Sru 2508114402Sru@Defmac {EE, , man} 2509114402SruEnd a non-filled display started with @code{EX}. 2510114402Sru@endDefmac 2511114402Sru 2512114402Sru@Defmac {G, [@Var{text}], man} 2513114402SruSets @var{text} in Helvetica. 2514114402SruIf no text is present on the line where 2515114402Sruthe macro is called, then the text of the 2516114402Srunext line appears in Helvetica. 2517114402Sru@endDefmac 2518114402Sru 2519114402Sru@Defmac {GL, [@Var{text}], man} 2520114402SruSets @var{text} in Helvetica Oblique. 2521114402SruIf no text is present on the line where 2522114402Sruthe macro is called, then the text of the 2523114402Srunext line appears in Helvetica Oblique. 2524114402Sru@endDefmac 2525114402Sru 2526114402Sru@Defmac {HB, [@Var{text}], man} 2527114402SruSets @var{text} in Helvetica Bold. 2528114402SruIf no text is present on the line where 2529114402Sruthe macro is called, then all text up to 2530114402Sruthe next @code{HB} appears in Helvetica Bold. 2531114402Sru@endDefmac 2532114402Sru 2533114402Sru@Defmac {TB, [@Var{text}], man} 2534114402SruIdentical to @code{HB}. 2535114402Sru@endDefmac 2536114402Sru 2537114402Sru@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} 2538114402SruSet a manpage reference in Ultrix format. 2539114402SruThe @var{title} is in Courier instead of italic. 2540114402SruOptional punctuation follows the section number without 2541114402Sruan intervening space. 2542114402Sru@endDefmac 2543114402Sru 2544114402Sru@Defmac {NT, [@code{C}] [@Var{title}], man} 2545114402SruBegin a note. 2546114402SruPrint the optional @Var{title}, or the word ``Note'', 2547114402Srucentered on the page. 2548114402SruText following the macro makes up the body of the note, 2549114402Sruand is indented on both sides. 2550114402SruIf the first argument is @code{C}, the body of the 2551114402Srunote is printed centered (the second argument replaces 2552114402Sruthe word ``Note'' if specified). 2553114402Sru@endDefmac 2554114402Sru 2555114402Sru@Defmac {NE, , man} 2556114402SruEnd a note begun with @code{NT}. 2557114402Sru@endDefmac 2558114402Sru 2559114402Sru@Defmac {PN, @Var{path} [@Var{punct}], man} 2560114402SruSet the path name in constant width (Courier), 2561114402Srufollowed by optional punctuation. 2562114402Sru@endDefmac 2563114402Sru 2564114402Sru@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} 2565114402SruWhen called with two arguments, identical to @code{PN}. 2566114402SruWhen called with three arguments, 2567114402Sruset the second argument in constant width (Courier), 2568114402Srubracketed by the first and third arguments in the current font. 2569114402Sru@endDefmac 2570114402Sru 2571114402Sru@Defmac {R, , man} 2572114402SruSwitch to roman font and turn off any underlining in effect. 2573114402Sru@endDefmac 2574114402Sru 2575114402Sru@Defmac {RN, , man} 2576114402SruPrint the string @samp{<RETURN>}. 2577114402Sru@endDefmac 2578114402Sru 2579114402Sru@Defmac {VS, [@code{4}], man} 2580114402SruStart printing a change bar in the margin if 2581114402Sruthe number @code{4} is specified. 2582114402SruOtherwise, this macro does nothing. 2583114402Sru@endDefmac 2584114402Sru 2585114402Sru@Defmac {VE, , man} 2586114402SruEnd printing the change bar begun by @code{VS}. 2587114402Sru@endDefmac 2588114402Sru 2589114402Sru@unnumberedsubsubsec Simple example 2590114402Sru 2591114402SruThe following example @file{man.local} file 2592114402Srualters the @code{SH} macro to add some extra 2593114402Sruvertical space before printing the heading. 2594114402SruHeadings are printed in Helvetica Bold. 2595114402Sru 2596114402Sru@Example 2597114402Sru.\" Make the heading fonts Helvetica 2598114402Sru.ds HF HB 2599114402Sru. 2600114402Sru.\" Put more whitespace in front of headings. 2601114402Sru.rn SH SH-orig 2602114402Sru.de SH 2603114402Sru. if t .sp (u;\\n[PD]*2) 2604114402Sru. SH-orig \\$* 2605114402Sru.. 2606114402Sru@endExample 2607114402Sru 260869626Sru@c ===================================================================== 260969626Sru 261069626Sru@node mdoc, ms, man, Macro Packages 261169626Sru@section @file{mdoc} 2612104862Sru@cindex @code{mdoc} macros 261369626Sru 261469626Sru@c XXX documentation 2615104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 2616104862SruSee the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc} 2617104862Sruat the command line). 261869626Sru 261969626Sru 262069626Sru@c ===================================================================== 262169626Sru 262269626Sru@node ms, me, mdoc, Macro Packages 262369626Sru@section @file{ms} 2624104862Sru@cindex @code{ms} macros 262569626Sru 2626104862SruThe @file{-ms} 2627104862Srumacros are suitable for reports, letters, books, 2628104862Sruuser manuals, and so forth. 2629104862SruThe package provides macros for cover pages, section headings, 2630104862Sruparagraphs, lists, footnotes, pagination, 2631104862Sruand a table of contents. 263269626Sru 2633104862Sru@menu 2634104862Sru* ms Intro:: 2635104862Sru* General ms Structure:: 2636104862Sru* ms Document Control Registers:: 2637104862Sru* ms Cover Page Macros:: 2638104862Sru* ms Body Text:: 2639104862Sru* ms Page Layout:: 2640104862Sru* Differences from AT&T ms:: 2641104862Sru@end menu 264269626Sru 2643104862Sru@c --------------------------------------------------------------------- 2644104862Sru 2645104862Sru@node ms Intro, General ms Structure, ms, ms 2646104862Sru@subsection Introduction to @file{ms} 2647104862Sru 2648104862SruThe original @file{-ms} macros were included with 2649104862Sru@acronym{AT&T} @code{troff} as well as the 2650104862Sru@file{man} macros. 2651104862SruWhile the @file{man} package is intended for brief documents 2652104862Sruthat can be read on-line as well as printed, the @file{ms} 2653104862Srumacros are suitable for longer documents that are meant to be 2654104862Sruprinted rather than read on-line. 2655104862Sru 2656104862SruThe @file{ms} macro package included with @code{groff} 2657104862Sruis a complete, bottom-up re-implementation. 2658104862SruSeveral macros (specific to @acronym{AT&T} 2659104862Sruor Berkeley) are not included, while several new commands are. 2660104862Sru@xref{Differences from AT&T ms}, for more information. 2661104862Sru 2662104862Sru@c --------------------------------------------------------------------- 2663104862Sru 2664104862Sru@node General ms Structure, ms Document Control Registers, ms Intro, ms 2665104862Sru@subsection General structure of an @file{ms} document 2666104862Sru@cindex @code{ms} macros, general structure 2667104862Sru 2668104862SruThe @file{ms} macro package expects a certain amount of structure, 2669104862Srubut not as much as packages such as @file{man} or @file{mdoc}. 2670104862Sru 2671104862SruThe simplest documents can begin with a paragraph macro 2672104862Sru(such as @code{LP} or @code{PP}), 2673104862Sruand consist of text separated by paragraph macros 2674104862Sruor even blank lines. 2675104862SruLonger documents have a structure as follows: 2676104862Sru 2677104862Sru@table @strong 2678104862Sru@item Document type 2679104862SruIf you invoke the @code{RP} 2680104862Sru(report) macro on the first line of the document, 2681104862Sru@code{groff} prints the cover page information on its own page; 2682104862Sruotherwise it prints the information on the 2683104862Srufirst page with your document text immediately following. 2684104862SruOther document formats found in @acronym{AT&T} @code{troff} 2685104862Sruare specific to @acronym{AT&T} or Berkeley, and are not supported in 2686104862Sru@code{groff}. 2687104862Sru 2688104862Sru@item Format and layout 2689104862SruBy setting number registers, 2690104862Sruyou can change your document's type (font and size), 2691104862Srumargins, spacing, headers and footers, and footnotes. 2692104862Sru@xref{ms Document Control Registers}, for more details. 2693104862Sru 2694104862Sru@item Cover page 2695104862SruA cover page consists of a title, the author's name and institution, 2696104862Sruan abstract, and the date. 2697104862Sru@footnote{Actually, only the title is required.} 2698104862Sru@xref{ms Cover Page Macros}, for more details. 2699104862Sru 2700104862Sru@item Body 2701104862SruFollowing the cover page is your document. 2702104862SruYou can use the @file{ms} 2703104862Srumacros to write reports, letters, books, and so forth. 2704104862SruThe package is designed for structured documents, 2705104862Sruconsisting of paragraphs interspersed with headings 2706104862Sruand augmented by lists, footnotes, tables, and other 2707104862Srucommon constructs. 2708104862Sru@xref{ms Body Text}, for more details. 2709104862Sru 2710104862Sru@item Table of contents 2711104862SruLonger documents usually include a table of contents, 2712104862Sruwhich you can invoke by placing the 2713104862Sru@code{TC} 2714104862Srumacro at the end of your document. 2715104862SruThe @file{ms} 2716104862Srumacros have minimal indexing facilities, consisting of the 2717104862Sru@code{IX} macro, which prints an entry on standard error. 2718104862SruPrinting the table of contents at the end is necessary since 2719104862Sru@code{groff} is a single-pass text formatter, 2720104862Sruthus it cannot determine the page number of each section 2721104862Sruuntil that section has actually been set and printed. 2722104862SruSince @file{ms} output is intended for hardcopy, 2723104862Sruyou can manually relocate the pages containing 2724104862Sruthe table of contents between the cover page and the 2725104862Srubody text after printing. 2726104862Sru@end table 2727104862Sru 2728104862Sru@c --------------------------------------------------------------------- 2729104862Sru 2730104862Sru@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms 2731104862Sru@subsection Document control registers 2732104862Sru@cindex @code{ms} macros, document control registers 2733104862Sru 2734104862SruThe following is a list of document control number registers. 2735104862SruFor the sake of consistency, 2736104862Sruset registers related to margins at the beginning of your document, 2737104862Sruor just after the @code{RP} macro. 2738104862SruYou can set other registers later in your document, 2739104862Srubut you should keep them together at the beginning 2740104862Sruto make them easy to find and edit as necessary. 2741104862Sru 2742104862Sru@unnumberedsubsubsec Margin Settings 2743104862Sru 2744104862Sru@Defmpreg {PO, ms} 2745104862SruDefines the page offset (i.e.@: the left margin). 2746104862SruThere is no explicit right margin setting; the combination of 2747104862Sruthe @code{PO} and @code{LL} registers implicitly define the 2748104862Sruright margin width. 2749104862Sru 2750104862SruEffective: next page. 2751104862Sru 2752104862SruDefault value: 1@dmn{i}. 2753104862Sru@endDefmpreg 2754104862Sru 2755104862Sru@Defmpreg {LL, ms} 2756104862SruDefines the line length (i.e.@: the width of the body text). 2757104862Sru 2758104862SruEffective: next paragraph. 2759104862Sru 2760104862SruDefault: 6@dmn{i}. 2761104862Sru@endDefmpreg 2762104862Sru 2763104862Sru@Defmpreg {LT, ms} 2764104862SruDefines the title length (i.e.@: the header and footer width). 2765104862SruThis is usually the same as @code{LL}, but not necessarily. 2766104862Sru 2767104862SruEffective: next paragraph. 2768104862Sru 2769104862SruDefault: 6@dmn{i}. 2770104862Sru@endDefmpreg 2771104862Sru 2772104862Sru@Defmpreg {HM, ms} 2773104862SruDefines the header margin height at the top of the page. 2774104862Sru 2775104862SruEffective: next page. 2776104862Sru 2777104862SruDefault: 1@dmn{i}. 2778104862Sru@endDefmpreg 2779104862Sru 2780104862Sru@Defmpreg {FM, ms} 2781104862SruDefines the footer margin height at the bottom of the page. 2782104862Sru 2783104862SruEffective: next page. 2784104862Sru 2785104862SruDefault: 1@dmn{i}. 2786104862Sru@endDefmpreg 2787104862Sru 2788104862Sru@unnumberedsubsubsec Text Settings 2789104862Sru 2790104862Sru@Defmpreg {PS, ms} 2791104862SruDefines the point size of the body text. 2792104862Sru 2793104862SruEffective: next paragraph. 2794104862Sru 2795104862SruDefault: 10@dmn{p}. 2796104862Sru@endDefmpreg 2797104862Sru 2798104862Sru@Defmpreg {VS, ms} 2799104862SruDefines the space between lines (line height plus leading). 2800104862Sru 2801104862SruEffective: next paragraph. 2802104862Sru 2803104862SruDefault: 12@dmn{p}. 2804104862Sru@endDefmpreg 2805104862Sru 2806104862Sru@unnumberedsubsubsec Paragraph Settings 2807104862Sru 2808104862Sru@Defmpreg {PI, ms} 2809104862SruDefines the initial indent of a @code{.PP} paragraph. 2810104862Sru 2811104862SruEffective: next paragraph. 2812104862Sru 2813104862SruDefault: 5@dmn{n}. 2814104862Sru@endDefmpreg 2815104862Sru 2816104862Sru@Defmpreg {PD, ms} 2817104862SruDefines the space between paragraphs. 2818104862Sru 2819104862SruEffective: next paragraph. 2820104862Sru 2821104862SruDefault: 0.3@dmn{v}. 2822104862Sru@endDefmpreg 2823104862Sru 2824104862Sru@Defmpreg {QI, ms} 2825104862SruDefines the indent on both sides of a quoted (@code{.QP}) paragraph. 2826104862Sru 2827104862SruEffective: next paragraph. 2828104862Sru 2829104862SruDefault: 5@dmn{n}. 2830104862Sru@endDefmpreg 2831104862Sru 2832104862Sru@unnumberedsubsubsec Footnote Settings 2833104862Sru 2834104862Sru@Defmpreg {FL, ms} 2835104862SruDefines the length of a footnote. 2836104862Sru 2837104862SruEffective: next footnote. 2838104862Sru 2839104862SruDefault: @math{@code{@\n[LL]} * 5 / 6}. 2840104862Sru@endDefmpreg 2841104862Sru 2842104862Sru@Defmpreg {FI, ms} 2843104862SruDefines the footnote indent. 2844104862Sru 2845104862SruEffective: next footnote. 2846104862Sru 2847104862SruDefault: 2@dmn{n}. 2848104862Sru@endDefmpreg 2849104862Sru 2850104862Sru@Defmpreg {FF, ms} 2851104862SruThe footnote format: 2852104862Sru@table @code 2853104862Sru@item 0 2854104862SruPrints the footnote number as a superscript; indents the footnote (default). 2855104862Sru 2856104862Sru@item 1 2857104862SruPrints the number followed by a period (like 1.) 2858104862Sruand indents the footnote. 2859104862Sru 2860104862Sru@item 2 2861104862SruLike 1, without an indent. 2862104862Sru 2863104862Sru@item 3 2864104862SruLike 1, but prints the footnote number as a hanging paragraph. 2865104862Sru@end table 2866104862Sru 2867104862SruEffective: next footnote. 2868104862Sru 2869104862SruDefault: 0. 2870104862Sru@endDefmpreg 2871104862Sru 2872104862Sru@unnumberedsubsubsec Miscellaneous Number Registers 2873104862Sru 2874104862Sru@Defmpreg {MINGW, ms} 2875104862SruDefines the minimum width between columns in a multi-column document. 2876104862Sru 2877104862SruEffective: next page. 2878104862Sru 2879104862SruDefault: 2@dmn{n}. 2880104862Sru@endDefmpreg 2881104862Sru 2882104862Sru@c --------------------------------------------------------------------- 2883104862Sru 2884104862Sru@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms 2885104862Sru@subsection Cover page macros 2886104862Sru@cindex @code{ms} macros, cover page 2887104862Sru@cindex cover page macros, [@code{ms}] 2888104862Sru 2889104862SruUse the following macros to create a cover page for your document 2890104862Sruin the order shown. 2891104862Sru 2892104862Sru@Defmac {RP, [@code{no}], ms} 2893104862SruSpecifies the report format for your document. 2894104862SruThe report format creates a separate cover page. 2895104862SruThe default action (no @code{.RP} 2896104862Srumacro) is to print a subset of the 2897104862Srucover page on page 1 of your document. 2898104862Sru 2899104862SruIf you use the word @code{no} as an optional argument, 2900104862Sru@code{groff} prints a title page but 2901104862Srudoes not repeat any of the title page information 2902104862Sru(title, author, abstract, etc.) 2903104862Sruon page 1 of the document. 2904104862Sru@endDefmac 2905104862Sru 2906104862Sru@Defmac {DA, [@dots{}], ms} 2907104862Sru(optional) Print the current date, or the arguments to the macro if any, 2908104862Sruon the title page (if specified) and in the footers. 2909104862SruThis is the default for @code{nroff}. 2910104862Sru@endDefmac 2911104862Sru 2912104862Sru@Defmac {ND, [@dots{}], ms} 2913104862Sru(optional) Print the current date, or the arguments to the macro if any, 2914104862Sruon the title page (if specified) but not in the footers. 2915104862SruThis is the default for @code{troff}. 2916104862Sru@endDefmac 2917104862Sru 2918104862Sru@Defmac {TL, , ms} 2919104862SruSpecifies the document title. 2920104862Sru@code{groff} collects text following the @code{.TL} 2921104862Srumacro into the title, until reaching the author name or abstract. 2922104862Sru@endDefmac 2923104862Sru 2924104862Sru@Defmac {AU, , ms} 2925104862SruSpecifies the author's name, which appears on the 2926104862Sruline (or lines) immediately following. 2927104862SruYou can specify multiple authors as follows: 2928104862Sru 2929104862Sru@Example 2930104862Sru.AU 2931104862SruJohn Doe 2932104862Sru.AI 2933104862SruUniversity of West Bumblefuzz 2934104862Sru.AU 2935104862SruMartha Buck 2936104862Sru.AI 2937104862SruMonolithic Corporation 2938104862Sru 2939104862Sru... 2940104862Sru@endExample 2941104862Sru@endDefmac 2942104862Sru 2943104862Sru@Defmac {AI, , ms} 2944104862SruSpecifies the author's institution. 2945104862SruYou can specify multiple institutions in the same way 2946104862Sruthat you specify multiple authors. 2947104862Sru@endDefmac 2948104862Sru 2949104862Sru@Defmac {AB, [@code{no}], ms} 2950104862SruBegins the abstract. 2951104862SruThe default is to print the word @acronym{ABSTRACT}, 2952104862Srucentered and in italics, above the text of the abstract. 2953104862SruThe word @code{no} as an optional argument suppresses this heading. 2954104862Sru@endDefmac 2955104862Sru 2956104862Sru@Defmac {AE, , ms} 2957104862SruEnd the abstract. 2958104862Sru@endDefmac 2959104862Sru 2960104862SruThe following is example mark-up for a title page. 2961104862Sru@cindex title page, example markup 2962104862Sru@cindex example markup, title page 2963104862Sru 2964104862Sru@Example 2965104862Sru@cartouche 2966104862Sru.RP 2967104862Sru.TL 2968104862SruThe Inevitability of Code Bloat 2969104862Sruin Commercial and Free Software 2970104862Sru.AU 2971104862SruJ. Random Luser 2972104862Sru.AI 2973104862SruUniversity of West Bumblefuzz 2974104862Sru.AB 2975104862SruThis report examines the long-term growth 2976104862Sruof the code bases in two large, popular software 2977104862Srupackages; the free Emacs and the commercial 2978104862SruMicrosoft Word. 2979104862SruWhile differences appear in the type or order 2980104862Sruof features added, due to the different 2981104862Srumethodologies used, the results are the same 2982104862Sruin the end. 2983104862Sru.PP 2984104862SruThe free software approach is shown to be 2985104862Srusuperior in that while free software can 2986104862Srubecome as bloated as commercial offerings, 2987104862Srufree software tends to have fewer serious 2988104862Srubugs and the added features are in line with 2989104862Sruuser demand. 2990104862Sru.AE 2991104862Sru 2992104862Sru... the rest of the paper follows ... 2993104862Sru@end cartouche 2994104862Sru@endExample 2995104862Sru 2996104862Sru@c --------------------------------------------------------------------- 2997104862Sru 2998104862Sru@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms 2999104862Sru@subsection Body text 3000104862Sru@cindex @code{ms} macros, body text 3001104862Sru 3002104862SruThis section describes macros used to mark up the body of your document. 3003104862SruExamples include paragraphs, sections, and other groups. 3004104862Sru 3005104862Sru@menu 3006104862Sru* Paragraphs in ms:: 3007104862Sru* Headings in ms:: 3008104862Sru* Highlighting in ms:: 3009104862Sru* Lists in ms:: 3010104862Sru* Indents in ms:: 3011104862Sru* Tabstops in ms:: 3012104862Sru* ms Displays and Keeps:: 3013104862Sru* ms Insertions:: 3014104862Sru* Example multi-page table:: 3015104862Sru* ms Footnotes:: 3016104862Sru@end menu 3017104862Sru 3018104862Sru@c --------------------------------------------------------------------- 3019104862Sru 3020104862Sru@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text 3021104862Sru@subsubsection Paragraphs 3022104862Sru@cindex @code{ms} macros, paragraph handling 3023104862Sru 3024104862SruThe following paragraph types are available. 3025104862Sru 3026104862Sru@Defmac {PP, , ms} 3027104862SruSets a paragraph with an initial indent. 3028104862Sru@endDefmac 3029104862Sru 3030104862Sru@Defmac {LP, , ms} 3031104862SruSets a paragraph with no initial indent. 3032104862Sru@endDefmac 3033104862Sru 3034104862Sru@Defmac {QP, , ms} 3035104862SruSets a paragraph that is indented at both left and right margins. 3036104862SruThe effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element. 3037104862SruThe next paragraph or heading returns margins to normal. 3038104862Sru@endDefmac 3039104862Sru 3040104862Sru@Defmac {XP, , ms} 3041104862SruSets a paragraph whose lines are indented, 3042104862Sruexcept for the first line. 3043104862SruThis is a Berkeley extension. 3044104862Sru@endDefmac 3045104862Sru 3046104862SruThe following markup uses all four paragraph macros. 3047104862Sru 3048104862Sru@Example 3049104862Sru@cartouche 3050104862Sru.NH 2 3051104862SruCases used in the study 3052104862Sru.LP 3053104862SruThe following software and versions were 3054104862Sruconsidered for this report. 3055104862Sru.PP 3056104862SruFor commercial software, we chose 3057104862Sru.B "Microsoft Word for Windows" , 3058104862Srustarting with version 1.0 through the 3059104862Srucurrent version (Word 2000). 3060104862Sru.PP 3061104862SruFor free software, we chose 3062104862Sru.B Emacs , 3063104862Srufrom its first appearance as a standalone 3064104862Srueditor through the current version (v20). 3065104862SruSee [Bloggs 2002] for details. 3066104862Sru.QP 3067104862SruFranklin's Law applied to software: 3068104862Srusoftware expands to outgrow both 3069104862SruRAM and disk space over time. 3070104862Sru.LP 3071104862SruBibliography: 3072104862Sru.XP 3073104862SruBloggs, Joseph R., 3074104862Sru.I "Everyone's a Critic" , 3075104862SruUnderground Press, March 2002. 3076104862SruA definitive work that answers all questions 3077104862Sruand criticisms about the quality and usability of 3078104862Srufree software. 3079104862Sru 3080104862Sru@end cartouche 3081104862Sru@endExample 3082104862Sru 3083104862Sru@c --------------------------------------------------------------------- 3084104862Sru 3085104862Sru@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text 3086104862Sru@subsubsection Headings 3087104862Sru@cindex @code{ms} macros, headings 3088104862Sru 3089104862SruUse headings to create a hierarchical structure for your document. 3090104862SruThe @file{ms} macros print headings in @strong{bold}, 3091104862Sruusing the same font family and point size as the body text. 3092104862Sru 3093104862SruThe following describes the heading macros: 3094104862Sru 3095104862Sru@DefmacList {NH, @Var{curr-level}, ms} 3096104862Sru@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} 3097104862SruNumbered heading. 3098104862SruThe argument is either a numeric argument to indicate the 3099114402Srulevel of the heading, or the letter@tie{}@code{S} followed by numeric 3100104862Sruarguments to set the heading level explicitly. 3101104862Sru 3102104862SruIf you specify heading levels out of sequence, such as invoking 3103104862Sru@samp{.NH 3} after @samp{.NH 1}, @code{groff} 3104104862Sruprints a warning on standard error. 3105104862Sru@endDefmac 3106104862Sru 3107104862Sru@Defmac {SH, , ms} 3108104862SruUnnumbered subheading. 3109104862Sru@endDefmac 3110104862Sru 3111104862Sru@c --------------------------------------------------------------------- 3112104862Sru 3113104862Sru@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text 3114104862Sru@subsubsection Highlighting 3115104862Sru@cindex @code{ms} macros, highlighting 3116104862Sru 3117104862SruThe @file{ms} macros provide a variety of methods to highlight 3118104862Sruor emphasize text: 3119104862Sru 3120104862Sru@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3121104862SruSets its first argument in @strong{bold type}. 3122104862SruIf you specify a second argument, @code{groff} prints it in the 3123104862Sruprevious font after the bold text, with no intervening space 3124104862Sru(this allows you to set punctuation after the highlighted text 3125104862Sruwithout highlighting the punctuation). 3126104862SruSimilarly, it prints the third argument (if any) in the previous 3127104862Srufont @strong{before} the first argument. 3128104862SruFor example, 3129104862Sru 3130104862Sru@Example 3131104862Sru.B foo ) ( 3132104862Sru@endExample 3133104862Sru 3134104862Sruprints (@strong{foo}). 3135104862Sru 3136104862SruIf you give this macro no arguments, @code{groff} 3137104862Sruprints all text following in bold until 3138104862Sruthe next highlighting, paragraph, or heading macro. 3139104862Sru@endDefmac 3140104862Sru 3141104862Sru@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3142104862SruSets its first argument in roman (or regular) type. 3143114402SruIt operates similarly to the @code{B}@tie{}macro otherwise. 3144104862Sru@endDefmac 3145104862Sru 3146104862Sru@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3147104862SruSets its first argument in @emph{italic type}. 3148114402SruIt operates similarly to the @code{B}@tie{}macro otherwise. 3149104862Sru@endDefmac 3150104862Sru 3151104862Sru@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3152104862SruSets its first argument in a @code{constant width face}. 3153114402SruIt operates similarly to the @code{B}@tie{}macro otherwise. 3154104862Sru@endDefmac 3155104862Sru 3156104862Sru@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3157104862SruSets its first argument in bold italic type. 3158114402SruIt operates similarly to the @code{B}@tie{}macro otherwise. 3159104862Sru@endDefmac 3160104862Sru 3161104862Sru@Defmac {BX, [@Var{txt}], ms} 3162104862SruPrints its argument and draws a box around it. 3163104862SruIf you want to box a string that contains spaces, 3164104862Sruuse a digit-width space (@code{\0}). 3165104862Sru@endDefmac 3166104862Sru 3167104862Sru@Defmac {UL, [@Var{txt} [@Var{post}]], ms} 3168104862SruPrints its first argument with an underline. 3169104862SruIf you specify a second argument, @code{groff} 3170104862Sruprints it in the previous font after 3171104862Sruthe underlined text, with no intervening space. 3172104862Sru@endDefmac 3173104862Sru 3174104862Sru@Defmac {LG, , ms} 3175104862SruPrints all text following in larger type 3176104862Sru(two points larger than the current point size) until 3177104862Sruthe next font size, highlighting, paragraph, or heading macro. 3178104862SruYou can specify this macro multiple times 3179104862Sruto enlarge the point size as needed. 3180104862Sru@endDefmac 3181104862Sru 3182104862Sru@Defmac {SM, , ms} 3183104862SruPrints all text following in smaller type 3184104862Sru(two points smaller than the current point size) until 3185104862Sruthe next type size, highlighting, paragraph, or heading macro. 3186104862SruYou can specify this macro multiple times 3187104862Sruto reduce the point size as needed. 3188104862Sru@endDefmac 3189104862Sru 3190104862Sru@Defmac {NL, , ms} 3191104862SruPrints all text following in the normal point size 3192104862Sru(that is, the value of the @code{PS} register). 3193104862Sru@endDefmac 3194104862Sru 3195104862Sru@c --------------------------------------------------------------------- 3196104862Sru 3197104862Sru@node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text 3198104862Sru@subsubsection Lists 3199104862Sru@cindex @code{ms} macros, lists 3200104862Sru 3201104862SruThe @code{.IP} macro handles duties for all lists. 3202104862Sru 3203104862Sru@Defmac {IP, [@Var{marker} [@Var{width}]], ms} 3204104862SruThe @var{marker} is usually a bullet glyph (@code{\[bu]}) 3205104862Srufor unordered lists, a number (or auto-incrementing number 3206104862Sruregister) for numbered lists, or a word or phrase for indented 3207104862Sru(glossary-style) lists. 3208104862Sru 3209104862SruThe @var{width} specifies the indent for the body of each list item; 3210104862Sruits default unit is @samp{n}. 3211104862SruOnce specified, the indent remains the same for all 3212104862Srulist items in the document until specified again. 3213104862Sru@endDefmac 3214104862Sru 3215104862SruThe following is an example of a bulleted list. 3216104862Sru@cindex example markup, bulleted list [@code{ms}] 3217104862Sru@cindex bulleted list, example markup [@code{ms}] 3218104862Sru 3219104862Sru@Example 3220104862SruA bulleted list: 3221104862Sru.IP \[bu] 2 3222104862Srulawyers 3223104862Sru.IP \[bu] 3224104862Sruguns 3225104862Sru.IP \[bu] 3226104862Srumoney 3227104862Sru@endExample 3228104862Sru 3229104862SruProduces: 3230104862Sru 3231104862Sru@Example 3232104862SruA bulleted list: 3233104862Sru 3234104862Sruo lawyers 3235104862Sru 3236104862Sruo guns 3237104862Sru 3238104862Sruo money 3239104862Sru@endExample 3240104862Sru 3241104862Sru@sp 1 3242104862Sru 3243104862SruThe following is an example of a numbered list. 3244104862Sru@cindex example markup, numbered list [@code{ms}] 3245104862Sru@cindex numbered list, example markup [@code{ms}] 3246104862Sru 3247104862Sru@Example 3248104862Sru.nr step 1 1 3249104862SruA numbered list: 3250104862Sru.IP \n[step] 3 3251104862Srulawyers 3252104862Sru.IP \n+[step] 3253104862Sruguns 3254104862Sru.IP \n+[step] 3255104862Srumoney 3256104862Sru@endExample 3257104862Sru 3258104862SruProduces: 3259104862Sru 3260104862Sru@Example 3261104862SruA numbered list: 3262104862Sru 3263104862Sru1. lawyers 3264104862Sru 3265104862Sru2. guns 3266104862Sru 3267104862Sru3. money 3268104862Sru@endExample 3269104862Sru 3270104862SruNote the use of the auto-incrementing number 3271104862Sruregister in this example. 3272104862Sru 3273104862Sru@sp 1 3274104862SruThe following is an example of a glossary-style list. 3275104862Sru@cindex example markup, glossary-style list [@code{ms}] 3276104862Sru@cindex glossary-style list, example markup [@code{ms}] 3277104862Sru 3278104862Sru@Example 3279104862SruA glossary-style list: 3280104862Sru.IP lawyers 0.4i 3281104862SruTwo or more attorneys. 3282104862Sru.IP guns 3283104862SruFirearms, preferably 3284104862Srularge-caliber. 3285104862Sru.IP money 3286104862SruGotta pay for those 3287104862Srulawyers and guns! 3288104862Sru@endExample 3289104862Sru 3290104862SruProduces: 3291104862Sru 3292104862Sru@Example 3293104862SruA glossary-style list: 3294104862Sru 3295104862Srulawyers 3296104862Sru Two or more attorneys. 3297104862Sru 3298104862Sruguns Firearms, preferably large-caliber. 3299104862Sru 3300104862Srumoney 3301104862Sru Gotta pay for those lawyers and guns! 3302104862Sru@endExample 3303104862Sru 3304104862SruIn the last example, the @code{IP} macro places the definition 3305104862Sruon the same line as the term if it has enough space; otherwise, 3306104862Sruit breaks to the next line and starts the definition below the 3307104862Sruterm. 3308104862SruThis may or may not be the effect you want, especially if some 3309104862Sruof the definitions break and some do not. 3310104862SruThe following examples show two possible ways to force a break. 3311104862Sru 3312104862SruThe first workaround uses the @code{br} 3313104862Srurequest to force a break after printing the term or label. 3314104862Sru 3315104862Sru@Example 3316104862Sru@cartouche 3317104862SruA glossary-style list: 3318104862Sru.IP lawyers 0.4i 3319104862SruTwo or more attorneys. 3320104862Sru.IP guns 3321104862Sru.br 3322104862SruFirearms, preferably large-caliber. 3323104862Sru.IP money 3324104862SruGotta pay for those lawyers and guns! 3325104862Sru@end cartouche 3326104862Sru@endExample 3327104862Sru 3328104862Sru@sp 1 3329104862SruThe second workaround uses the @code{\p} escape to force the break. 3330104862SruNote the space following the escape; this is important. 3331104862SruIf you omit the space, @code{groff} prints the first word on 3332104862Sruthe same line as the term or label (if it fits) @strong{then} 3333104862Srubreaks the line. 3334104862Sru 3335104862Sru@Example 3336104862Sru@cartouche 3337104862SruA glossary-style list: 3338104862Sru.IP lawyers 0.4i 3339104862SruTwo or more attorneys. 3340104862Sru.IP guns 3341104862Sru\p Firearms, preferably large-caliber. 3342104862Sru.IP money 3343104862SruGotta pay for those lawyers and guns! 3344104862Sru@end cartouche 3345104862Sru@endExample 3346104862Sru 3347104862Sru@sp 1 3348104862SruTo set nested lists, use the @code{RS} and @code{RE} macros. 3349104862Sru@xref{Indents in ms}, for more information. 3350104862Sru@cindex @code{ms} macros, nested lists 3351104862Sru@cindex nested lists [@code{ms}] 3352104862Sru 3353104862SruFor example: 3354104862Sru 3355104862Sru@Example 3356104862Sru@cartouche 3357104862Sru.IP \[bu] 2 3358104862SruLawyers: 3359104862Sru.RS 3360104862Sru.IP \[bu] 3361104862SruDewey, 3362104862Sru.IP \[bu] 3363104862SruCheatham, 3364104862Sru.IP \[bu] 3365104862Sruand Howe. 3366104862Sru.RE 3367104862Sru.IP \[bu] 3368104862SruGuns 3369104862Sru@end cartouche 3370104862Sru@endExample 3371104862Sru 3372104862SruProduces: 3373104862Sru 3374104862Sru@Example 3375104862Sruo Lawyers: 3376104862Sru 3377104862Sru o Dewey, 3378104862Sru 3379104862Sru o Cheatham, 3380104862Sru 3381104862Sru o and Howe. 3382104862Sru 3383104862Sruo Guns 3384104862Sru@endExample 3385104862Sru 3386104862Sru@c --------------------------------------------------------------------- 3387104862Sru 3388104862Sru@node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text 3389104862Sru@subsubsection Indents 3390104862Sru 3391104862SruIn many situations, 3392104862Sruyou may need to indent a section of text 3393104862Sruwhile still wrapping and filling. 3394104862Sru@xref{Lists in ms}, 3395104862Srufor an example of nested lists. 3396104862Sru 3397104862Sru@DefmacList {RS, , ms} 3398104862Sru@DefmacListEnd {RE, , ms} 3399104862SruThese macros begin and end an indented section. 3400104862SruThe @code{PI} register controls the amount of indent, 3401104862Sruallowing the indented text to line up under hanging 3402104862Sruand indented paragraphs. 3403104862Sru@endDefmac 3404104862Sru 3405104862Sru@xref{ms Displays and Keeps}, 3406104862Srufor macros to indent and turn off filling. 3407104862Sru 3408104862Sru@c --------------------------------------------------------------------- 3409104862Sru 3410104862Sru@node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text 3411104862Sru@subsubsection Tab Stops 3412104862Sru 3413104862SruUse the @code{ta} request to define tab stops as needed. 3414104862Sru@xref{Tabs and Fields}. 3415104862Sru 3416104862Sru@Defmac{TA, , ms} 3417104862SruUse this macro to reset the tab stops to the default for @file{ms} 3418104862Sru(every 5n). 3419104862SruYou can redefine the @code{TA} macro to create a different set 3420104862Sruof default tab stops. 3421104862Sru@endDefmac 3422104862Sru 3423104862Sru@c --------------------------------------------------------------------- 3424104862Sru 3425104862Sru@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text 3426104862Sru@subsubsection Displays and keeps 3427104862Sru@cindex @code{ms} macros, displays 3428104862Sru@cindex @code{ms} macros, keeps 3429104862Sru@cindex keeps [@code{ms}] 3430104862Sru@cindex displays [@code{ms}] 3431104862Sru 3432104862SruUse displays to show text-based examples or figures 3433104862Sru(such as code listings). 3434104862Sru 3435104862SruDisplays turn off filling, so lines of code are displayed 3436104862Sruas-is without inserting @code{br} requests in between each line. 3437104862SruDisplays can be @dfn{kept} on a single page, or allowed 3438104862Sruto break across pages. 3439104862Sru 3440104862Sru@DefmacList {DS, @t{L}, ms} 3441104862Sru@DefmacItem {LD, , ms} 3442104862Sru@DefmacListEnd {DE, , ms} 3443104862SruLeft-justified display. 3444104862SruThe @samp{.DS L} call generates a page break, if necessary, 3445104862Sruto keep the entire display on one page. 3446104862SruThe @code{LD} macro allows the display to break across pages. 3447104862SruThe @code{DE} macro ends the display. 3448104862Sru@endDefmac 3449104862Sru 3450104862Sru@DefmacList {DS, @t{I}, ms} 3451104862Sru@DefmacItem {ID, , ms} 3452104862Sru@DefmacListEnd {DE, , ms} 3453104862SruIndents the display as defined by the @code{DI} register. 3454104862SruThe @samp{.DS I} call generates a page break, if necessary, 3455104862Sruto keep the entire display on one page. 3456104862SruThe @code{ID} macro allows the display to break across pages. 3457104862SruThe @code{DE} macro ends the display. 3458104862Sru@endDefmac 3459104862Sru 3460104862Sru@DefmacList {DS, @t{B}, ms} 3461104862Sru@DefmacItem {BD, , ms} 3462104862Sru@DefmacListEnd {DE, , ms} 3463104862SruSets a block-centered display: the entire display is left-justified, 3464104862Srubut indented so that the longest line in the display is centered 3465104862Sruon the page. 3466104862SruThe @samp{.DS B} call generates a page break, if necessary, 3467104862Sruto keep the entire display on one page. 3468104862SruThe @code{BD} macro allows the display to break across pages. 3469104862SruThe @code{DE} macro ends the display. 3470104862Sru@endDefmac 3471104862Sru 3472104862Sru@DefmacList {DS, @t{C}, ms} 3473104862Sru@DefmacItem {CD, , ms} 3474104862Sru@DefmacListEnd {DE, , ms} 3475104862SruSets a centered display: each line in the display is centered. 3476104862SruThe @samp{.DS C} call generates a page break, if necessary, 3477104862Sruto keep the entire display on one page. 3478104862SruThe @code{CD} macro allows the display to break across pages. 3479104862SruThe @code{DE} macro ends the display. 3480104862Sru@endDefmac 3481104862Sru 3482104862Sru@DefmacList {DS, @t{R}, ms} 3483104862Sru@DefmacItem {RD, , ms} 3484104862Sru@DefmacListEnd {DE, , ms} 3485104862SruRight-justifies each line in the display. 3486104862SruThe @samp{.DS R} call generates a page break, if necessary, 3487104862Sruto keep the entire display on one page. 3488104862SruThe @code{RD} macro allows the display to break across pages. 3489104862SruThe @code{DE} macro ends the display. 3490104862Sru@endDefmac 3491104862Sru 3492104862Sru@sp 1 3493104862SruOn occasion, you may want to @dfn{keep} other text together on a page. 3494104862SruFor example, you may want to keep two paragraphs together, or 3495104862Srua paragraph that refers to a table (or list, or other item) 3496104862Sruimmediately following. 3497104862SruThe @file{ms} macros provide the @code{KS} and @code{KE} 3498104862Srumacros for this purpose. 3499104862Sru 3500104862Sru@DefmacList {KS, , ms} 3501104862Sru@DefmacListEnd {KE, , ms} 3502104862SruThe @code{KS} macro begins a block of text to be kept on a 3503104862Srusingle page, and the @code{KE} macro ends the block. 3504104862Sru@endDefmac 3505104862Sru 3506104862Sru@DefmacList {KF, , ms} 3507104862Sru@DefmacListEnd {KE, , ms} 3508104862SruSpecifies a @dfn{floating keep}; 3509104862Sruif the keep cannot fit on the current page, @code{groff} 3510104862Sruholds the contents of the keep and allows text following 3511104862Sruthe keep (in the source file) to fill in the remainder of 3512104862Sruthe current page. 3513104862SruWhen the page breaks, whether by an explicit @code{bp} 3514104862Srurequest or by reaching the end of the page, @code{groff} 3515104862Sruprints the floating keep at the top of the new page. 3516104862SruThis is useful for printing large graphics or tables 3517104862Sruthat do not need to appear exactly where specified. 3518104862Sru@endDefmac 3519104862Sru 3520104862SruYou can also use the @code{ne} request to force a page break if 3521104862Sruthere is not enough vertical space remaining on the page. 3522104862Sru 3523104862Sru@sp 1 3524104862SruUse the following macros to draw a box around a section of 3525104862Srutext (such as a display). 3526104862Sru 3527104862Sru@DefmacList {B1, , ms} 3528104862Sru@DefmacListEnd {B2, , ms} 3529104862SruMarks the beginning and ending of text that is to have a 3530104862Srubox drawn around it. 3531104862SruThe @code{B1} macro begins the box; the @code{B2} macro ends it. 3532104862SruText in the box is automatically placed in a diversion (keep). 3533104862Sru@endDefmac 3534104862Sru 3535104862Sru@c --------------------------------------------------------------------- 3536104862Sru 3537104862Sru@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text 3538104862Sru@subsubsection Tables, figures, equations, and references 3539104862Sru@cindex @code{ms} macros, tables 3540104862Sru@cindex @code{ms} macros, figures 3541104862Sru@cindex @code{ms} macros, equations 3542104862Sru@cindex @code{ms} macros, references 3543104862Sru@cindex tables [@code{ms}] 3544104862Sru@cindex figures [@code{ms}] 3545104862Sru@cindex equations [@code{ms}] 3546104862Sru@cindex references [@code{ms}] 3547104862Sru 3548104862SruThe @file{ms} macros support the standard 3549104862Sru@code{groff} preprocessors: 3550104862Sru@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. 3551104862Sru@pindex tbl 3552104862Sru@pindex pic 3553104862Sru@pindex eqn 3554104862Sru@pindex refer 3555104862SruYou mark text meant for preprocessors by enclosing it 3556104862Sruin pairs of tags as follows. 3557104862Sru 3558104862Sru@DefmacList {TS, [@code{H}], ms} 3559104862Sru@DefmacListEnd {TE, , ms} 3560104862SruDenotes a table, to be processed by the @code{tbl} preprocessor. 3561114402SruThe optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} 3562104862Sruto create a running header with the information 3563104862Sruup to the @code{TH} macro. 3564104862Sru@code{groff} prints the header at the beginning of the 3565104862Srutable; if the table runs onto another page, @code{groff} 3566104862Sruprints the header on the next page as well. 3567104862Sru@endDefmac 3568104862Sru 3569104862Sru@DefmacList {PS, , ms} 3570104862Sru@DefmacListEnd {PE, , ms} 3571104862SruDenotes a graphic, to be processed by the @code{pic} preprocessor. 3572104862SruYou can create a @code{pic} file by hand, using the @acronym{AT&T} 3573104862Sru@code{pic} manual available on the Web as a reference, or by using 3574104862Srua graphics program such as @code{xfig}. 3575104862Sru@endDefmac 3576104862Sru 3577104862Sru@DefmacList {EQ, [@Var{align}], ms} 3578104862Sru@DefmacListEnd {EN, , ms} 3579104862SruDenotes an equation, to be processed by the @code{eqn} preprocessor. 3580114402SruThe optional @var{align} argument can be @code{C}, @code{L}, 3581114402Sruor@tie{}@code{I} to center (the default), left-justify, or indent the 3582114402Sruequation. 3583104862Sru@endDefmac 3584104862Sru 3585104862Sru@DefmacList {[, , ms} 3586104862Sru@DefmacListEnd {], , ms} 3587104862SruDenotes a reference, to be processed by the @code{refer} preprocessor. 3588104862SruThe @acronym{GNU} @cite{refer(1)} man page provides a comprehensive 3589104862Srureference to the preprocessor and the format of the bibliographic 3590104862Srudatabase. 3591104862Sru@endDefmac 3592104862Sru 3593104862Sru@menu 3594104862Sru* Example multi-page table:: 3595104862Sru@end menu 3596104862Sru 3597104862Sru@c --------------------------------------------------------------------- 3598104862Sru 3599104862Sru@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text 3600104862Sru@subsubsection An example multi-page table 3601104862Sru@cindex example markup, multi-page table [@code{ms}] 3602104862Sru@cindex multi-page table, example markup [@code{ms}] 3603104862Sru 3604104862SruThe following is an example of how to set up a 3605104862Srutable that may print across two or more pages. 3606104862Sru 3607104862Sru@Example 3608104862Sru@cartouche 3609104862Sru.TS H 3610104862Sruallbox expand; 3611104862Srucb | cb . 3612104862SruText ...of heading... 3613104862Sru_ 3614104862Sru.TH 3615104862Sru.T& 3616104862Srul | l . 3617104862Sru... the rest of the table follows... 3618104862Sru.CW 3619104862Sru.TE 3620104862Sru@end cartouche 3621104862Sru@endExample 3622104862Sru 3623104862Sru@c --------------------------------------------------------------------- 3624104862Sru 3625104862Sru@node ms Footnotes, , Example multi-page table, ms Body Text 3626104862Sru@subsubsection Footnotes 3627104862Sru@cindex @code{ms} macros, footnotes 3628104862Sru@cindex footnotes [@code{ms}] 3629104862Sru 3630104862SruThe @file{ms} macro package has a flexible footnote system. 3631104862SruYou can specify either numbered footnotes or symbolic footnotes 3632104862Sru(that is, using a marker such as a dagger symbol). 3633104862Sru 3634104862Sru@Defstr {*, ms} 3635104862SruSpecifies the location of a numbered footnote marker in the text. 3636104862Sru@endDefesc 3637104862Sru 3638104862Sru@DefmacList {FS, , ms} 3639104862Sru@DefmacListEnd {FE, , ms} 3640104862SruSpecifies the text of the footnote. 3641104862SruThe default action is to create a numbered footnote; 3642104862Sruyou can create a symbolic footnote by specifying 3643104862Srua @dfn{mark} glyph 3644104862Sru(such as @code{\[dg]} for the dagger glyph) 3645104862Sruin the body text and as an argument to the @code{FS} macro, 3646104862Srufollowed by the text of the footnote 3647104862Sruand the @code{FE} macro. 3648104862Sru@endDefmac 3649104862Sru 3650104862SruYou can control how @code{groff} 3651104862Sruprints footnote numbers by changing the value of the 3652104862Sru@code{FF} register. @xref{ms Document Control Registers}. 3653104862Sru 3654104862Sru@c --------------------------------------------------------------------- 3655104862Sru 3656104862Sru@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms 3657104862Sru@subsection Page layout 3658104862Sru@cindex @code{ms} macros, page layout 3659104862Sru@cindex page layout [@code{ms}] 3660104862Sru 3661104862SruThe default output from the @file{ms} 3662104862Srumacros provides a minimalist page layout: 3663104862Sruit prints a single column, with the page number centered at the top 3664104862Sruof each page. 3665104862SruIt prints no footers. 3666104862Sru 3667104862SruYou can change the layout by setting 3668104862Sruthe proper number registers and strings. 3669104862Sru 3670104862Sru@menu 3671104862Sru* ms Headers and Footers:: 3672104862Sru* ms Margins:: 3673104862Sru* ms Multiple Columns:: 3674104862Sru* ms TOC:: 3675104862Sru* ms Strings and Special Characters:: 3676104862Sru@end menu 3677104862Sru 3678104862Sru@c --------------------------------------------------------------------- 3679104862Sru 3680104862Sru@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout 3681104862Sru@subsubsection Headers and footers 3682104862Sru@cindex @code{ms} macros, headers 3683104862Sru@cindex @code{ms} macros, footers 3684104862Sru@cindex headers [@code{ms}] 3685104862Sru@cindex footers [@code{ms}] 3686104862Sru 3687104862SruFor documents that do not distinguish between odd and even pages, 3688104862Sruset the following strings: 3689104862Sru 3690104862Sru@DefstrList {LH, ms} 3691104862Sru@DefstrItem {CH, ms} 3692104862Sru@DefstrListEnd {RH, ms} 3693104862SruSets the left, center, and right headers. 3694104862Sru@endDefstr 3695104862Sru 3696104862Sru@DefstrList {LF, ms} 3697104862Sru@DefstrItem {CF, ms} 3698104862Sru@DefstrListEnd {RF, ms} 3699104862SruSets the left, center, and right footers. 3700104862Sru@endDefstr 3701104862Sru 3702104862Sru@sp 1 3703104862SruFor documents that need different information printed in the 3704104862Srueven and odd pages, use the following macros: 3705104862Sru 3706104862Sru@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3707104862Sru@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3708104862Sru@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3709104862Sru@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3710104862SruThe @code{OH} and @code{EH} macros define headers for the odd and even pages; 3711104862Sruthe @code{OF} and @code{EF} macros define footers for the odd and even pages. 3712104862SruThis is more flexible than defining the individual strings. 3713104862Sru 3714104862SruYou can replace the quote (@code{'}) marks with any character not 3715104862Sruappearing in the header or footer text. 3716104862Sru@endDefmac 3717104862Sru 3718104862Sru@c --------------------------------------------------------------------- 3719104862Sru 3720104862Sru@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout 3721104862Sru@subsubsection Margins 3722104862Sru@cindex @code{ms} macros, margins 3723104862Sru 3724104862SruYou control margins using a set of number registers. 3725104862Sru@xref{ms Document Control Registers}, for details. 3726104862Sru 3727104862Sru@c --------------------------------------------------------------------- 3728104862Sru 3729104862Sru@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout 3730104862Sru@subsubsection Multiple columns 3731104862Sru@cindex @code{ms} macros, multiple columns 3732104862Sru@cindex multiple columns [@code{ms}] 3733104862Sru 3734104862SruThe @file{ms} macros can set text in as many columns as will 3735104862Srureasonably fit on the page. 3736104862SruThe following macros are available; 3737104862Sruall of them force a page break if a multi-column mode is already set. 3738104862SruHowever, if the current mode is single-column, starting a multi-column 3739104862Srumode does @strong{not} force a page break. 3740104862Sru 3741104862Sru@Defmac {1C, , ms} 3742104862SruSingle-column mode. 3743104862Sru@endDefmac 3744104862Sru 3745104862Sru@Defmac {2C, , ms} 3746104862SruTwo-column mode. 3747104862Sru@endDefmac 3748104862Sru 3749104862Sru@Defmac {MC, [@Var{width} [@Var{gutter}]], ms} 3750104862SruMulti-column mode. 3751104862SruIf you specify no arguments, it is equivalent to the 3752104862Sru@code{2C} macro. 3753104862SruOtherwise, @var{width} is the width of each column and 3754104862Sru@var{gutter} is the space between columns. 3755104862SruThe @code{MINGW} number register controls the default gutter width. 3756104862Sru@endDefmac 3757104862Sru 3758104862Sru@c --------------------------------------------------------------------- 3759104862Sru 3760104862Sru@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout 3761104862Sru@subsubsection Creating a table of contents 3762104862Sru@cindex @code{ms} macros, creating table of contents 3763104862Sru@cindex table of contents, creating [@code{ms}] 3764104862Sru 3765104862SruThe facilities in the @file{ms} macro package for creating 3766104862Srua table of contents are semi-automated at best. 3767104862SruAssuming that you want the table of contents to consist of 3768104862Sruthe document's headings, you need to repeat those headings 3769104862Sruwrapped in @code{XS} and @code{XE} macros. 3770104862Sru 3771104862Sru@DefmacList {XS, [@Var{page}], ms} 3772104862Sru@DefmacItem {XA, [@Var{page}], ms} 3773104862Sru@DefmacListEnd {XE, , ms} 3774104862SruThese macros define a table of contents 3775104862Sruor an individual entry in the table of contents, 3776104862Srudepending on their use. 3777104862SruThe macros are very simple; they cannot indent a heading based on its level. 3778104862SruThe easiest way to work around this is to add tabs 3779104862Sruto the table of contents string. 3780104862SruThe following is an example: 3781104862Sru 3782104862Sru@Example 3783104862Sru@cartouche 3784104862Sru.NH 1 3785104862SruIntroduction 3786104862Sru.XS 3787104862SruIntroduction 3788104862Sru.XE 3789104862Sru.LP 3790104862Sru... 3791104862Sru.CW 3792104862Sru.NH 2 3793104862SruMethodology 3794104862Sru.XS 3795114402SruMethodology 3796104862Sru.XE 3797104862Sru.LP 3798104862Sru... 3799104862Sru@end cartouche 3800104862Sru@endExample 3801104862Sru 3802104862SruYou can manually create a table of contents 3803104862Sruby beginning with the @code{XS} macro for the first entry, 3804104862Sruspecifying the page number for that entry as the argument to @code{XS}. 3805104862SruAdd subsequent entries using the @code{XA} macro, 3806104862Sruspecifying the page number for that entry as the argument to @code{XA}. 3807104862SruThe following is an example: 3808104862Sru 3809104862Sru@Example 3810104862Sru@cartouche 3811104862Sru.XS 1 3812104862SruIntroduction 3813104862Sru.XA 2 3814104862SruA Brief History of the Universe 3815104862Sru.XA 729 3816104862SruDetails of Galactic Formation 3817104862Sru... 3818104862Sru.XE 3819104862Sru@end cartouche 3820104862Sru@endExample 3821104862Sru@endDefmac 3822104862Sru 3823104862Sru@Defmac {TC, [@code{no}], ms} 3824104862SruPrints the table of contents on a new page, 3825114402Srusetting the page number to@tie{}@strong{i} (Roman numeral one). 3826104862SruYou should usually place this macro at the end of the 3827104862Srufile, since @code{groff} is a single-pass formatter and 3828104862Srucan only print what has been collected up to the point 3829104862Sruthat the @code{TC} macro appears. 3830104862Sru 3831104862SruThe optional argument @code{no} suppresses printing 3832104862Sruthe title specified by the string register @code{TOC}. 3833104862Sru@endDefmac 3834104862Sru 3835104862Sru@Defmac{PX, [@code{no}], ms} 3836104862SruPrints the table of contents on a new page, 3837104862Sruusing the current page numbering sequence. 3838104862SruUse this macro to print a manually-generated table of contents 3839104862Sruat the beginning of your document. 3840104862Sru 3841104862SruThe optional argument @code{no} suppresses printing 3842104862Sruthe title specified by the string register @code{TOC}. 3843104862Sru@endDefmac 3844104862Sru 3845104862SruThe @cite{Groff and Friends HOWTO} 3846104862Sruincludes a @code{sed} script that automatically inserts 3847104862Sru@code{XS} and @code{XE} macro entries after each heading in a document. 3848104862Sru 3849104862SruAltering the @code{NH} macro to automatically build the table 3850104862Sruof contents is perhaps initially more difficult, but would save 3851104862Srua great deal of time in the long run if you use @file{ms} regularly. 3852104862Sru 3853104862Sru@c --------------------------------------------------------------------- 3854104862Sru 3855104862Sru@node ms Strings and Special Characters, , ms TOC, ms Page Layout 3856104862Sru@subsubsection Strings and Special Characters 3857104862Sru@cindex @code{ms} macros, strings 3858104862Sru@cindex @code{ms} macros, special characters 3859104862Sru@cindex @code{ms} macros, accent marks 3860104862Sru@cindex accent marks [@code{ms}] 3861104862Sru@cindex special characters [@code{ms}] 3862104862Sru@cindex strings [@code{ms}] 3863104862Sru 3864104862SruThe @file{ms} macros provide the following predefined strings. 3865104862SruYou can change the string definitions to help in creating 3866104862Srudocuments in languages other than English. 3867104862Sru 3868104862Sru@Defstr {REFERENCES, ms} 3869104862SruContains the string printed at the beginning of the 3870104862Srureferences (bibliography) page. 3871104862SruThe default is @samp{References}. 3872104862Sru@endDefstr 3873104862Sru 3874104862Sru@Defstr {ABSTRACT, ms} 3875104862SruContains the string printed at the beginning of the abstract. 3876104862SruThe default is @samp{ABSTRACT}. 3877104862Sru@endDefstr 3878104862Sru 3879104862Sru@Defstr {TOC, ms} 3880104862SruContains the string printed at the beginning of the table of contents. 3881104862Sru@endDefstr 3882104862Sru 3883104862Sru@DefstrList {MONTH1, ms} 3884104862Sru@DefstrItem {MONTH2, ms} 3885104862Sru@DefstrItem {MONTH3, ms} 3886104862Sru@DefstrItem {MONTH4, ms} 3887104862Sru@DefstrItem {MONTH5, ms} 3888104862Sru@DefstrItem {MONTH6, ms} 3889104862Sru@DefstrItem {MONTH7, ms} 3890104862Sru@DefstrItem {MONTH8, ms} 3891104862Sru@DefstrItem {MONTH9, ms} 3892104862Sru@DefstrItem {MONTH10, ms} 3893104862Sru@DefstrItem {MONTH11, ms} 3894104862Sru@DefstrListEnd {MONTH12, ms} 3895104862SruPrints the full name of the month in dates. 3896104862SruThe default is @samp{January}, @samp{February}, etc. 3897104862Sru@endDefstr 3898104862Sru 3899104862SruThe following special characters are available@footnote{For an 3900104862Sruexplanation what special characters are see @ref{Special Characters}.}: 3901104862Sru 3902104862Sru@Defstr {-, ms} 3903104862SruPrints an em dash. 3904104862Sru@endDefstr 3905104862Sru 3906104862Sru@DefstrList {*Q, ms} 3907104862Sru@DefstrListEnd {*U, ms} 3908104862SruPrints typographer's quotes in troff, 3909104862Sruplain quotes in nroff. 3910104862Sru@code{*Q} is the left quote and @code{*U} is the right quote. 3911104862Sru@endDefstr 3912104862Sru 3913104862SruImproved accent marks are available in the @file{ms} macros. 3914104862Sru 3915104862Sru@Defmac {AM, , ms} 3916104862SruSpecify this macro at the beginning of your document 3917104862Sruto enable extended accent marks and special characters. 3918104862SruThis is a Berkeley extension. 3919104862Sru 3920104862SruTo use the accent marks, place them @strong{after} 3921104862Sruthe character being accented. 3922104862Sru@endDefmac 3923104862Sru 3924104862SruThe following accent marks are available 3925104862Sruafter invoking the @code{AM} macro: 3926104862Sru 3927104862Sru@Defstr {\', ms} 3928104862SruAcute accent. 3929104862Sru@endDefstr 3930104862Sru 3931104862Sru@Defstr {\`, ms} 3932104862SruGrave accent. 3933104862Sru@endDefstr 3934104862Sru 3935104862Sru@Defstr {^, ms} 3936104862SruCircumflex. 3937104862Sru@endDefstr 3938104862Sru 3939104862Sru@Defstr {\,, ms} 3940104862SruCedilla. 3941104862Sru@endDefstr 3942104862Sru 3943104862Sru@Defstr {~, ms} 3944104862SruTilde. 3945104862Sru@endDefstr 3946104862Sru 3947104862Sru@deffn String @t{\*[:]} 3948104862Sru@ifnotinfo 3949104862Sru@stindex : @r{[}ms@r{]} 3950104862Sru@end ifnotinfo 3951104862Sru@ifinfo 3952114402Sru@stindex \*[@r{<colon>}] @r{[}ms@r{]} 3953104862Sru@end ifinfo 3954104862SruUmlaut. 3955104862Sru@end deffn 3956104862Sru 3957104862Sru@Defstr {v, ms} 3958104862SruHacek. 3959104862Sru@endDefstr 3960104862Sru 3961104862Sru@Defstr {_, ms} 3962104862SruMacron (overbar). 3963104862Sru@endDefstr 3964104862Sru 3965104862Sru@Defstr {., ms} 3966104862SruUnderdot. 3967104862Sru@endDefstr 3968104862Sru 3969104862Sru@Defstr {o, ms} 3970104862SruRing above. 3971104862Sru@endDefstr 3972104862Sru 3973104862SruThe following are standalone characters 3974104862Sruavailable after invoking the @code{AM} macro: 3975104862Sru 3976104862Sru@Defstr {?, ms} 3977104862SruUpside-down question mark. 3978104862Sru@endDefstr 3979104862Sru 3980104862Sru@Defstr {!, ms} 3981104862SruUpside-down exclamation point. 3982104862Sru@endDefstr 3983104862Sru 3984104862Sru@Defstr {8, ms} 3985104862SruGerman @ss{} ligature. 3986104862Sru@endDefstr 3987104862Sru 3988104862Sru@Defstr {3, ms} 3989104862SruYogh. 3990104862Sru@endDefstr 3991104862Sru 3992104862Sru@Defstr {Th, ms} 3993104862SruUppercase thorn. 3994104862Sru@endDefstr 3995104862Sru 3996104862Sru@Defstr {th, ms} 3997104862SruLowercase thorn. 3998104862Sru@endDefstr 3999104862Sru 4000104862Sru@Defstr {D-, ms} 4001104862SruUppercase eth. 4002104862Sru@endDefstr 4003104862Sru 4004104862Sru@Defstr {d-, ms} 4005104862SruLowercase eth. 4006104862Sru@endDefstr 4007104862Sru 4008104862Sru@Defstr {q, ms} 4009104862SruHooked o. 4010104862Sru@endDefstr 4011104862Sru 4012104862Sru@Defstr {ae, ms} 4013104862SruLowercase @ae{} ligature. 4014104862Sru@endDefstr 4015104862Sru 4016104862Sru@Defstr {Ae, ms} 4017104862SruUppercase @AE{} ligature. 4018104862Sru@endDefstr 4019104862Sru 4020104862Sru@c --------------------------------------------------------------------- 4021104862Sru 4022104862Sru@node Differences from AT&T ms, , ms Page Layout, ms 4023104862Sru@subsection Differences from @acronym{AT&T} @file{ms} 4024104862Sru@cindex @code{ms} macros, differences from @acronym{AT&T} 4025104862Sru@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences 4026104862Sru 4027104862SruThis section lists the (minor) differences between the 4028104862Sru@code{groff -ms} macros and @acronym{AT&T} 4029104862Sru@code{troff -ms} macros. 4030104862Sru 4031104862Sru@menu 4032104862Sru* Missing ms Macros:: 4033104862Sru* Additional ms Macros:: 4034104862Sru@end menu 4035104862Sru 4036104862Sru@c --------------------------------------------------------------------- 4037104862Sru 4038104862Sru@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms 4039104862Sru@subsubsection @code{troff} macros not appearing in @code{groff} 4040104862Sru 4041104862SruMacros missing from @code{groff -ms} 4042104862Sruare cover page macros specific to Bell Labs. 4043104862SruThe macros known to be missing are: 4044104862Sru 4045104862Sru@table @code 4046104862Sru@item .TM 4047104862SruTechnical memorandum; a cover sheet style 4048104862Sru 4049104862Sru@item .IM 4050104862SruInternal memorandum; a cover sheet style 4051104862Sru 4052104862Sru@item .MR 4053104862SruMemo for record; a cover sheet style 4054104862Sru 4055104862Sru@item .MF 4056104862SruMemo for file; a cover sheet style 4057104862Sru 4058104862Sru@item .EG 4059104862SruEngineer's notes; a cover sheet style 4060104862Sru 4061104862Sru@item .TR 4062104862SruComputing Science Tech Report; a cover sheet style 4063104862Sru 4064104862Sru@item .OK 4065104862SruOther keywords 4066104862Sru 4067104862Sru@item .CS 4068104862SruCover sheet information 4069104862Sru 4070104862Sru@item .MH 4071104862SruA cover sheet macro 4072104862Sru@end table 4073104862Sru 4074104862Sru@c --------------------------------------------------------------------- 4075104862Sru 4076104862Sru@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms 4077104862Sru@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff} 4078104862Sru 4079104862SruThe @code{groff -ms} macros have a few minor extensions 4080104862Srucompared to the @acronym{AT&T} @code{troff -ms} macros. 4081104862Sru 4082104862Sru@Defmac {AM, , ms} 4083104862SruImproved accent marks. 4084104862Sru@xref{ms Strings and Special Characters}, for details. 4085104862Sru@endDefmac 4086104862Sru 4087104862Sru@Defmac {DS, @t{I}, ms} 4088104862SruIndented display. 4089104862SruThe default behavior of @acronym{AT&T} @code{troff -ms} 4090104862Sruwas to indent; the @code{groff} default prints displays 4091104862Sruflush left with the body text. 4092104862Sru@endDefmac 4093104862Sru 4094104862Sru@Defmac {CW, , ms} 4095104862SruPrint text in @code{constant width} (Courier) font. 4096104862Sru@endDefmac 4097104862Sru 4098104862Sru@Defmac {IX, , ms} 4099104862SruIndexing term (printed on standard error). 4100104862SruYou can write a script to capture and process an index 4101104862Srugenerated in this manner. 4102104862Sru@endDefmac 4103104862Sru 4104104862Sru@sp 1 4105104862SruThe following additional number registers 4106104862Sruappear in @code{groff -ms}: 4107104862Sru 4108104862Sru@Defmpreg {MINGW, ms} 4109104862SruSpecifies a minimum space 4110104862Srubetween columns (for multi-column output); this takes the 4111104862Sruplace of the @code{GW} register that was documented but apparently 4112104862Srunot implemented in @acronym{AT&T} @code{troff}. 4113104862Sru@endDefmpreg 4114104862Sru 4115104862Sru@sp 1 4116104862SruSeveral new string registers are available as well. 4117104862SruYou can change these to handle (for example) the local language. 4118104862Sru@xref{ms Strings and Special Characters}, for details. 4119104862Sru 4120104862Sru 412169626Sru@c ===================================================================== 412269626Sru 412369626Sru@node me, mm, ms, Macro Packages 412469626Sru@section @file{me} 4125104862Sru@cindex @code{me} macro package 412669626Sru 412769626Sru@c XXX documentation 4128104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 4129104862SruSee the @file{meintro.me} and @file{meref.me} documents in 4130104862Srugroff's @file{doc} directory. 413169626Sru 413269626Sru 413369626Sru@c ===================================================================== 413469626Sru 413569626Sru@node mm, , me, Macro Packages 413669626Sru@section @file{mm} 4137104862Sru@cindex @code{mm} macro package 413869626Sru 413969626Sru@c XXX documentation 4140104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 4141104862SruSee the @cite{groff_mm(7)} man page (type @command{man groff_mm} at 4142104862Sruthe command line). 414369626Sru 414469626Sru 414569626Sru@c ===================================================================== 414669626Sru@c ===================================================================== 414769626Sru 414875584Sru@node gtroff Reference, Preprocessors, Macro Packages, Top 414975584Sru@chapter @code{gtroff} Reference 415075584Sru@cindex reference, @code{gtroff} 4151104862Sru@cindex @code{gtroff}, reference 415255839Sasmodai 415369626SruThis chapter covers @strong{all} of the facilities of @code{gtroff}. 415469626SruUsers of macro packages may skip it if not interested in details. 415555839Sasmodai 415655839Sasmodai 415755839Sasmodai@menu 415875584Sru* Text:: 415975584Sru* Measurements:: 416075584Sru* Expressions:: 416175584Sru* Identifiers:: 416275584Sru* Embedded Commands:: 416375584Sru* Registers:: 416475584Sru* Manipulating Filling and Adjusting:: 416575584Sru* Manipulating Hyphenation:: 416675584Sru* Manipulating Spacing:: 416775584Sru* Tabs and Fields:: 416875584Sru* Character Translations:: 416975584Sru* Troff and Nroff Mode:: 417075584Sru* Line Layout:: 4171104862Sru* Line Control:: 417275584Sru* Page Layout:: 417375584Sru* Page Control:: 4174114402Sru* Fonts and Symbols:: 417575584Sru* Sizes:: 417675584Sru* Strings:: 417775584Sru* Conditionals and Loops:: 417875584Sru* Writing Macros:: 417975584Sru* Page Motions:: 418075584Sru* Drawing Requests:: 418175584Sru* Traps:: 418275584Sru* Diversions:: 418375584Sru* Environments:: 418475584Sru* Suppressing output:: 4185104862Sru* Colors:: 418675584Sru* I/O:: 418775584Sru* Postprocessor Access:: 418875584Sru* Miscellaneous:: 418975584Sru* Gtroff Internals:: 419075584Sru* Debugging:: 419175584Sru* Implementation Differences:: 419255839Sasmodai@end menu 419355839Sasmodai 419469626Sru 419569626Sru@c ===================================================================== 419669626Sru 4197114402Sru@node Text, Measurements, gtroff Reference, gtroff Reference 419855839Sasmodai@section Text 419969626Sru@cindex text, @code{gtroff} processing 420055839Sasmodai 420169626Sru@code{gtroff} input files contain text with control commands 420269626Sruinterspersed throughout. But, even without control codes, @code{gtroff} 420375584Srustill does several things with the input text: 420455839Sasmodai 420575584Sru@itemize @bullet 420675584Sru@item 420775584Srufilling and adjusting 420875584Sru 420975584Sru@item 421075584Sruadding additional space after sentences 421175584Sru 421275584Sru@item 421375584Sruhyphenating 421475584Sru 421575584Sru@item 421675584Sruinserting implicit line breaks 421775584Sru@end itemize 421875584Sru 421955839Sasmodai@menu 422075584Sru* Filling and Adjusting:: 422175584Sru* Hyphenation:: 422275584Sru* Sentences:: 422375584Sru* Tab Stops:: 422475584Sru* Implicit Line Breaks:: 4225114402Sru* Input Conventions:: 4226114402Sru* Input Encodings:: 422755839Sasmodai@end menu 422855839Sasmodai 422969626Sru@c --------------------------------------------------------------------- 423069626Sru 423155839Sasmodai@node Filling and Adjusting, Hyphenation, Text, Text 423255839Sasmodai@subsection Filling and Adjusting 423369626Sru@cindex filling 423469626Sru@cindex adjusting 423555839Sasmodai 423675584SruWhen @code{gtroff} reads text, it collects words from the input and fits 423769626Sruas many of them together on one output line as it can. This is known as 423855839Sasmodai@dfn{filling}. 423955839Sasmodai 424069626Sru@cindex leading spaces 424169626Sru@cindex spaces, leading and trailing 424269626Sru@cindex extra spaces 424369626Sru@cindex trailing spaces 424475584SruOnce @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 424575584Sruit. This means it widens the spacing between words until the text 424669626Srureaches the right margin (in the default adjustment mode). Extra spaces 424769626Srubetween words are preserved, but spaces at the end of lines are ignored. 424875584SruSpaces at the front of a line cause a @dfn{break} (breaks are 4249104862Sruexplained in @ref{Implicit Line Breaks}). 425055839Sasmodai 425169626Sru@xref{Manipulating Filling and Adjusting}. 425255839Sasmodai 425369626Sru@c --------------------------------------------------------------------- 425469626Sru 425555839Sasmodai@node Hyphenation, Sentences, Filling and Adjusting, Text 425655839Sasmodai@subsection Hyphenation 425755839Sasmodai@cindex hyphenation 425855839Sasmodai 425969626SruSince the odds are not great for finding a set of words, for every 426075584Sruoutput line, which fit nicely on a line without inserting excessive 426175584Sruamounts of space between words, @code{gtroff} hyphenates words so 426275584Sruthat it can justify lines without inserting too much space between 426369626Sruwords. It uses an internal hyphenation algorithm (a simplified version 426469626Sruof the algorithm used within @TeX{}) to indicate which words can be 426575584Sruhyphenated and how to do so. When a word is hyphenated, the first part 426675584Sruof the word is added to the current filled line being output (with 426775584Sruan attached hyphen), and the other portion is added to the next 426869626Sruline to be filled. 426955839Sasmodai 427069626Sru@xref{Manipulating Hyphenation}. 427155839Sasmodai 427269626Sru@c --------------------------------------------------------------------- 427355839Sasmodai 427455839Sasmodai@node Sentences, Tab Stops, Hyphenation, Text 427555839Sasmodai@subsection Sentences 427655839Sasmodai@cindex sentences 427755839Sasmodai 427869626SruAlthough it is often debated, some typesetting rules say there should be 427969626Srudifferent amounts of space after various punctuation marks. For 428069626Sruexample, the @cite{Chicago typsetting manual} says that a period at the 428169626Sruend of a sentence should have twice as much space following it as would 428269626Srua comma or a period as part of an abbreviation. 428355839Sasmodai 428469626Sru@c XXX exact citation of Chicago manual 428555839Sasmodai 428669626Sru@cindex sentence space 428769626Sru@cindex space between sentences 428869626Sru@cindex french-spacing 428969626Sru@code{gtroff} does this by flagging certain characters (normally 4290104862Sru@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters. 429169626SruWhen @code{gtroff} encounters one of these characters at the end of a 429275584Sruline, it appends a normal space followed by a @dfn{sentence space} in 429375584Sruthe formatted output. (This justifies one of the conventions mentioned 429475584Sruin @ref{Input Conventions}.) 429555839Sasmodai 429669626Sru@cindex transparent characters 429769626Sru@cindex character, transparent 4298104862Sru@cindex @code{dg} glyph, at end of sentence 4299104862Sru@cindex @code{rq} glyph, at end of sentence 4300104862Sru@cindex @code{"}, at end of sentence 4301104862Sru@cindex @code{'}, at end of sentence 4302104862Sru@cindex @code{)}, at end of sentence 4303104862Sru@cindex @code{]}, at end of sentence 4304104862Sru@cindex @code{*}, at end of sentence 4305104862SruIn addition, the following characters and symbols are treated 4306104862Srutransparently while handling end-of-sentence characters: @samp{"}, 4307104862Sru@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}. 430855839Sasmodai 430969626SruSee the @code{cflags} request in @ref{Using Symbols}, for more details. 431055839Sasmodai 4311104862Sru@cindex @code{\&}, at end of sentence 4312104862SruTo prevent the insertion of extra space after an end-of-sentence 431369626Srucharacter (at the end of a line), append @code{\&}. 431455839Sasmodai 431569626Sru@c --------------------------------------------------------------------- 431669626Sru 431755839Sasmodai@node Tab Stops, Implicit Line Breaks, Sentences, Text 431855839Sasmodai@subsection Tab Stops 431955839Sasmodai@cindex tab stops 432055839Sasmodai@cindex stops, tabulator 432169626Sru@cindex tab character 432269626Sru@cindex character, tabulator 432355839Sasmodai 432469626Sru@cindex @acronym{EBCDIC} encoding 4325104862Sru@cindex encoding, @acronym{EBCDIC} 432669626Sru@code{gtroff} translates @dfn{tabulator characters}, also called 432775584Sru@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 432869626Sru@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 432969626Srutabulator stop. These tab stops are initially located every half inch 433075584Sruacross the page. Using this, simple tables can be made easily. 433169626SruHowever, it can often be deceptive as the appearance (and width) of the 433269626Srutext on a terminal and the results from @code{gtroff} can vary greatly. 433355839Sasmodai 433455839SasmodaiAlso, a possible sticking point is that lines beginning with tab 433575584Srucharacters are still filled, again producing unexpected results. 433655839SasmodaiFor example, the following input 433755839Sasmodai 433869626Sru@multitable {12345678} {12345678} {12345678} {12345678} 433969626Sru@item 434069626Sru@tab 1 @tab 2 @tab 3 434169626Sru@item 434269626Sru@tab @tab 4 @tab 5 434369626Sru@end multitable 434455839Sasmodai 434555839Sasmodai@noindent 434675584Sruproduces 434755839Sasmodai 434869626Sru@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 434969626Sru@item 435069626Sru@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 435169626Sru@end multitable 435255839Sasmodai 435369626Sru@xref{Tabs and Fields}. 435455839Sasmodai 435569626Sru@c --------------------------------------------------------------------- 435655839Sasmodai 4357114402Sru@node Implicit Line Breaks, Input Conventions, Tab Stops, Text 435855839Sasmodai@subsection Implicit Line Breaks 435955839Sasmodai@cindex implicit line breaks 436055839Sasmodai@cindex implicit breaks of lines 436155839Sasmodai@cindex line, implicit breaks 436255839Sasmodai@cindex break, implicit 436355839Sasmodai@cindex line break 436455839Sasmodai 436569626SruAn important concept in @code{gtroff} is the @dfn{break}. When a break 436675584Sruoccurs, @code{gtroff} outputs the partially filled line 436775584Sru(unjustified), and resumes collecting and filling text on the next output 436869626Sruline. 436955839Sasmodai 437055839Sasmodai@cindex blank line 437155839Sasmodai@cindex empty line 437255839Sasmodai@cindex line, blank 4373104862Sru@cindex blank line macro (@code{blm}) 437475584SruThere are several ways to cause a break in @code{gtroff}. A blank 4375104862Sruline not only causes a break, but it also outputs a one-line vertical 437675584Sruspace (effectively a blank line). Note that this behaviour can be 437775584Srumodified with the blank line macro request @code{blm}. 4378104862Sru@xref{Blank Line Traps}. 437955839Sasmodai 438069626Sru@cindex fill mode 438169626Sru@cindex mode, fill 438275584SruA line that begins with a space causes a break and the space is 438375584Sruoutput at the beginning of the next line. Note that this space isn't 438469626Sruadjusted, even in fill mode. 438555839Sasmodai 438675584SruThe end of file also causes a break -- otherwise the last line of 438769626Sruthe document may vanish! 438855839Sasmodai 438975584SruCertain requests also cause breaks, implicitly or explicitly. This is 439075584Srudiscussed in @ref{Manipulating Filling and Adjusting}. 439155839Sasmodai 4392114402Sru@c --------------------------------------------------------------------- 439355839Sasmodai 4394114402Sru@node Input Conventions, Input Encodings, Implicit Line Breaks, Text 4395114402Sru@subsection Input Conventions 439655839Sasmodai@cindex input conventions 439755839Sasmodai@cindex conventions for input 439855839Sasmodai 439969626SruSince @code{gtroff} does filling automatically, it is traditional in 440069626Sru@code{groff} not to try and type things in as nicely formatted 440169626Sruparagraphs. These are some conventions commonly used when typing 440269626Sru@code{gtroff} text: 440355839Sasmodai 440469626Sru@itemize @bullet 440569626Sru@item 440675584SruBreak lines after punctuation, particularly at the end of a sentence 440769626Sruand in other logical places. Keep separate phrases on lines by 440869626Sruthemselves, as entire phrases are often added or deleted when editing. 440955839Sasmodai 441055839Sasmodai@item 4411114402SruTry to keep lines less than 40-60@tie{}characters, to allow space for 441269626Sruinserting more text. 441369626Sru 441455839Sasmodai@item 441569626SruDo not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 441675584Srudon't try using spaces to get proper indentation). 441755839Sasmodai@end itemize 441855839Sasmodai 4419114402Sru@c --------------------------------------------------------------------- 442055839Sasmodai 4421114402Sru@node Input Encodings, , Input Conventions, Text 4422114402Sru@subsection Input Encodings 4423114402Sru 4424114402SruCurrently, the following input encodings are available. 4425114402Sru 4426114402Sru@table @asis 4427114402Sru@item cp1047 4428114402Sru@cindex encoding, input, @acronym{EBCDIC} 4429114402Sru@cindex @acronym{EBCDIC}, input encoding 4430114402Sru@cindex input encoding, @acronym{EBCDIC} 4431114402Sru@cindex encoding, input, cp1047 4432114402Sru@cindex cp1047, input encoding 4433114402Sru@cindex input encoding, cp1047 4434114402Sru@cindex IBM cp1047 input encoding 4435114402Sru@pindex cp1047.tmac 4436114402SruThis input encoding works only on @acronym{EBCDIC} platforms (and vice 4437114402Sruversa, the other input encodings don't work with @acronym{EBCDIC}); the 4438114402Srufile @file{cp1047.tmac} is by default loaded at start-up. 4439114402Sru 4440114402Sru@item latin-1 4441114402Sru@cindex encoding, input, @w{latin-1} (ISO @w{8859-1}) 4442114402Sru@cindex @w{latin-1} (ISO @w{8859-1}), input encoding 4443114402Sru@cindex ISO @w{8859-1} (@w{latin-1}), input encoding 4444114402Sru@cindex input encoding, @w{latin-1} (ISO @w{8859-1}) 4445114402Sru@pindex latin1.tmac 4446114402SruThis is the default input encoding on non-@acronym{EBCDIC} platforms; 4447114402Sruthe file @file{latin1.tmac} is loaded at start-up. 4448114402Sru 4449114402Sru@item latin-2 4450114402Sru@cindex encoding, input, @w{latin-2} (ISO @w{8859-2}) 4451114402Sru@cindex @w{latin-2} (ISO @w{8859-2}), input encoding 4452114402Sru@cindex ISO @w{8859-2} (@w{latin-2}), input encoding 4453114402Sru@cindex input encoding, @w{latin-2} (ISO @w{8859-2}) 4454114402Sru@pindex latin2.tmac 4455114402SruTo use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very 4456114402Srubeginning of your document or use @samp{-mlatin2} as a command line 4457114402Sruargument for @code{groff}. 4458114402Sru 4459114402Sru@item latin-9 (latin-0) 4460114402Sru@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15}) 4461114402Sru@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding 4462114402Sru@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding 4463114402Sru@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15}) 4464114402Sru@pindex latin9.tmac 4465114402SruThis encoding is intended (at least in Europe) to replace @w{latin-1} 4466114402Sruencoding. The main difference to @w{latin-1} is that @w{latin-9} 4467114402Srucontains the Euro character. To use this encoding, either say 4468114402Sru@w{@samp{.mso latin9.tmac}} at the very beginning of your document or 4469114402Sruuse @samp{-mlatin9} as a command line argument for @code{groff}. 4470114402Sru@end table 4471114402Sru 4472114402SruNote that it can happen that some input encoding characters are not 4473114402Sruavailable for a particular output device. For example, saying 4474114402Sru 4475114402Sru@Example 4476114402Srugroff -Tlatin1 -mlatin9 ... 4477114402Sru@endExample 4478114402Sru 4479114402Sru@noindent 4480114402Sruwill fail if you use the Euro character in the input. Usually, this 4481114402Srulimitation is present only for devices which have a limited set of 4482114402Sruoutput glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other 4483114402Srudevices it is usually sufficient to install proper fonts which contain 4484114402Sruthe necessary glyphs. 4485114402Sru 4486114402Sru@pindex freeeuro.pfa 4487114402Sru@pindex ec.tmac 4488114402SruDue to the importance of the Euro glyph in Europe, the groff package now 4489114402Srucomes with a @sc{PostScript} font called @file{freeeuro.pfa} which 4490114402Sruprovides various glyph shapes for the Euro. With other words, 4491114402Sru@w{latin-9} encoding is supported for the @option{-Tps} device out of 4492114402Sruthe box (@w{latin-2} isn't). 4493114402Sru 4494114402SruBy its very nature, @option{-Tutf8} supports all input encodings; 4495114402Sru@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the 4496114402Srucommand line @option{-mec} is used also to load the file @file{ec.tmac} 4497114402Sru(which flips to the EC fonts). 4498114402Sru 4499114402Sru 450069626Sru@c ===================================================================== 450169626Sru 4502114402Sru@node Measurements, Expressions, Text, gtroff Reference 450355839Sasmodai@section Measurements 450455839Sasmodai@cindex measurements 450555839Sasmodai 450655839Sasmodai@cindex units of measurement 4507104862Sru@cindex basic unit (@code{u}) 4508104862Sru@cindex machine unit (@code{u}) 4509104862Sru@cindex measurement unit 451069626Sru@cindex @code{u} unit 451169626Sru@cindex unit, @code{u} 451275584Sru@code{gtroff} (like many other programs) requires numeric parameters to 451369626Sruspecify various measurements. Most numeric parameters@footnote{those 451469626Sruthat specify vertical or horizontal motion or a type size} may have a 451569626Sru@dfn{measurement unit} attached. These units are specified as a single 451669626Srucharacter which immediately follows the number or expression. Each of 451769626Sruthese units are understood, by @code{gtroff}, to be a multiple of its 451855839Sasmodai@dfn{basic unit}. So, whenever a different measurement unit is 451969626Sruspecified @code{gtroff} converts this into its @dfn{basic units}. This 452069626Srubasic unit, represented by a @samp{u}, is a device dependent measurement 452175584Sruwhich is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 452275584Sruinch. The values may be given as fractional numbers; however, 452375584Srufractional basic units are always rounded to integers. 452455839Sasmodai 452569626SruSome of the measurement units are completely independent of any of the 452669626Srucurrent settings (e.g.@: type size) of @code{gtroff}. 452755839Sasmodai 452869626Sru@table @code 452955839Sasmodai@item i 4530104862Sru@cindex inch unit (@code{i}) 453169626Sru@cindex @code{i} unit 453269626Sru@cindex unit, @code{i} 453355839SasmodaiInches. An antiquated measurement unit still in use in certain 453475584Srubackwards countries with incredibly low-cost computer equipment. One 4535114402Sruinch is equal to@tie{}2.54@dmn{cm}. 453669626Sru 453755839Sasmodai@item c 4538104862Sru@cindex centimeter unit (@code{c}) 453969626Sru@cindex @code{c} unit 454069626Sru@cindex unit, @code{c} 4541114402SruCentimeters. One centimeter is equal to@tie{}0.3937@dmn{in}. 454269626Sru 454355839Sasmodai@item p 4544104862Sru@cindex point unit (@code{p}) 454569626Sru@cindex @code{p} unit 454669626Sru@cindex unit, @code{p} 454755839SasmodaiPoints. This is a typesetter's measurement used for measure type size. 4548114402SruIt is 72@tie{}points to an inch. 454969626Sru 455055839Sasmodai@item P 4551104862Sru@cindex pica unit (@code{P}) 455269626Sru@cindex @code{P} unit 455369626Sru@cindex unit, @code{P} 4554114402SruPica. Another typesetting measurement. 6@tie{}Picas to an inch (and 4555114402Sru12@tie{}points to a pica). 455669626Sru 455755839Sasmodai@item s 455869626Sru@itemx z 455969626Sru@cindex @code{s} unit 456069626Sru@cindex unit, @code{s} 456169626Sru@cindex @code{z} unit 456269626Sru@cindex unit, @code{z} 456369626Sru@xref{Fractional Type Sizes}, for a discussion of these units. 4564104862Sru 4565104862Sru@item f 4566104862Sru@cindex @code{f} unit 4567104862Sru@cindex unit, @code{f} 4568104862SruFractions. Value is 65536. 4569104862Sru@xref{Colors}, for usage. 457055839Sasmodai@end table 457155839Sasmodai 457275584SruThe other measurements understood by @code{gtroff} depend on 457369626Srusettings currently in effect in @code{gtroff}. These are very useful 457469626Srufor specifying measurements which should look proper with any size of 457569626Srutext. 457655839Sasmodai 457769626Sru@table @code 457855839Sasmodai@item m 4579104862Sru@cindex em unit (@code{m}) 458069626Sru@cindex @code{m} unit 458169626Sru@cindex unit, @code{m} 458269626SruEms. This unit is equal to the current font size in points. So called 4583114402Srubecause it is @emph{approximately} the width of the letter@tie{}@samp{m} 458469626Sruin the current font. 458569626Sru 458655839Sasmodai@item n 4587104862Sru@cindex en unit (@code{n}) 458869626Sru@cindex @code{n} unit 458969626Sru@cindex unit, @code{n} 4590104862SruEns. In @code{groff}, this is half of an em. 459169626Sru 459255839Sasmodai@item v 4593104862Sru@cindex vertical space unit (@code{v}) 4594104862Sru@cindex space, vertical, unit (@code{v}) 459569626Sru@cindex @code{v} unit 459669626Sru@cindex unit, @code{v} 459755839SasmodaiVertical space. This is equivalent to the current line spacing. 459855839Sasmodai@xref{Sizes}, for more information about this. 459969626Sru 460055839Sasmodai@item M 460169626Sru@cindex @code{M} unit 460269626Sru@cindex unit, @code{M} 460355839Sasmodai100ths of an em. 460455839Sasmodai@end table 460555839Sasmodai 460655839Sasmodai@menu 460775584Sru* Default Units:: 460855839Sasmodai@end menu 460955839Sasmodai 461069626Sru@c --------------------------------------------------------------------- 461169626Sru 461255839Sasmodai@node Default Units, , Measurements, Measurements 461355839Sasmodai@subsection Default Units 461455839Sasmodai@cindex default units 461555839Sasmodai@cindex units, default 461655839Sasmodai 461769626SruMany requests take a default unit. While this can be helpful at times, 461869626Sruit can cause strange errors in some expressions. For example, the line 461969626Srulength request expects em units. Here are several attempts to get a 4620114402Sruline length of 3.5@tie{}inches and their results: 462155839Sasmodai 462275584Sru@Example 462355839Sasmodai3.5i @result{} 3.5i 462455839Sasmodai7/2 @result{} 0i 462555839Sasmodai7/2i @result{} 0i 4626104862Sru(7 / 2)u @result{} 0i 462769626Sru7i/2 @result{} 0.1i 462855839Sasmodai7i/2u @result{} 3.5i 462975584Sru@endExample 463055839Sasmodai 463169626Sru@noindent 463275584SruEverything is converted to basic units first. In the above example it 4633114402Sruis assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m} 4634114402Sruequals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value 4635114402Sru7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to 463675584Sru1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 4637104862Sru0.1@dmn{i}. As can be seen, a scaling indicator after a closing 4638104862Sruparenthesis is simply ignored. 463955839Sasmodai 464069626Sru@cindex measurements, specifying safely 464175584SruThus, the safest way to specify measurements is to always 464269626Sruattach a scaling indicator. If you want to multiply or divide by a 464369626Srucertain scalar value, use @samp{u} as the unit for that value. 464469626Sru 464569626Sru 464669626Sru@c ===================================================================== 464769626Sru 464875584Sru@node Expressions, Identifiers, Measurements, gtroff Reference 464955839Sasmodai@section Expressions 465055839Sasmodai@cindex expressions 465155839Sasmodai 465275584Sru@code{gtroff} has most arithmetic operators common to other languages: 465355839Sasmodai 465455839Sasmodai@itemize @bullet 465555839Sasmodai@item 465669626Sru@cindex arithmetic operators 465769626Sru@cindex operators, arithmetic 465869626Sru@opindex + 465969626Sru@opindex - 466069626Sru@opindex / 466169626Sru@opindex * 466269626Sru@opindex % 466369626SruArithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 466469626Sru(division), @samp{*} (multiplication), @samp{%} (modulo). 466569626Sru 466669626Sru@code{gtroff} only provides integer arithmetic. The internal type used 466769626Srufor computing results is @samp{int}, which is usually a 32@dmn{bit} 466869626Srusigned integer. 466969626Sru 467055839Sasmodai@item 467169626Sru@cindex comparison operators 467269626Sru@cindex operators, comparison 467369626Sru@opindex < 467469626Sru@opindex > 467569626Sru@opindex >= 467669626Sru@opindex <= 467769626Sru@opindex = 467869626Sru@opindex == 467969626SruComparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 468069626Sru(less than or equal), @samp{>=} (greater than or equal), @samp{=} 468169626Sru(equal), @samp{==} (the same as @samp{=}). 468269626Sru 468355839Sasmodai@item 468469626Sru@cindex logical operators 468569626Sru@cindex operators, logical 468669626Sru@opindex & 4687104862Sru@ifnotinfo 468869626Sru@opindex : 4689104862Sru@end ifnotinfo 4690104862Sru@ifinfo 4691104862Sru@opindex @r{<colon>} 4692104862Sru@end ifinfo 469369626SruLogical: @samp{&} (logical and), @samp{:} (logical or). 469469626Sru 469555839Sasmodai@item 469669626Sru@cindex unary operators 469769626Sru@cindex operators, unary 469869626Sru@opindex - 469969626Sru@opindex + 470069626Sru@opindex ! 4701104862Sru@cindex @code{if} request, and the @samp{!} operator 4702104862Sru@cindex @code{while} request, and the @samp{!} operator 470369626SruUnary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 470469626Sru(just for completeness; does nothing in expressions), @samp{!} (logical 470569626Srunot; this works only within @code{if} and @code{while} requests). See 470669626Srubelow for the use of unary operators in motion requests. 470769626Sru 470855839Sasmodai@item 4709104862Sru@cindex extremum operators (@code{>?}, @code{<?}) 4710104862Sru@cindex operators, extremum (@code{>?}, @code{<?}) 471169626Sru@opindex >? 471269626Sru@opindex <? 4713104862SruExtrema: @samp{>?} (maximum), @samp{<?} (minimum). 471469626Sru 4715104862SruExample: 471669626Sru 4717104862Sru@Example 4718104862Sru.nr x 5 4719104862Sru.nr y 3 4720104862Sru.nr z (\n[x] >? \n[y]) 4721104862Sru@endExample 4722104862Sru 4723104862Sru@noindent 4724114402SruThe register@tie{}@code{z} now contains@tie{}5. 4725104862Sru 472655839Sasmodai@item 472769626Sru@cindex scaling operator 472869626Sru@cindex operator, scaling 4729114402SruScaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c} 4730104862Sruas the default scaling indicator. If @var{c} is missing, ignore scaling 4731114402Sruindicators in the evaluation of@tie{}@var{e}. 473255839Sasmodai@end itemize 473355839Sasmodai 473469626Sru@cindex parentheses 473569626Sru@cindex order of evaluation in expressions 473669626Sru@cindex expression, order of evaluation 473769626Sru@opindex ( 473869626Sru@opindex ) 473969626SruParentheses may be used as in any other language. However, in 474069626Sru@code{gtroff} they are necessary to ensure order of evaluation. 474169626Sru@code{gtroff} has no operator precedence; expressions are evaluated left 474275584Sruto right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 474369626Sruparenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 474469626Sruexpected. 474555839Sasmodai 4746104862Sru@cindex @code{+}, and page motion 4747104862Sru@cindex @code{-}, and page motion 474869626Sru@cindex motion operators 474969626Sru@cindex operators, motion 475069626SruFor many requests which cause a motion on the page, the unary operators 4751104862Sru@samp{+} and @samp{-} work differently if leading an expression. They 4752104862Sruthen indicate a motion relative to the current position (down or up, 4753104862Srurespectively). 4754104862Sru 4755104862Sru@cindex @code{|}, and page motion 4756104862Sru@cindex absolute position operator (@code{|}) 4757104862Sru@cindex position, absolute, operator (@code{|}) 4758104862SruSimilarly, a leading @samp{|} operator indicates an absolute position. 4759104862SruFor vertical movements, it specifies the distance from the top of the 4760104862Srupage; for horizontal movements, it gives the distance from the beginning 4761104862Sruof the @emph{input} line. 4762104862Sru 4763114402Sru@cindex @code{bp} request, using @code{+} and@tie{}@code{-} 4764114402Sru@cindex @code{in} request, using @code{+} and@tie{}@code{-} 4765114402Sru@cindex @code{ll} request, using @code{+} and@tie{}@code{-} 4766114402Sru@cindex @code{lt} request, using @code{+} and@tie{}@code{-} 4767114402Sru@cindex @code{nm} request, using @code{+} and@tie{}@code{-} 4768114402Sru@cindex @code{nr} request, using @code{+} and@tie{}@code{-} 4769114402Sru@cindex @code{pl} request, using @code{+} and@tie{}@code{-} 4770114402Sru@cindex @code{pn} request, using @code{+} and@tie{}@code{-} 4771114402Sru@cindex @code{po} request, using @code{+} and@tie{}@code{-} 4772114402Sru@cindex @code{ps} request, using @code{+} and@tie{}@code{-} 4773114402Sru@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} 4774114402Sru@cindex @code{rt} request, using @code{+} and@tie{}@code{-} 4775114402Sru@cindex @code{ti} request, using @code{+} and@tie{}@code{-} 4776114402Sru@cindex @code{\H}, using @code{+} and@tie{}@code{-} 4777114402Sru@cindex @code{\R}, using @code{+} and@tie{}@code{-} 4778114402Sru@cindex @code{\s}, using @code{+} and@tie{}@code{-} 477969626Sru@samp{+} and @samp{-} are also treated differently by the following 478069626Srurequests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 478169626Sru@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 4782104862Sru@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}. 4783104862SruHere, leading plus and minus signs indicate increments and decrements. 478455839Sasmodai 4785104862Sru@xref{Setting Registers}, for some examples. 478669626Sru 4787104862Sru@Defesc {\\B, ', anything, '} 4788104862Sru@cindex numeric expression, valid 4789104862Sru@cindex valid numeric expression 4790114402SruReturn@tie{}1 if @var{anything} is a valid numeric expression; 4791114402Sruor@tie{}0 if @var{anything} is empty or not a valid numeric expression. 4792104862Sru@endDefesc 4793104862Sru 4794104862Sru@cindex space characters, in expressions 4795104862Sru@cindex expressions, and space characters 479655839SasmodaiDue to the way arguments are parsed, spaces are not allowed in 479769626Sruexpressions, unless the entire expression is surrounded by parentheses. 479855839Sasmodai 4799114402Sru@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}. 480055839Sasmodai 480169626Sru 480269626Sru@c ===================================================================== 480369626Sru 480475584Sru@node Identifiers, Embedded Commands, Expressions, gtroff Reference 480555839Sasmodai@section Identifiers 480655839Sasmodai@cindex identifiers 480755839Sasmodai 480869626SruLike any other language, @code{gtroff} has rules for properly formed 480969626Sru@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 481069626Srualmost any printable character, with the exception of the following 481169626Srucharacters: 481255839Sasmodai 481369626Sru@itemize @bullet 481469626Sru@item 481569626Sru@cindex whitespace characters 481669626Sru@cindex newline character 481769626Sru@cindex character, whitespace 481875584SruWhitespace characters (spaces, tabs, and newlines). 481969626Sru 482069626Sru@item 482169626Sru@cindex character, backspace 482269626Sru@cindex backspace character 482369626Sru@cindex @acronym{EBCDIC} encoding of backspace 4824114402SruBackspace (@acronym{ASCII}@tie{}@code{0x08} or 4825114402Sru@acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}. 482669626Sru 482769626Sru@item 482869626Sru@cindex invalid input characters 482969626Sru@cindex input characters, invalid 483069626Sru@cindex characters, invalid input 4831104862Sru@cindex Unicode 483275584SruThe following input characters are invalid and are ignored if 483369626Sru@code{groff} runs on a machine based on @acronym{ASCII}, causing a 483469626Sruwarning message of type @samp{input} (see @ref{Debugging}, for more 483569626Srudetails): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 483669626Sru@code{0x80}-@code{0x9F}. 483769626Sru 483869626SruAnd here are the invalid input characters if @code{groff} runs on an 483969626Sru@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 484069626Sru@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 484169626Sru@code{0x30}-@code{0x3F}. 484269626Sru 484369626SruCurrently, some of these reserved codepoints are used internally, thus 484469626Srumaking it non-trivial to extend @code{gtroff} to cover Unicode or other 484575584Srucharacter sets and encodings which use characters of these ranges. 484669626Sru 484775584SruNote that invalid characters are removed before parsing; an 484869626Sruidentifier @code{foo}, followed by an invalid character, followed by 484975584Sru@code{bar} is treated as @code{foobar}. 485069626Sru@end itemize 485169626Sru 485269626SruFor example, any of the following is valid. 485369626Sru 485475584Sru@Example 485555839Sasmodaibr 485655839SasmodaiPP 485755839Sasmodai(l 485855839Sasmodaiend-list 485955839Sasmodai@@_ 486075584Sru@endExample 486155839Sasmodai 4862104862Sru@cindex @code{]}, as part of an identifier 486375584Sru@noindent 486469626SruNote that identifiers longer than two characters with a closing bracket 486569626Sru(@samp{]}) in its name can't be accessed with escape sequences which 486675584Sruexpect an identifier as a parameter. For example, @samp{\[foo]]} 486775584Sruaccesses the glyph @samp{foo}, followed by @samp{]}, whereas 486869626Sru@samp{\C'foo]'} really asks for glyph @samp{foo]}. 486955839Sasmodai 4870104862Sru@cindex @code{refer}, and macro names starting with @code{[} or @code{]} 4871104862Sru@cindex @code{[}, macro names starting with, and @code{refer} 4872104862Sru@cindex @code{]}, macro names starting with, and @code{refer} 4873104862Sru@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} 4874104862SruTo avoid problems with the @code{refer} preprocessor, macro names 4875104862Srushould not start with @samp{[} or @samp{]}. Due to backwards 4876104862Srucompatibility, everything after @samp{.[} and @samp{.]} is handled as 4877104862Srua special argument to @code{refer}. For example, @samp{.[foo} makes 4878104862Sru@code{refer} to start a reference, using @samp{foo} as a parameter. 487955839Sasmodai 488075584Sru@Defesc {\\A, ', ident, '} 488175584SruTest whether an identifier @var{ident} is valid in @code{gtroff}. It 4882114402Sruexpands to the character@tie{}1 or@tie{}0 according to whether its 488375584Sruargument (usually delimited by quotes) is or is not acceptable as the 488475584Sruname of a string, macro, diversion, number register, environment, or 4885114402Srufont. It returns@tie{}0 if no argument is given. This is useful for 488675584Srulooking up user input in some sort of associative table. 488769626Sru 488875584Sru@Example 488969626Sru\A'end-list' 489069626Sru @result{} 1 489175584Sru@endExample 489275584Sru@endDefesc 489369626Sru 489469626Sru@xref{Escapes}, for details on parameter delimiting characters. 489569626Sru 489669626SruIdentifiers in @code{gtroff} can be any length, but, in some contexts, 489769626Sru@code{gtroff} needs to be told where identifiers end and text begins 489869626Sru(and in different ways depending on their length): 489969626Sru 490069626Sru@itemize @bullet 490155839Sasmodai@item 490269626SruSingle character. 490369626Sru 4904104862Sru@cindex @code{(}, starting a two-character identifier 490555839Sasmodai@item 490669626SruTwo characters. Must be prefixed with @samp{(} in some situations. 490769626Sru 4908104862Sru@cindex @code{[}, starting an identifier 4909104862Sru@cindex @code{]}, ending an identifier 491055839Sasmodai@item 491169626SruArbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 4912114402Sruand@tie{}@samp{]} in some situations. Any length identifier can be put 491369626Sruin brackets. 491455839Sasmodai@end itemize 491555839Sasmodai 491669626Sru@cindex undefined identifiers 4917104862Sru@cindex identifiers, undefined 491855839SasmodaiUnlike many other programming languages, undefined identifiers are 491955839Sasmodaisilently ignored or expanded to nothing. 492075584SruWhen @code{gtroff} finds an undefined identifier, it emits a 4921104862Sruwarning, doing the following: 492255839Sasmodai 492375584Sru@itemize @bullet 492475584Sru@item 492575584SruIf the identifier is a string, macro, or diversion, 492675584Sru@code{gtroff} defines it as empty. 492755839Sasmodai 492875584Sru@item 492975584SruIf the identifier is a number register, @code{gtroff} 4930114402Srudefines it with a value of@tie{}0. 493175584Sru@end itemize 493275584Sru 4933104862Sru@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. 493475584Sru 4935104862SruNote that macros, strings, and diversions share the same name space. 493675584Sru 4937104862Sru@Example 4938104862Sru.de xxx 4939104862Sru. nop foo 4940104862Sru.. 4941104862Sru. 4942104862Sru.di xxx 4943104862Srubar 4944104862Sru.br 4945104862Sru.di 4946104862Sru. 4947104862Sru.xxx 4948104862Sru @result{} bar 4949104862Sru@endExample 4950104862Sru 4951104862Sru@noindent 4952104862SruAs can be seen in the previous example, @code{gtroff} reuses the 4953104862Sruidentifier @samp{xxx}, changing it from a macro to a diversion. 4954104862SruNo warning is emitted! The contents of the first macro definition is 4955104862Srulost. 4956104862Sru 495769626Sru@xref{Interpolating Registers}, and @ref{Strings}. 495855839Sasmodai 495969626Sru 496069626Sru@c ===================================================================== 496169626Sru 496275584Sru@node Embedded Commands, Registers, Identifiers, gtroff Reference 496355839Sasmodai@section Embedded Commands 496455839Sasmodai@cindex embedded commands 496555839Sasmodai@cindex commands, embedded 496655839Sasmodai 496769626SruMost documents need more functionality beyond filling, adjusting and 496869626Sruimplicit line breaking. In order to gain further functionality, 496969626Sru@code{gtroff} allows commands to be embedded into the text, in two ways. 497055839Sasmodai 497155839SasmodaiThe first is a @dfn{request} which takes up an entire line, and does 497275584Srusome large-scale operation (e.g.@: break lines, start new pages). 497355839Sasmodai 4974104862SruThe other is an @dfn{escape} which can be usually embedded anywhere 4975104862Sruin the text; most requests can accept it even as an argument. 497669626SruEscapes generally do more minor operations like sub- and superscripts, 497769626Sruprint a symbol, etc. 497855839Sasmodai 497955839Sasmodai@menu 498075584Sru* Requests:: 498175584Sru* Macros:: 498275584Sru* Escapes:: 498355839Sasmodai@end menu 498455839Sasmodai 498569626Sru@c --------------------------------------------------------------------- 498669626Sru 498755839Sasmodai@node Requests, Macros, Embedded Commands, Embedded Commands 498855839Sasmodai@subsection Requests 498955839Sasmodai@cindex requests 499055839Sasmodai 4991104862Sru@cindex control character (@code{.}) 4992104862Sru@cindex character, control (@code{.}) 4993104862Sru@cindex no-break control character (@code{'}) 4994104862Sru@cindex character, no-break control (@code{'}) 4995104862Sru@cindex control character, no-break (@code{'}) 499669626SruA request line begins with a control character, which is either a single 499769626Sruquote (@samp{'}, the @dfn{no-break control character}) or a period 499869626Sru(@samp{.}, the normal @dfn{control character}). These can be changed; 499969626Srusee @ref{Character Translations}, for details. After this there may be 500069626Sruoptional tabs or spaces followed by an identifier which is the name of 500169626Sruthe request. This may be followed by any number of space-separated 500275584Sruarguments (@emph{no} tabs here). 500355839Sasmodai 500475584Sru@cindex structuring source code of documents or macro packages 500575584Sru@cindex documents, structuring the source code 5006104862Sru@cindex macro packages, structuring the source code 500775584SruSince a control character followed by whitespace only is ignored, it 500875584Sruis common practice to use this feature for structuring the source code 500975584Sruof documents or macro packages. 501075584Sru 501175584Sru@Example 501275584Sru.de foo 501375584Sru. tm This is foo. 501475584Sru.. 501575584Sru. 501675584Sru. 501775584Sru.de bar 501875584Sru. tm This is bar. 501975584Sru.. 502075584Sru@endExample 502175584Sru 502275584Sru@cindex blank line 5023104862Sru@cindex blank line macro (@code{blm}) 502475584SruAnother possibility is to use the blank line macro request @code{blm} 502575584Sruby assigning an empty macro to it. 502675584Sru 502775584Sru@Example 502875584Sru.de do-nothing 502975584Sru.. 503075584Sru.blm do-nothing \" activate blank line macro 503175584Sru 503275584Sru.de foo 503375584Sru. tm This is foo. 503475584Sru.. 503575584Sru 503675584Sru 503775584Sru.de bar 503875584Sru. tm This is bar. 503975584Sru.. 504075584Sru 504175584Sru.blm \" deactivate blank line macro 504275584Sru@endExample 504375584Sru 5044104862Sru@xref{Blank Line Traps}. 504575584Sru 5046104862Sru@cindex zero width space character (@code{\&}) 5047104862Sru@cindex character, zero width space (@code{\&}) 5048104862Sru@cindex space character, zero width (@code{\&}) 504975584Sru@cindex @code{\&}, escaping control characters 505069626SruTo begin a line with a control character without it being interpreted, 505169626Sruprecede it with @code{\&}. This represents a zero width space, which 505275584Srumeans it does not affect the output. 505355839Sasmodai 505469626SruIn most cases the period is used as a control character. Several 505575584Srurequests cause a break implicitly; using the single quote control 505675584Srucharacter prevents this. 505755839Sasmodai 505855839Sasmodai@menu 5059114402Sru* Request and Macro Arguments:: 506055839Sasmodai@end menu 506155839Sasmodai 5062114402Sru@node Request and Macro Arguments, , Requests, Requests 5063114402Sru@subsubsection Request and Macro Arguments 506455839Sasmodai@cindex request arguments 5065114402Sru@cindex macro arguments 5066114402Sru@cindex arguments to requests and macros 506755839Sasmodai 5068114402SruArguments to requests and macros are processed much like the shell: 5069104862SruThe line is split into arguments according to 5070114402Sruspaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows 5071104862Srutabs for argument separation -- @code{gtroff} intentionally doesn't 5072114402Srusupport this.} 507355839Sasmodai 5074114402Sru@cindex spaces, in a macro argument 5075114402SruAn argument to a macro which is intended to contain spaces can either be 5076114402Sruenclosed in double quotes, or have the spaces @dfn{escaped} with 5077114402Srubackslashes. This is @emph{not} true for requests. 507855839Sasmodai 5079114402SruHere are a few examples for a hypothetical macro @code{uh}: 5080114402Sru 508175584Sru@Example 508255839Sasmodai.uh The Mouse Problem 508355839Sasmodai.uh "The Mouse Problem" 508455839Sasmodai.uh The\ Mouse\ Problem 508575584Sru@endExample 508655839Sasmodai 5087104862Sru@cindex @code{\~}, difference to @code{\@key{SP}} 5088104862Sru@cindex @code{\@key{SP}}, difference to @code{\~} 508969626Sru@noindent 509069626SruThe first line is the @code{uh} macro being called with 3 arguments, 509169626Sru@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 509275584Srusame effect of calling the @code{uh} macro with one argument, @samp{The 509369626SruMouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 509469626Sruis ``classical'' in the sense that it can be found in most @code{troff} 509569626Srudocuments. Nevertheless, it is not optimal in all situations, since 509669626Sru@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 509769626Srucan't stretch. @code{gtroff} provides a different command @code{\~} to 509869626Sruinsert a stretchable, non-breaking space.} 509955839Sasmodai 5100104862Sru@cindex @code{"}, in a macro argument 5101104862Sru@cindex double quote, in a macro argument 510275584SruA double quote which isn't preceded by a space doesn't start a macro 510375584Sruargument. If not closing a string, it is printed literally. 510475584Sru 510575584SruFor example, 510675584Sru 510775584Sru@Example 510875584Sru.xxx a" "b c" "de"fg" 510975584Sru@endExample 511075584Sru 511175584Sru@noindent 511275584Sruhas the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 5113104862SruDon't rely on this obscure behaviour! 511475584Sru 5115104862SruThere are two possibilities to get a double quote reliably. 5116104862Sru 5117104862Sru@itemize @bullet 5118104862Sru@item 5119104862SruEnclose the whole argument with double quotes and use two consecutive double 5120104862Sruquotes to represent a single one. This traditional solution has the 5121104862Srudisadvantage that double quotes don't survive argument expansion again if 5122104862Srucalled in compatibility mode (using the @option{-C} option of @code{groff}): 5123104862Sru 5124104862Sru@Example 5125104862Sru.de xx 5126104862Sru. tm xx: `\\$1' `\\$2' `\\$3' 5127104862Sru. 5128104862Sru. yy "\\$1" "\\$2" "\\$3" 5129104862Sru.. 5130104862Sru.de yy 5131104862Sru. tm yy: `\\$1' `\\$2' `\\$3' 5132104862Sru.. 5133104862Sru.xx A "test with ""quotes""" . 5134104862Sru @result{} xx: `A' `test with "quotes"' `.' 5135104862Sru @result{} yy: `A' `test with ' `quotes""' 5136104862Sru@endExample 5137104862Sru 5138104862Sru@noindent 5139104862SruIf not in compatibility mode, you get the expected result 5140104862Sru 5141104862Sru@Example 5142104862Sruxx: `A' `test with "quotes"' `.' 5143104862Sruyy: `A' `test with "quotes"' `.' 5144104862Sru@endExample 5145104862Sru 5146104862Sru@noindent 5147104862Srusince @code{gtroff} preserves the input level. 5148104862Sru 5149104862Sru@item 5150104862SruUse the double quote glyph @code{\(dq}. This works with and without 5151104862Srucompatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq} 5152104862Sruback to a double quote input character. 5153104862Sru 5154104862SruNot that this method won't work with @acronym{UNIX} @code{troff} in general 5155104862Srusince the glyph `dq' isn't defined normally. 5156104862Sru@end itemize 5157104862Sru 5158104862Sru@cindex @code{ds} request, and double quotes 5159104862SruDouble quotes in the @code{ds} request are handled differently. 516069626Sru@xref{Strings}, for more details. 516155839Sasmodai 516269626Sru@c --------------------------------------------------------------------- 516355839Sasmodai 516455839Sasmodai@node Macros, Escapes, Requests, Embedded Commands 516555839Sasmodai@subsection Macros 516655839Sasmodai@cindex macros 516755839Sasmodai 516869626Sru@code{gtroff} has a @dfn{macro} facility for defining a series of lines 516969626Sruwhich can be invoked by name. They are called in the same manner as 5170114402Srurequests -- arguments also may be passed basically in the same manner. 517155839Sasmodai 5172114402Sru@xref{Writing Macros}, and @ref{Request and Macro Arguments}. 517355839Sasmodai 517469626Sru@c --------------------------------------------------------------------- 517555839Sasmodai 517655839Sasmodai@node Escapes, , Macros, Embedded Commands 517755839Sasmodai@subsection Escapes 517855839Sasmodai@cindex escapes 517955839Sasmodai 518069626SruEscapes may occur anywhere in the input to @code{gtroff}. They usually 518169626Srubegin with a backslash and are followed by a single character which 518269626Sruindicates the function to be performed. The escape character can be 518369626Sruchanged; see @ref{Character Translations}. 518455839Sasmodai 518569626SruEscape sequences which require an identifier as a parameter accept three 518669626Srupossible syntax forms. 518755839Sasmodai 518869626Sru@itemize @bullet 518969626Sru@item 519069626SruThe next single character is the identifier. 519155839Sasmodai 5192104862Sru@cindex @code{(}, starting a two-character identifier 519369626Sru@item 519469626SruIf this single character is an opening parenthesis, take the following 519569626Srutwo characters as the identifier. Note that there is no closing 519669626Sruparenthesis after the identifier. 519769626Sru 5198104862Sru@cindex @code{[}, starting an identifier 5199104862Sru@cindex @code{]}, ending an identifier 520069626Sru@item 520169626SruIf this single character is an opening bracket, take all characters 520269626Sruuntil a closing bracket as the identifier. 520369626Sru@end itemize 520469626Sru 520569626Sru@noindent 520669626SruExamples: 520769626Sru 520875584Sru@Example 520955839Sasmodai\fB 521055839Sasmodai\n(XX 521155839Sasmodai\*[TeX] 521275584Sru@endExample 521355839Sasmodai 5214104862Sru@cindex @code{'}, delimiting arguments 521569626Sru@cindex argument delimiting characters 521669626Sru@cindex characters, argument delimiting 521769626Sru@cindex delimiting characters for arguments 521869626SruOther escapes may require several arguments and/or some special format. 521969626SruIn such cases the argument is traditionally enclosed in single quotes 522069626Sru(and quotes are always used in this manual for the definitions of escape 522169626Srusequences). The enclosed text is then processed according to what that 522269626Sruescape expects. Example: 522355839Sasmodai 522475584Sru@Example 522555839Sasmodai\l'1.5i\(bu' 522675584Sru@endExample 522755839Sasmodai 5228104862Sru@cindex @code{\o}, possible quote characters 5229104862Sru@cindex @code{\b}, possible quote characters 5230104862Sru@cindex @code{\X}, possible quote characters 523169626SruNote that the quote character can be replaced with any other character 523269626Sruwhich does not occur in the argument (even a newline or a space 523369626Srucharacter) in the following escapes: @code{\o}, @code{\b}, and 523469626Sru@code{\X}. This makes e.g. 523569626Sru 523675584Sru@Example 523769626SruA caf 523869626Sru\o 523969626Srue\' 524069626Sru 524169626Sru 524269626Sruin Paris 524369626Sru @result{} A caf@'e in Paris 524475584Sru@endExample 524569626Sru 524669626Sru@noindent 524769626Srupossible, but it is better not to use this feature to avoid confusion. 524869626Sru 5249104862Sru@cindex @code{\%}, used as delimiter 5250104862Sru@cindex @code{\@key{SP}}, used as delimiter 5251104862Sru@cindex @code{\|}, used as delimiter 5252104862Sru@cindex @code{\^}, used as delimiter 5253104862Sru@cindex @code{\@{}, used as delimiter 5254104862Sru@cindex @code{\@}}, used as delimiter 5255104862Sru@cindex @code{\'}, used as delimiter 5256104862Sru@cindex @code{\`}, used as delimiter 5257104862Sru@cindex @code{\-}, used as delimiter 5258104862Sru@cindex @code{\_}, used as delimiter 5259104862Sru@cindex @code{\!}, used as delimiter 5260104862Sru@cindex @code{\?}, used as delimiter 5261104862Sru@cindex @code{\@@}, used as delimiter 5262104862Sru@cindex @code{\)}, used as delimiter 5263104862Sru@cindex @code{\/}, used as delimiter 5264104862Sru@cindex @code{\,}, used as delimiter 5265104862Sru@cindex @code{\&}, used as delimiter 5266104862Sru@ifnotinfo 5267104862Sru@cindex @code{\:}, used as delimiter 5268104862Sru@end ifnotinfo 5269104862Sru@ifinfo 5270104862Sru@cindex @code{\@r{<colon>}}, used as delimiter 5271104862Sru@end ifinfo 5272104862Sru@cindex @code{\~}, used as delimiter 5273104862Sru@cindex @code{\0}, used as delimiter 5274104862Sru@cindex @code{\a}, used as delimiter 5275104862Sru@cindex @code{\c}, used as delimiter 5276104862Sru@cindex @code{\d}, used as delimiter 5277104862Sru@cindex @code{\e}, used as delimiter 5278104862Sru@cindex @code{\E}, used as delimiter 5279104862Sru@cindex @code{\p}, used as delimiter 5280104862Sru@cindex @code{\r}, used as delimiter 5281104862Sru@cindex @code{\t}, used as delimiter 5282104862Sru@cindex @code{\u}, used as delimiter 528369626SruThe following escapes sequences (which are handled similarly to 528469626Srucharacters since they don't take a parameter) are also allowed as 528569626Srudelimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 528669626Sru@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 528769626Sru@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 5288104862Sru@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, 5289104862Sru@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. 5290104862SruAgain, don't use these if possible. 529169626Sru 5292104862Sru@cindex @code{\A}, allowed delimiters 5293104862Sru@cindex @code{\B}, allowed delimiters 5294104862Sru@cindex @code{\Z}, allowed delimiters 5295104862Sru@cindex @code{\C}, allowed delimiters 5296104862Sru@cindex @code{\w}, allowed delimiters 529769626SruNo newline characters as delimiters are allowed in the following 5298104862Sruescapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}. 529969626Sru 5300104862Sru@cindex @code{\D}, allowed delimiters 5301104862Sru@cindex @code{\h}, allowed delimiters 5302104862Sru@cindex @code{\H}, allowed delimiters 5303104862Sru@cindex @code{\l}, allowed delimiters 5304104862Sru@cindex @code{\L}, allowed delimiters 5305104862Sru@cindex @code{\N}, allowed delimiters 5306104862Sru@cindex @code{\R}, allowed delimiters 5307104862Sru@cindex @code{\s}, allowed delimiters 5308104862Sru@cindex @code{\S}, allowed delimiters 5309104862Sru@cindex @code{\v}, allowed delimiters 5310104862Sru@cindex @code{\x}, allowed delimiters 531169626SruFinally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 5312104862Sru@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, 5313104862Sruand @code{\x} can't use the following characters as delimiters: 531469626Sru 531569626Sru@itemize @bullet 531669626Sru@item 5317104862Sru@cindex numbers, and delimiters 5318104862Sru@cindex digits, and delimiters 531969626SruThe digits @code{0}-@code{9}. 532069626Sru 532169626Sru@item 5322104862Sru@cindex operators, as delimiters 5323104862Sru@cindex @code{+}, as delimiter 5324104862Sru@cindex @code{-}, as delimiter 5325104862Sru@cindex @code{/}, as delimiter 5326104862Sru@cindex @code{*}, as delimiter 5327104862Sru@cindex @code{%}, as delimiter 5328104862Sru@cindex @code{<}, as delimiter 5329104862Sru@cindex @code{>}, as delimiter 5330104862Sru@cindex @code{=}, as delimiter 5331104862Sru@cindex @code{&}, as delimiter 5332104862Sru@ifnotinfo 5333104862Sru@cindex @code{:}, as delimiter 5334104862Sru@end ifnotinfo 5335104862Sru@ifinfo 5336104862Sru@cindex <colon>, as delimiter 5337104862Sru@end ifinfo 5338104862Sru@cindex @code{(}, as delimiter 5339104862Sru@cindex @code{)}, as delimiter 5340104862Sru@cindex @code{.}, as delimiter 534169626SruThe (single-character) operators @samp{+-/*%<>=&:().}. 534269626Sru 534369626Sru@item 534469626Sru@cindex space character 534569626Sru@cindex character, space 534669626Sru@cindex tab character 534769626Sru@cindex character, tab 534869626Sru@cindex newline character 534969626Sru@cindex character, newline 535069626SruThe space, tab, and newline characters. 535169626Sru 535269626Sru@item 5353104862Sru@cindex @code{\%}, used as delimiter 5354104862Sru@ifnotinfo 5355104862Sru@cindex @code{\:}, used as delimiter 5356104862Sru@end ifnotinfo 5357104862Sru@ifinfo 5358104862Sru@cindex @code{\@r{<colon>}}, used as delimiter 5359104862Sru@end ifinfo 5360104862Sru@cindex @code{\@{}, used as delimiter 5361104862Sru@cindex @code{\@}}, used as delimiter 5362104862Sru@cindex @code{\'}, used as delimiter 5363104862Sru@cindex @code{\`}, used as delimiter 5364104862Sru@cindex @code{\-}, used as delimiter 5365104862Sru@cindex @code{\_}, used as delimiter 5366104862Sru@cindex @code{\!}, used as delimiter 5367104862Sru@cindex @code{\@@}, used as delimiter 5368104862Sru@cindex @code{\/}, used as delimiter 5369104862Sru@cindex @code{\c}, used as delimiter 5370104862Sru@cindex @code{\e}, used as delimiter 5371104862Sru@cindex @code{\p}, used as delimiter 5372104862SruAll escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}}, 537369626Sru@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 537469626Sru@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 537569626Sru@end itemize 537669626Sru 5377104862Sru@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 5378104862Sru@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 537975584SruTo have a backslash (actually, the current escape character) appear in the 538069626Sruoutput several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 538155839SasmodaiThese are very similar, and only differ with respect to being used in 5382104862Srumacros or diversions. @xref{Character Translations}, for an exact 5383104862Srudescription of those escapes. 538455839Sasmodai 5385104862Sru@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions}, 5386104862Sru@ref{Identifiers}, for more information. 538755839Sasmodai 538855839Sasmodai@menu 538975584Sru* Comments:: 539055839Sasmodai@end menu 539155839Sasmodai 539255839Sasmodai@node Comments, , Escapes, Escapes 539355839Sasmodai@subsubsection Comments 539455839Sasmodai@cindex comments 539555839Sasmodai 539655839SasmodaiProbably one of the most@footnote{Unfortunately, this is a lie. But 539769626Sruhopefully future @code{gtroff} hackers will believe it @code{:-)}} 539855839Sasmodaicommon forms of escapes is the comment. 539955839Sasmodai 540075584Sru@Defesc {\\", , , } 540169626SruStart a comment. Everything to the end of the input line is ignored. 540269626Sru 540355839SasmodaiThis may sound simple, but it can be tricky to keep the comments from 540469626Sruinterfering with the appearance of the final output. 540555839Sasmodai 5406104862Sru@cindex @code{ds}, @code{ds1} requests, and comments 5407104862Sru@cindex @code{as}, @code{as1} requests, and comments 540875584SruIf the escape is to the right of some text or a request, that portion 540975584Sruof the line is ignored, but the space leading up to it is noticed by 5410104862Sru@code{gtroff}. This only affects the @code{ds} and @code{as} 5411104862Srurequest and its variants. 541255839Sasmodai 5413104862Sru@cindex tabs, before comments 541469626Sru@cindex comments, lining up with tabs 541569626SruOne possibly irritating idiosyncracy is that tabs must not be used to 5416104862Sruline up comments. Tabs are not treated as whitespace between the 541769626Srurequest and macro arguments. 541855839Sasmodai 541969626Sru@cindex undefined request 542069626Sru@cindex request, undefined 542175584SruA comment on a line by itself is treated as a blank line, because 542269626Sruafter eliminating the comment, that is all that remains: 542355839Sasmodai 542475584Sru@Example 542569626SruTest 542669626Sru\" comment 542769626SruTest 542875584Sru@endExample 542969626Sru 543069626Sru@noindent 543175584Sruproduces 543269626Sru 543375584Sru@Example 543469626SruTest 543569626Sru 543669626SruTest 543775584Sru@endExample 543869626Sru 543975584SruTo avoid this, it is common to start the line with @code{.\"} which 544075584Srucauses the line to be treated as an undefined request and thus ignored 544175584Srucompletely. 544269626Sru 5443104862Sru@cindex @code{'}, as a comment 544455839SasmodaiAnother commenting scheme seen sometimes is three consecutive single 544569626Sruquotes (@code{'''}) at the beginning of a line. This works, but 544675584Sru@code{gtroff} gives a warning about an undefined macro (namely 544769626Sru@code{''}), which is harmless, but irritating. 544875584Sru@endDefesc 544955839Sasmodai 545075584Sru@Defesc {\\#, , , } 545175584SruTo avoid all this, @code{gtroff} has a new comment mechanism using the 545275584Sru@code{\#} escape. This escape works the same as @code{\"} except that 545375584Sruthe newline is also ignored: 545455839Sasmodai 545575584Sru@Example 545669626SruTest 545769626Sru\# comment 545869626SruTest 545975584Sru@endExample 546069626Sru 546169626Sru@noindent 546275584Sruproduces 546369626Sru 546475584Sru@Example 546569626SruTest Test 546675584Sru@endExample 546769626Sru 546869626Sru@noindent 546969626Sruas expected. 547075584Sru@endDefesc 547169626Sru 5472114402Sru@Defreq {ig, [@Var{end}]} 547375584SruIgnore all input until @code{gtroff} encounters the macro named 5474114402Sru@code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not 547575584Sruspecified). This is useful for commenting out large blocks of text: 547655839Sasmodai 547775584Sru@Example 547875584Srutext text text... 547975584Sru.ig 548075584SruThis is part of a large block 548175584Sruof text that has been 548275584Srutemporarily(?) commented out. 548369626Sru 548475584SruWe can restore it simply by removing 548575584Sruthe .ig request and the ".." at the 548675584Sruend of the block. 548775584Sru.. 548875584SruMore text text text... 548975584Sru@endExample 549069626Sru 549175584Sru@noindent 549275584Sruproduces 549369626Sru 549475584Sru@Example 549575584Srutext text text@dots{} More text text text@dots{} 549675584Sru@endExample 549775584Sru 549875584Sru@noindent 549975584SruNote that the commented-out block of text does not 550075584Srucause a break. 550175584Sru 550275584SruThe input is read in copy-mode; auto-incremented registers @emph{are} 550375584Sruaffected (@pxref{Auto-increment}). 550475584Sru@endDefreq 550575584Sru 550675584Sru 550769626Sru@c ===================================================================== 550869626Sru 550975584Sru@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 551055839Sasmodai@section Registers 551155839Sasmodai@cindex registers 551255839Sasmodai 551369626SruNumeric variables in @code{gtroff} are called @dfn{registers}. There 551469626Sruare a number of built-in registers, supplying anything from the date to 551569626Srudetails of formatting parameters. 551655839Sasmodai 551769626Sru@xref{Identifiers}, for details on register identifiers. 551855839Sasmodai 551955839Sasmodai@menu 552075584Sru* Setting Registers:: 552175584Sru* Interpolating Registers:: 552275584Sru* Auto-increment:: 552375584Sru* Assigning Formats:: 552475584Sru* Built-in Registers:: 552555839Sasmodai@end menu 552655839Sasmodai 552769626Sru@c --------------------------------------------------------------------- 552869626Sru 552955839Sasmodai@node Setting Registers, Interpolating Registers, Registers, Registers 553055839Sasmodai@subsection Setting Registers 5531104862Sru@cindex setting registers (@code{nr}, @code{\R}) 5532104862Sru@cindex registers, setting (@code{nr}, @code{\R}) 553355839Sasmodai 553475584SruDefine or set registers using the @code{nr} request or the 553569626Sru@code{\R} escape. 553655839Sasmodai 5537104862Sru@DefreqList {nr, ident value} 5538104862Sru@DefescListEnd {\\R, ', ident value, '} 553975584SruSet number register @var{ident} to @var{value}. If @var{ident} 554075584Srudoesn't exist, @code{gtroff} creates it. 554155839Sasmodai 554275584SruThe argument to @code{\R} usually has to be enclosed in quotes. 554369626Sru@xref{Escapes}, for details on parameter delimiting characters. 5544104862Sru 5545104862SruThe @code{\R} escape doesn't produce an input token in @code{gtroff}; 5546104862Sruwith other words, it vanishes completely after @code{gtroff} has 5547104862Sruprocessed it. 554875584Sru@endDefreq 554969626Sru 555069626SruFor example, the following two lines are equivalent: 555169626Sru 555275584Sru@Example 5553104862Sru.nr a (((17 + (3 * 4))) % 4) 5554104862Sru\R'a (((17 + (3 * 4))) % 4)' 5555104862Sru @result{} 1 555675584Sru@endExample 555755839Sasmodai 555869626SruBoth @code{nr} and @code{\R} have two additional special forms to 555975584Sruincrement or decrement a register. 556055839Sasmodai 5561104862Sru@DefreqList {nr, ident @t{+}@Var{value}} 5562104862Sru@DefreqItem {nr, ident @t{-}@Var{value}} 5563114402Sru@DefescItem {\\R, ', ident @t{+}value, '} 5564114402Sru@DefescListEnd {\\R, ', ident @t{-}value, '} 556569626SruIncrement (decrement) register @var{ident} by @var{value}. 556655839Sasmodai 556775584Sru@Example 556869626Sru.nr a 1 556969626Sru.nr a +1 557069626Sru\na 557169626Sru @result{} 2 557275584Sru@endExample 557355839Sasmodai 557469626Sru@cindex negating register values 557569626SruTo assign the negated value of a register to another register, some care 557669626Srumust be taken to get the desired result: 557755839Sasmodai 557875584Sru@Example 557969626Sru.nr a 7 558069626Sru.nr b 3 558169626Sru.nr a -\nb 558269626Sru\na 558369626Sru @result{} 4 558469626Sru.nr a (-\nb) 558569626Sru\na 558669626Sru @result{} -3 558775584Sru@endExample 558869626Sru 558969626Sru@noindent 559069626SruThe surrounding parentheses prevent the interpretation of the minus sign 559169626Sruas a decrementing operator. An alternative is to start the assignment 559269626Sruwith a @samp{0}: 559369626Sru 559475584Sru@Example 559569626Sru.nr a 7 559669626Sru.nr b -3 559769626Sru.nr a \nb 559869626Sru\na 559969626Sru @result{} 4 560069626Sru.nr a 0\nb 560169626Sru\na 560269626Sru @result{} -3 560375584Sru@endExample 560475584Sru@endDefreq 560569626Sru 560675584Sru@Defreq {rr, ident} 5607104862Sru@cindex removing number register (@code{rr}) 5608104862Sru@cindex number register, removing (@code{rr}) 5609104862Sru@cindex register, removing (@code{rr}) 561069626SruRemove number register @var{ident}. If @var{ident} doesn't exist, the 561169626Srurequest is ignored. 561275584Sru@endDefreq 561369626Sru 561475584Sru@Defreq {rnn, ident1 ident2} 5615104862Sru@cindex renaming number register (@code{rnn}) 5616104862Sru@cindex number register, renaming (@code{rnn}) 5617104862Sru@cindex register, renaming (@code{rnn}) 561869626SruRename number register @var{ident1} to @var{ident2}. If either 561969626Sru@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 562075584Sru@endDefreq 562169626Sru 562275584Sru@Defreq {aln, ident1 ident2} 5623104862Sru@cindex alias, number register, creating (@code{aln}) 5624104862Sru@cindex creating alias, for number register (@code{aln}) 5625104862Sru@cindex number register, creating alias (@code{aln}) 5626104862Sru@cindex register, creating alias (@code{aln}) 562775584SruCreate an alias @var{ident1} for a number register @var{ident2}. The 562875584Srunew name and the old name are exactly equivalent. If @var{ident1} is 562975584Sruundefined, a warning of type @samp{reg} is generated, and the request 563075584Sruis ignored. @xref{Debugging}, for information about warnings. 563175584Sru@endDefreq 563269626Sru 563369626Sru@c --------------------------------------------------------------------- 563469626Sru 563555839Sasmodai@node Interpolating Registers, Auto-increment, Setting Registers, Registers 563655839Sasmodai@subsection Interpolating Registers 5637104862Sru@cindex interpolating registers (@code{\n}) 5638104862Sru@cindex registers, interpolating (@code{\n}) 563955839Sasmodai 564069626SruNumeric registers can be accessed via the @code{\n} escape. 564155839Sasmodai 5642104862Sru@DefescList {\\n, , i, } 5643104862Sru@DefescItem {\\n, @lparen{}, id, } 5644104862Sru@DefescListEnd {\\n, @lbrack{}, ident, @rbrack} 564575584Sru@cindex nested assignments 564675584Sru@cindex assignments, nested 564775584Sru@cindex indirect assignments 564875584Sru@cindex assignments, indirect 5649114402SruInterpolate number register with name @var{ident} (one-character 5650114402Sruname@tie{}@var{i}, two-character name @var{id}). This means that the value 5651114402Sruof the register is expanded in-place while @code{gtroff} is parsing the 5652114402Sruinput line. Nested assignments (also called indirect assignments) are 5653114402Srupossible. 565455839Sasmodai 565575584Sru@Example 565669626Sru.nr a 5 565755839Sasmodai.nr as \na+\na 565855839Sasmodai\n(as 565969626Sru @result{} 10 566075584Sru@endExample 566155839Sasmodai 566275584Sru@Example 566375584Sru.nr a1 5 566475584Sru.nr ab 6 566575584Sru.ds str b 566675584Sru.ds num 1 566775584Sru\n[a\n[num]] 566875584Sru @result{} 5 566975584Sru\n[a\*[str]] 567075584Sru @result{} 6 567175584Sru@endExample 567275584Sru@endDefesc 567375584Sru 567469626Sru@c --------------------------------------------------------------------- 567555839Sasmodai 567655839Sasmodai@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 567755839Sasmodai@subsection Auto-increment 567855839Sasmodai@cindex auto-increment 567955839Sasmodai@cindex increment, automatic 568055839Sasmodai 568175584SruNumber registers can also be auto-incremented and auto-decremented. 568275584SruThe increment or decrement value can be specified with a third 568369626Sruargument to the @code{nr} request or @code{\R} escape. 568455839Sasmodai 568575584Sru@Defreq {nr, ident value incr} 5686104862Sru@cindex @code{\R}, difference to @code{nr} 568769626SruSet number register @var{ident} to @var{value}; the increment for 568875584Sruauto-incrementing is set to @var{incr}. Note that the @code{\R} 568975584Sruescape doesn't support this notation. 569075584Sru@endDefreq 569169626Sru 569275584SruTo activate auto-incrementing, the escape @code{\n} has a special 569375584Srusyntax form. 569469626Sru 5695104862Sru@DefescList {\\n, +, i, } 5696104862Sru@DefescItem {\\n, -, i, } 5697104862Sru@DefescItem {\\n, @lparen{}+, id, } 5698104862Sru@DefescItem {\\n, @lparen{}-, id, } 5699104862Sru@DefescItem {\\n, +@lparen{}, id, } 5700104862Sru@DefescItem {\\n, -@lparen{}, id, } 5701104862Sru@DefescItem {\\n, @lbrack{}+, ident, @rbrack{}} 5702104862Sru@DefescItem {\\n, @lbrack{}-, ident, @rbrack{}} 5703104862Sru@DefescItem {\\n, +@lbrack{}, ident, @rbrack{}} 5704104862Sru@DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}} 570575584SruBefore interpolating, increment or decrement @var{ident} 5706114402Sru(one-character name@tie{}@var{i}, two-character name @var{id}) by the 570769626Sruauto-increment value as specified with the @code{nr} request (or the 570875584Sru@code{\R} escape). If no auto-increment value has been specified, 570975584Sruthese syntax forms are identical to @code{\n}. 571075584Sru@endDefesc 571169626Sru 571269626SruFor example, 571369626Sru 571475584Sru@Example 571555839Sasmodai.nr a 0 1 571655839Sasmodai.nr xx 0 5 571769626Sru.nr foo 0 -2 571855839Sasmodai\n+a, \n+a, \n+a, \n+a, \n+a 571955839Sasmodai.br 572069626Sru\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 572169626Sru.br 572269626Sru\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 572375584Sru@endExample 572455839Sasmodai 572569626Sru@noindent 572669626Sruproduces 572755839Sasmodai 572875584Sru@Example 572955839Sasmodai1, 2, 3, 4, 5 573069626Sru-5, -10, -15, -20, -25 573169626Sru-2, -4, -6, -8, -10 573275584Sru@endExample 573355839Sasmodai 573469626Sru@cindex increment value without changing the register 5735104862Sru@cindex value, incrementing without changing the register 573675584SruTo change the increment value without changing the value of a register 573775584Sru(@var{a} in the example), the following can be used: 573855839Sasmodai 573975584Sru@Example 574055839Sasmodai.nr a \na 10 574175584Sru@endExample 574255839Sasmodai 574369626Sru@c --------------------------------------------------------------------- 574455839Sasmodai 574569626Sru@node Assigning Formats, Built-in Registers, Auto-increment, Registers 574655839Sasmodai@subsection Assigning Formats 5747104862Sru@cindex assigning formats (@code{af}) 5748104862Sru@cindex formats, assigning (@code{af}) 574955839Sasmodai 575075584SruWhen a register is used in the text of an input file (as opposed to 575175584Srupart of an expression), it is textually replaced (or interpolated) 575275584Sruwith a representation of that number. This output format can be 575375584Sruchanged to a variety of formats (numbers, Roman numerals, etc.). This 575475584Sruis done using the @code{af} request. 575555839Sasmodai 575675584Sru@Defreq {af, ident format} 575769626SruChange the output format of a number register. The first argument 575869626Sru@var{ident} is the name of the number register to be changed, and the 575975584Srusecond argument @var{format} is the output format. The following 576075584Sruoutput formats are available: 576155839Sasmodai 576269626Sru@table @code 576355839Sasmodai@item 1 5764114402SruDecimal arabic numbers. This is the default format: 0, 1, 2, 5765114402Sru3,@tie{}@enddots{} 576669626Sru 576769626Sru@item 0@dots{}0 576869626SruDecimal numbers with as many digits as specified. So, @samp{00} would 5769114402Sruresult in printing numbers as 01, 02, 03,@tie{}@enddots{} 577069626Sru 577169626SruIn fact, any digit instead of zero will do; @code{gtroff} only counts 577269626Sruhow many digits are specified. As a consequence, @code{af}'s default 577369626Sruformat @samp{1} could be specified as @samp{0} also (and exactly this is 577469626Srureturned by the @code{\g} escape, see below). 577569626Sru 577655839Sasmodai@item I 577775584Sru@cindex Roman numerals 577869626Sru@cindex numerals, Roman 5779114402SruUpper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{} 578069626Sru 578155839Sasmodai@item i 5782114402SruLower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{} 578369626Sru 578455839Sasmodai@item A 5785114402SruUpper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{} 578669626Sru 578755839Sasmodai@item a 5788114402SruLower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{} 578955839Sasmodai@end table 579055839Sasmodai 579175584SruOmitting the number register format causes a warning of type 579269626Sru@samp{missing}. @xref{Debugging}, for more details. Specifying a 579369626Srunonexistent format causes an error. 579455839Sasmodai 579575584SruThe following example produces @samp{10, X, j, 010}: 579669626Sru 579775584Sru@Example 579855839Sasmodai.nr a 10 579955839Sasmodai.af a 1 \" the default format 580055839Sasmodai\na, 580155839Sasmodai.af a I 580255839Sasmodai\na, 580355839Sasmodai.af a a 580455839Sasmodai\na, 580555839Sasmodai.af a 001 580655839Sasmodai\na 580775584Sru@endExample 580855839Sasmodai 580975584Sru@cindex Roman numerals, maximum and minimum 581069626Sru@cindex maximum values of Roman numerals 581169626Sru@cindex minimum values of Roman numerals 581269626SruThe largest number representable for the @samp{i} and @samp{I} formats 581375584Sruis 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 581475584Sruand @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 581569626Sru@code{gtroff}. Currently, the correct glyphs of Roman numeral five 581669626Sruthousand and Roman numeral ten thousand (Unicode code points 581769626Sru@code{U+2182} and @code{U+2181}, respectively) are not available. 581855839Sasmodai 581975584SruIf @var{ident} doesn't exist, it is created. 582055839Sasmodai 582169626Sru@cindex read-only register, changing format 5822104862Sru@cindex changing format, and read-only registers 582369626SruChanging the output format of a read-only register causes an error. It 582469626Sruis necessary to first copy the register's value to a writeable register, 582569626Sruthen apply the @code{af} request to this other register. 582675584Sru@endDefreq 582755839Sasmodai 5828104862Sru@DefescList {\\g, , i, } 5829104862Sru@DefescItem {\\g, @lparen{}, id, } 5830104862Sru@DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}} 5831104862Sru@cindex format of register (@code{\g}) 5832104862Sru@cindex register, format (@code{\g}) 583375584SruReturn the current format of the specified register @var{ident} 5834114402Sru(one-character name@tie{}@var{i}, two-character name @var{id}). For 583575584Sruexample, @samp{\ga} after the previous example would produce the 583675584Srustring @samp{000}. If the register hasn't been defined yet, nothing 583775584Sruis returned. 583875584Sru@endDefesc 583955839Sasmodai 584069626Sru@c --------------------------------------------------------------------- 584155839Sasmodai 584269626Sru@node Built-in Registers, , Assigning Formats, Registers 584369626Sru@subsection Built-in Registers 584469626Sru@cindex built-in registers 584569626Sru@cindex registers, built-in 584655839Sasmodai 584769626SruThe following lists some built-in registers which are not described 584869626Sruelsewhere in this manual. Any register which begins with a @samp{.} is 584969626Sruread-only. A complete listing of all built-in registers can be found in 5850114402Sruappendix@tie{}@ref{Register Index}. 585169626Sru 585255839Sasmodai@table @code 5853104862Sru@item .F 5854104862Sru@cindex current input file name register (@code{.F}) 5855104862Sru@cindex input file name, current, register (@code{.F}) 5856104862Sru@vindex .F 5857104862SruThis string-valued register returns the current input file name. 5858104862Sru 585955839Sasmodai@item .H 5860104862Sru@cindex horizontal resolution register (@code{.H}) 5861104862Sru@cindex resolution, horizontal, register (@code{.H}) 586255839Sasmodai@vindex .H 586355839SasmodaiHorizontal resolution in basic units. 586469626Sru 586555839Sasmodai@item .V 5866104862Sru@cindex vertical resolution register (@code{.V}) 5867104862Sru@cindex resolution, vertical, register (@code{.V}) 586855839Sasmodai@vindex .V 586955839SasmodaiVertical resolution in basic units. 587069626Sru 5871104862Sru@item seconds 5872104862Sru@cindex seconds, current time (@code{seconds}) 5873104862Sru@cindex time, current, seconds (@code{seconds}) 5874104862Sru@cindex current time, seconds (@code{seconds}) 5875104862Sru@vindex seconds 5876114402SruThe number of seconds after the minute, normally in the range@tie{}0 5877114402Sruto@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized 5878104862Sruat start-up of @code{gtroff}. 5879104862Sru 5880104862Sru@item minutes 5881104862Sru@cindex minutes, current time (@code{minutes}) 5882104862Sru@cindex time, current, minutes (@code{minutes}) 5883104862Sru@cindex current time, minutes (@code{minutes}) 5884104862Sru@vindex minutes 5885114402SruThe number of minutes after the hour, in the range@tie{}0 to@tie{}59. 5886104862SruInitialized at start-up of @code{gtroff}. 5887104862Sru 5888104862Sru@item hours 5889104862Sru@cindex hours, current time (@code{hours}) 5890104862Sru@cindex time, current, hours (@code{hours}) 5891104862Sru@cindex current time, hours (@code{hours}) 5892104862Sru@vindex hours 5893114402SruThe number of hours past midnight, in the range@tie{}0 to@tie{}23. 5894104862SruInitialized at start-up of @code{gtroff}. 5895104862Sru 589655839Sasmodai@item dw 5897104862Sru@cindex day of the week register (@code{dw}) 5898104862Sru@cindex date, day of the week register (@code{dw}) 589955839Sasmodai@vindex dw 590055839SasmodaiDay of the week (1-7). 590169626Sru 590255839Sasmodai@item dy 5903104862Sru@cindex day of the month register (@code{dy}) 5904104862Sru@cindex date, day of the month register (@code{dy}) 590555839Sasmodai@vindex dy 590669626SruDay of the month (1-31). 590769626Sru 590855839Sasmodai@item mo 5909104862Sru@cindex month of the year register (@code{mo}) 5910104862Sru@cindex date, month of the year register (@code{mo}) 591155839Sasmodai@vindex mo 591255839SasmodaiCurrent month (1-12). 591369626Sru 591469626Sru@item year 5915104862Sru@cindex date, year register (@code{year}, @code{yr}) 5916104862Sru@cindex year, current, register (@code{year}, @code{yr}) 591769626Sru@vindex year 591869626SruThe current year. 591969626Sru 592055839Sasmodai@item yr 592155839Sasmodai@vindex yr 5922114402SruThe current year minus@tie{}1900. Unfortunately, the documentation of 5923114402Sru@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It 592469626Sruincorrectly claimed that @code{yr} contains the last two digits of the 5925104862Sruyear. That claim has never been true of either @acronym{AT&T} 5926104862Sru@code{troff} or GNU @code{troff}. Old @code{troff} input that looks 5927104862Srulike this: 592869626Sru 592975584Sru@Example 593069626Sru'\" The following line stopped working after 1999 593169626SruThis document was formatted in 19\n(yr. 593275584Sru@endExample 593369626Sru 593469626Sru@noindent 593569626Srucan be corrected as follows: 593669626Sru 593775584Sru@Example 593869626SruThis document was formatted in \n[year]. 593975584Sru@endExample 594069626Sru 594169626Sru@noindent 594269626Sruor, to be portable to older @code{troff} versions, as follows: 594369626Sru 594475584Sru@Example 594569626Sru.nr y4 1900+\n(yr 594669626SruThis document was formatted in \n(y4. 594775584Sru@endExample 594869626Sru 594955839Sasmodai@item .c 595055839Sasmodai@vindex .c 595155839Sasmodai@itemx c. 595255839Sasmodai@vindex c. 5953104862Sru@cindex input line number register (@code{.c}, @code{c.}) 5954104862Sru@cindex line number, input, register (@code{.c}, @code{c.}) 595569626SruThe current @emph{input} line number. Register @samp{.c} is read-only, 595669626Sruwhereas @samp{c.} (a @code{gtroff} extension) is writable also, 595769626Sruaffecting both @samp{.c} and @samp{c.}. 595869626Sru 595955839Sasmodai@item ln 596055839Sasmodai@vindex ln 5961104862Sru@cindex output line number register (@code{ln}) 5962104862Sru@cindex line number, output, register (@code{ln}) 596369626SruThe current @emph{output} line number after a call to the @code{nm} 596469626Srurequest to activate line numbering. 596569626Sru 596675584Sru@xref{Miscellaneous}, for more information about line numbering. 596769626Sru 596855839Sasmodai@item .x 596955839Sasmodai@vindex .x 5970104862Sru@cindex major version number register (@code{.x}) 5971104862Sru@cindex version number, major, register (@code{.x}) 5972114402SruThe major version number. For example, if the version number 5973114402Sruis 1.03 then @code{.x} contains@tie{}@samp{1}. 597469626Sru 597555839Sasmodai@item .y 597655839Sasmodai@vindex .y 5977104862Sru@cindex minor version number register (@code{.y}) 5978104862Sru@cindex version number, minor, register (@code{.y}) 5979114402SruThe minor version number. For example, if the version number 5980114402Sruis 1.03 then @code{.y} contains@tie{}@samp{03}. 598169626Sru 598269626Sru@item .Y 598369626Sru@vindex .Y 5984104862Sru@cindex revision number register (@code{.Y}) 598569626SruThe revision number of @code{groff}. 598669626Sru 5987104862Sru@item $$ 5988104862Sru@vindex $$ 5989104862Sru@cindex process ID of @code{gtroff} register (@code{$$}) 5990104862Sru@cindex @code{gtroff}, process ID register (@code{$$}) 5991104862SruThe process ID of @code{gtroff}. 5992104862Sru 599355839Sasmodai@item .g 599455839Sasmodai@vindex .g 5995104862Sru@cindex @code{gtroff}, identification register (@code{.g}) 5996104862Sru@cindex GNU-specific register (@code{.g}) 5997114402SruAlways@tie{}1. Macros should use this to determine whether they are 599869626Srurunning under GNU @code{troff}. 599969626Sru 600055839Sasmodai@item .A 600155839Sasmodai@vindex .A 6002104862Sru@cindex @acronym{ASCII} approximation output register (@code{.A}) 600369626SruIf the command line option @option{-a} is used to produce an 6004114402Sru@acronym{ASCII} approximation of the output, this is set to@tie{}1, zero 600569626Sruotherwise. @xref{Groff Options}. 600669626Sru 600755839Sasmodai@item .P 600855839Sasmodai@vindex .P 6009114402SruThis register is set to@tie{}1 (and to@tie{}0 otherwise) if the current 601069626Srupage is actually being printed, i.e., if the @option{-o} option is being 601169626Sruused to only print selected pages. @xref{Groff Options}, for more 601269626Sruinformation. 601369626Sru 601469626Sru@item .T 601569626Sru@vindex .T 601669626SruIf @code{gtroff} is called with the @option{-T} command line option, the 6017114402Srunumber register @code{.T} is set to@tie{}1, and zero otherwise. 601869626Sru@xref{Groff Options}. 601969626Sru 602075584Sru@stindex .T 6021104862Sru@cindex output device name string register (@code{.T}) 602275584SruAdditionally, @code{gtroff} predefines a single read-write string 602369626Sruregister @code{.T} which contains the current output device (for 602469626Sruexample, @samp{latin1} or @samp{ps}). 602555839Sasmodai@end table 602655839Sasmodai 602769626Sru 602869626Sru@c ===================================================================== 602969626Sru 603075584Sru@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 603155839Sasmodai@section Manipulating Filling and Adjusting 603255839Sasmodai@cindex manipulating filling and adjusting 603355839Sasmodai@cindex filling and adjusting, manipulating 603455839Sasmodai@cindex adjusting and filling, manipulating 603569626Sru@cindex justifying text 603669626Sru@cindex text, justifying 603755839Sasmodai 603855839Sasmodai@cindex break 603955839Sasmodai@cindex line break 6040104862Sru@cindex @code{bp} request, causing implicit linebreak 6041104862Sru@cindex @code{ce} request, causing implicit linebreak 6042104862Sru@cindex @code{cf} request, causing implicit linebreak 6043104862Sru@cindex @code{fi} request, causing implicit linebreak 6044104862Sru@cindex @code{fl} request, causing implicit linebreak 6045104862Sru@cindex @code{in} request, causing implicit linebreak 6046104862Sru@cindex @code{nf} request, causing implicit linebreak 6047104862Sru@cindex @code{rj} request, causing implicit linebreak 6048104862Sru@cindex @code{sp} request, causing implicit linebreak 6049104862Sru@cindex @code{ti} request, causing implicit linebreak 6050104862Sru@cindex @code{trf} request, causing implicit linebreak 605169626SruVarious ways of causing @dfn{breaks} were given in @ref{Implicit Line 605275584SruBreaks}. The @code{br} request likewise causes a break. Several 605375584Sruother requests also cause breaks, but implicitly. These are 605469626Sru@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 605569626Sru@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 605655839Sasmodai 605775584Sru@Defreq {br, } 605875584SruBreak the current line, i.e., the input collected so far is emitted 605969626Sruwithout adjustment. 606069626Sru 606175584SruIf the no-break control character is used, @code{gtroff} suppresses 606275584Sruthe break: 606369626Sru 606475584Sru@Example 606569626Srua 606669626Sru'br 606769626Srub 606869626Sru @result{} a b 606975584Sru@endExample 607075584Sru@endDefreq 607169626Sru 607275584SruInitially, @code{gtroff} fills and adjusts text to both margins. 607369626SruFilling can be disabled via the @code{nf} request and re-enabled with 607469626Sruthe @code{fi} request. 607569626Sru 6076104862Sru@DefreqList {fi, } 6077104862Sru@DefregListEnd {.u} 6078104862Sru@cindex fill mode (@code{fi}) 6079104862Sru@cindex mode, fill (@code{fi}) 608069626SruActivate fill mode (which is the default). This request implicitly 608175584Sruenables adjusting; it also inserts a break in the text currently being 6082114402Srufilled. The read-only number register @code{.u} is set to@tie{}1. 608355839Sasmodai 608469626SruThe fill mode status is associated with the current environment 608569626Sru(@pxref{Environments}). 6086104862Sru 6087104862SruSee @ref{Line Control}, for interaction with the @code{\c} escape. 608875584Sru@endDefreq 608955839Sasmodai 609075584Sru@Defreq {nf, } 6091104862Sru@cindex no-fill mode (@code{nf}) 6092104862Sru@cindex mode, no-fill (@code{nf}) 609369626SruActivate no-fill mode. Input lines are output as-is, retaining line 609475584Srubreaks and ignoring the current line length. This command implicitly 609575584Srudisables adjusting; it also causes a break. The number register 6096114402Sru@code{.u} is set to@tie{}0. 609769626Sru 609869626SruThe fill mode status is associated with the current environment 609969626Sru(@pxref{Environments}). 6100104862Sru 6101104862SruSee @ref{Line Control}, for interaction with the @code{\c} escape. 610275584Sru@endDefreq 610369626Sru 6104104862Sru@DefreqList {ad, [@Var{mode}]} 6105104862Sru@DefregListEnd {.j} 610669626SruSet adjusting mode. 610769626Sru 610875584SruActivation and deactivation of adjusting is done implicitly with 610975584Srucalls to the @code{fi} or @code{nf} requests. 611069626Sru 611169626Sru@var{mode} can have one of the following values: 611269626Sru 611369626Sru@table @code 611455839Sasmodai@item l 611555839Sasmodai@cindex ragged-right 611655839SasmodaiAdjust text to the left margin. This produces what is traditionally 611755839Sasmodaicalled ragged-right text. 611869626Sru 611955839Sasmodai@item r 612069626Sru@cindex ragged-left 612169626SruAdjust text to the right margin, producing ragged-left text. 612269626Sru 612355839Sasmodai@item c 612469626Sru@cindex centered text 6125114402Sru@cindex @code{ce} request, difference to @samp{.ad@tie{}c} 612669626SruCenter filled text. This is different to the @code{ce} request which 612769626Sruonly centers text without filling. 612869626Sru 612955839Sasmodai@item b 613055839Sasmodai@itemx n 613169626SruJustify to both margins. This is the default used by @code{gtroff}. 613255839Sasmodai@end table 613355839Sasmodai 6134114402SruFinally, @var{mode} can be the numeric argument returned by the @code{.j} 6135114402Sruregister. 6136114402Sru 613775584SruWith no argument, @code{gtroff} adjusts lines in the same way it did 613875584Srubefore adjusting was deactivated (with a call to @code{na}, for 613969626Sruexample). 614055839Sasmodai 614175584Sru@Example 614255839Sasmodaitext 614355839Sasmodai.ad r 6144114402Sru.nr ad \n[.j] 614555839Sasmodaitext 614655839Sasmodai.ad c 614755839Sasmodaitext 614855839Sasmodai.na 614955839Sasmodaitext 6150114402Sru.ad \" back to centering 615155839Sasmodaitext 6152114402Sru.ad \n[ad] \" back to right justifying 615375584Sru@endExample 615455839Sasmodai 6155104862Sru@cindex adjustment mode register (@code{.j}) 615675584SruThe current adjustment mode is available in the read-only number 615775584Sruregister @code{.j}; it can be stored and subsequently used to set 615875584Sruadjustment. 615955839Sasmodai 616069626SruThe adjustment mode status is associated with the current environment 616169626Sru(@pxref{Environments}). 616275584Sru@endDefreq 616355839Sasmodai 616475584Sru@Defreq {na, } 616569626SruDisable adjusting. This request won't change the current adjustment 616675584Srumode: A subsequent call to @code{ad} uses the previous adjustment 616769626Srusetting. 616855839Sasmodai 616969626SruThe adjustment mode status is associated with the current environment 617069626Sru(@pxref{Environments}). 617175584Sru@endDefreq 617269626Sru 6173104862Sru@DefreqList {brp, } 6174104862Sru@DefescListEnd {\\p, , , } 617569626SruAdjust the current line and cause a break. 617669626Sru 6177104862SruIn most cases this produces very ugly results since @code{gtroff} 617869626Srudoesn't have a sophisticated paragraph building algorithm (as @TeX{} 617975584Sruhave, for example); instead, @code{gtroff} fills and adjusts a paragraph 618069626Sruline by line: 618169626Sru 618275584Sru@Example 618369626Sru This is an uninteresting sentence. 618469626Sru This is an uninteresting sentence.\p 618569626Sru This is an uninteresting sentence. 618675584Sru@endExample 618769626Sru 618875584Sru@noindent 618969626Sruis formatted as 619069626Sru 619175584Sru@Example 619269626Sru This is an uninteresting sentence. This is an 619369626Sru uninteresting sentence. 619469626Sru This is an uninteresting sentence. 619575584Sru@endExample 6196104862Sru@endDefreq 619769626Sru 6198104862Sru@DefreqList {ss, word_space_size [@Var{sentence_space_size}]} 6199104862Sru@DefregItem {.ss} 6200104862Sru@DefregListEnd {.sss} 6201104862Sru@cindex word space size register (@code{.ss}) 6202104862Sru@cindex size of word space register (@code{.ss}) 6203104862Sru@cindex space between words register (@code{.ss}) 6204104862Sru@cindex sentence space size register (@code{.sss}) 6205104862Sru@cindex size of sentence space register (@code{.sss}) 6206104862Sru@cindex space between sentences register (@code{.sss}) 6207114402SruChange the size of a space between words. It takes its units as one 6208114402Srutwelfth of the space width parameter for the current font. 6209114402SruInitially both the @var{word_space_size} and @var{sentence_space_size} 6210114402Sruare@tie{}12. In fill mode, the values specify the minimum distance. 621169626Sru 621269626Sru@cindex fill mode 621369626Sru@cindex mode, fill 621475584SruIf two arguments are given to the @code{ss} request, the second 621575584Sruargument sets the sentence space size. If the second argument is not 621675584Srugiven, sentence space size is set to @var{word_space_size}. The 621775584Srusentence space size is used in two circumstances: If the end of a 621875584Srusentence occurs at the end of a line in fill mode, then both an 621975584Sruinter-word space and a sentence space are added; if two spaces follow 622075584Sruthe end of a sentence in the middle of a line, then the second space 622175584Sruis a sentence space. If a second argument is never given to the 622275584Sru@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 622375584Srusame as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 622475584Sruin @acronym{UNIX} @code{troff}, a sentence should always be followed 622575584Sruby either a newline or two spaces. 622669626Sru 622775584SruThe read-only number registers @code{.ss} and @code{.sss} hold the 622875584Sruvalues of the parameters set by the first and second arguments of the 622975584Sru@code{ss} request. 623055839Sasmodai 623169626SruThe word space and sentence space values are associated with the current 623269626Sruenvironment (@pxref{Environments}). 623355839Sasmodai 6234104862SruContrary to @acronym{AT&T} @code{troff}, this request is @emph{not} 6235104862Sruignored if a TTY output device is used; the given values are then 6236114402Srurounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}). 623755839Sasmodai 623875584SruThe request is ignored if there is no parameter. 6239114402Sru 6240114402Sru@cindex discardable horizontal space 6241114402Sru@cindex space, discardable, horizontal 6242114402Sru@cindex horizontal discardable space 6243114402SruAnother useful application of the @code{ss} request is to insert 6244114402Srudiscardable horizontal space, i.e., space which is discarded at a line 6245114402Srubreak. For example, paragraph-style footnotes could be separated this 6246114402Sruway: 6247114402Sru 6248114402Sru@Example 6249114402Sru.ll 4.5i 6250114402Sru1.\ This is the first footnote.\c 6251114402Sru.ss 48 6252114402Sru.nop 6253114402Sru.ss 12 6254114402Sru2.\ This is the second footnote. 6255114402Sru@endExample 6256114402Sru 6257114402Sru@noindent 6258114402SruThe result: 6259114402Sru 6260114402Sru@Example 6261114402Sru1. This is the first footnote. 2. This 6262114402Sruis the second footnote. 6263114402Sru@endExample 6264114402Sru 6265114402Sru@noindent 6266114402SruNote that the @code{\h} escape produces unbreakable space. 626775584Sru@endDefreq 626875584Sru 6269104862Sru@DefreqList {ce, [@Var{nnn}]} 6270104862Sru@DefregListEnd {.ce} 6271104862Sru@cindex centering lines (@code{ce}) 6272104862Sru@cindex lines, centering (@code{ce}) 627375584SruCenter text. While the @w{@samp{.ad c}} request also centers text, 627475584Sruit fills the text as well. @code{ce} does not fill the 6275104862Srutext it affects. This request causes a break. The number of lines 6276104862Srustill to be centered is associated with the current environment 6277104862Sru(@pxref{Environments}). 627855839Sasmodai 627975584SruThe following example demonstrates the differences. 628075584SruHere the input: 628169626Sru 628275584Sru@Example 628375584Sru.ll 4i 628475584Sru.ce 1000 628575584SruThis is a small text fragment which shows the differences 628675584Srubetween the `.ce' and the `.ad c' request. 628775584Sru.ce 0 628875584Sru 628975584Sru.ad c 629075584SruThis is a small text fragment which shows the differences 629175584Srubetween the `.ce' and the `.ad c' request. 629275584Sru@endExample 629375584Sru 629475584Sru@noindent 629575584SruAnd here the result: 629675584Sru 629775584Sru@Example 629875584Sru This is a small text fragment which 629975584Sru shows the differences 630075584Srubetween the `.ce' and the `.ad c' request. 630175584Sru 630275584Sru This is a small text fragment which 630375584Srushows the differences between the `.ce' 630475584Sru and the `.ad c' request. 630575584Sru@endExample 630675584Sru 630775584SruWith no arguments, @code{ce} centers the next line of text. @var{nnn} 630875584Sruspecifies the number of lines to be centered. If the argument is zero 630975584Sruor negative, centering is disabled. 631075584Sru 631169626SruThe basic length for centering text is the line length (as set with the 631269626Sru@code{ll} request) minus the indentation (as set with the @code{in} 631369626Srurequest). Temporary indentation is ignored. 631469626Sru 631575584SruAs can be seen in the previous example, it is a common idiom to turn 631675584Sruon centering for a large number of lines, and to turn off centering 631775584Sruafter text to be centered. This is useful for any request which takes 631875584Srua number of lines as an argument. 631969626Sru 632075584SruThe @code{.ce} read-only number register contains the number of lines 632175584Sruremaining to be centered, as set by the @code{ce} request. 632275584Sru@endDefreq 632355839Sasmodai 6324104862Sru@DefreqList {rj, [@Var{nnn}]} 6325104862Sru@DefregListEnd {.rj} 6326104862Sru@cindex justifying text (@code{rj}) 6327104862Sru@cindex text, justifying (@code{rj}) 6328104862Sru@cindex right-justifying (@code{rj}) 632969626SruJustify unfilled text to the right margin. Arguments are identical to 633075584Sruthe @code{ce} request. The @code{.rj} read-only number register is 633175584Sruthe number of lines to be right-justified as set by the @code{rj} 6332104862Srurequest. This request causes a break. The number of lines still to be 6333104862Sruright-justified is associated with the current environment 6334104862Sru(@pxref{Environments}). 633575584Sru@endDefreq 633655839Sasmodai 633755839Sasmodai 633869626Sru@c ===================================================================== 633955839Sasmodai 634075584Sru@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 634155839Sasmodai@section Manipulating Hyphenation 634255839Sasmodai@cindex manipulating hyphenation 634355839Sasmodai@cindex hyphenation, manipulating 634455839Sasmodai 634575584SruAs discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words. 634669626SruThere are a number of ways to influence hyphenation. 634755839Sasmodai 6348104862Sru@DefreqList {hy, [@Var{mode}]} 6349104862Sru@DefregListEnd {.hy} 635069626SruEnable hyphenation. The request has an optional numeric argument, 635169626Sru@var{mode}, to restrict hyphenation if necessary: 635255839Sasmodai 635369626Sru@table @code 635469626Sru@item 1 635569626SruThe default argument if @var{mode} is omitted. Hyphenate without 635669626Srurestrictions. This is also the start-up value of @code{gtroff}. 635755839Sasmodai 635855839Sasmodai@item 2 635955839SasmodaiDo not hyphenate the last word on a page or column. 636069626Sru 636155839Sasmodai@item 4 636255839SasmodaiDo not hyphenate the last two characters of a word. 636369626Sru 636455839Sasmodai@item 8 636555839SasmodaiDo not hyphenate the first two characters of a word. 636655839Sasmodai@end table 636755839Sasmodai 6368114402SruValues in the previous table are additive. For example, the 6369114402Sruvalue@tie{}12 causes @code{gtroff} to neither hyphenate the last 6370114402Srutwo nor the first two characters of a word. 637169626Sru 6372104862Sru@cindex hyphenation restrictions register (@code{.hy}) 637375584SruThe current hyphenation restrictions can be found in the read-only 637475584Srunumber register @samp{.hy}. 637569626Sru 637669626SruThe hyphenation mode is associated with the current environment 637769626Sru(@pxref{Environments}). 637875584Sru@endDefreq 637969626Sru 638075584Sru@Defreq {nh, } 638175584SruDisable hyphenation (i.e., set the hyphenation mode to zero). Note 638275584Sruthat the hyphenation mode of the last call to @code{hy} is not 638375584Sruremembered. 638469626Sru 638569626SruThe hyphenation mode is associated with the current environment 638669626Sru(@pxref{Environments}). 638775584Sru@endDefreq 638869626Sru 6389104862Sru@DefreqList {hlm, [@Var{nnn}]} 6390104862Sru@DefregItem {.hlm} 6391104862Sru@DefregListEnd {.hlc} 6392104862Sru@cindex explicit hyphen (@code{\%}) 6393104862Sru@cindex hyphen, explicit (@code{\%}) 6394104862Sru@cindex consecutive hyphenated lines (@code{hlm}) 6395104862Sru@cindex lines, consecutive hyphenated (@code{hlm}) 6396104862Sru@cindex hyphenated lines, consecutive (@code{hlm}) 639775584SruSet the maximum number of consecutive hyphenated lines to @var{nnn}. 639875584SruIf this number is negative, there is no maximum. The default value 6399114402Sruis@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated 640075584Sruwith the current environment (@pxref{Environments}). Only lines 640175584Sruoutput from a given environment count towards the maximum associated 640275584Sruwith that environment. Hyphens resulting from @code{\%} are counted; 640375584Sruexplicit hyphens are not. 640455839Sasmodai 640569626SruThe current setting of @code{hlm} is available in the @code{.hlm} 640675584Sruread-only number register. Also the number of immediately preceding 640775584Sruconsecutive hyphenated lines are available in the read-only number 640875584Sruregister @samp{.hlc}. 640975584Sru@endDefreq 641055839Sasmodai 641175584Sru@Defreq {hw, word1 word2 @dots{}} 641269626SruDefine how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 641369626Sruwords must be given with hyphens at the hyphenation points. For 641469626Sruexample: 641569626Sru 641675584Sru@Example 641769626Sru.hw in-sa-lub-rious 641875584Sru@endExample 641969626Sru 642069626Sru@noindent 642169626SruBesides the space character, any character whose hyphenation code value 642269626Sruis zero can be used to separate the arguments of @code{hw} (see the 642369626Srudocumentation for the @code{hcode} request below for more information). 642469626SruIn addition, this request can be used more than once. 642569626Sru 642669626SruHyphenation exceptions specified with the @code{hw} request are 642775584Sruassociated with the current hyphenation language; it causes an error 642869626Sruif there is no current hyphenation language. 642969626Sru 643069626SruThis request is ignored if there is no parameter. 643169626Sru 643269626SruIn old versions of @code{troff} there was a limited amount of space to 643369626Srustore such information; fortunately, with @code{gtroff}, this is no 643469626Srulonger a restriction. 643575584Sru@endDefreq 643669626Sru 6437104862Sru@DefescList {\\%, , , } 6438104862Sru@deffnx Escape @t{\:} 6439104862Sru@ifnotinfo 6440104862Sru@esindex \: 6441104862Sru@end ifnotinfo 6442104862Sru@ifinfo 6443114402Sru@esindex \@r{<colon>} 6444104862Sru@end ifinfo 6445104862Sru@cindex hyphenation character (@code{\%}) 6446104862Sru@cindex character, hyphenation (@code{\%}) 6447104862Sru@cindex disabling hyphenation (@code{\%}) 6448104862Sru@cindex hyphenation, disabling (@code{\%}) 644975584SruTo tell @code{gtroff} how to hyphenate words on the fly, use the 645075584Sru@code{\%} escape, also known as the @dfn{hyphenation character}. 645175584SruPreceding a word with this character prevents it from being 645275584Sruhyphenated; putting it inside a word indicates to @code{gtroff} that 645375584Sruthe word may be hyphenated at that point. Note that this mechanism 645475584Sruonly affects that one occurrence of the word; to change the 645575584Sruhyphenation of a word for the entire document, use the @code{hw} 645675584Srurequest. 6457104862Sru 6458104862SruThe @code{\:} escape inserts a zero-width break point 6459104862Sru(that is, the word breaks but without adding a hyphen). 6460104862Sru 6461104862Sru@Example 6462104862Sru... check the /var/log/\:httpd/\:access_log file ... 6463104862Sru@endExample 6464104862Sru 6465104862Sru@cindex @code{\X}, followed by @code{\%} 6466104862Sru@cindex @code{\Y}, followed by @code{\%} 6467104862Sru@cindex @code{\%}, following @code{\X} or @code{\Y} 6468104862SruNote that @code{\X} and @code{\Y} start a word, that is, the @code{\%} 6469114402Sruescape in (say) @w{@samp{\X'...'\%foobar}} and 6470114402Sru@w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts 6471104862Srua hyphenation point at the beginning of @samp{foobar}; most likely 6472104862Sruthis isn't what you want to do. 647375584Sru@endDefesc 647455839Sasmodai 647575584Sru@Defreq {hc, [@Var{char}]} 647675584SruChange the hyphenation character to @var{char}. This character then 647775584Sruworks the same as the @code{\%} escape, and thus, no longer appears in 647875584Sruthe output. Without an argument, @code{hc} resets the hyphenation 647975584Srucharacter to be @code{\%} (the default) only. 648055839Sasmodai 648169626SruThe hyphenation character is associated with the current environment 648269626Sru(@pxref{Environments}). 648375584Sru@endDefreq 648455839Sasmodai 6485104862Sru@DefreqList {hpf, pattern_file} 6486104862Sru@DefreqItem {hpfa, pattern_file} 6487104862Sru@DefreqListEnd {hpfcode, a b [c d @dots{}]} 6488104862Sru@cindex hyphenation patterns (@code{hpf}) 6489104862Sru@cindex patterns for hyphenation (@code{hpf}) 649075584SruRead in a file of hyphenation patterns. This file is searched for in 649175584Sruthe same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 649275584Srusearched for if the @option{-m@var{name}} option is specified. 649355839Sasmodai 6494104862SruIt should have the same format as (simple) @TeX{} patterns files. 6495104862SruMore specifically, the following scanning rules are implemented. 649669626Sru 6497104862Sru@itemize @bullet 6498104862Sru@item 6499104862SruA percent sign starts a comment (up to the end of the line) 6500104862Srueven if preceded by a backslash. 6501104862Sru 6502104862Sru@item 6503104862SruNo support for `digraphs' like @code{\$}. 6504104862Sru 6505104862Sru@item 6506104862Sru@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character 6507104862Srucode of @var{x} in the range 0-127) are recognized; other use of @code{^} 6508104862Srucauses an error. 6509104862Sru 6510104862Sru@item 6511104862SruNo macro expansion. 6512104862Sru 6513104862Sru@item 6514104862Sru@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} 6515104862Sru(possibly with whitespace before and after the braces). 6516104862SruEverything between the braces is taken as hyphenation patterns. 6517104862SruConsequently, @code{@{} and @code{@}} are not allowed in patterns. 6518104862Sru 6519104862Sru@item 6520104862SruSimilarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation 6521104862Sruexceptions. 6522104862Sru 6523104862Sru@item 6524104862Sru@code{\endinput} is recognized also. 6525104862Sru 6526104862Sru@item 6527104862SruFor backwards compatibility, if @code{\patterns} is missing, 6528104862Sruthe whole file is treated as a list of hyphenation patterns 6529104862Sru(only recognizing the @code{%} character as the start of a comment). 6530104862Sru@end itemize 6531104862Sru 653269626SruIf no @code{hpf} request is specified (either in the document or in a 653369626Srumacro package), @code{gtroff} won't hyphenate at all. 653469626Sru 6535104862SruThe @code{hpfa} request appends a file of patterns to the current list. 6536104862Sru 6537104862SruThe @code{hpfcode} request defines mapping values for character codes in 6538104862Sruhyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping 6539104862Sru(after reading the patterns) before replacing or appending them to 6540104862Sruthe current list of patterns. Its arguments are pairs of character codes 6541114402Sru-- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a} 6542114402Sruto code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You 6543104862Srucan use character codes which would be invalid otherwise. 6544104862Sru 654555839Sasmodai@pindex troffrc 654669626Sru@pindex troffrc-end 654769626Sru@pindex hyphen.us 6548114402Sru@pindex hyphenex.us 654969626SruThe set of hyphenation patterns is associated with the current language 655069626Sruset by the @code{hla} request. The @code{hpf} request is usually 655169626Sruinvoked by the @file{troffrc} or @file{troffrc-end} file; by default, 6552114402Sru@file{troffrc} loads hyphenation patterns and exceptions for American 6553114402SruEnglish (in files @file{hyphen.us} and @file{hyphenex.us}). 655455839Sasmodai 6555104862SruA second call to @code{hpf} (for the same language) will replace the 6556104862Sruhyphenation patterns with the new ones. 6557104862Sru 655875584SruInvoking @code{hpf} causes an error if there is no current hyphenation 655969626Srulanguage. 656075584Sru@endDefreq 656155839Sasmodai 656275584Sru@Defreq {hcode, c1 code1 c2 code2 @dots{}} 6563104862Sru@cindex hyphenation code (@code{hcode}) 6564104862Sru@cindex code, hyphenation (@code{hcode}) 656575584SruSet the hyphenation code of character @var{c1} to @var{code1}, that of 656675584Sru@var{c2} to @var{code2}, etc. A hyphenation code must be a single 656775584Sruinput character (not a special character) other than a digit or a 656875584Sruspace. Initially each lower-case letter (@samp{a}-@samp{z}) has its 6569104862Sruhyphenation code set to itself, and each upper-case letter 657075584Sru(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case 657175584Sruversion of itself. 657269626Sru 657375584SruThis request is ignored if it has no parameter. 657475584Sru@endDefreq 657569626Sru 6576104862Sru@DefreqList {hym, [@Var{length}]} 6577104862Sru@DefregListEnd {.hym} 6578104862Sru@cindex hyphenation margin (@code{hym}) 6579104862Sru@cindex margin for hyphenation (@code{hym}) 6580104862Sru@cindex @code{ad} request, and hyphenation margin 658169626SruSet the (right) hyphenation margin to @var{length}. If the current 6582104862Sruadjustment mode is not @samp{b} or @samp{n}, the line is not 658375584Sruhyphenated if it is shorter than @var{length}. Without an argument, 6584114402Sruthe hyphenation margin is reset to its default value, which is@tie{}0. 6585104862SruThe default scaling indicator for this request is @samp{m}. The 658675584Sruhyphenation margin is associated with the current environment 658769626Sru(@pxref{Environments}). 658869626Sru 658975584SruA negative argument resets the hyphenation margin to zero, emitting 659069626Srua warning of type @samp{range}. 659169626Sru 6592104862Sru@cindex hyphenation margin register (@code{.hym}) 659375584SruThe current hyphenation margin is available in the @code{.hym} read-only 659475584Srunumber register. 659575584Sru@endDefreq 659655839Sasmodai 6597104862Sru@DefreqList {hys, [@Var{hyphenation_space}]} 6598104862Sru@DefregListEnd {.hys} 6599104862Sru@cindex hyphenation space (@code{hys}) 6600104862Sru@cindex @code{ad} request, and hyphenation space 660169626SruSet the hyphenation space to @var{hyphenation_space}. If the current 6602104862Sruadjustment mode is @samp{b} or @samp{n}, don't hyphenate the line 660375584Sruif it can be justified by adding no more than @var{hyphenation_space} 660475584Sruextra space to each word space. Without argument, the hyphenation 6605114402Sruspace is set to its default value, which is@tie{}0. The default 6606104862Sruscaling indicator for this request is @samp{m}. The hyphenation 660775584Sruspace is associated with the current environment 660875584Sru(@pxref{Environments}). 660969626Sru 661075584SruA negative argument resets the hyphenation space to zero, emitting a 661169626Sruwarning of type @samp{range}. 661269626Sru 6613104862Sru@cindex hyphenation space register (@code{.hys}) 661475584SruThe current hyphenation space is available in the @code{.hys} read-only 661575584Srunumber register. 661675584Sru@endDefreq 661755839Sasmodai 6618104862Sru@Defreq {shc, [@Var{glyph}]} 6619104862Sru@cindex soft hyphen character, setting (@code{shc}) 6620104862Sru@cindex character, soft hyphen, setting (@code{shc}) 6621104862Sru@cindex glyph, soft hyphen (@code{hy}) 6622104862Sru@cindex soft hyphen glyph (@code{hy}) 6623104862Sru@cindex @code{char} request, and soft hyphen character 6624104862Sru@cindex @code{tr} request, and soft hyphen character 6625104862SruSet the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft 6626104862Sruhyphen character} is a misnomer since it is an output glyph.} If the 6627104862Sruargument is omitted, the soft hyphen character is set to the default 6628104862Sruglyph @code{\(hy} (this is the start-up value of @code{gtroff} also). 6629104862SruThe soft hyphen character is the glyph that is inserted when a word is 663075584Sruhyphenated at a line break. If the soft hyphen character does not 663175584Sruexist in the font of the character immediately preceding a potential 663275584Srubreak point, then the line is not broken at that point. Neither 663355839Sasmodaidefinitions (specified with the @code{char} request) nor translations 663469626Sru(specified with the @code{tr} request) are considered when finding the 663569626Srusoft hyphen character. 663675584Sru@endDefreq 663755839Sasmodai 6638104862Sru@DefreqList {hla, language} 6639104862Sru@DefregListEnd {.hla} 6640104862Sru@cindex @code{hpf} request, and hyphenation language 6641104862Sru@cindex @code{hw} request, and hyphenation language 664255839Sasmodai@pindex troffrc 664369626Sru@pindex troffrc-end 664469626SruSet the current hyphenation language to the string @var{language}. 664569626SruHyphenation exceptions specified with the @code{hw} request and 6646104862Sruhyphenation patterns specified with the @code{hpf} and @code{hpfa} 6647104862Srurequests are both associated with the current hyphenation language. 6648104862SruThe @code{hla} request is usually invoked by the @file{troffrc} or the 664969626Sru@file{troffrc-end} files; @file{troffrc} sets the default language to 665069626Sru@samp{us}. 665155839Sasmodai 6652104862Sru@cindex hyphenation language register (@code{.hla}) 665369626SruThe current hyphenation language is available as a string in the 665469626Sruread-only number register @samp{.hla}. 665555839Sasmodai 665675584Sru@Example 665769626Sru.ds curr_language \n[.hla] 665869626Sru\*[curr_language] 665969626Sru @result{} us 666075584Sru@endExample 666175584Sru@endDefreq 666255839Sasmodai 666369626Sru 666469626Sru@c ===================================================================== 666569626Sru 666675584Sru@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 666755839Sasmodai@section Manipulating Spacing 666855839Sasmodai@cindex manipulating spacing 666955839Sasmodai@cindex spacing, manipulating 667055839Sasmodai 667175584Sru@Defreq {sp, [@Var{distance}]} 6672114402SruSpace downwards @var{distance}. With no argument it advances 6673114402Sru1@tie{}line. A negative argument causes @code{gtroff} to move up the page 667469626Sruthe specified distance. If the argument is preceded by a @samp{|} 667575584Sruthen @code{gtroff} moves that distance from the top of the page. This 6676104862Srurequest causes a line break. The default scaling indicator is @samp{v}. 6677114402Sru 6678114402SruIf a vertical trap is sprung during execution of @code{sp}, the amount of 6679114402Sruvertical space after the trap is discarded. For example, this 6680114402Sru 6681114402Sru@Example 6682114402Sru.de xxx 6683114402Sru.. 6684114402Sru. 6685114402Sru.wh 0 xxx 6686114402Sru. 6687114402Sru.pl 5v 6688114402Srufoo 6689114402Sru.sp 2 6690114402Srubar 6691114402Sru.sp 50 6692114402Srubaz 6693114402Sru@endExample 6694114402Sru 6695114402Sru@noindent 6696114402Sruresults in 6697114402Sru 6698114402Sru@Example 6699114402Srufoo 6700114402Sru 6701114402Sru 6702114402Srubar 6703114402Sru 6704114402Srubaz 6705114402Sru@endExample 6706114402Sru 6707114402Sru@cindex @code{sp} request, and traps 6708114402Sru@cindex discarded space in traps 6709114402Sru@cindex space, discarded, in traps 6710114402Sru@cindex traps, and discarded space 6711114402SruThe amount of discarded space is available in the number register 6712114402Sru@code{.trunc}. 6713114402Sru 6714114402SruTo protect @code{sp} against vertical traps, use the @code{vpt} request: 6715114402Sru 6716114402Sru@Example 6717114402Sru.vpt 0 6718114402Sru.sp -3 6719114402Sru.vpt 1 6720114402Sru@endExample 672175584Sru@endDefreq 672255839Sasmodai 6723104862Sru@DefreqList {ls, [@Var{nnn}]} 6724104862Sru@DefregListEnd {.L} 6725104862Sru@cindex double-spacing (@code{ls}) 672675584SruOutput @w{@var{nnn}@minus{}1} blank lines after each line of text. 672775584SruWith no argument, @code{gtroff} uses the previous value before the 672875584Srulast @code{ls} call. 672955839Sasmodai 673075584Sru@Example 673169626Sru.ls 2 \" This causes double-spaced output 673269626Sru.ls 3 \" This causes triple-spaced output 6733104862Sru.ls \" Again double-spaced 673475584Sru@endExample 673569626Sru 673669626SruThe line spacing is associated with the current environment 673769626Sru(@pxref{Environments}). 673869626Sru 6739104862Sru@cindex line spacing register (@code{.L}) 674075584SruThe read-only number register @code{.L} contains the current line 674175584Sruspacing setting. 674275584Sru@endDefreq 674355839Sasmodai 6744104862Sru@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} 6745104862Sruas alternatives to @code{ls}. 674675584Sru 6747104862Sru@DefescList {\\x, ', spacing, '} 6748104862Sru@DefregListEnd {.a} 674975584SruSometimes, extra vertical spacing is only needed occasionally, e.g.@: 675075584Sruto allow space for a tall construct (like an equation). The @code{\x} 675175584Sruescape does this. The escape is given a numerical argument, usually 675269626Sruenclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 6753104862Sruis @samp{v}. If this number is positive extra vertical space is 675475584Sruinserted below the current line. A negative number adds space above. 675575584SruIf this escape is used multiple times on the same line, the maximum of 675675584Sruthe values is used. 675769626Sru 675869626Sru@xref{Escapes}, for details on parameter delimiting characters. 675969626Sru 6760104862Sru@cindex extra post-vertical line space register (@code{.a}) 676175584SruThe @code{.a} read-only number register contains the most recent 676275584Sru(nonnegative) extra vertical line space. 676355839Sasmodai 6764104862SruUsing @code{\x} can be necessary in combination with the @code{\b} 6765104862Sruescape, as the following example shows. 6766104862Sru 676775584Sru@Example 6768104862SruThis is a test with the \[rs]b escape. 6769104862Sru.br 6770104862SruThis is a test with the \[rs]b escape. 6771104862Sru.br 6772104862SruThis is a test with \b'xyz'\x'-1m'\x'1m'. 6773104862Sru.br 6774104862SruThis is a test with the \[rs]b escape. 6775104862Sru.br 6776104862SruThis is a test with the \[rs]b escape. 677775584Sru@endExample 6778104862Sru 6779104862Sru@noindent 6780104862Sruproduces 6781104862Sru 6782104862Sru@Example 6783104862SruThis is a test with the \b escape. 6784104862SruThis is a test with the \b escape. 6785104862Sru x 6786104862SruThis is a test with y. 6787104862Sru z 6788104862SruThis is a test with the \b escape. 6789104862SruThis is a test with the \b escape. 6790104862Sru@endExample 679175584Sru@endDefesc 679255839Sasmodai 6793104862Sru@DefreqList {ns, } 6794104862Sru@DefreqItem {rs, } 6795104862Sru@DefregListEnd {.ns} 6796104862Sru@cindex @code{sp} request, and no-space mode 6797104862Sru@cindex no-space mode (@code{ns}) 6798104862Sru@cindex mode, no-space (@code{ns}) 679969626Sru@cindex blank lines, disabling 680069626Sru@cindex lines, blank, disabling 680175584SruEnable @dfn{no-space mode}. In this mode, spacing (either via 680275584Sru@code{sp} or via blank lines) is disabled. The @code{bp} request to 680375584Sruadvance to the next page is also disabled, except if it is accompanied 680475584Sruby a page number (see @ref{Page Control}, for more information). This 680575584Srumode ends when actual text is output or the @code{rs} request is 6806104862Sruencountered which ends no-space mode. The read-only number register 6807114402Sru@code{.ns} is set to@tie{}1 as long as no-space mode is active. 680855839Sasmodai 6809104862SruThis request is useful for macros that conditionally 6810104862Sruinsert vertical space before the text starts 6811104862Sru(for example, a paragraph macro could insert some space 6812104862Sruexcept when it is the first paragraph after a section header). 681375584Sru@endDefreq 681469626Sru 681569626Sru 681669626Sru@c ===================================================================== 681769626Sru 681875584Sru@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 681955839Sasmodai@section Tabs and Fields 6820104862Sru@cindex tabs, and fields 6821104862Sru@cindex fields, and tabs 682255839Sasmodai 682369626Sru@cindex @acronym{EBCDIC} encoding of a tab 6824114402SruA tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC} 6825114402Sruchar@tie{}5) causes a horizontal movement to the next tab stop (much 682669626Srulike it did on a typewriter). 682755839Sasmodai 682875584Sru@Defesc {\\t, , , } 6829104862Sru@cindex tab character, non-interpreted (@code{\t}) 6830104862Sru@cindex character, tab, non-interpreted (@code{\t}) 683169626SruThis escape is a non-interpreted tab character. In copy mode 683269626Sru(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 683375584Sru@endDefesc 683455839Sasmodai 6835104862Sru@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 6836104862Sru@DefregListEnd {.tabs} 683769626SruChange tab stop positions. This request takes a series of tab 683869626Sruspecifiers as arguments (optionally divided into two groups with the 683975584Sruletter @samp{T}) which indicate where each tab stop is to be 684075584Sru(overriding any previous settings). 684155839Sasmodai 684269626SruTab stops can be specified absolutely, i.e., as the distance from the 6843114402Sruleft margin. For example, the following sets 6@tie{}tab stops every 684469626Sruone inch. 684569626Sru 684675584Sru@Example 684755839Sasmodai.ta 1i 2i 3i 4i 5i 6i 684875584Sru@endExample 684955839Sasmodai 685075584SruTab stops can also be specified using a leading @samp{+} 685175584Sruwhich means that the specified tab stop is set relative to 685269626Sruthe previous tab stop. For example, the following is equivalent to the 685369626Sruprevious example. 685455839Sasmodai 685575584Sru@Example 685655839Sasmodai.ta 1i +1i +1i +1i +1i +1i 685775584Sru@endExample 685855839Sasmodai 685969626Sru@code{gtroff} supports an extended syntax to specify repeat values after 686069626Sruthe @samp{T} mark (these values are always taken as relative) -- this is 686169626Sruthe usual way to specify tabs set at equal intervals. The following is, 686269626Sruyet again, the same as the previous examples. It does even more since 686369626Sruit defines an infinite number of tab stops separated by one inch. 686455839Sasmodai 686575584Sru@Example 686655839Sasmodai.ta T 1i 686775584Sru@endExample 686855839Sasmodai 686969626SruNow we are ready to interpret the full syntax given at the beginning: 687069626SruSet tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 687169626Srutabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 687269626Sruand then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 687369626Sru@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 687455839Sasmodai 687569626SruExample: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 687669626Sru20c 23c 28c 30c @dots{}}. 687769626Sru 687869626SruThe material in each tab column (i.e., the column between two tab stops) 687969626Srumay be justified to the right or left or centered in the column. This 688069626Sruis specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 688169626Sruspecifier. The default justification is @samp{L}. Example: 688269626Sru 688375584Sru@Example 6884104862Sru.ta 1i 2iC 3iR 688575584Sru@endExample 688655839Sasmodai 688769626SruSome notes: 688869626Sru 688969626Sru@itemize @bullet 689069626Sru@item 689169626SruThe default unit of the @code{ta} request is @samp{m}. 689269626Sru 689369626Sru@item 689469626SruA tab stop is converted into a non-breakable horizontal movement which 689569626Srucan be neither stretched nor squeezed. For example, 689669626Sru 689775584Sru@Example 689869626Sru.ds foo a\tb\tc 689969626Sru.ta T 5i 690069626Sru\*[foo] 690175584Sru@endExample 690269626Sru 690369626Sru@noindent 6904114402Srucreates a single line which is a bit longer than 10@tie{}inches (a string 690569626Sruis used to show exactly where the tab characters are). Now consider the 690669626Srufollowing: 690769626Sru 690875584Sru@Example 690969626Sru.ds bar a\tb b\tc 691069626Sru.ta T 5i 691169626Sru\*[bar] 691275584Sru@endExample 691369626Sru 691469626Sru@noindent 691569626Sru@code{gtroff} first converts the tab stops of the line into unbreakable 691669626Sruhorizontal movements, then splits the line after the second @samp{b} 691769626Sru(assuming a sufficiently short line length). Usually, this isn't what 691869626Sruthe user wants. 691969626Sru 692069626Sru@item 692169626SruSuperfluous tabs (i.e., tab characters which do not correspond to a tab 692269626Srustop) are ignored except the first one which delimits the characters 692375584Srubelonging to the last tab stop for right-justifying or centering. 692469626SruConsider the following example 692569626Sru 692675584Sru@Example 692769626Sru.ds Z foo\tbar\tfoo 692869626Sru.ds ZZ foo\tbar\tfoobar 692969626Sru.ds ZZZ foo\tbar\tfoo\tbar 693069626Sru.ta 2i 4iR 693169626Sru\*[Z] 693269626Sru.br 693369626Sru\*[ZZ] 693469626Sru.br 693569626Sru\*[ZZZ] 693669626Sru.br 693775584Sru@endExample 693869626Sru 693969626Sru@noindent 694069626Sruwhich produces the following output: 694169626Sru 694275584Sru@Example 694369626Srufoo bar foo 694469626Srufoo bar foobar 694569626Srufoo bar foobar 694675584Sru@endExample 694769626Sru 694869626Sru@noindent 694969626SruThe first line right-justifies the second `foo' relative to the tab 695069626Srustop. The second line right-justifies `foobar'. The third line finally 695169626Sruright-justifies only `foo' because of the additional tab character which 695269626Srumarks the end of the string belonging to the last defined tab stop. 695369626Sru 695469626Sru@item 695569626SruTab stops are associated with the current environment 695669626Sru(@pxref{Environments}). 695769626Sru 695869626Sru@item 695975584SruCalling @code{ta} without an argument removes all tab stops. 696069626Sru 696169626Sru@item 6962104862Sru@cindex tab stops, for TTY output devices 6963114402SruThe start-up value of @code{gtroff} is @w{@samp{T 0.8i}}. 696469626Sru@end itemize 696569626Sru 6966104862Sru@cindex tab settings register (@code{.tabs}) 696775584SruThe read-only number register @code{.tabs} contains a string 696875584Srurepresentation of the current tab settings suitable for use as an 696975584Sruargument to the @code{ta} request. 697055839Sasmodai 697175584Sru@Example 697269626Sru.ds tab-string \n[.tabs] 697369626Sru\*[tab-string] 697469626Sru @result{} T120u 697575584Sru@endExample 6976104862Sru 6977114402Sru@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs} 6978114402Sru@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S}) 6979114402SruThe @code{troff} version of the Plan@tie{}9 operating system uses 6980104862Sruregister @code{.S} for the same purpose. 698175584Sru@endDefreq 698255839Sasmodai 6983104862Sru@Defreq {tc, [@Var{fill-glyph}]} 6984104862Sru@cindex tab repetition character (@code{tc}) 6985104862Sru@cindex character, tab repetition (@code{tc}) 6986104862Sru@cindex glyph, tab repetition (@code{tc}) 698775584SruNormally @code{gtroff} fills the space to the next tab stop with 698875584Sruwhitespace. This can be changed with the @code{tc} request. With no 698975584Sruargument @code{gtroff} reverts to using whitespace, which is the 6990104862Srudefault. The value of this @dfn{tab repetition character} is 6991104862Sruassociated with the current environment 6992104862Sru(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a 6993104862Srumisnomer since it is an output glyph.} 699475584Sru@endDefreq 699569626Sru 6996104862Sru@DefreqList {linetabs, n} 6997104862Sru@DefregListEnd {.linetabs} 6998104862Sru@cindex tab, line-tabs mode 6999104862Sru@cindex line-tabs mode 7000104862Sru@cindex mode, line-tabs 7001104862SruIf @var{n} is missing or not zero, enable @dfn{line-tabs} mode, 7002104862Sruor disable it otherwise (the default). 7003104862SruIn line-tabs mode, @code{gtroff} computes tab distances 7004104862Srurelative to the (current) output line instead of the input line. 7005104862Sru 7006104862SruFor example, the following code: 7007104862Sru 7008104862Sru@Example 7009104862Sru.ds x a\t\c 7010104862Sru.ds y b\t\c 7011104862Sru.ds z c 7012104862Sru.ta 1i 3i 7013104862Sru\*x 7014104862Sru\*y 7015104862Sru\*z 7016104862Sru@endExample 7017104862Sru 7018104862Sru@noindent 7019104862Sruin normal mode, results in the output 7020104862Sru 7021104862Sru@Example 7022104862Srua b c 7023104862Sru@endExample 7024104862Sru 7025104862Sru@noindent 7026104862Sruin line-tabs mode, the same code outputs 7027104862Sru 7028104862Sru@Example 7029104862Srua b c 7030104862Sru@endExample 7031104862Sru 7032104862SruLine-tabs mode is associated with the current environment. 7033114402SruThe read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs 7034104862Srumode, and 0 in normal mode. 7035104862Sru@endDefreq 7036104862Sru 703769626Sru@menu 703875584Sru* Leaders:: 703975584Sru* Fields:: 704069626Sru@end menu 704169626Sru 704269626Sru@c --------------------------------------------------------------------- 704369626Sru 704469626Sru@node Leaders, Fields, Tabs and Fields, Tabs and Fields 704555839Sasmodai@subsection Leaders 704655839Sasmodai@cindex leaders 704755839Sasmodai 704869626SruSometimes it may may be desirable to use the @code{tc} request to fill a 7049104862Sruparticular tab stop with a given glyph (for example dots in a table 705069626Sruof contents), but also normal tab stops on the rest of the line. For 705169626Sruthis @code{gtroff} provides an alternate tab mechanism, called 705275584Sru@dfn{leaders} which does just that. 705355839Sasmodai 705469626Sru@cindex leader character 7055114402SruA leader character (character code@tie{}1) behaves similarly to a tab 705669626Srucharacter: It moves to the next tab stop. The only difference is that 7057104862Srufor this movement, the fill glyph defaults to a period character and 705869626Srunot to space. 705955839Sasmodai 706075584Sru@Defesc {\\a, , , } 7061104862Sru@cindex leader character, non-interpreted (@code{\a}) 7062104862Sru@cindex character, leader, non-interpreted (@code{\a}) 706369626SruThis escape is a non-interpreted leader character. In copy mode 706469626Sru(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 706569626Srucharacter. 706675584Sru@endDefesc 706755839Sasmodai 7068104862Sru@Defreq {lc, [@Var{fill-glyph}]} 7069104862Sru@cindex leader repetition character (@code{lc}) 7070104862Sru@cindex character, leader repetition (@code{lc}) 7071104862Sru@cindex glyph, leader repetition (@code{lc}) 7072104862SruDeclare the @dfn{leader repetition character}.@footnote{@dfn{Leader 7073104862Srurepetition character} is a misnomer since it is an output glyph.} 7074104862SruWithout an argument, leaders act the same as tabs (i.e., using 7075104862Sruwhitespace for filling). @code{gtroff}'s start-up value is a dot 7076104862Sru(@samp{.}). The value of the leader repetition character is 7077104862Sruassociated with the current environment (@pxref{Environments}). 707875584Sru@endDefreq 707969626Sru 708055839Sasmodai@cindex table of contents 708155839Sasmodai@cindex contents, table of 708269626SruFor a table of contents, to name an example, tab stops may be defined so 708355839Sasmodaithat the section number is one tab stop, the title is the second with 708469626Sruthe remaining space being filled with a line of dots, and then the page 708569626Srunumber slightly separated from the dots. 708655839Sasmodai 708775584Sru@Example 708869626Sru.ds entry 1.1\tFoo\a\t12 708955839Sasmodai.lc . 709069626Sru.ta 1i 5i +.25i 709169626Sru\*[entry] 709275584Sru@endExample 709355839Sasmodai 709469626Sru@noindent 709569626SruThis produces 709669626Sru 709775584Sru@Example 709869626Sru1.1 Foo.......................................... 12 709975584Sru@endExample 710069626Sru 710169626Sru@c --------------------------------------------------------------------- 710269626Sru 710369626Sru@node Fields, , Leaders, Tabs and Fields 710455839Sasmodai@subsection Fields 710555839Sasmodai@cindex fields 710655839Sasmodai 7107104862Sru@cindex field delimiting character (@code{fc}) 7108104862Sru@cindex delimiting character, for fields (@code{fc}) 7109104862Sru@cindex character, field delimiting (@code{fc}) 7110104862Sru@cindex field padding character (@code{fc}) 7111104862Sru@cindex padding character, for fields (@code{fc}) 7112104862Sru@cindex character, field padding (@code{fc}) 711369626Sru@dfn{Fields} are a more general way of laying out tabular data. A field 711469626Sruis defined as the data between a pair of @dfn{delimiting characters}. 711569626SruIt contains substrings which are separated by @dfn{padding characters}. 711669626SruThe width of a field is the distance on the @emph{input} line from the 711769626Sruposition where the field starts to the next tab stop. A padding 711869626Srucharacter inserts stretchable space similar to @TeX{}'s @code{\hss} 711969626Srucommand (thus it can even be negative) to make the sum of all substring 712069626Srulengths plus the stretchable space equal to the field width. If more 712169626Sruthan one padding character is inserted, the available space is evenly 712269626Srudistributed among them. 712355839Sasmodai 712475584Sru@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 712569626SruDefine a delimiting and a padding character for fields. If the latter 712669626Sruis missing, the padding character defaults to a space character. If 712769626Sruthere is no argument at all, the field mechanism is disabled (which is 712875584Sruthe default). Note that contrary to e.g.@: the tab repetition 7129104862Srucharacter, delimiting and padding characters are @emph{not} associated 7130104862Sruto the current environment (@pxref{Environments}). 713169626Sru 713269626SruExample: 713369626Sru 713475584Sru@Example 713569626Sru.fc # ^ 713669626Sru.ta T 3i 713769626Sru#foo^bar^smurf# 713869626Sru.br 713969626Sru#foo^^bar^smurf# 714075584Sru@endExample 714169626Sru 714269626Sru@noindent 714369626Sruand here the result: 714469626Sru 714575584Sru@Example 714669626Srufoo bar smurf 714769626Srufoo bar smurf 714875584Sru@endExample 714975584Sru@endDefreq 715069626Sru 715169626Sru 715269626Sru@c ===================================================================== 715369626Sru 715475584Sru@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 715555839Sasmodai@section Character Translations 715655839Sasmodai@cindex character translations 715755839Sasmodai@cindex translations of characters 715855839Sasmodai 7159104862Sru@cindex control character, changing (@code{cc}) 7160104862Sru@cindex character, control, changing (@code{cc}) 7161104862Sru@cindex no-break control character, changing (@code{c2}) 7162104862Sru@cindex character, no-break control, changing (@code{c2}) 7163104862Sru@cindex control character, no-break, changing (@code{c2}) 716455839SasmodaiThe control character (@samp{.}) and the no-break control character 716555839Sasmodai(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 716655839Sasmodairespectively. 716755839Sasmodai 716875584Sru@Defreq {cc, [@Var{c}]} 7169114402SruSet the control character to@tie{}@var{c}. With no argument the default 717069626Srucontrol character @samp{.} is restored. The value of the control 717169626Srucharacter is associated with the current environment 717269626Sru(@pxref{Environments}). 717375584Sru@endDefreq 717455839Sasmodai 717575584Sru@Defreq {c2, [@Var{c}]} 7176114402SruSet the no-break control character to@tie{}@var{c}. With no argument the 717769626Srudefault control character @samp{'} is restored. The value of the 717869626Sruno-break control character is associated with the current environment 717969626Sru(@pxref{Environments}). 718075584Sru@endDefreq 718155839Sasmodai 718275584Sru@Defreq {eo, } 7183104862Sru@cindex disabling @code{\} (@code{eo}) 7184104862Sru@cindex @code{\}, disabling (@code{eo}) 718575584SruDisable the escape mechanism completely. After executing this 718675584Srurequest, the backslash character @samp{\} no longer starts an escape 718775584Srusequence. 718869626Sru 718969626SruThis request can be very helpful in writing macros since it is not 719069626Srunecessary then to double the escape character. Here an example: 719169626Sru 719275584Sru@Example 719369626Sru.\" This is a simplified version of the 719469626Sru.\" .BR request from the man macro package 719569626Sru.eo 719669626Sru.de BR 719769626Sru. ds result \& 719869626Sru. while (\n[.$] >= 2) \@{\ 719969626Sru. as result \fB\$1\fR\$2 720069626Sru. shift 2 720169626Sru. \@} 720269626Sru. if \n[.$] .as result \fB\$1 720369626Sru\*[result] 720469626Sru. ft R 720569626Sru.. 720669626Sru.ec 720775584Sru@endExample 720875584Sru@endDefreq 720969626Sru 721075584Sru@Defreq {ec, [@Var{c}]} 7211104862Sru@cindex escape character, changing (@code{ec}) 7212104862Sru@cindex character, escape, changing (@code{ec}) 7213114402SruSet the escape character to@tie{}@var{c}. With no argument the default 721475584Sruescape character @samp{\} is restored. It can be also used to 721575584Srure-enable the escape mechanism after an @code{eo} request. 721669626Sru 721775584SruNote that changing the escape character globally will likely break 7218104862Srumacro packages since @code{gtroff} has no mechanism to `intern' macros, 7219104862Srui.e., to convert a macro definition into an internal form which is 7220104862Sruindependent of its representation (@TeX{} has this mechanism). 7221104862SruIf a macro is called, it is executed literally. 722275584Sru@endDefreq 722369626Sru 7224104862Sru@DefreqList {ecs, } 7225104862Sru@DefreqListEnd {ecr, } 7226104862SruThe @code{ecs} request saves the current escape character 7227104862Sruin an internal register. 7228104862SruUse this request in combination with the @code{ec} request to 7229104862Srutemporarily change the escape character. 7230104862Sru 7231104862SruThe @code{ecr} request restores the escape character 7232104862Srusaved with @code{ecs}. 7233104862SruWithout a previous call to @code{ecs}, this request 7234104862Srusets the escape character to @code{\}. 7235104862Sru@endDefreq 7236104862Sru 7237104862Sru@DefescList {\\\\, , , } 7238104862Sru@DefescItem {\\e, , , } 7239104862Sru@DefescListEnd {\\E, , , } 7240104862SruPrint the current escape character (which is the backslash character 7241104862Sru@samp{\} by default). 7242104862Sru 7243104862Sru@code{\\} is a `delayed' backslash; more precisely, it is the default 7244104862Sruescape character followed by a backslash, which no longer has special 7245104862Srumeaning due to the leading escape character. It is @emph{not} an escape 7246104862Srusequence in the usual sense! In any unknown escape sequence 7247104862Sru@code{\@var{X}} the escape character is ignored and @var{X} is printed. 7248104862SruBut if @var{X} is equal to the current escape character, no warning is 7249104862Sruemitted. 7250104862Sru 7251104862SruAs a consequence, only at top-level or in a diversion a backslash glyph is 7252104862Sruprinted; in copy-in mode, it expands to a single backslash which then 7253104862Srucombines with the following character to an escape sequence. 7254104862Sru 7255104862SruThe @code{\E} escape differs from @code{\e} by printing an escape 7256104862Srucharacter that is not interpreted in copy mode. 7257104862SruUse this to define strings with escapes that work 7258104862Sruwhen used in copy mode (for example, as a macro argument). 7259104862SruThe following example defines strings to begin and end 7260104862Srua superscript: 7261104862Sru 7262104862Sru@Example 7263114402Sru.ds @{ \v'-.3m'\s'\En[.s]*60/100' 7264104862Sru.ds @} \s0\v'.3m' 7265104862Sru@endExample 7266104862Sru 7267104862SruAnother example to demonstrate the differences between the various escape 7268104862Srusequences, using a strange escape character, @samp{-}. 7269104862Sru 7270104862Sru@Example 7271104862Sru.ec - 7272104862Sru.de xxx 7273104862Sru--A'123' 7274104862Sru.. 7275104862Sru.xxx 7276104862Sru @result{} -A'foo' 7277104862Sru@endExample 7278104862Sru 7279104862Sru@noindent 7280104862SruThe result is surprising for most users, expecting @samp{1} since 7281104862Sru@samp{foo} is a valid identifier. What has happened? As mentioned 7282104862Sruabove, the leading escape character makes the following character 7283104862Sruordinary. Written with the default escape character the sequence 7284104862Sru@samp{--} becomes @samp{\-} -- this is the minus sign. 7285104862Sru 7286104862SruIf the escape character followed by itself is a valid escape sequence, 7287104862Sruonly @code{\E} yields the expected result: 7288104862Sru 7289104862Sru@Example 7290104862Sru.ec - 7291104862Sru.de xxx 7292104862Sru-EA'123' 7293104862Sru.. 7294104862Sru.xxx 7295104862Sru @result{} 1 7296104862Sru@endExample 729775584Sru@endDefesc 729869626Sru 7299104862Sru@Defesc {\\., , , } 7300104862SruSimilar to @code{\\}, the sequence @code{\.} isn't a real escape sequence. 7301104862SruAs before, a warning message is suppressed if the escape character is 7302104862Srufollowed by a dot, and the dot itself is printed. 7303104862Sru 7304104862Sru@Example 7305104862Sru.de foo 7306104862Sru. nop foo 7307104862Sru. 7308104862Sru. de bar 7309104862Sru. nop bar 7310104862Sru\\.. 7311104862Sru. 7312104862Sru.. 7313104862Sru.foo 7314104862Sru.bar 7315104862Sru @result{} foo bar 7316104862Sru@endExample 7317104862Sru 7318104862Sru@noindent 7319104862SruThe first backslash is consumed while the macro is read, and the second 7320104862Sruis swallowed while exexuting macro @code{foo}. 7321104862Sru@endDefesc 7322104862Sru 732369626SruA @dfn{translation} is a mapping of an input character to an output 7324104862Sruglyph. The mapping occurs at output time, i.e., the input character 7325104862Srugets assigned the metric information of the mapped output character 7326104862Sruright before input tokens are converted to nodes (@pxref{Gtroff 7327104862SruInternals}, for more on this process). 732869626Sru 7329104862Sru@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7330104862Sru@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7331114402SruTranslate character @var{a} to glyph@tie{}@var{b}, character @var{c} to 7332114402Sruglyph@tie{}@var{d}, etc. If there is an odd number of arguments, the 7333104862Srulast one is translated to an unstretchable space (@w{@samp{\ }}). 733469626Sru 7335104862SruThe @code{trin} request is identical to @code{tr}, 7336104862Srubut when you unformat a diversion with @code{asciify} 7337104862Sruit ignores the translation. 7338104862Sru@xref{Diversions}, for details about the @code{asciify} request. 7339104862Sru 734069626SruSome notes: 734169626Sru 734269626Sru@itemize @bullet 734369626Sru@item 7344104862Sru@cindex @code{\(}, and translations 7345104862Sru@cindex @code{\[}, and translations 7346104862Sru@cindex @code{\'}, and translations 7347104862Sru@cindex @code{\`}, and translations 7348104862Sru@cindex @code{\-}, and translations 7349104862Sru@cindex @code{\_}, and translations 7350104862Sru@cindex @code{\C}, and translations 7351104862Sru@cindex @code{\N}, and translations 7352104862Sru@cindex @code{char} request, and translations 7353104862Sru@cindex special characters 735469626Sru@cindex character, special 7355104862Sru@cindex numbered glyph (@code{\N}) 7356104862Sru@cindex glyph, numbered (@code{\N}) 735769626SruSpecial characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 735869626Sru@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 7359104862Sruglyphs defined with the @code{char} request, and numbered glyphs 736069626Sru(@code{\N'@var{xxx}'}) can be translated also. 736169626Sru 736269626Sru@item 7363104862Sru@cindex @code{\e}, and translations 736469626SruThe @code{\e} escape can be translated also. 736569626Sru 736669626Sru@item 7367104862Sru@cindex @code{\%}, and translations 7368104862Sru@cindex @code{\~}, and translations 736975584SruCharacters can be mapped onto the @code{\%} and @code{\~} escapes (but 7370104862Sru@code{\%} and @code{\~} can't be mapped onto another glyph). 737169626Sru 737269626Sru@item 7373104862Sru@cindex backspace character, and translations 7374104862Sru@cindex character, backspace, and translations 7375104862Sru@cindex leader character, and translations 7376104862Sru@cindex character, leader, and translations 7377104862Sru@cindex newline character, and translations 7378104862Sru@cindex character, newline, and translations 7379104862Sru@cindex tab character, and translations 7380104862Sru@cindex character, tab, and translations 7381104862Sru@cindex @code{\a}, and translations 7382104862Sru@cindex @code{\t}, and translations 738369626SruThe following characters can't be translated: space (with one exception, 738469626Srusee below), backspace, newline, leader (and @code{\a}), tab (and 738569626Sru@code{\t}). 738669626Sru 738769626Sru@item 7388104862Sru@cindex @code{shc} request, and translations 738969626SruTranslations are not considered for finding the soft hyphen character 739069626Sruset with the @code{shc} request. 739169626Sru 739269626Sru@item 7393104862Sru@cindex @code{\&}, and translations 7394114402SruThe pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c} 7395114402Srufollowed by the zero width space character) maps this character to nothing. 739669626Sru 739775584Sru@Example 739869626Sru.tr a\& 739969626Srufoo bar 740069626Sru @result{} foo br 740175584Sru@endExample 740269626Sru 740369626Sru@noindent 740469626SruIt is even possible to map the space character to nothing: 740569626Sru 740675584Sru@Example 740769626Sru.tr aa \& 740869626Srufoo bar 740969626Sru @result{} foobar 741075584Sru@endExample 741169626Sru 741269626Sru@noindent 741369626SruAs shown in the example, the space character can't be the first 7414104862Srucharacter/glyph pair as an argument of @code{tr}. Additionally, it is 7415104862Srunot possible to map the space character to any other glyph; requests 741675584Srulike @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 741769626Sru 741875584SruIf justification is active, lines are justified in spite of the 741969626Sru`empty' space character (but there is no minimal distance, i.e.@: the 742069626Sruspace character, between words). 742169626Sru 742269626Sru@item 7423104862SruAfter an output glyph has been constructed (this happens at the 7424104862Srumoment immediately before the glyph is appended to an output 7425104862Sruglyph list, either by direct output, in a macro, diversion, or 742669626Srustring), it is no longer affected by @code{tr}. 742769626Sru 7428104862Sru@item 7429104862SruTranslating character to glyphs where one of them or both are 7430104862Sruundefined is possible also; @code{tr} does not check whether the 7431104862Sruentities in its argument do exist. 743269626Sru 7433104862Sru@xref{Gtroff Internals}. 7434104862Sru 743569626Sru@item 7436104862Sru@code{troff} no longer has a hard-coded dependency on @w{Latin-1}; 7437104862Sruall @code{char@var{XXX}} entities have been removed from the font 7438104862Srudescription files. This has a notable consequence which shows up in 7439104862Sruwarnings like @code{can't find character with input code @var{XXX}} 7440104862Sruif the @code{tr} request isn't handled properly. 7441104862Sru 7442104862SruConsider the following translation: 7443104862Sru 7444104862Sru@Example 7445104862Sru.tr @'e@'E 7446104862Sru@endExample 7447104862Sru 7448104862Sru@noindent 7449104862SruThis maps input character @code{@'e} onto glyph @code{@'E}, which is 7450104862Sruidentical to glyph @code{char201}. But this glyph intentionally 7451104862Srudoesn't exist! Instead, @code{\[char201]} is treated as an input 7452104862Srucharacter entity and is by default mapped onto @code{\['E]}, and 7453104862Sru@code{gtroff} doesn't handle translations of translations. 7454104862Sru 7455104862SruThe right way to write the above translation is 7456104862Sru 7457104862Sru@Example 7458104862Sru.tr @'e\['E] 7459104862Sru@endExample 7460104862Sru 7461104862Sru@noindent 7462104862SruWith other words, the first argument of @code{tr} should be an input 7463104862Srucharacter or entity, and the second one a glyph entity. 7464104862Sru 7465104862Sru@item 746669626SruWithout an argument, the @code{tr} request is ignored. 746769626Sru@end itemize 746875584Sru@endDefreq 746969626Sru 7470104862Sru@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 747175584Sru@cindex @code{\!}, and @code{trnt} 747269626Sru@code{trnt} is the same as the @code{tr} request except that the 747375584Srutranslations do not apply to text that is transparently throughput 747475584Sruinto a diversion with @code{\!}. @xref{Diversions}, for more 747575584Sruinformation. 747669626Sru 747755839SasmodaiFor example, 747855839Sasmodai 747975584Sru@Example 748055839Sasmodai.tr ab 748155839Sasmodai.di x 748255839Sasmodai\!.tm a 748355839Sasmodai.di 748455839Sasmodai.x 748575584Sru@endExample 748655839Sasmodai 748769626Sru@noindent 748875584Sruprints @samp{b} to the standard error stream; if @code{trnt} is used 748975584Sruinstead of @code{tr} it prints @samp{a}. 749075584Sru@endDefreq 749155839Sasmodai 749255839Sasmodai 749369626Sru@c ===================================================================== 749469626Sru 749575584Sru@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 749669626Sru@section Troff and Nroff Mode 749769626Sru@cindex troff mode 749869626Sru@cindex mode, troff 749969626Sru@cindex nroff mode 750069626Sru@cindex mode, nroff 750169626Sru 750269626SruOriginally, @code{nroff} and @code{troff} were two separate programs, 7503104862Sruthe former for TTY output, the latter for everything else. With GNU 750475584Sru@code{troff}, both programs are merged into one executable, sending 7505104862Sruits output to a device driver (@code{grotty} for TTY devices, 750675584Sru@code{grops} for @sc{PostScript}, etc.) which interprets the 750775584Sruintermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 750875584Sruit makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 750975584Srusince the differences are hardcoded. For GNU @code{troff}, this 751075584Srudistinction is not appropriate because @code{gtroff} simply takes the 751175584Sruinformation given in the font files for a particular device without 7512104862Sruhandling requests specially if a TTY output device is used. 751369626Sru 751475584SruUsually, a macro package can be used with all output devices. 751575584SruNevertheless, it is sometimes necessary to make a distinction between 7516104862SruTTY and non-TTY devices: @code{gtroff} provides two built-in 751775584Sruconditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 751875584Sru@code{while} requests to decide whether @code{gtroff} shall behave 751975584Srulike @code{nroff} or like @code{troff}. 752069626Sru 7521104862Sru@Defreq {troff, } 752269626Sru@pindex troffrc 752369626Sru@pindex troffrc-end 752469626SruMake the @samp{t} built-in condition true (and the @samp{n} built-in 752575584Srucondition false) for @code{if}, @code{ie}, and @code{while} 752675584Sruconditional requests. This is the default if @code{gtroff} 752775584Sru(@emph{not} @code{groff}) is started with the @option{-R} switch to 752875584Sruavoid loading of the start-up files @file{troffrc} and 752975584Sru@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 7530104862Srumode if the output device is not a TTY (e.g.@: `ps'). 753175584Sru@endDefreq 753269626Sru 7533104862Sru@Defreq {nroff, } 753475584Sru@pindex tty.tmac 753569626SruMake the @samp{n} built-in condition true (and the @samp{t} built-in 753675584Srucondition false) for @code{if}, @code{ie}, and @code{while} 7537104862Sruconditional requests. This is the default if @code{gtroff} uses a TTY 753875584Sruoutput device; the code for switching to nroff mode is in the file 753975584Sru@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 754075584Sru@endDefreq 754169626Sru 754275584Sru@xref{Conditionals and Loops}, for more details on built-in 754375584Sruconditions. 754469626Sru 754569626Sru 754669626Sru@c ===================================================================== 754769626Sru 7548104862Sru@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference 754955839Sasmodai@section Line Layout 755055839Sasmodai@cindex line layout 755155839Sasmodai@cindex layout, line 755255839Sasmodai 755355839Sasmodai@cindex dimensions, line 755455839Sasmodai@cindex line dimensions 755569626SruThe following drawing shows the dimensions which @code{gtroff} uses for 755655839Sasmodaiplacing a line of output onto the page. They are labeled with the 755769626Srurequest which manipulates each dimension. 755855839Sasmodai 755975584Sru@Example 756069626Sru -->| in |<-- 756169626Sru |<-----------ll------------>| 756255839Sasmodai +----+----+----------------------+----+ 756355839Sasmodai | : : : | 756455839Sasmodai +----+----+----------------------+----+ 756569626Sru -->| po |<-- 756669626Sru |<--------paper width---------------->| 756775584Sru@endExample 756855839Sasmodai 756969626Sru@noindent 757055839SasmodaiThese dimensions are: 757155839Sasmodai 757255839Sasmodai@ftable @code 757355839Sasmodai@item po 7574104862Sru@cindex left margin (@code{po}) 7575104862Sru@cindex margin, left (@code{po}) 7576104862Sru@cindex page offset (@code{po}) 7577104862Sru@cindex offset, page (@code{po}) 757869626Sru@dfn{Page offset} -- this is the leftmost position of text on the final 757969626Sruoutput, defining the @dfn{left margin}. 758069626Sru 758155839Sasmodai@item in 7582104862Sru@cindex indentation (@code{in}) 7583104862Sru@cindex line indentation (@code{in}) 758469626Sru@dfn{Indentation} -- this is the distance from the left margin where 758575584Srutext is printed. 758655839Sasmodai 758755839Sasmodai@item ll 7588104862Sru@cindex line length (@code{ll}) 7589104862Sru@cindex length of line (@code{ll}) 759069626Sru@dfn{Line length} -- this is the distance from the left margin to right 759169626Srumargin. 759255839Sasmodai@end ftable 759355839Sasmodai 7594104862SruA simple demonstration: 759569626Sru 759675584Sru@Example 7597104862Sru.ll 3i 7598104862SruThis is text without indentation. 7599104862SruThe line length has been set to 3\~inch. 760055839Sasmodai.in +.5i 760155839Sasmodai.ll -.5i 7602104862SruNow the left and right margins are both increased. 7603104862Sru.in 7604104862Sru.ll 7605104862SruCalling .in and .ll without parameters restore 7606104862Sruthe previous values. 760775584Sru@endExample 760855839Sasmodai 7609104862SruResult: 7610104862Sru 7611104862Sru@Example 7612104862SruThis is text without indenta- 7613104862Srution. The line length has 7614104862Srubeen set to 3 inch. 7615104862Sru Now the left and 7616104862Sru right margins are 7617104862Sru both increased. 7618104862SruCalling .in and .ll without 7619104862Sruparameters restore the previ- 7620104862Sruous values. 7621104862Sru@endExample 7622104862Sru 7623104862Sru@DefreqList {po, [@Var{offset}]} 7624104862Sru@DefreqItem {po, @t{+}@Var{offset}} 7625104862Sru@DefreqItem {po, @t{-}@Var{offset}} 7626104862Sru@DefregListEnd {.o} 762775584Sru@pindex troffrc 762875584SruSet horizontal page offset to @var{offset} (or increment or decrement 762975584Sruthe current value by @var{offset}). Note that this request does not 763075584Srucause a break, so changing the page offset in the middle of text being 763175584Srufilled may not yield the expected result. The initial value is 7632104862Sru1@dmn{i}. For TTY output devices, it is set to 0 in the startup file 7633104862Sru@file{troffrc}; the default scaling indicator is @samp{m} (and 7634104862Srunot @samp{v} as incorrectly documented in the original 763575584Sru@acronym{UNIX} troff manual). 763655839Sasmodai 763775584SruThe current page offset can be found in the read-only number register 763869626Sru@samp{.o}. 763969626Sru 764069626SruIf @code{po} is called without an argument, the page offset is reset to 764169626Sruthe previous value before the last call to @code{po}. 764269626Sru 764375584Sru@Example 764469626Sru.po 3i 764569626Sru\n[.o] 764669626Sru @result{} 720 764769626Sru.po -1i 764869626Sru\n[.o] 764969626Sru @result{} 480 765069626Sru.po 765169626Sru\n[.o] 765269626Sru @result{} 720 765375584Sru@endExample 765475584Sru@endDefreq 765569626Sru 7656104862Sru@DefreqList {in, [@Var{indent}]} 7657104862Sru@DefreqItem {in, @t{+}@Var{indent}} 7658104862Sru@DefreqItem {in, @t{-}@Var{indent}} 7659104862Sru@DefregListEnd {.i} 766075584SruSet indentation to @var{indent} (or increment or decrement the 766169626Srucurrent value by @var{indent}). This request causes a break. 766269626SruInitially, there is no indentation. 766369626Sru 766469626SruIf @code{in} is called without an argument, the indentation is reset to 766569626Sruthe previous value before the last call to @code{in}. The default 7666104862Sruscaling indicator is @samp{m}. 766769626Sru 7668104862SruThe indentation is associated with the current environment 7669104862Sru(@pxref{Environments}). 767069626Sru 767169626SruIf a negative indentation value is specified (which is not allowed), 767269626Sru@code{gtroff} emits a warning of type @samp{range} and sets the 767369626Sruindentation to zero. 767469626Sru 767569626SruThe effect of @code{in} is delayed until a partially collected line (if 767675584Sruit exists) is output. A temporary indent value is reset to zero also. 767769626Sru 767869626SruThe current indentation (as set by @code{in}) can be found in the 767975584Sruread-only number register @samp{.i}. 768075584Sru@endDefreq 768169626Sru 7682104862Sru@DefreqList {ti, offset} 7683104862Sru@DefreqItem {ti, @t{+}@Var{offset}} 7684104862Sru@DefreqItem {ti, @t{-}@Var{offset}} 7685104862Sru@DefregListEnd {.in} 768669626SruTemporarily indent the next output line by @var{offset}. If an 768769626Sruincrement or decrement value is specified, adjust the temporary 768869626Sruindentation relative to the value set by the @code{in} request. 768969626Sru 769069626SruThis request causes a break; its value is associated with the current 7691104862Sruenvironment (@pxref{Environments}). The default scaling indicator 7692104862Sruis @samp{m}. A call of @code{ti} without an argument is ignored. 769369626Sru 769469626SruIf the total indentation value is negative (which is not allowed), 769569626Sru@code{gtroff} emits a warning of type @samp{range} and sets the 769669626Srutemporary indentation to zero. `Total indentation' is either 769769626Sru@var{offset} if specified as an absolute value, or the temporary plus 769869626Srunormal indentation, if @var{offset} is given as a relative value. 769969626Sru 770069626SruThe effect of @code{ti} is delayed until a partially collected line (if 770169626Sruit exists) is output. 770269626Sru 770375584SruThe read-only number register @code{.in} is the indentation that applies 770475584Sruto the current output line. 770569626Sru 770669626SruThe difference between @code{.i} and @code{.in} is that the latter takes 770769626Sruinto account whether a partially collected line still uses the old 770875584Sruindentation value or a temporary indentation value is active. 770975584Sru@endDefreq 771069626Sru 7711104862Sru@DefreqList {ll, [@Var{length}]} 7712104862Sru@DefreqItem {ll, @t{+}@Var{length}} 7713104862Sru@DefreqItem {ll, @t{-}@Var{length}} 7714104862Sru@DefregItem {.l} 7715104862Sru@DefregListEnd {.ll} 771675584SruSet the line length to @var{length} (or increment or decrement the 771769626Srucurrent value by @var{length}). Initially, the line length is set to 771869626Sru6.5@dmn{i}. The effect of @code{ll} is delayed until a partially 771975584Srucollected line (if it exists) is output. The default scaling 7720104862Sruindicator is @samp{m}. 772169626Sru 772269626SruIf @code{ll} is called without an argument, the line length is reset to 772369626Sruthe previous value before the last call to @code{ll}. If a negative 772469626Sruline length is specified (which is not allowed), @code{gtroff} emits a 772569626Sruwarning of type @samp{range} and sets the line length to zero. 772669626Sru 7727104862SruThe line length is associated with the current environment 7728104862Sru(@pxref{Environments}). 772969626Sru 7730104862Sru@cindex line length register (@code{.l}) 773169626SruThe current line length (as set by @code{ll}) can be found in the 773275584Sruread-only number register @samp{.l}. The read-only number register 773375584Sru@code{.ll} is the line length that applies to the current output line. 773469626Sru 773569626SruSimilar to @code{.i} and @code{.in}, the difference between @code{.l} 773669626Sruand @code{.ll} is that the latter takes into account whether a partially 773769626Srucollected line still uses the old line length value. 773875584Sru@endDefreq 773969626Sru 774069626Sru 774169626Sru@c ===================================================================== 774269626Sru 7743104862Sru@node Line Control, Page Layout, Line Layout, gtroff Reference 7744104862Sru@section Line Control 7745104862Sru@cindex line control 7746104862Sru@cindex control, line 7747104862Sru 7748104862SruIt is important to understand how @code{gtroff} handles input and output 7749104862Srulines. 7750104862Sru 7751104862SruMany escapes use positioning relative to the input line. For example, 7752104862Sruthis 7753104862Sru 7754104862Sru@Example 7755104862SruThis is a \h'|1.2i'test. 7756104862Sru 7757104862SruThis is a 7758104862Sru\h'|1.2i'test. 7759104862Sru@endExample 7760104862Sru 7761104862Sru@noindent 7762104862Sruproduces 7763104862Sru 7764104862Sru@Example 7765104862SruThis is a test. 7766104862Sru 7767104862SruThis is a test. 7768104862Sru@endExample 7769104862Sru 7770104862SruThe main usage of this feature is to define macros which act exactly 7771104862Sruat the place where called. 7772104862Sru 7773104862Sru@Example 7774104862Sru.\" A simple macro to underline a word 7775104862Sru.de underline 7776104862Sru. nop \\$1\l'|0\[ul]' 7777104862Sru.. 7778104862Sru@endExample 7779104862Sru 7780104862Sru@noindent 7781104862SruIn the above example, @samp{|0} specifies a negative distance from the 7782104862Srucurrent position (at the end of the just emitted argument @code{\$1}) back 7783104862Sruto the beginning of the input line. Thus, the @samp{\l} escape draws a 7784104862Sruline from right to left. 7785104862Sru 7786104862Sru@cindex input line continuation (@code{\}) 7787104862Sru@cindex line, input, continuation (@code{\}) 7788104862Sru@cindex continuation, input line (@code{\}) 7789104862Sru@cindex output line, continuation (@code{\c}) 7790104862Sru@cindex line, output, continuation (@code{\c}) 7791104862Sru@cindex continuation, output line (@code{\c}) 7792104862Sru@cindex interrupted line 7793104862Sru@cindex line, interrupted 7794104862Sru@code{gtroff} makes a difference between input and output line 7795104862Srucontinuation; the latter is also called @dfn{interrupting} a line. 7796104862Sru 7797104862Sru@DefescList {\\@key{RET}, , ,} 7798104862Sru@DefescItem {\\c, , ,} 7799104862Sru@DefregListEnd{.int} 7800104862SruContinue a line. @code{\@key{RET}} (this is a backslash at the end 7801104862Sruof a line immediately followed by a newline) works on the input level, 7802104862Srusuppressing the effects of the following newline in the input. 7803104862Sru 7804104862Sru@Example 7805104862SruThis is a \ 7806104862Sru.test 7807104862Sru @result{} This is a .test 7808104862Sru@endExample 7809104862Sru 7810104862SruThe @samp{|} operator is also affected. 7811104862Sru 7812104862Sru@cindex @code{\R}, after @code{\c} 7813104862Sru@code{\c} works on the output level. Anything after this escape on the 7814104862Srusame line is ignored, except @code{\R} which works as usual. Anything 7815104862Srubefore @code{\c} on the same line will be appended to the current partial 7816104862Sruoutput line. The next non-command line after an interrupted line counts 7817104862Sruas a new input line. 7818104862Sru 7819104862SruThe visual results depend on whether no-fill mode is active. 7820104862Sru 7821104862Sru@itemize @bullet 7822104862Sru@item 7823104862Sru@cindex @code{\c}, and no-fill mode 7824104862Sru@cindex no-fill mode, and @code{\c} 7825104862Sru@cindex mode, no-fill, and @code{\c} 7826104862SruIf no-fill mode is active (using the @code{nf} request), the next input 7827104862Srutext line after @code{\c} will be handled as a continuation of the same 7828104862Sruinput text line. 7829104862Sru 7830104862Sru@Example 7831104862Sru.nf 7832104862SruThis is a \c 7833104862Srutest. 7834104862Sru @result{} This is a test. 7835104862Sru@endExample 7836104862Sru 7837104862Sru@item 7838104862Sru@cindex @code{\c}, and fill mode 7839104862Sru@cindex fill mode, and @code{\c} 7840104862Sru@cindex mode, fill, and @code{\c} 7841104862SruIf fill mode is active (using the @code{fi} request), a word interrupted 7842104862Sruwith @code{\c} will be continued with the text on the next input text line, 7843104862Sruwithout an intervening space. 7844104862Sru 7845104862Sru@Example 7846104862SruThis is a te\c 7847104862Srust. 7848104862Sru @result{} This is a test. 7849104862Sru@endExample 7850104862Sru@end itemize 7851104862Sru 7852104862SruNote that an intervening control line which causes a break is stronger 7853104862Sruthan @code{\c}, flushing out the current partial line in the usual way. 7854104862Sru 7855104862Sru@cindex interrupted line register (@code{.int}) 7856104862SruThe @code{.int} register contains a positive value 7857104862Sruif the last output line was interrupted with @code{\c}; this is 7858104862Sruassociated with the current environment (@pxref{Environments}). 7859104862Sru 7860104862Sru@endDefesc 7861104862Sru 7862104862Sru@c ===================================================================== 7863104862Sru 7864104862Sru@node Page Layout, Page Control, Line Control, gtroff Reference 786555839Sasmodai@section Page Layout 786655839Sasmodai@cindex page layout 786755839Sasmodai@cindex layout, page 786855839Sasmodai 786969626Sru@code{gtroff} provides some very primitive operations for controlling 787069626Srupage layout. 787155839Sasmodai 7872104862Sru@DefreqList {pl, [@Var{length}]} 7873104862Sru@DefreqItem {pl, @t{+}@Var{length}} 7874104862Sru@DefreqItem {pl, @t{-}@Var{length}} 7875104862Sru@DefregListEnd {.p} 7876104862Sru@cindex page length (@code{pl}) 7877104862Sru@cindex length of page (@code{pl}) 787875584SruSet the @dfn{page length} to @var{length} (or increment or decrement 787975584Sruthe current value by @var{length}). This is the length of the 7880104862Sruphysical output page. The default scaling indicator is @samp{v}. 788155839Sasmodai 7882104862Sru@cindex page length register (@code{.p}) 788375584SruThe current setting can be found in the read-only number register 788469626Sru@samp{.p}. 788555839Sasmodai 788669626Sru@cindex top margin 788769626Sru@cindex margin, top 788869626Sru@cindex bottom margin 788969626Sru@cindex margin, bottom 789069626SruNote that this only specifies the size of the page, not the top and 789175584Srubottom margins. Those are not set by @code{gtroff} directly. 789275584Sru@xref{Traps}, for further information on how to do this. 789369626Sru 789469626SruNegative @code{pl} values are possible also, but not very useful: No 789569626Srutrap is sprung, and each line is output on a single page (thus 789669626Srusuppressing all vertical spacing). 789769626Sru 789875584SruIf no argument or an invalid argument is given, @code{pl} sets the page 789975584Srulength to 11@dmn{i}. 790075584Sru@endDefreq 790175584Sru 790255839Sasmodai@cindex headers 790355839Sasmodai@cindex footers 790455839Sasmodai@cindex titles 790569626Sru@code{gtroff} provides several operations which help in setting up top 790669626Sruand bottom titles (or headers and footers). 790755839Sasmodai 790875584Sru@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 7909104862Sru@cindex title line (@code{tl}) 7910104862Sru@cindex three-part title (@code{tl}) 7911104862Sru@cindex page number character (@code{%}) 791275584SruPrint a @dfn{title line}. It consists of three parts: a left 791375584Srujustified portion, a centered portion, and a right justified portion. 791475584SruThe argument separator @samp{'} can be replaced with any character not 791575584Sruoccurring in the title line. The @samp{%} character is replaced with 791675584Sruthe current page number. This character can be changed with the 791775584Sru@code{pc} request (see below). 791855839Sasmodai 791975584SruWithout argument, @code{tl} is ignored. 792075584Sru 792175584SruSome notes: 792275584Sru 792375584Sru@itemize @bullet 792475584Sru@item 792575584SruA title line is not restricted to the top or bottom of a page. 792675584Sru 792775584Sru@item 792875584Sru@code{tl} prints the title line immediately, ignoring a partially filled 792975584Sruline (which stays untouched). 793075584Sru 793175584Sru@item 793275584SruIt is not an error to omit closing delimiters. For example, 793375584Sru@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 793475584Srutitle line with the left justified word @samp{foo}; the centered and 793575584Sruright justfied parts are empty. 793675584Sru 793775584Sru@item 793875584Sru@code{tl} accepts the same parameter delimiting characters as the 793975584Sru@code{\A} escape; see @ref{Escapes}. 794075584Sru@end itemize 794175584Sru@endDefreq 794275584Sru 7943104862Sru@DefreqList {lt, [@Var{length}]} 7944104862Sru@DefreqItem {lt, @t{+}@Var{length}} 7945104862Sru@DefreqItem {lt, @t{-}@Var{length}} 7946104862Sru@DefregListEnd {.lt} 7947104862Sru@cindex length of title line (@code{lt}) 7948104862Sru@cindex title line, length (@code{lt}) 7949104862Sru@cindex title line length register (@code{.lt}) 795075584SruThe title line is printed using its own line length, which is 795175584Sruspecified (or incremented or decremented) with the @code{lt} request. 795275584SruInitially, the title line length is set to 6.5@dmn{i}. If a negative 795375584Sruline length is specified (which is not allowed), @code{gtroff} emits a 795475584Sruwarning of type @samp{range} and sets the title line length to zero. 7955104862SruThe default scaling indicator is @samp{m}. If @code{lt} is called 795675584Sruwithout an argument, the title length is reset to the previous value 795775584Srubefore the last call to @code{lt}. 795855839Sasmodai 795975584SruThe current setting of this is available in the @code{.lt} read-only 796075584Srunumber register; it is associated with the current environment 796175584Sru(@pxref{Environments}). 796275584Sru 796375584Sru@endDefreq 796475584Sru 7965104862Sru@DefreqList {pn, page} 7966104862Sru@DefreqItem {pn, @t{+}@Var{page}} 7967104862Sru@DefreqItem {pn, @t{-}@Var{page}} 7968104862Sru@DefregListEnd {.pn} 7969104862Sru@cindex page number (@code{pn}) 7970104862Sru@cindex number, page (@code{pn}) 797175584SruChange (increase or decrease) the page number of the @emph{next} page. 797275584SruThe only argument is the page number; the request is ignored without a 797375584Sruparameter. 797455839Sasmodai 797575584SruThe read-only number register @code{.pn} contains the number of the next 797675584Srupage: either the value set by a @code{pn} request, or the number of the 7977114402Srucurrent page plus@tie{}1. 797875584Sru@endDefreq 797975584Sru 798075584Sru@Defreg {%} 7981104862Sru@cindex page number register (@code{%}) 798275584SruA read-write register holding the current page number. 798375584Sru@endDefreg 798455839Sasmodai 7985104862Sru@Defreq {pc, [@Var{char}]} 7986104862Sru@cindex changing the page number character (@code{pc}) 7987104862Sru@cindex page number character, changing (@code{pc}) 798875584Sru@vindex % 798975584SruChange the page number character (used by the @code{tl} request) to a 799075584Srudifferent character. With no argument, this mechanism is disabled. 7991114402SruNote that this doesn't affect the number register@tie{}@code{%}. 799275584Sru@endDefreq 799355839Sasmodai 799469626Sru@xref{Traps}. 799555839Sasmodai 799655839Sasmodai 799769626Sru@c ===================================================================== 799869626Sru 7999114402Sru@node Page Control, Fonts and Symbols, Page Layout, gtroff Reference 800055839Sasmodai@section Page Control 800155839Sasmodai@cindex page control 800255839Sasmodai@cindex control, page 800355839Sasmodai 8004104862Sru@DefreqList {bp, [@Var{page}]} 8005104862Sru@DefreqItem {bp, @t{+}@Var{page}} 8006104862Sru@DefreqListEnd {bp, @t{-}@Var{page}} 8007104862Sru@cindex new page (@code{bp}) 8008104862Sru@cindex page, new (@code{bp}) 800975584SruStop processing the current page and move to the next page. This 801075584Srurequest causes a break. It can also take an argument to set 801175584Sru(increase, decrease) the page number of the next page. The only 801275584Srudifference between @code{bp} and @code{pn} is that @code{pn} does not 801375584Srucause a break or actually eject a page. 801455839Sasmodai 801575584Sru@Example 801675584Sru.de newpage \" define macro 801775584Sru'bp \" begin page 801875584Sru'sp .5i \" vertical space 801975584Sru.tl 'left top'center top'right top' \" title 802075584Sru'sp .3i \" vertical space 802175584Sru.. \" end macro 802275584Sru@endExample 802355839Sasmodai 8024104862Sru@cindex @code{bp} request, and top-level diversion 8025104862Sru@cindex top-level diversion, and @code{bp} 8026104862Sru@cindex diversion, top-level, and @code{bp} 802775584Sru@code{bp} has no effect if not called within the top-level diversion 802875584Sru(@pxref{Diversions}). 8029114402Sru 8030114402SruThe number register @code{.pe} is set to@tie{}1 while @code{bp} is 8031114402Sruactive. @xref{Page Location Traps}. 803275584Sru@endDefreq 803375584Sru 803475584Sru@Defreq {ne, [@Var{space}]} 8035104862Sru@cindex orphan lines, preventing with @code{ne} 8036104862Sru@cindex conditional page break (@code{ne}) 8037104862Sru@cindex page break, conditional (@code{ne}) 803869626SruIt is often necessary to force a certain amount of space before a new 803969626Srupage occurs. This is most useful to make sure that there is not a 804069626Srusingle @dfn{orphan} line left at the bottom of a page. The @code{ne} 804175584Srurequest ensures that there is a certain distance, specified by the 804275584Srufirst argument, before the next page is triggered (see @ref{Traps}, 8043104862Srufor further information). The default scaling indicator for @code{ne} 8044114402Sruis @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no 8045104862Sruargument is given. 804655839Sasmodai 8047114402SruFor example, to make sure that no fewer than 2@tie{}lines get orphaned, 804869626Srudo the following before each paragraph: 804955839Sasmodai 805075584Sru@Example 805155839Sasmodai.ne 2 805275584Srutext text text 805375584Sru@endExample 8054104862Sru 8055104862Sru@code{ne} will then automatically cause a page break if there is space 8056104862Srufor one line only. 805775584Sru@endDefreq 805855839Sasmodai 8059104862Sru@DefreqList {sv, [@Var{space}]} 8060104862Sru@DefreqListEnd {os, } 8061104862Sru@cindex @code{ne} request, comparison with @code{sv} 806275584Sru@code{sv} is similar to the @code{ne} request; it reserves the 806375584Sruspecified amount of vertical space. If the desired amount of space 8064104862Sruexists before the next trap (or the bottom page boundary if no trap is 8065104862Sruset), the space is output immediately (ignoring a partially filled line 8066104862Sruwhich stays untouched). If there is not enough space, it is stored for 8067114402Srulater output via the @code{os} request. The default value is@tie{}1@dmn{v} 8068104862Sruif no argument is given; the default scaling indicator is @samp{v}. 8069104862Sru 8070104862Sru@cindex @code{sv} request, and no-space mode 8071104862Sru@cindex @code{os} request, and no-space mode 8072104862SruBoth @code{sv} and @code{os} ignore no-space mode. While the @code{sv} 8073104862Srurequest allows negative values for @var{space}, @code{os} will ignore 8074104862Sruthem. 807575584Sru@endDefreq 807655839Sasmodai 8077104862Sru@Defreg {nl} 8078104862SruThis register contains the current vertical position. If the vertical 8079104862Sruposition is zero and the top of page transition hasn't happened yet, 8080104862Sru@code{nl} is set to negative value. @code{gtroff} itself does this at 8081104862Sruthe very beginning of a document before anything has been printed, but 8082104862Sruthe main usage is to plant a header trap on a page if this page has 8083104862Srualready started. 808455839Sasmodai 8085104862SruConsider the following: 8086104862Sru 8087104862Sru@Example 8088104862Sru.de xxx 8089104862Sru. sp 8090104862Sru. tl ''Header'' 8091104862Sru. sp 8092104862Sru.. 8093104862Sru. 8094104862SruFirst page. 8095104862Sru.bp 8096104862Sru.wh 0 xxx 8097104862Sru.nr nl (-1) 8098104862SruSecond page. 8099104862Sru@endExample 8100104862Sru 8101104862Sru@noindent 8102104862SruResult: 8103104862Sru 8104104862Sru@Example 8105104862SruFirst page. 8106104862Sru 8107104862Sru... 8108104862Sru 8109104862Sru Header 8110104862Sru 8111104862SruSecond page. 8112104862Sru 8113104862Sru... 8114104862Sru@endExample 8115104862Sru 8116104862Sru@noindent 8117104862SruWithout resetting @code{nl} to a negative value, the just planted trap 8118104862Sruwould be active beginning with the @emph{next} page, not the current 8119104862Sruone. 8120104862Sru 8121104862Sru@xref{Diversions}, for a comparison with the @code{.h} and @code{.d} 8122104862Sruregisters. 8123104862Sru@endDefreg 8124104862Sru 812569626Sru@c ===================================================================== 812669626Sru 8127114402Sru@node Fonts and Symbols, Sizes, Page Control, gtroff Reference 8128114402Sru@section Fonts and Symbols 812955839Sasmodai@cindex fonts 813055839Sasmodai 813175584Sru@code{gtroff} can switch fonts at any point in the text. 813255839Sasmodai 813375584SruThe basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 8134104862SruThese are Times Roman, Italic, Bold, and Bold Italic. For non-TTY 813575584Srudevices, there is also at least one symbol font which contains various 813675584Sruspecial symbols (Greek, mathematics). 813755839Sasmodai 813855839Sasmodai@menu 813975584Sru* Changing Fonts:: 814075584Sru* Font Families:: 814175584Sru* Font Positions:: 814275584Sru* Using Symbols:: 814375584Sru* Special Fonts:: 814475584Sru* Artificial Fonts:: 814575584Sru* Ligatures and Kerning:: 814655839Sasmodai@end menu 814755839Sasmodai 814869626Sru@c --------------------------------------------------------------------- 814969626Sru 8150114402Sru@node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols 815155839Sasmodai@subsection Changing Fonts 8152104862Sru@cindex fonts 815355839Sasmodai 8154104862Sru@DefreqList {ft, [@Var{font}]} 8155104862Sru@DefescItem {\\f, , f, } 8156104862Sru@DefescItem {\\f, @lparen{}, fn, } 8157104862Sru@DefescListEnd {\\f, @lbrack{}, font, @rbrack} 8158104862Sru@cindex changing fonts (@code{ft}, @code{\f}) 8159104862Sru@cindex fonts, changing (@code{ft}, @code{\f}) 8160104862Sru@cindex @code{sty} request, and changing fonts 8161104862Sru@cindex @code{fam} request, and changing fonts 8162104862Sru@cindex @code{\F}, and changing fonts 816375584Sru@kindex styles 816475584Sru@kindex family 816575584Sru@pindex DESC 816675584SruThe @code{ft} request and the @code{\f} escape change the current font 8167114402Sruto @var{font} (one-character name@tie{}@var{f}, two-character name 816875584Sru@var{fn}). 816975584Sru 817075584SruIf @var{font} is a style name (as set with the @code{sty} request or 817175584Sruwith the @code{styles} command in the @file{DESC} file), use it within 8172104862Sruthe current font family (as set with the @code{fam} request, @code{\F} 8173104862Sruescape, or with the @code{family} command in the @file{DESC} file). 817475584Sru 8175104862Sru@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP}) 8176104862Sru@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP}) 817775584SruWith no argument or using @samp{P} as an argument, @code{.ft} switches 8178104862Sruto the previous font. Use @code{\f[]} to do this with the escape. The 8179104862Sruold syntax forms @code{\fP} or @code{\f[P]} are also supported. 818055839Sasmodai 818175584SruFonts are generally specified as upper-case strings, which are usually 8182114402Sru1@tie{}to 4 characters representing an abbreviation or acronym of the 818375584Srufont name. This is no limitation, just a convention. 818475584Sru 818575584SruThe example below produces two identical lines. 818675584Sru 818775584Sru@Example 818855839Sasmodaieggs, bacon, 818955839Sasmodai.ft B 819055839Sasmodaispam 819155839Sasmodai.ft 819255839Sasmodaiand sausage. 819355839Sasmodai 819455839Sasmodaieggs, bacon, \fBspam\fP and sausage. 819575584Sru@endExample 819655839Sasmodai 8197104862SruNote that @code{\f} doesn't produce an input token in @code{gtroff}. 8198104862SruAs a consequence, it can be used in requests like @code{mc} (which 8199104862Sruexpects a single character as an argument) to change the font on 8200104862Sruthe fly: 8201104862Sru 8202104862Sru@Example 8203104862Sru.mc \f[I]x\f[] 8204104862Sru@endExample 8205104862Sru 820675584Sru@xref{Font Positions}, for an alternative syntax. 820775584Sru@endDefreq 820855839Sasmodai 820975584Sru@Defreq {ftr, f [@Var{g}]} 8210104862Sru@cindex @code{ft} request, and font translations 8211104862Sru@cindex @code{ul} request, and font translations 8212104862Sru@cindex @code{bd} request, and font translations 8213104862Sru@cindex @code{\f}, and font translations 8214104862Sru@cindex @code{cs} request, and font translations 8215104862Sru@cindex @code{tkf} request, and font translations 8216104862Sru@cindex @code{special} request, and font translations 8217104862Sru@cindex @code{fspecial} request, and font translations 8218104862Sru@cindex @code{fp} request, and font translations 8219104862Sru@cindex @code{sty} request, and font translations 8220114402SruTranslate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font 8221114402Srunamed@tie{}@var{f} is referred to in a @code{\f} escape sequence, or in the 822275584Sru@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 8223104862Sru@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, 8224114402Srufont@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f} 822575584Sruthe translation is undone. 822675584Sru@endDefreq 822755839Sasmodai 822869626Sru@c --------------------------------------------------------------------- 822969626Sru 8230114402Sru@node Font Families, Font Positions, Changing Fonts, Fonts and Symbols 823155839Sasmodai@subsection Font Families 823255839Sasmodai@cindex font families 823355839Sasmodai@cindex families, font 823475584Sru@cindex font styles 823575584Sru@cindex styles, font 823655839Sasmodai 823769626SruDue to the variety of fonts available, @code{gtroff} has added the 823875584Sruconcept of @dfn{font families} and @dfn{font styles}. The fonts are 823975584Sruspecified as the concatenation of the font family and style. Specifying 824075584Srua font without the family part causes @code{gtroff} to use that style of 824175584Sruthe current family. 824255839Sasmodai 8243104862Sru@cindex PostScript fonts 8244104862Sru@cindex fonts, PostScript 8245104862SruCurrently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and 8246104862Sru@option{-Tlbp} are set up to this mechanism. 824775584SruBy default, @code{gtroff} uses the Times family with the four styles 824875584Sru@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 824955839Sasmodai 825069626SruThis way, it is possible to use the basic four fonts and to select a 825175584Srudifferent font family on the command line (@pxref{Groff Options}). 825255839Sasmodai 8253104862Sru@DefreqList {fam, [@Var{family}]} 8254104862Sru@DefregItem {.fam} 8255104862Sru@DefescItem {\\F, , f, } 8256104862Sru@DefescItem {\\F, @lparen{}, fm, } 8257104862Sru@DefescItem {\\F, @lbrack{}, family, @rbrack} 8258104862Sru@DefregListEnd {.fn} 8259104862Sru@cindex changing font family (@code{fam}, @code{\F}) 8260104862Sru@cindex font family, changing (@code{fam}, @code{\F}) 8261114402SruSwitch font family to @var{family} (one-character name@tie{}@var{f}, 8262104862Srutwo-character name @var{fm}). If no argument is given, switch 8263104862Sruback to the previous font family. Use @code{\F[]} to do this with the 8264104862Sruescape. Note that @code{\FP} doesn't work; it selects font family 8265104862Sru@samp{P} instead. 826655839Sasmodai 8267104862SruThe value at start-up is @samp{T}. 8268104862SruThe current font family is available in the read-only number register 8269104862Sru@samp{.fam} (this is a string-valued register); it is associated with 8270104862Sruthe current environment. 8271104862Sru 827275584Sru@Example 827355839Sasmodaispam, 827475584Sru.fam H \" helvetica family 827575584Sruspam, \" used font is family H + style R = HR 827675584Sru.ft B \" family H + style B = font HB 827755839Sasmodaispam, 827875584Sru.fam T \" times family 827975584Sruspam, \" used font is family T + style B = TB 828075584Sru.ft AR \" font AR (not a style) 828155839Sasmodaibaked beans, 828275584Sru.ft R \" family T + style R = font TR 828355839Sasmodaiand spam. 828475584Sru@endExample 8285104862Sru 8286104862SruNote that @code{\F} doesn't produce an input token in @code{gtroff}. 8287104862SruAs a consequence, it can be used in requests like @code{mc} (which 8288104862Sruexpects a single character as an argument) to change the font family on 8289104862Sruthe fly: 8290104862Sru 8291104862Sru@Example 8292104862Sru.mc \F[P]x\F[] 8293104862Sru@endExample 8294104862Sru 8295104862SruThe @samp{.fn} register contains the current @dfn{real font name} 8296104862Sruof the current font. 8297104862SruThis is a string-valued register. 8298104862SruIf the current font is a style, the value of @code{\n[.fn]} 8299104862Sruis the proper concatenation of family and style name. 830075584Sru@endDefreq 830155839Sasmodai 830275584Sru@Defreq {sty, n style} 8303104862Sru@cindex changing font style (@code{sty}) 8304104862Sru@cindex font style, changing (@code{sty}) 8305104862Sru@cindex @code{cs} request, and font styles 8306104862Sru@cindex @code{bd} request, and font styles 8307104862Sru@cindex @code{tkf} request, and font styles 8308104862Sru@cindex @code{uf} request, and font styles 8309104862Sru@cindex @code{fspecial} request, and font styles 8310114402SruAssociate @var{style} with font position@tie{}@var{n}. A font position 831175584Srucan be associated either with a font or with a style. The current 831275584Srufont is the index of a font position and so is also either a font or a 8313104862Srustyle. If it is a style, the font that is actually used is the font 8314104862Sruwhich name is the concatenation of the name of the current 831575584Srufamily and the name of the current style. For example, if the current 8316114402Srufont is@tie{}1 and font position@tie{}1 is associated with style 8317104862Sru@samp{R} and the current font family is @samp{T}, then font 831875584Sru@samp{TR} will be used. If the current font is not a style, then the 8319104862Srucurrent family is ignored. If the requests @code{cs}, @code{bd}, 8320104862Sru@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, 832175584Sruthey will instead be applied to the member of the current family 832275584Srucorresponding to that style. 832375584Sru 8324114402Sru@var{n}@tie{}must be a non-negative integer value. 832575584Sru 832675584Sru@pindex DESC 832775584Sru@kindex styles 832875584SruThe default family can be set with the @option{-f} option 832975584Sru(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 833075584Srufile controls which font positions (if any) are initially associated 833175584Sruwith styles rather than fonts. For example, the default setting for 833275584Sru@sc{PostScript} fonts 833375584Sru 833475584Sru@Example 833575584Srustyles R I B BI 833675584Sru@endExample 833775584Sru 833875584Sru@noindent 833975584Sruis equivalent to 834075584Sru 834175584Sru@Example 834275584Sru.sty 1 R 834375584Sru.sty 2 I 834475584Sru.sty 3 B 834575584Sru.sty 4 BI 834675584Sru@endExample 834775584Sru 8348104862Sru@code{fam} and @code{\F} always check whether the current font position 8349104862Sruis valid; this can give surprising results if the current font position is 835075584Sruassociated with a style. 835175584Sru 835275584SruIn the following example, we want to access the @sc{PostScript} font 835375584Sru@code{FooBar} from the font family @code{Foo}: 835475584Sru 835575584Sru@Example 835675584Sru.sty \n[.fp] Bar 835775584Sru.fam Foo 835875584Sru @result{} warning: can't find font `FooR' 835975584Sru@endExample 836075584Sru 836175584Sru@noindent 8362114402SruThe default font position at start-up is@tie{}1; for the 836375584Sru@sc{PostScript} device, this is associated with style @samp{R}, so 836475584Sru@code{gtroff} tries to open @code{FooR}. 836575584Sru 836675584SruA solution to this problem is to use a dummy font like the following: 836775584Sru 836875584Sru@Example 836975584Sru.fp 0 dummy TR \" set up dummy font at position 0 837075584Sru.sty \n[.fp] Bar \" register style `Bar' 837175584Sru.ft 0 \" switch to font at position 0 837275584Sru.fam Foo \" activate family `Foo' 837375584Sru.ft Bar \" switch to font `FooBar' 837475584Sru@endExample 837575584Sru 837675584Sru@xref{Font Positions}. 837775584Sru@endDefreq 837875584Sru 837969626Sru@c --------------------------------------------------------------------- 838055839Sasmodai 8381114402Sru@node Font Positions, Using Symbols, Font Families, Fonts and Symbols 838255839Sasmodai@subsection Font Positions 838355839Sasmodai@cindex font positions 838455839Sasmodai@cindex positions, font 838555839Sasmodai 838675584SruFor the sake of old phototypesetters and compatibility with old versions 838769626Sruof @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 838875584Sruon which various fonts are mounted. 838955839Sasmodai 8390104862Sru@DefreqList {fp, pos font [@Var{external-name}]} 8391104862Sru@DefregItem {.f} 8392104862Sru@DefregListEnd {.fp} 8393104862Sru@cindex mounting font (@code{fp}) 8394104862Sru@cindex font, mounting (@code{fp}) 839575584SruMount font @var{font} at position @var{pos} (which must be a 839675584Srunon-negative integer). This numeric position can then be referred to 839775584Sruwith font changing commands. When @code{gtroff} starts it is using 8398114402Srufont position@tie{}1 (which must exist; position@tie{}0 is unused 839975584Sruusually at start-up). 840055839Sasmodai 8401104862Sru@cindex font position register (@code{.f}) 840275584SruThe current font in use, as a font position, is available in the 840375584Sruread-only number register @samp{.f}. This can be useful to remember the 840475584Srucurrent font for later recall. It is associated with the current 840575584Sruenvironment (@pxref{Environments}). 840655839Sasmodai 840775584Sru@Example 840875584Sru.nr save-font \n[.f] 840975584Sru.ft B 841075584Sru... text text text ... 841155839Sasmodai.ft \n[save-font] 841275584Sru@endExample 841355839Sasmodai 8414104862Sru@cindex next free font position register (@code{.fp}) 841575584SruThe number of the next free font position is available in the read-only 841675584Srunumber register @samp{.fp}. This is useful when mounting a new font, 841775584Srulike so: 841855839Sasmodai 841975584Sru@Example 842055839Sasmodai.fp \n[.fp] NEATOFONT 842175584Sru@endExample 842255839Sasmodai 842369626Sru@pindex DESC@r{, and font mounting} 842455839SasmodaiFonts not listed in the @file{DESC} file are automatically mounted on 842575584Sruthe next available font position when they are referenced. If a font 842675584Sruis to be mounted explicitly with the @code{fp} request on an unused 842775584Srufont position, it should be mounted on the first unused font position, 842875584Sruwhich can be found in the @code{.fp} register. Although @code{gtroff} 842975584Srudoes not enforce this strictly, it is not allowed to mount a font at a 843075584Sruposition whose number is much greater (approx.@: 1000 positions) than 843175584Sruthat of any currently used position. 843255839Sasmodai 843369626SruThe @code{fp} request has an optional third argument. This argument 843469626Srugives the external name of the font, which is used for finding the font 843555839Sasmodaidescription file. The second argument gives the internal name of the 843669626Srufont which is used to refer to the font in @code{gtroff} after it has 843775584Srubeen mounted. If there is no third argument then the internal name is 843875584Sruused as the external name. This feature makes it possible to use 843969626Srufonts with long names in compatibility mode. 844075584Sru@endDefreq 844155839Sasmodai 844275584SruBoth the @code{ft} request and the @code{\f} escape have alternative 844375584Srusyntax forms to access font positions. 844475584Sru 8445104862Sru@DefreqList {ft, nnn} 8446104862Sru@DefescItem {\\f, , n, } 8447104862Sru@DefescItem {\\f, @lparen{}, nn, } 8448104862Sru@DefescListEnd {\\f, @lbrack{}, nnn, @rbrack} 8449104862Sru@cindex changing font position (@code{\f}) 8450104862Sru@cindex font position, changing (@code{\f}) 8451104862Sru@cindex @code{sty} request, and font positions 8452104862Sru@cindex @code{fam} request, and font positions 8453104862Sru@cindex @code{\F}, and font positions 845475584Sru@kindex styles 845575584Sru@kindex family 845675584Sru@pindex DESC 8457114402SruChange the current font position to @var{nnn} (one-digit 8458114402Sruposition@tie{}@var{n}, two-digit position @var{nn}), which must be a 8459114402Srunon-negative integer. 846075584Sru 846175584SruIf @var{nnn} is associated with a style (as set with the @code{sty} 846275584Srurequest or with the @code{styles} command in the @file{DESC} file), use 8463104862Sruit within the current font family (as set with the @code{fam} request, 8464104862Sruthe @code{\F} escape, or with the @code{family} command in the @file{DESC} 8465104862Srufile). 846675584Sru 846775584Sru@Example 846875584Sruthis is font 1 846975584Sru.ft 2 847075584Sruthis is font 2 847175584Sru.ft \" switch back to font 1 847275584Sru.ft 3 847375584Sruthis is font 3 847475584Sru.ft 847575584Sruthis is font 1 again 847675584Sru@endExample 847775584Sru 847875584Sru@xref{Changing Fonts}, for the standard syntax form. 847975584Sru@endDefreq 848075584Sru 848169626Sru@c --------------------------------------------------------------------- 848255839Sasmodai 8483114402Sru@node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols 848455839Sasmodai@subsection Using Symbols 848555839Sasmodai@cindex using symbols 848655839Sasmodai@cindex symbols, using 848755839Sasmodai 848875584Sru@cindex glyph 848975584Sru@cindex character 849075584Sru@cindex ligature 849175584SruA @dfn{glyph} is a graphical representation of a @dfn{character}. 849275584SruWhile a character is an abstract entity containing semantic 849375584Sruinformation, a glyph is something which can be actually seen on screen 849475584Sruor paper. It is possible that a character has multiple glyph 849575584Srurepresentation forms (for example, the character `A' can be either 849675584Sruwritten in a roman or an italic font, yielding two different glyphs); 849775584Srusometimes more than one character maps to a single glyph (this is a 849875584Sru@dfn{ligature} -- the most common is `fi'). 849955839Sasmodai 850075584Sru@cindex symbol 850175584Sru@cindex special fonts 850275584Sru@kindex fonts 850375584Sru@pindex DESC 8504114402Sru@cindex @code{special} request, and glyph search order 8505114402Sru@cindex @code{fspecial} request, and glyph search order 850675584SruA @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 850775584Sruglyph names of a particular font are defined in its font file. If the 850875584Sruuser requests a glyph not available in this font, @code{gtroff} looks 850975584Sruup an ordered list of @dfn{special fonts}. By default, the 851075584Sru@sc{PostScript} output device supports the two special fonts @samp{SS} 851175584Sru(slanted symbols) and @samp{S} (symbols) (the former is looked up 851275584Srubefore the latter). Other output devices use different names for 851375584Sruspecial fonts. Fonts mounted with the @code{fonts} keyword in the 851475584Sru@file{DESC} file are globally available. To install additional 851575584Sruspecial fonts locally (i.e.@: for a particular font), use the 851675584Sru@code{fspecial} request. 851755839Sasmodai 8518114402SruHere the exact rules how @code{gtroff} searches a given symbol: 8519104862Sru 8520104862Sru@itemize @bullet 8521104862Sru@item 8522104862SruIf the symbol has been defined with the @code{char} request, use it. 8523104862SruThis hides a symbol with the same name in the current font. 8524104862Sru 8525104862Sru@item 8526104862SruCheck the current font. 8527104862Sru 8528104862Sru@item 8529104862SruIf the symbol has been defined with the @code{fchar} request, use it. 8530104862Sru 8531104862Sru@item 8532114402SruCheck whether the current font has a font-specific list of special fonts; 8533114402Srutest all fonts in the order of appearance in the last @code{fspecial} 8534114402Srucall if appropriate. 8535104862Sru 8536104862Sru@item 8537114402SruIf the symbol has been defined with the @code{fschar} request for the 8538114402Srucurrent font, use it. 8539104862Sru 8540104862Sru@item 8541114402SruCheck all fonts in the order of appearance in the last @code{special} 8542114402Srucall. 8543114402Sru 8544114402Sru@item 8545114402SruIf the symbol has been defined with the @code{schar} request, use it. 8546114402Sru 8547114402Sru@item 8548114402SruAs a last resort, consult all fonts loaded up to now for special fonts 8549114402Sruand check them, starting with the lowest font number. Note that this can 8550114402Srusometimes lead to surprising results since the @code{fonts} line in the 8551114402Sru@file{DESC} file often contains empty positions which are filled later 8552114402Sruon. For example, consider the following: 8553114402Sru 8554114402Sru@Example 8555114402Srufonts 3 0 0 FOO 8556114402Sru@endExample 8557114402Sru 8558114402Sru@noindent 8559114402SruThis mounts font @code{foo} at font position@tie{}3. We assume that 8560114402Sru@code{FOO} is a special font, containing glyph @code{foo}, 8561114402Sruand that no font has been loaded yet. The line 8562114402Sru 8563114402Sru@Example 8564114402Sru.fspecial BAR BAZ 8565114402Sru@endExample 8566114402Sru 8567114402Sru@noindent 8568114402Srumakes font @code{BAZ} special only if font @code{BAR} is active. We 8569114402Srufurther assume that @code{BAZ} is really a special font, i.e., the font 8570114402Srudescription file contains the @code{special} keyword, and that it 8571114402Srualso contains glyph @code{foo} with a special shape fitting to font 8572114402Sru@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at 8573114402Srufont position@tie{}1, and @code{BAZ} at position@tie{}2. 8574114402Sru 8575114402SruWe now switch to a new font @code{XXX}, trying to access glyph @code{foo} 8576114402Sruwhich is assumed to be missing. There are neither font-specific special 8577114402Srufonts for @code{XXX} nor any other fonts made special with the 8578114402Sru@code{special} request, so @code{gtroff} starts the search for special 8579114402Srufonts in the list of already mounted fonts, with increasing font 8580114402Srupositions. Consequently, it finds @code{BAZ} before @code{FOO} even for 8581114402Sru@code{XXX} which is not the intended behaviour. 8582104862Sru@end itemize 8583104862Sru 858475584Sru@xref{Font Files}, and @ref{Special Fonts}, for more details. 858555839Sasmodai 8586104862Sru@cindex list of available glyphs (@cite{groff_char(7)} man page) 8587104862Sru@cindex available glyphs, list (@cite{groff_char(7)} man page) 8588104862Sru@cindex glyphs, available, list (@cite{groff_char(7)} man page) 8589104862SruThe list of available symbols is device dependent; see the 8590114402Sru@cite{groff_char(7)} man page for a complete list of all glyphs. For 8591114402Sruexample, say 859275584Sru 8593104862Sru@Example 8594104862Sruman -Tdvi groff_char > groff_char.dvi 8595104862Sru@endExample 8596104862Sru 8597104862Sru@noindent 8598104862Srufor a list using the default DVI fonts (not all versions of the 8599104862Sru@code{man} program support the @option{-T} option). If you want to 8600104862Sruuse an additional macro package to change the used fonts, @code{groff} 8601104862Srumust be called directly: 8602104862Sru 8603104862Sru@Example 8604104862Srugroff -Tdvi -mec -man groff_char.7 > groff_char.dvi 8605104862Sru@endExample 8606104862Sru 8607114402Sru@cindex composite glyph names 8608114402Sru@cindex glyph names, composite 8609114402Sru@cindex groff glyph list (GGL) 8610114402Sru@cindex GGL (groff glyph list) 8611114402Sru@cindex adobe glyph list (AGL) 8612114402Sru@cindex AGL (adobe glyph list) 8613114402SruGlyph names not listed in groff_char(7) are derived algorithmically, 8614114402Sruusing a simplified version of the Adobe Glyph List (AGL) algorithm 8615114402Srudescribed in 8616114402Sru@uref{http://partners.adobe.com/asn/developer/typeforum/unicodegn.html}. 8617114402SruThe (frozen) set of glyph names which can't be derived algorithmically 8618114402Sruis called @dfn{groff glyph list (GGL)}. 8619114402Sru 8620114402Sru@itemize @bullet 8621114402Sru@item 8622114402SruA glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is 8623114402Srunot a composite character will be named 8624114402Sru@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an 8625114402Sruuppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E}, 8626114402Sru@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at 8627114402Sruleast four @code{X} digits; if necessary, add leading zeroes (after the 8628114402Sru@samp{u}). No zero padding is allowed for character codes greater than 8629114402Sru0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF 8630114402Srurepresented with character codes from the surrogate area U+D800-U+DFFF) 8631114402Sruare not allowed too. 8632114402Sru 8633114402Sru@item 8634114402SruA glyph representing more than a single input character will be named 8635114402Sru 8636114402Sru@display 8637114402Sru@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{} 8638114402Sru@end display 8639114402Sru 8640114402Sru@noindent 8641114402SruExample: @code{u0045_0302_0301}. 8642114402Sru 8643114402SruFor simplicity, all Unicode characters which are composites must be 8644114402Srudecomposed maximally (this is normalization form@tie{}D in the Unicode 8645114402Srustandard); for example, @code{u00CA_0301} is not a valid glyph name 8646114402Srusince U+00CA (@sc{latin capital letter e with circumflex}) can be 8647114402Srufurther decomposed into U+0045 (@sc{latin capital letter e}) and U+0302 8648114402Sru(@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the 8649114402Sruglyph name for U+1EBE, @sc{latin capital letter e with circumflex and 8650114402Sruacute}. 8651114402Sru 8652114402Sru@item 8653114402Srugroff maintains a table to decompose all algorithmically derived glyph 8654114402Srunames which are composites itself. For example, @code{u0100} (@sc{latin 8655114402Sruletter a with macron}) will be automatically decomposed into 8656114402Sru@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred 8657114402Sruto an algorithmically derived glyph name; groff also automatically does 8658114402Sruthe mapping. Example: The glyph @code{u0045_0302} will be mapped to 8659114402Sru@code{^E}. 8660114402Sru 8661114402Sru@item 8662114402Sruglyph names of the GGL can't be used in composite glyph names; for 8663114402Sruexample, @code{^E_u0301} is invalid. 8664114402Sru@end itemize 8665114402Sru 8666114402Sru@DefescList {\\, @lparen{}, nm, } 8667114402Sru@DefescItem {\\, @lbrack{}, name, @rbrack} 8668114402Sru@DefescListEnd {\\, @lbrack{}, component1 component2 @dots{}, @rbrack} 8669114402SruInsert a symbol @var{name} (two-character name @var{nm}) or a composite 8670114402Sruglyph with component glyphs @var{component1}, @var{component2}, 8671114402Sru@enddots{} There is no special syntax for one-character names -- the 8672114402Srunatural form @samp{\@var{n}} would collide with escapes.@footnote{Note 8673114402Sruthat a one-character symbol is not the same as an input character, i.e., 8674114402Sruthe character @code{a} is not the same as @code{\[a]}. By default, 8675114402Sru@code{groff} defines only a single one-character symbol, @code{\[-]}; it 8676114402Sruis usually accessed as @code{\-}. On the other hand, @code{gtroff} has 8677114402Sruthe special feature that @code{\[char@var{XXX}]} is the same as the 8678114402Sruinput character with character code @var{XXX}. For example, 8679114402Sru@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} 8680114402Sruencoding is active.} 8681114402Sru 8682114402SruIf @var{name} is undefined, a warning of type @samp{char} is generated, 8683114402Sruand the escape is ignored. @xref{Debugging}, for information about 8684114402Sruwarnings. 8685114402Sru 8686114402Srugroff resolves @code{\[...]} with more than a single component as 8687114402Srufollows: 8688114402Sru 8689114402Sru@itemize @bullet 8690114402Sru@item 8691114402SruAny component which is found in the GGL will be converted to the 8692114402Sru@code{u@var{XXXX}} form. 8693114402Sru 8694114402Sru@item 8695114402SruAny component @code{u@var{XXXX}} which is found in the list of 8696114402Srudecomposable glyphs will be decomposed. 8697114402Sru 8698114402Sru@item 8699114402SruThe resulting elements are then concatenated with @samp{_} inbetween, 8700114402Srudropping the leading @samp{u} in all elements but the first. 8701114402Sru@end itemize 8702114402Sru 8703114402SruNo check for the existence of any component (similar to @code{tr} 8704114402Srurequest) will be done. 8705114402Sru 8706114402SruExamples: 8707114402Sru 8708114402Sru@table @code 8709114402Sru@item \[A ho] 8710114402Sru@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the 8711114402Srufinal glyph name would be @code{u0041_02DB}. Note this is not the 8712114402Sruexpected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for 8713114402Srua proper composite a non-spacing ogonek (U+0328) is necessary. Looking 8714114402Sruinto the file @file{composite.tmac} one can find @w{@samp{.composite ho 8715114402Sruu0328}} which changes the mapping of @samp{ho} while a composite glyph 8716114402Sruname is constructed, causing the final glyph name to be 8717114402Sru@code{u0041_0328}. 8718114402Sru 8719114402Sru@item \[^E u0301] 8720114402Sru@itemx \[^E aa] 8721114402Sru@itemx \[E a^ aa] 8722114402Sru@itemx \[E ^ '] 8723114402Sru@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is 8724114402Sru@code{u0045_0302_0301} in all forms (assuming proper calls of the 8725114402Sru@code{composite} request). 8726114402Sru@end table 8727114402Sru 8728114402SruIt is not possible to define glyphs with names like @w{@samp{A ho}} 8729114402Sruwithin a groff font file. This is not really a limitation; instead, you 8730114402Sruhave to define @code{u0041_0328}. 873175584Sru@endDefesc 873275584Sru 873375584Sru@Defesc {\\C, ', xxx, '} 8734104862Sru@cindex named character (@code{\C}) 8735104862Sru@cindex character, named (@code{\C}) 8736104862SruTypeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a 8737104862Srumisnomer since it accesses an output glyph.} Normally it is more 8738104862Sruconvenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage 8739104862Sruthat it is compatible with newer versions of @acronym{AT&T} 8740104862Sru@code{troff} and is available in compatibility mode. 874175584Sru@endDefesc 874275584Sru 8743114402Sru@Defreq {composite, from to} 8744114402Sru@pindex composite.tmac 8745114402SruMap glyph name @var{from} to glyph name @var{to} if it is used in 8746114402Sru@code{\[...]} with more than one component. See above for examples. 8747114402Sru 8748114402SruThis mapping is based on glyph names only; no check for the existence of 8749114402Srueither glyph is done. 8750114402Sru 8751114402SruA set of default mappings for many accents can be found in the file 8752114402Sru@file{composite.tmac} which is loaded at start-up. 8753114402Sru@endDefreq 8754114402Sru 875575584Sru@Defesc {\\N, ', n, '} 8756104862Sru@cindex numbered glyph (@code{\N}) 8757104862Sru@cindex glyph, numbered (@code{\N}) 8758104862Sru@cindex @code{char} request, used with @code{\N} 8759104862Sru@cindex Unicode 8760114402SruTypeset the glyph with code@tie{}@var{n} in the current font 8761114402Sru(@code{n}@tie{}is @strong{not} the input character code). The 8762114402Srunumber @var{n}@tie{}can be any non-negative decimal integer. Most devices 8763114402Sruonly have glyphs with codes between 0 and@tie{}255; the Unicode 8764104862Sruoutput device uses codes in the range 0--65535. If the current 8765104862Srufont does not contain a glyph with that code, special fonts are 8766104862Sru@emph{not} searched. The @code{\N} escape sequence can be 8767104862Sruconveniently used in conjunction with the @code{char} request: 876875584Sru 876975584Sru@Example 877075584Sru.char \[phone] \f[ZD]\N'37' 877175584Sru@endExample 877275584Sru 877369626Sru@noindent 877469626Sru@pindex DESC 8775104862Sru@cindex unnamed glyphs 8776104862Sru@cindex glyphs, unnamed 8777104862SruThe code of each glyph is given in the fourth column in the font 877875584Srudescription file after the @code{charset} command. It is possible to 8779104862Sruinclude unnamed glyphs in the font description file by using a 878075584Sruname of @samp{---}; the @code{\N} escape sequence is the only way to 878175584Sruuse these. 8782114402Sru 8783114402SruNo kerning is applied to glyphs accessed with @code{\N}. 878475584Sru@endDefesc 878555839Sasmodai 8786104862SruSome escape sequences directly map onto special glyphs. 878769626Sru 8788104862Sru@Defesc {\\', , , } 8789104862SruThis is a backslash followed by the apostrophe character, @acronym{ASCII} 8790104862Srucharacter @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same 8791104862Sruas @code{\[aa]}, the acute accent. 8792104862Sru@endDefesc 8793104862Sru 8794104862Sru@Defesc {\\`, , , } 8795104862SruThis is a backslash followed by @acronym{ASCII} character @code{0x60} 8796104862Sru(@acronym{EBCDIC} character @code{0x79} usually). The same as 8797104862Sru@code{\[ga]}, the grave accent. 8798104862Sru@endDefesc 8799104862Sru 8800104862Sru@Defesc {\\-, , , } 8801104862SruThis is the same as @code{\[-]}, the minus sign in the current font. 8802104862Sru@endDefesc 8803104862Sru 880475584Sru@Defreq {cflags, n c1 c2 @dots{}} 8805104862Sru@cindex glyph properties (@code{cflags}) 8806104862Sru@cindex character properties (@code{cflags}) 8807104862Sru@cindex properties of glyphs (@code{cflags}) 8808104862Sru@cindex properties of characters (@code{cflags}) 8809104862SruInput characters and symbols have certain properties associated 8810104862Sruwith it.@footnote{Note that the output glyphs themselves don't have 8811104862Srusuch properties. For @code{gtroff}, a glyph is a numbered box with 8812104862Srua given width, depth, and height, nothing else. All manipulations 8813104862Sruwith the @code{cflags} request work on the input level.} These 8814104862Sruproperties can be modified with the @code{cflags} request. The 8815104862Srufirst argument is the sum of the desired flags and the remaining 8816104862Sruarguments are the characters or symbols to have those properties. 8817104862SruIt is possible to omit the spaces between the characters or symbols. 881869626Sru 881955839Sasmodai@table @code 882055839Sasmodai@item 1 8821104862Sru@cindex end-of-sentence characters 8822104862Sru@cindex characters, end-of-sentence 8823104862SruThe character ends sentences (initially characters @samp{.?!} have this 8824104862Sruproperty). 882569626Sru 882655839Sasmodai@item 2 882769626Sru@cindex hyphenating characters 882869626Sru@cindex characters, hyphenation 8829104862SruLines can be broken before the character (initially no characters have 8830104862Sruthis property). 883169626Sru 883255839Sasmodai@item 4 8833104862Sru@cindex @code{hy} glyph, and @code{cflags} 8834104862Sru@cindex @code{em} glyph, and @code{cflags} 8835104862SruLines can be broken after the character (initially the character 8836114402Sru@samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property). 883769626Sru 883855839Sasmodai@item 8 883969626Sru@cindex overlapping characters 884069626Sru@cindex characters, overlapping 8841104862Sru@cindex @code{ul} glyph, and @code{cflags} 8842104862Sru@cindex @code{rn} glyph, and @code{cflags} 8843104862Sru@cindex @code{ru} glyph, and @code{cflags} 8844114402Sru@cindex @code{radicalex} glyph, and @code{cflags} 8845114402Sru@cindex @code{sqrtex} glyph, and @code{cflags} 8846104862SruThe character overlaps horizontally (initially the symbols 8847114402Sru@samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]}, @samp{\[radicalex}, and 8848114402Sru@samp{\[sqrtex]} have this property). 884969626Sru 885055839Sasmodai@item 16 8851104862Sru@cindex @code{br} glyph, and @code{cflags} 8852114402SruThe character overlaps vertically (initially symbol @samp{\[br]} has 8853104862Sruthis property). 885469626Sru 885555839Sasmodai@item 32 885669626Sru@cindex transparent characters 885769626Sru@cindex character, transparent 8858104862Sru@cindex @code{"}, at end of sentence 8859104862Sru@cindex @code{'}, at end of sentence 8860104862Sru@cindex @code{)}, at end of sentence 8861104862Sru@cindex @code{]}, at end of sentence 8862104862Sru@cindex @code{*}, at end of sentence 8863104862Sru@cindex @code{dg} glyph, at end of sentence 8864104862Sru@cindex @code{rq} glyph, at end of sentence 8865104862SruAn end-of-sentence character followed by any number of characters with 886675584Sruthis property is treated as the end of a sentence if followed by a 886775584Srunewline or two spaces; in other words the character is 8868104862Sru@dfn{transparent} for the purposes of end-of-sentence recognition -- 886975584Sruthis is the same as having a zero space factor in @TeX{} (initially 8870114402Srucharacters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have 8871114402Sruthis property). 887255839Sasmodai@end table 887375584Sru@endDefreq 887455839Sasmodai 8875104862Sru@DefreqList {char, g [@Var{string}]} 8876114402Sru@DefreqItem {fchar, g [@Var{string}]} 8877114402Sru@DefreqItem {fschar, f g [@Var{string}]} 8878114402Sru@DefreqListEnd {schar, g [@Var{string}]} 8879104862Sru@cindex defining character (@code{char}) 8880114402Sru@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar}) 8881104862Sru@cindex character, defining (@code{char}) 8882114402Sru@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar}) 8883114402Sru@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar}) 8884104862Sru@cindex creating new characters (@code{char}) 8885104862Sru@cindex defining symbol (@code{char}) 8886104862Sru@cindex symbol, defining (@code{char}) 8887104862Sru@cindex defining glyph (@code{char}) 8888104862Sru@cindex glyph, defining (@code{char}) 8889104862Sru@cindex escape character, while defining glyph 8890104862Sru@cindex character, escape, while defining glyph 8891104862Sru@cindex @code{tr} request, and glyph definitions 8892104862Sru@cindex @code{cp} request, and glyph definitions 8893104862Sru@cindex @code{rc} request, and glyph definitions 8894104862Sru@cindex @code{lc} request, and glyph definitions 8895104862Sru@cindex @code{\l}, and glyph definitions 8896104862Sru@cindex @code{\L}, and glyph definitions 8897104862Sru@cindex @code{\&}, and glyph definitions 8898104862Sru@cindex @code{\e}, and glyph definitions 8899104862Sru@cindex @code{hcode} request, and glyph definitions 8900114402SruDefine a new glyph@tie{}@var{g} to be @var{string} (which can be 8901104862Sruempty).@footnote{@code{char} is a misnomer since an output glyph is 8902114402Srudefined.} Every time glyph@tie{}@var{g} needs to be printed, 890375584Sru@var{string} is processed in a temporary environment and the result is 890475584Sruwrapped up into a single object. Compatibility mode is turned off and 890575584Sruthe escape character is set to @samp{\} while @var{string} is being 890675584Sruprocessed. Any emboldening, constant spacing or track kerning is 890769626Sruapplied to this object rather than to individual characters in 8908104862Sru@var{string}. 8909104862Sru 8910114402SruA glyph defined by these requests can be used just 8911104862Srulike a normal glyph provided by the output device. In particular, 8912104862Sruother characters can be translated to it with the @code{tr} or 8913104862Sru@code{trin} requests; it can be made the leader character by the 8914104862Sru@code{lc} request; repeated patterns can be drawn with the glyph 8915104862Sruusing the @code{\l} and @code{\L} escape sequences; words containing 8916104862Sruthe glyph can be hyphenated correctly if the @code{hcode} request 8917104862Sruis used to give the glyph's symbol a hyphenation code. 8918104862Sru 8919104862SruThere is a special anti-recursion feature: Use of @code{g} within 8920104862Sruthe glyph's definition is handled like normal characters and symbols 8921104862Srunot defined with @code{char}. 8922104862Sru 8923104862SruNote that the @code{tr} and @code{trin} requests take precedence if 8924104862Sru@code{char} accesses the same symbol. 8925104862Sru 8926104862Sru@Example 8927104862Sru.tr XY 8928104862SruX 8929104862Sru @result{} Y 8930104862Sru.char X Z 8931104862SruX 8932104862Sru @result{} Y 8933104862Sru.tr XX 8934104862SruX 8935104862Sru @result{} Z 8936104862Sru@endExample 8937104862Sru 8938104862SruThe @code{fchar} request defines a fallback glyph: 8939104862Sru@code{gtroff} only checks for glyphs defined with @code{fchar} 8940104862Sruif it cannot find the glyph in the current font. 8941104862Sru@code{gtroff} carries out this test before checking special fonts. 8942114402Sru 8943114402Sru@code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff} 8944114402Sruchecks for glyphs defined with @code{fschar} after the list of fonts 8945114402Srudeclared as font-specific special fonts with the @code{fspecial} request, 8946114402Srubut before the list of fonts declared as global special fonts with the 8947114402Sru@code{special} request. 8948114402Sru 8949114402SruFinally, the @code{schar} request defines a global fallback glyph: 8950114402Sru@code{gtroff} checks for glyphs defined with @code{schar} after the list 8951114402Sruof fonts declared as global special fonts with the @code{special} request, 8952114402Srubut before the already mounted special fonts. 8953114402Sru 8954114402Sru@xref{Using Symbols}, for a detailed description of the glyph 8955114402Srusearching mechanism in @code{gtroff}. 895675584Sru@endDefreq 895769626Sru 8958114402Sru@DefreqList {rchar, c1 c2 @dots{}} 8959114402Sru@DefreqListEnd {rfschar, f c1 c2 @dots{}} 8960114402Sru@cindex removing glyph definition (@code{rchar}, @code{rfschar}) 8961114402Sru@cindex glyph, removing definition (@code{rchar}, @code{rfschar}) 8962114402Sru@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar}) 8963114402SruRemove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{} 8964114402SruThis undoes the effect of a @code{char}, @code{fchar}, or 8965114402Sru@code{schar} request. 896655839Sasmodai 896775584SruIt is possible to omit the whitespace between arguments. 8968114402Sru 8969114402SruThe request @code{rfschar} removes glyph definitions defined with 8970114402Sru@code{fschar} for glyph@tie{}f. 897175584Sru@endDefreq 897275584Sru 897369626Sru@xref{Special Characters}. 897455839Sasmodai 897569626Sru@c --------------------------------------------------------------------- 897669626Sru 8977114402Sru@node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols 897875584Sru@subsection Special Fonts 897975584Sru@cindex special fonts 898075584Sru@cindex fonts, special 898175584Sru 8982104862SruSpecial fonts are those that @code{gtroff} searches 8983104862Sruwhen it cannot find the requested glyph in the current font. 8984104862SruThe Symbol font is usually a special font. 898575584Sru 8986104862Sru@code{gtroff} provides the following two requests to add more special 8987104862Srufonts. @xref{Using Symbols}, for a detailed description of the glyph 8988104862Srusearching mechanism in @code{gtroff}. 898975584Sru 8990104862SruUsually, only non-TTY devices have special fonts. 8991104862Sru 8992114402Sru@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]} 8993114402Sru@DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]} 8994104862Sru@kindex fonts 8995104862Sru@pindex DESC 8996114402SruUse the @code{special} request to define special fonts. Initially, this 8997114402Srulist is empty. 8998104862Sru 8999114402SruUse the @code{fspecial} request to designate special fonts only when 9000114402Srufont@tie{}@var{f} is active. Initially, this list is empty. 9001114402Sru 9002114402SruPrevious calls to @code{special} or @code{fspecial} are overwritten; 9003114402Sruwithout arguments, the particular list of special fonts is set to empty. 9004114402SruSpecial fonts are searched in the order they appear as arguments. 9005114402Sru 9006114402SruAll fonts which appear in a call to @code{special} or @code{fspecial} are 9007114402Sruloaded. 9008114402Sru 9009114402Sru@xref{Using Symbols}, for the exact search order of glyphs. 9010104862Sru@endDefreq 9011104862Sru 901275584Sru@c --------------------------------------------------------------------- 901375584Sru 9014114402Sru@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols 901555839Sasmodai@subsection Artificial Fonts 901655839Sasmodai@cindex artificial fonts 901755839Sasmodai@cindex fonts, artificial 901855839Sasmodai 9019104862SruThere are a number of requests and escapes for artificially creating 9020104862Srufonts. These are largely vestiges of the days when output devices 9021104862Srudid not have a wide variety of fonts, and when @code{nroff} and 9022104862Sru@code{troff} were separate programs. Most of them are no longer 9023104862Srunecessary in GNU @code{troff}. Nevertheless, they are supported. 902455839Sasmodai 9025104862Sru@DefescList {\\H, ', height, '} 9026114402Sru@DefescItem {\\H, ', @t{+}height, '} 9027114402Sru@DefescItem {\\H, ', @t{-}height, '} 9028114402Sru@DefregListEnd {.height} 9029104862Sru@cindex changing the font height (@code{\H}) 9030104862Sru@cindex font height, changing (@code{\H}) 9031104862Sru@cindex height, font, changing (@code{\H}) 9032104862SruChange (increment, decrement) the height of the current font, but not 9033104862Sruthe width. If @var{height} is zero, restore the original height. 9034104862SruDefault scaling indicator is @samp{z}. 9035104862Sru 9036114402SruThe read-only number register @code{.height} contains the font height as 9037114402Sruset by @code{\H}. 9038114402Sru 9039104862SruCurrently, only the @option{-Tps} device supports this feature. 9040104862Sru 9041104862SruNote that @code{\H} doesn't produce an input token in @code{gtroff}. 9042104862SruAs a consequence, it can be used in requests like @code{mc} (which 9043104862Sruexpects a single character as an argument) to change the font on 9044104862Sruthe fly: 9045104862Sru 9046104862Sru@Example 9047104862Sru.mc \H'+5z'x\H'0' 9048104862Sru@endExample 9049104862Sru 9050104862SruIn compatibility mode, @code{gtroff} behaves differently: If an 9051104862Sruincrement or decrement is used, it is always taken relative to the 9052104862Srucurrent point size and not relative to the previously selected font 9053104862Sruheight. Thus, 9054104862Sru 9055104862Sru@Example 9056104862Sru.cp 1 9057104862Sru\H'+5'test \H'+5'test 9058104862Sru@endExample 9059104862Sru 9060104862Sru@noindent 9061104862Sruprints the word @samp{test} twice with the same font height (five 9062104862Srupoints larger than the current font size). 9063104862Sru@endDefesc 9064104862Sru 9065104862Sru@DefescList {\\S, ', slant, '} 9066114402Sru@DefregListEnd {.slant} 9067104862Sru@cindex changing the font slant (@code{\S}) 9068104862Sru@cindex font slant, changing (@code{\S}) 9069104862Sru@cindex slant, font, changing (@code{\S}) 9070104862SruSlant the current font by @var{slant} degrees. Positive values slant 9071114402Sruto the right. Only integer values are possible. 9072104862Sru 9073114402SruThe read-only number register @code{.slant} contains the font slant as 9074114402Sruset by @code{\S}. 9075114402Sru 9076104862SruCurrently, only the @option{-Tps} device supports this feature. 9077104862Sru 9078104862SruNote that @code{\S} doesn't produce an input token in @code{gtroff}. 9079104862SruAs a consequence, it can be used in requests like @code{mc} (which 9080104862Sruexpects a single character as an argument) to change the font on 9081104862Sruthe fly: 9082104862Sru 9083104862Sru@Example 9084104862Sru.mc \S'20'x\S'0' 9085104862Sru@endExample 9086104862Sru 9087104862SruThis request is incorrectly documented in the original @acronym{UNIX} 9088104862Srutroff manual; the slant is always set to an absolute value. 9089104862Sru@endDefesc 9090104862Sru 909175584Sru@Defreq {ul, [@Var{lines}]} 9092104862Sru@cindex underlining (@code{ul}) 9093104862SruThe @code{ul} request normally underlines subsequent lines if a TTY 909475584Sruoutput device is used. Otherwise, the lines are printed in italics 909575584Sru(only the term `underlined' is used in the following). The single 909675584Sruargument is the number of input lines to be underlined; with no 909775584Sruargument, the next line is underlined. If @var{lines} is zero or 909875584Srunegative, stop the effects of @code{ul} (if it was active). Requests 909975584Sruand empty lines do not count for computing the number of underlined 910075584Sruinput lines, even if they produce some output like @code{tl}. Lines 910175584Sruinserted by macros (e.g.@: invoked by a trap) do count. 910255839Sasmodai 910375584SruAt the beginning of @code{ul}, the current font is stored and the 910475584Sruunderline font is activated. Within the span of a @code{ul} request, 910575584Sruit is possible to change fonts, but after the last line affected by 910675584Sru@code{ul} the saved font is restored. 910775584Sru 9108104862SruThis number of lines still to be underlined is associated with the 9109104862Srucurrent environment (@pxref{Environments}). The underline font can be 9110104862Sruchanged with the @code{uf} request. 911175584Sru 911275584Sru@c XXX @xref should be changed to grotty 911375584Sru 9114104862Sru@c @xref{Troff and Nroff Mode}, for a discussion how underlining is 9115104862Sru@c implemented in for TTY output devices, and which problems can arise. 911675584Sru 911775584SruThe @code{ul} request does not underline spaces. 911875584Sru@endDefreq 911975584Sru 912075584Sru@Defreq {cu, [@Var{lines}]} 9121104862Sru@cindex continuous underlining (@code{cu}) 9122104862Sru@cindex underlining, continuous (@code{cu}) 912375584SruThe @code{cu} request is similar to @code{ul} but underlines spaces as 9124104862Sruwell (if a TTY output device is used). 912575584Sru@endDefreq 912655839Sasmodai 912775584Sru@Defreq {uf, font} 9128104862Sru@cindex underline font (@code{uf}) 9129104862Sru@cindex font for underlining (@code{uf}) 913075584SruSet the underline font (globally) used by @code{ul} and @code{cu}. By 9131114402Srudefault, this is the font at position@tie{}2. @var{font} can be either 913275584Srua non-negative font position or the name of a font. 913375584Sru@endDefreq 913455839Sasmodai 9135104862Sru@DefreqList {bd, font [@Var{offset}]} 9136104862Sru@DefreqItem {bd, font1 font2 [@Var{offset}]} 9137104862Sru@DefregListEnd {.b} 9138104862Sru@cindex imitating bold face (@code{bd}) 9139104862Sru@cindex bold face, imitating (@code{bd}) 9140104862SruArtificially create a bold font by printing each glyph twice, 914175584Sruslightly offset. 914255839Sasmodai 914375584SruTwo syntax forms are available. 914475584Sru 914575584Sru@itemize @bullet 914675584Sru@item 914775584SruImitate a bold font unconditionally. The first argument specifies the 914875584Srufont to embolden, and the second is the number of basic units, minus 9149104862Sruone, by which the two glyphs are offset. If the second argument is 915075584Srumissing, emboldening is turned off. 915175584Sru 915275584Sru@var{font} can be either a non-negative font position or the name of a 915375584Srufont. 915475584Sru 915575584Sru@var{offset} is available in the @code{.b} read-only register if a 915675584Sruspecial font is active; in the @code{bd} request, its default unit is 915775584Sru@samp{u}. 915875584Sru 9159104862Sru@cindex @code{fspecial} request, and imitating bold 916075584Sru@kindex special 916175584Sru@cindex embolding of special fonts 916275584Sru@cindex special fonts, emboldening 916375584Sru@item 916475584SruImitate a bold form conditionally. Embolden @var{font1} by 916575584Sru@var{offset} only if font @var{font2} is the current font. This 916675584Srucommand can be issued repeatedly to set up different emboldening 916775584Sruvalues for different current fonts. If the second argument is 916875584Srumissing, emboldening is turned off for this particular current font. 916975584Sru 917075584SruThis affects special fonts only (either set up with the @code{special} 917175584Srucommand in font files or with the @code{fspecial} request). 917275584Sru@end itemize 917375584Sru@endDefreq 917475584Sru 917575584Sru@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 9176104862Sru@cindex constant glyph space mode (@code{cs}) 9177104862Sru@cindex mode for constant glyph space (@code{cs}) 9178104862Sru@cindex glyph, constant space 9179104862Sru@cindex @code{ps} request, and constant glyph space mode 9180104862SruSwitch to and from @dfn{constant glyph space mode}. If activated, the 9181104862Sruwidth of every glyph is @math{@var{width}/36} ems. The em size is 918275584Srugiven absolutely by @var{em-size}; if this argument is missing, the em 918375584Sruvalue is taken from the current font size (as set with the @code{ps} 918475584Srurequest) when the font is effectively in use. Without second and 9185104862Sruthird argument, constant glyph space mode is deactivated. 918675584Sru 9187104862SruDefault scaling indicator for @var{em-size} is @samp{z}; @var{width} is 9188104862Sruan integer. 918975584Sru@endDefreq 919075584Sru 919169626Sru@c --------------------------------------------------------------------- 919255839Sasmodai 9193114402Sru@node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols 919455839Sasmodai@subsection Ligatures and Kerning 919555839Sasmodai@cindex ligatures and kerning 919655839Sasmodai@cindex kerning and ligatures 919755839Sasmodai 9198104862SruLigatures are groups of characters that are run together, i.e, producing 9199104862Srua single glyph. For example, the letters `f' and `i' can form a 9200104862Sruligature `fi' as in the word `file'. This produces a cleaner look 9201104862Sru(albeit subtle) to the printed output. Usually, ligatures are not 9202104862Sruavailable in fonts for TTY output devices. 920355839Sasmodai 920475584SruMost @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 9205104862Srutypesetter that was the target of @acronym{AT&T} @code{troff} also 9206104862Srusupported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or 9207104862Sru`expert' fonts may include ligatures for `ft' and `ct', although GNU 920875584Sru@code{troff} does not support these (yet). 920969626Sru 9210114402SruOnly the current font is checked for ligatures and kerns; neither special 9211114402Srufonts nor entities defined with the @code{char} request (and its siblings) 9212114402Sruare taken into account. 9213114402Sru 9214104862Sru@DefreqList {lg, [@Var{flag}]} 9215104862Sru@DefregListEnd {.lg} 9216104862Sru@cindex activating ligatures (@code{lg}) 9217104862Sru@cindex ligatures, activating (@code{lg}) 9218104862Sru@cindex ligatures enabled register (@code{.lg}) 9219104862SruSwitch the ligature mechanism on or off; if the parameter is non-zero 9220104862Sruor missing, ligatures are enabled, otherwise disabled. Default is on. 9221104862SruThe current ligature mode can be found in the read-only number register 9222114402Sru@code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise). 922355839Sasmodai 9224114402SruSetting the ligature mode to@tie{}2 enables the two-character ligatures 922575584Sru(fi, fl, and ff) and disables the three-character ligatures (ffi and 922675584Sruffl). 922775584Sru@endDefreq 922855839Sasmodai 922975584Sru@dfn{Pairwise kerning} is another subtle typesetting mechanism that 9230104862Srumodifies the distance between a glyph pair to improve readability. 923175584SruIn most cases (but not always) the distance is decreased. 923275584Sru@ifnotinfo 923375584SruFor example, compare the combination of the letters `V' and `A'. With 923475584Srukerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 923575584Sru@end ifnotinfo 9236104862SruTypewriter-like fonts and fonts for terminals where all glyphs 923775584Sruhave the same width don't use kerning. 923869626Sru 9239104862Sru@DefreqList {kern, [@Var{flag}]} 9240104862Sru@DefregListEnd {.kern} 9241104862Sru@cindex activating kerning (@code{kern}) 9242104862Sru@cindex kerning, activating (@code{kern}) 9243104862Sru@cindex kerning enabled register (@code{.kern}) 9244104862SruSwitch kerning on or off. If the parameter is non-zero or missing, 9245104862Sruenable pairwise kerning, otherwise disable it. The read-only number 9246114402Sruregister @code{.kern} is set to@tie{}1 if pairwise kerning is enabled, 9247114402Sru0@tie{}otherwise. 924875584Sru 9249104862Sru@cindex zero width space character (@code{\&}) 9250104862Sru@cindex character, zero width space (@code{\&}) 9251104862Sru@cindex space character, zero width (@code{\&}) 925255839SasmodaiIf the font description file contains pairwise kerning information, 9253104862Sruglyphs from that font are kerned. Kerning between two glyphs 925475584Srucan be inhibited by placing @code{\&} between them: @samp{V\&A}. 925555839Sasmodai 925675584Sru@xref{Font File Format}. 925775584Sru@endDefreq 925855839Sasmodai 925969626Sru@cindex track kerning 926069626Sru@cindex kerning, track 9261104862Sru@dfn{Track kerning} expands or reduces the space between glyphs. 926275584SruThis can be handy, for example, if you need to squeeze a long word 926375584Sruonto a single line or spread some text to fill a narrow column. It 926475584Srumust be used with great care since it is usually considered bad 926575584Srutypography if the reader notices the effect. 926669626Sru 926775584Sru@Defreq {tkf, f s1 n1 s2 n2} 9268104862Sru@cindex activating track kerning (@code{tkf}) 9269104862Sru@cindex track kerning, activating (@code{tkf}) 9270114402SruEnable track kerning for font@tie{}@var{f}. If the current font 9271114402Sruis@tie{}@var{f} the width of every glyph is increased by an amount 927275584Srubetween @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 927375584Sruthe current point size is less than or equal to @var{s1} the width is 927475584Sruincreased by @var{n1}; if it is greater than or equal to @var{s2} the 927575584Sruwidth is increased by @var{n2}; if the point size is greater than or 927675584Sruequal to @var{s1} and less than or equal to @var{s2} the increase in 927775584Sruwidth is a linear function of the point size. 927869626Sru 9279104862SruThe default scaling indicator is @samp{z} for @var{s1} and @var{s2}, 9280104862Sru@samp{p} for @var{n1} and @var{n2}. 9281104862Sru 9282104862SruNote that the track kerning amount is added even to the rightmost glyph 9283104862Sruin a line; for large values it is thus recommended to increase the line 9284104862Srulength by the same amount to compensate it. 928575584Sru@endDefreq 928669626Sru 928775584SruSometimes, when typesetting letters of different fonts, more or less 928875584Sruspace at such boundaries are needed. There are two escapes to help 928975584Sruwith this. 929069626Sru 929175584Sru@Defesc {\\/, , , } 9292104862Sru@cindex italic correction (@code{\/}) 9293104862Sru@cindex correction, italic (@code{\/}) 9294104862Sru@cindex correction between italic and roman glyph (@code{\/}, @code{\,}) 9295104862Sru@cindex roman glyph, correction after italic glyph (@code{\/}) 9296104862Sru@cindex italic glyph, correction before roman glyph (@code{\/}) 9297104862Sru@cindex glyph, italic correction (@code{\/}) 9298104862SruIncrease the width of the preceding glyph so that the spacing 9299104862Srubetween that glyph and the following glyph is correct if the 9300104862Srufollowing glyph is a roman glyph. For example, if an 9301114402Sruitalic@tie{}@code{f} is immediately followed by a roman right 9302114402Sruparenthesis, then in many fonts the top right portion of the@tie{}@code{f} 930375584Sruoverlaps the top left of the right parenthesis. Use this escape 9304104862Srusequence whenever an italic glyph is immediately followed by a 9305104862Sruroman glyph without any intervening space. This small amount of 930675584Sruspace is also called @dfn{italic correction}. 930775584Sru 930875584Sru@iftex 930969626Sru@example 931075584Sru@group 931175584Sru\f[I]f\f[R]) 931275584Sru @result{} {@it f}@r{)} 931375584Sru\f[I]f\/\f[R]) 931475584Sru @result{} @i{f}@r{)} 931575584Sru@end group 931669626Sru@end example 931775584Sru@end iftex 931875584Sru@endDefesc 931969626Sru 932075584Sru@Defesc {\\\,, , , } 9321104862Sru@cindex left italic correction (@code{\,}) 9322104862Sru@cindex correction, left italic (@code{\,}) 9323104862Sru@cindex glyph, left italic correction (@code{\,}) 9324104862Sru@cindex roman glyph, correction before italic glyph (@code{\,}) 9325104862Sru@cindex italic glyph, correction after roman glyph (@code{\,}) 9326104862SruModify the spacing of the following glyph so that the spacing 9327104862Srubetween that glyph and the preceding glyph is correct if the 9328104862Srupreceding glyph is a roman glyph. Use this escape sequence 9329104862Sruwhenever a roman glyph is immediately followed by an italic 9330104862Sruglyph without any intervening space. In analogy to above, this 933175584Sruspace could be called @dfn{left italic correction}, but this term 933275584Sruisn't used widely. 933355839Sasmodai 933475584Sru@iftex 933575584Sru@example 933675584Sru@group 933775584Sruq\f[I]f 933875584Sru @result{} @r{q}@i{f} 933975584Sruq\,\f[I]f 934075584Sru @result{} @r{q}@math{@ptexcomma}@i{f} 934175584Sru@end group 934275584Sru@end example 934375584Sru@end iftex 934475584Sru@endDefesc 934555839Sasmodai 934675584Sru@Defesc {\\&, , , } 934775584SruInsert a zero-width character, which is invisible. Its intended use 934875584Sruis to stop interaction of a character with its surrounding. 934975584Sru 935075584Sru@itemize @bullet 935175584Sru@item 9352104862SruIt prevents the insertion of extra space after an end-of-sentence 935375584Srucharacter. 935475584Sru 935575584Sru@Example 935675584SruTest. 935775584SruTest. 935875584Sru @result{} Test. Test. 935975584SruTest.\& 936075584SruTest. 936175584Sru @result{} Test. Test. 936275584Sru@endExample 936375584Sru 936475584Sru@item 936575584SruIt prevents interpretation of a control character at the beginning of 936675584Sruan input line. 936775584Sru 936875584Sru@Example 936975584Sru.Test 937075584Sru @result{} warning: `Test' not defined 937175584Sru\&.Test 937275584Sru @result{} .Test 937375584Sru@endExample 937475584Sru 937575584Sru@item 9376104862SruIt prevents kerning between two glyphs. 937775584Sru 937875584Sru@ifnotinfo 937975584Sru@example 938075584Sru@group 938175584SruVA 938275584Sru @result{} @r{VA} 938375584SruV\&A 938475584Sru @result{} @r{V@w{}A} 938575584Sru@end group 938675584Sru@end example 938775584Sru@end ifnotinfo 938875584Sru 938975584Sru@item 939075584SruIt is needed to map an arbitrary character to nothing in the @code{tr} 939175584Srurequest (@pxref{Character Translations}). 939275584Sru@end itemize 939375584Sru@endDefesc 939475584Sru 9395104862Sru@Defesc {\\), , , } 9396104862SruThis escape is similar to @code{\&} except that it behaves like a 9397104862Srucharacter declared with the @code{cflags} request to be transparent 9398104862Srufor the purposes of an end-of-sentence character. 939975584Sru 9400104862SruIts main usage is in macro definitions to protect against arguments 9401104862Srustarting with a control character. 9402104862Sru 9403104862Sru@Example 9404104862Sru.de xxx 9405104862Sru\)\\$1 9406104862Sru.. 9407104862Sru.de yyy 9408104862Sru\&\\$1 9409104862Sru.. 9410104862SruThis is a test.\c 9411104862Sru.xxx ' 9412104862SruThis is a test. 9413104862Sru @result{}This is a test.' This is a test. 9414104862SruThis is a test.\c 9415104862Sru.yyy ' 9416104862SruThis is a test. 9417104862Sru @result{}This is a test.' This is a test. 9418104862Sru@endExample 9419104862Sru@endDefesc 9420104862Sru 9421104862Sru 942269626Sru@c ===================================================================== 942369626Sru 9424114402Sru@node Sizes, Strings, Fonts and Symbols, gtroff Reference 942555839Sasmodai@section Sizes 942655839Sasmodai@cindex sizes 942755839Sasmodai 942855839Sasmodai@cindex baseline 942969626Sru@cindex type size 943069626Sru@cindex size of type 943169626Sru@cindex vertical spacing 943269626Sru@cindex spacing, vertical 943375584Sru@code{gtroff} uses two dimensions with each line of text, type size 943475584Sruand vertical spacing. The @dfn{type size} is approximately the height 9435104862Sruof the tallest glyph.@footnote{This is usually the parenthesis. 943675584SruNote that in most cases the real dimensions of the glyphs in a font 943775584Sruare @emph{not} related to its type size! For example, the standard 943875584Sru@sc{PostScript} font families `Times Roman', `Helvetica', and 943975584Sru`Courier' can't be used together at 10@dmn{pt}; to get acceptable 944075584Sruoutput, the size of `Helvetica' has to be reduced by one point, and 944175584Sruthe size of `Courier' must be increased by one point.} @dfn{Vertical 944275584Sruspacing} is the amount of space @code{gtroff} allows for a line of 9443114402Srutext; normally, this is about 20%@tie{}larger than the current type 944475584Srusize. Ratios smaller than this can result in hard-to-read text; 944575584Srularger than this, it spreads the text out more vertically (useful for 9446114402Sruterm papers). By default, @code{gtroff} uses 10@tie{}point type on 9447114402Sru12@tie{}point spacing. 944855839Sasmodai 944955839Sasmodai@cindex leading 945055839SasmodaiThe difference between type size and vertical spacing is known, by 9451104862Srutypesetters, as @dfn{leading} (this is pronounced `ledding'). 945255839Sasmodai 945355839Sasmodai@menu 945475584Sru* Changing Type Sizes:: 945575584Sru* Fractional Type Sizes:: 945655839Sasmodai@end menu 945755839Sasmodai 945869626Sru@c --------------------------------------------------------------------- 945969626Sru 946055839Sasmodai@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 946155839Sasmodai@subsection Changing Type Sizes 946255839Sasmodai 9463104862Sru@DefreqList {ps, [@Var{size}]} 9464104862Sru@DefreqItem {ps, @t{+}@Var{size}} 9465104862Sru@DefreqItem {ps, @t{-}@Var{size}} 9466104862Sru@DefescItem {\\s, , size, } 9467104862Sru@DefregListEnd {.s} 9468104862Sru@cindex changing type sizes (@code{ps}, @code{\s}) 9469104862Sru@cindex type sizes, changing (@code{ps}, @code{\s}) 9470104862Sru@cindex point sizes, changing (@code{ps}, @code{\s}) 947175584SruUse the @code{ps} request or the @code{\s} escape to change (increase, 947275584Srudecrease) the type size (in points). Specify @var{size} as either an 947375584Sruabsolute point size, or as a relative change from the current size. 9474114402SruThe size@tie{}0, or no argument, goes back to the previous size. 947555839Sasmodai 9476104862SruDefault scaling indicator of @code{size} is @samp{z}. If @code{size} 9477104862Sruis zero or negative, it is set to 1@dmn{u}. 947855839Sasmodai 9479104862Sru@cindex type size registers (@code{.s}, @code{.ps}) 9480104862Sru@cindex point size registers (@code{.s}, @code{.ps}) 948175584SruThe read-only number register @code{.s} returns the point size in 948275584Srupoints as a decimal fraction. This is a string. To get the point 948375584Srusize in scaled points, use the @code{.ps} register instead. 948475584Sru 948575584Sru@code{.s} is associated with the current environment 948675584Sru(@pxref{Environments}). 948775584Sru 948875584Sru@Example 948955839Sasmodaisnap, snap, 949055839Sasmodai.ps +2 949155839Sasmodaigrin, grin, 949255839Sasmodai.ps +2 949355839Sasmodaiwink, wink, \s+2nudge, nudge,\s+8 say no more! 949455839Sasmodai.ps 10 949575584Sru@endExample 949655839Sasmodai 949769626SruThe @code{\s} escape may be called in a variety of ways. Much like 949869626Sruother escapes there must be a way to determine where the argument ends 949969626Sruand the text begins. Any of the following forms are valid: 950055839Sasmodai 950169626Sru@table @code 950269626Sru@item \s@var{n} 9503114402SruSet the point size to @var{n}@tie{}points. @var{n}@tie{}must be either 9504114402Sru0 or in the range 4 to@tie{}39. 950569626Sru 950669626Sru@item \s+@var{n} 950769626Sru@itemx \s-@var{n} 9508114402SruIncrease or decrease the point size by @var{n}@tie{}points. 9509114402Sru@var{n}@tie{}must be exactly one digit. 951069626Sru 951169626Sru@item \s(@var{nn} 9512114402SruSet the point size to @var{nn}@tie{}points. @var{nn} must be exactly 951375584Srutwo digits. 951469626Sru 951569626Sru@item \s+(@var{nn} 951669626Sru@itemx \s-(@var{nn} 951769626Sru@itemx \s(+@var{nn} 951869626Sru@itemx \s(-@var{nn} 9519114402SruIncrease or decrease the point size by @var{nn}@tie{}points. @var{nn} 952075584Srumust be exactly two digits. 952169626Sru@end table 952269626Sru 9523104862SruNote that @code{\s} doesn't produce an input token in @code{gtroff}. 9524104862SruAs a consequence, it can be used in requests like @code{mc} (which 9525104862Sruexpects a single character as an argument) to change the font on 9526104862Sruthe fly: 9527104862Sru 9528104862Sru@Example 9529104862Sru.mc \s[20]x\s[0] 9530104862Sru@endExample 9531104862Sru 953275584Sru@xref{Fractional Type Sizes}, for yet another syntactical form of 953375584Sruusing the @code{\s} escape. 9534104862Sru@endDefreq 953569626Sru 9536104862Sru@Defreq {sizes, s1 s2 @dots{} sn [0]} 953755839SasmodaiSome devices may only have certain permissible sizes, in which case 953875584Sru@code{gtroff} rounds to the nearest permissible size. 9539104862SruThe @file{DESC} file specifies which sizes are permissible for the device. 9540104862Sru 9541104862SruUse the @code{sizes} request to change the permissible sizes 9542104862Srufor the current output device. 9543104862SruArguments are in scaled points; 9544104862Sruthe @code{sizescale} line in the 9545104862Sru@file{DESC} file for the output device 9546104862Sruprovides the scaling factor. 9547104862SruFor example, if the scaling factor is 1000, 9548114402Sruthen the value 12000 is 12@tie{}points. 9549104862Sru 9550104862SruEach argument can be a single point size (such as @samp{12000}), 9551104862Sruor a range of sizes (such as @samp{4000-72000}). 9552104862SruYou can optionally end the list with a zero. 955375584Sru@endDefreq 955455839Sasmodai 9555104862Sru@DefreqList {vs, [@Var{space}]} 9556104862Sru@DefreqItem {vs, @t{+}@Var{space}} 9557104862Sru@DefreqItem {vs, @t{-}@Var{space}} 9558104862Sru@DefregListEnd {.v} 9559104862Sru@cindex changing vertical line spacing (@code{vs}) 9560104862Sru@cindex vertical line spacing, changing (@code{vs}) 9561104862Sru@cindex vertical line spacing register (@code{.v}) 956275584SruChange (increase, decrease) the vertical spacing by @var{space}. The 9563104862Srudefault scaling indicator is @samp{p}. 956475584Sru 956575584SruIf @code{vs} is called without an argument, the vertical spacing is 956675584Srureset to the previous value before the last call to @code{vs}. 956775584Sru 9568104862Sru@cindex @code{.V} register, and @code{vs} 956975584Sru@code{gtroff} creates a warning of type @samp{range} if @var{space} is 9570114402Srunegative; the vertical spacing is then set to the vertical 957175584Sruresolution (as given in the @code{.V} register). 957275584Sru 957375584SruThe read-only number register @code{.v} contains the current vertical 957475584Sruspacing; it is associated with the current environment 957575584Sru(@pxref{Environments}). 957675584Sru@endDefreq 957775584Sru 9578104862Sru@cindex vertical line spacing, effective value 9579104862SruThe effective vertical line spacing consists of four components. 958069626Sru 9581104862Sru@itemize @bullet 9582104862Sru@item 9583104862SruThe vertical line spacing as set with the @code{vs} request. 958455839Sasmodai 9585104862Sru@cindex post-vertical line spacing 9586104862Sru@cindex line spacing, post-vertical (@code{pvs}) 9587104862Sru@item 9588104862SruThe @dfn{post-vertical line spacing} as set with the @code{pvs} request. 9589104862SruThis is vertical space which will be added after a line has been 9590104862Sruoutput. 9591104862Sru 9592104862Sru@cindex extra pre-vertical line space (@code{\x}) 9593104862Sru@cindex line space, extra pre-vertical (@code{\x}) 9594104862Sru@item 9595104862SruThe @dfn{extra pre-vertical line space} as set with the @code{\x} request, 9596104862Sruusing a negative value. This is vertical space which will be added once 9597104862Srubefore the current line has been output. 9598104862Sru 9599104862Sru@cindex extra post-vertical line space (@code{\x}) 9600104862Sru@cindex line space, extra post-vertical (@code{\x}) 9601104862Sru@item 9602104862SruThe @dfn{extra post-vertical line space} as set with the @code{\x} request, 9603104862Sruusing a positive value. This is vertical space which will be added once 9604104862Sruafter the current line has been output. 9605104862Sru@end itemize 9606104862Sru 9607104862Sru@cindex double-spacing (@code{vs}, @code{pvs}) 9608104862SruIt is usually better to use @code{vs} or @code{pvs} instead of @code{ls} 9609104862Sruto produce double-spaced documents: @code{vs} and @code{pvs} have a finer 9610104862Srugranularity for the inserted vertical space compared to @code{ls}; 9611104862Srufurthermore, certain preprocessors assume single-spacing. 9612104862Sru 9613104862Sru@xref{Manipulating Spacing}, for more details on the @code{\x} escape 9614104862Sruand the @code{ls} request. 9615104862Sru 9616104862Sru@DefreqList {pvs, [@Var{space}]} 9617104862Sru@DefreqItem {pvs, @t{+}@Var{space}} 9618104862Sru@DefreqItem {pvs, @t{-}@Var{space}} 9619104862Sru@DefregListEnd {.pvs} 9620104862Sru@cindex @code{ls} request, alternative to (@code{pvs}) 9621104862Sru@cindex post-vertical line spacing, changing (@code{pvs}) 9622104862Sru@cindex post-vertical line spacing register (@code{.pvs}) 9623104862SruChange (increase, decrease) the post-vertical spacing by 9624104862Sru@var{space}. The default scaling indicator is @samp{p}. 9625104862Sru 9626104862SruIf @code{pvs} is called without an argument, the post-vertical spacing is 9627104862Srureset to the previous value before the last call to @code{pvs}. 9628104862Sru 9629104862Sru@code{gtroff} creates a warning of type @samp{range} if @var{space} is 9630104862Sruzero or negative; the vertical spacing is then set to zero. 9631104862Sru 9632104862SruThe read-only number register @code{.pvs} contains the current 9633104862Srupost-vertical spacing; it is associated with the current environment 9634104862Sru(@pxref{Environments}). 9635104862Sru@endDefreq 9636104862Sru 963769626Sru@c --------------------------------------------------------------------- 963869626Sru 963955839Sasmodai@node Fractional Type Sizes, , Changing Type Sizes, Sizes 964055839Sasmodai@subsection Fractional Type Sizes 964155839Sasmodai@cindex fractional type sizes 9642104862Sru@cindex fractional point sizes 964355839Sasmodai@cindex type sizes, fractional 9644104862Sru@cindex point sizes, fractional 9645104862Sru@cindex sizes, fractional 964655839Sasmodai 964769626Sru@cindex @code{s} unit 964869626Sru@cindex unit, @code{s} 964969626Sru@cindex @code{z} unit 965069626Sru@cindex unit, @code{z} 9651104862Sru@cindex @code{ps} request, with fractional type sizes 9652104862Sru@cindex @code{cs} request, with fractional type sizes 9653104862Sru@cindex @code{tkf} request, with fractional type sizes 9654104862Sru@cindex @code{\H}, with fractional type sizes 9655104862Sru@cindex @code{\s}, with fractional type sizes 965675584SruA @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 9657114402Sruwhere @var{sizescale} is specified in the @file{DESC} file (1@tie{}by 965875584Srudefault). There is a new scale indicator @samp{z} which has the 965975584Srueffect of multiplying by @var{sizescale}. Requests and escape 966075584Srusequences in @code{gtroff} interpret arguments that represent a point 966175584Srusize as being in units of scaled points, but they evaluate each such 966275584Sruargument using a default scale indicator of @samp{z}. Arguments 966375584Srutreated in this way are the argument to the @code{ps} request, the 966475584Sruthird argument to the @code{cs} request, the second and fourth 966575584Sruarguments to the @code{tkf} request, the argument to the @code{\H} 966675584Sruescape sequence, and those variants of the @code{\s} escape sequence 966775584Sruthat take a numeric expression as their argument (see below). 966855839Sasmodai 9669114402SruFor example, suppose @var{sizescale} is@tie{}1000; then a scaled point 967075584Sruis equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 967169626Sruequivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 9672114402Sru10250@tie{}scaled points, which is equal to 10.25@tie{}points. 967355839Sasmodai 967475584Sru@code{gtroff} disallows the use of the @samp{z} scale indicator in 967575584Sruinstances where it would make no sense, such as a numeric 967669626Sruexpression whose default scale indicator was neither @samp{u} nor 967775584Sru@samp{z}. Similarly it would make 967855839Sasmodaino sense to use a scaling indicator other than @samp{z} or @samp{u} in a 967955839Sasmodainumeric expression whose default scale indicator was @samp{z}, and so 968069626Sru@code{gtroff} disallows this as well. 968155839Sasmodai 968255839SasmodaiThere is also new scale indicator @samp{s} which multiplies by the 968369626Srunumber of units in a scaled point. So, for example, @samp{\n[.ps]s} is 968469626Sruequal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 968555839Sasmodaiscale indicators. 968655839Sasmodai 968775584Sru@Defreg {.ps} 968875584SruA read-only number register returning the point size in scaled points. 968969626Sru 969075584Sru@code{.ps} is associated with the current environment 969175584Sru(@pxref{Environments}). 969275584Sru@endDefreg 969375584Sru 9694104862Sru@DefregList {.psr} 9695104862Sru@DefregListEnd {.sr} 9696104862Sru@cindex last-requested point size registers (@code{.psr}, @code{.sr}) 9697104862Sru@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) 9698104862Sru@cindex @code{.ps} register, in comparison with @code{.psr} 9699104862Sru@cindex @code{.s} register, in comparison with @code{.sr} 970069626SruThe last-requested point size in scaled points is contained in the 970175584Sru@code{.psr} read-only number register. The last requested point size 970275584Sruin points as a decimal fraction can be found in @code{.sr}. This is a 970375584Srustring-valued read-only number register. 970469626Sru 970575584SruNote that the requested point sizes are device-independent, whereas 970675584Sruthe values returned by the @code{.ps} and @code{.s} registers are not. 9707104862SruFor example, if a point size of 11@dmn{pt} is requested, and a 9708104862Sru@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file) 9709104862Sruspecifies 10.95@dmn{pt} instead, this value is actually used. 971075584Sru 971175584SruBoth registers are associated with the current environment 971275584Sru(@pxref{Environments}). 971375584Sru@endDefreg 971475584Sru 971575584SruThe @code{\s} escape has the following syntax for working with 971675584Srufractional type sizes: 971775584Sru 971869626Sru@table @code 971969626Sru@item \s[@var{n}] 972069626Sru@itemx \s'@var{n}' 9721114402SruSet the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric 972255839Sasmodaiexpression with a default scale indicator of @samp{z}. 972355839Sasmodai 972469626Sru@item \s[+@var{n}] 972569626Sru@itemx \s[-@var{n}] 972669626Sru@itemx \s+[@var{n}] 972769626Sru@itemx \s-[@var{n}] 972869626Sru@itemx \s'+@var{n}' 972969626Sru@itemx \s'-@var{n}' 973069626Sru@itemx \s+'@var{n}' 973169626Sru@itemx \s-'@var{n}' 9732114402SruIncrease or or decrease the point size by @var{n}@tie{}scaled points; 9733114402Sru@var{n}@tie{}is a numeric expression with a default scale indicator of 973469626Sru@samp{z}. 973569626Sru@end table 973655839Sasmodai 973769626Sru@xref{Font Files}. 973855839Sasmodai 973955839Sasmodai 974069626Sru@c ===================================================================== 974155839Sasmodai 974275584Sru@node Strings, Conditionals and Loops, Sizes, gtroff Reference 974355839Sasmodai@section Strings 974455839Sasmodai@cindex strings 974555839Sasmodai 974669626Sru@code{gtroff} has string variables, which are entirely for user 974775584Sruconvenience (i.e.@: there are no built-in strings exept @code{.T}, but 974875584Srueven this is a read-write string variable). 974955839Sasmodai 9750104862Sru@DefreqList {ds, name [@Var{string}]} 9751104862Sru@DefreqItem {ds1, name [@Var{string}]} 9752104862Sru@DefescItem {\\*, , n, } 9753104862Sru@DefescItem {\\*, @lparen{}, nm, } 9754104862Sru@DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}} 9755104862Sru@cindex string interpolation (@code{\*}) 9756104862Sru@cindex string expansion (@code{\*}) 9757104862Sru@cindex interpolation of strings (@code{\*}) 9758104862Sru@cindex expansion of strings (@code{\*}) 9759104862Sru@cindex string arguments 9760104862Sru@cindex arguments, of strings 9761114402SruDefine and access a string variable @var{name} (one-character 9762114402Sruname@tie{}@var{n}, two-character name @var{nm}). If @var{name} already 9763114402Sruexists, @code{ds} overwrites the previous definition. Only the syntax form 9764104862Sruusing brackets can take arguments which are handled identically to 9765104862Srumacro arguments; the single exception is that a closing bracket as an 9766114402Sruargument must be enclosed in double quotes. @xref{Request and Macro 9767114402SruArguments}, and @ref{Parameters}. 976855839Sasmodai 976975584SruExample: 977075584Sru 977175584Sru@Example 9772104862Sru.ds foo a \\$1 test 977375584Sru. 9774104862SruThis is \*[foo nice]. 9775104862Sru @result{} This is a nice test. 977675584Sru@endExample 977755839Sasmodai 977875584SruThe @code{\*} escape @dfn{interpolates} (expands in-place) a 977975584Srupreviously-defined string variable. To be more precise, the stored 978075584Srustring is pushed onto the input stack which is then parsed by 978175584Sru@code{gtroff}. Similar to number registers, it is possible to nest 9782104862Srustrings, i.e. string variables can be called within string variables. 978355839Sasmodai 9784104862SruIf the string named by the @code{\*} escape does not exist, it is 9785104862Srudefined as empty, and a warning of type @samp{mac} is emitted (see 978675584Sru@ref{Debugging}, for more details). 978775584Sru 978855839Sasmodai@cindex comments, with @code{ds} 9789104862Sru@cindex @code{ds} request, and comments 979069626Sru@strong{Caution:} Unlike other requests, the second argument to the 979169626Sru@code{ds} request takes up the entire line including trailing spaces. 979269626SruThis means that comments on a line with such a request can introduce 979369626Sruunwanted space into a string. 979455839Sasmodai 979575584Sru@Example 979669626Sru.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 979775584Sru@endExample 979855839Sasmodai 979969626Sru@noindent 980069626SruInstead the comment should be put on another line or have the comment 980169626Sruescape adjacent with the end of the string. 980255839Sasmodai 980375584Sru@Example 980469626Sru.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 980575584Sru@endExample 980655839Sasmodai 980769626Sru@cindex trailing quotes 980869626Sru@cindex quotes, trailing 980969626Sru@cindex leading spaces with @code{ds} 981069626Sru@cindex spaces with @code{ds} 9811104862Sru@cindex @code{ds} request, and leading spaces 981275584SruTo produce leading space the string can be started with a double 981375584Sruquote. No trailing quote is needed; in fact, any trailing quote is 981475584Sruincluded in your string. 981555839Sasmodai 981675584Sru@Example 981755839Sasmodai.ds sign " Yours in a white wine sauce, 981875584Sru@endExample 981955839Sasmodai 982069626Sru@cindex multi-line strings 982169626Sru@cindex strings, multi-line 9822104862Sru@cindex newline character, in strings, escaping 9823104862Sru@cindex escaping newline characters, in strings 982469626SruStrings are not limited to a single line of text. A string can span 982575584Sruseveral lines by escaping the newlines with a backslash. The 982675584Sruresulting string is stored @emph{without} the newlines. 982755839Sasmodai 982875584Sru@Example 982955839Sasmodai.ds foo lots and lots \ 983055839Sasmodaiof text are on these \ 983155839Sasmodainext several lines 983275584Sru@endExample 983355839Sasmodai 9834104862SruIt is not possible to have real newlines in a string. To put a single 9835104862Srudouble quote character into a string, use two consecutive double quote 9836104862Srucharacters. 983769626Sru 9838104862SruThe @code{ds1} request turns off compatibility mode 9839104862Sruwhile interpreting a string. To be more precise, a @dfn{compatibility 9840104862Srusave} input token is inserted at the beginning of the string, and a 9841104862Sru@dfn{compatibility restore} input token at the end. 9842104862Sru 9843104862Sru@Example 9844104862Sru.nr xxx 12345 9845104862Sru.ds aa The value of xxx is \\n[xxx]. 9846104862Sru.ds1 bb The value of xxx ix \\n[xxx]. 9847104862Sru. 9848104862Sru.cp 1 9849104862Sru. 9850104862Sru\*(aa 9851104862Sru @result{} warning: number register `[' not defined 9852104862Sru @result{} The value of xxx is 0xxx]. 9853104862Sru\*(bb 9854104862Sru @result{} The value of xxx ix 12345. 9855104862Sru@endExample 9856104862Sru 9857104862Sru@cindex name space, common, of macros, diversions, and strings 9858104862Sru@cindex common name space of macros, diversions, and strings 9859104862Sru@cindex macros, shared name space with strings and diversions 9860104862Sru@cindex strings, shared name space with macros and diversions 9861104862Sru@cindex diversions, shared name space with macros and strings 986275584SruStrings, macros, and diversions (and boxes) share the same name space. 986375584SruInternally, even the same mechanism is used to store them. This has 986475584Srusome interesting consequences. For example, it is possible to call a 986575584Srumacro with string syntax and vice versa. 986669626Sru 986775584Sru@Example 986875584Sru.de xxx 986975584Srua funny test. 987075584Sru.. 987175584SruThis is \*[xxx] 987275584Sru @result{} This is a funny test. 987369626Sru 987475584Sru.ds yyy a funny test 987575584SruThis is 987675584Sru.yyy 987775584Sru @result{} This is a funny test. 987875584Sru@endExample 987969626Sru 9880104862SruDiversions and boxes can be also called with string syntax. 988169626Sru 988275584SruAnother consequence is that you can copy one-line diversions or boxes 988375584Sruto a string. 988475584Sru 988575584Sru@Example 988675584Sru.di xxx 988775584Srua \fItest\fR 988875584Sru.br 988975584Sru.di 989075584Sru.ds yyy This is \*[xxx]\c 989175584Sru\*[yyy]. 989275584Sru @result{} @r{This is a }@i{test}. 989375584Sru@endExample 989475584Sru 989569626Sru@noindent 989675584SruAs the previous example shows, it is possible to store formatted 989775584Sruoutput in strings. The @code{\c} escape prevents the insertion of an 989875584Sruadditional blank line in the output. 989969626Sru 990075584SruCopying diversions longer than a single output line produces 990175584Sruunexpected results. 990255839Sasmodai 990375584Sru@Example 990475584Sru.di xxx 990575584Srua funny 990675584Sru.br 990775584Srutest 990875584Sru.br 990975584Sru.di 991075584Sru.ds yyy This is \*[xxx]\c 991175584Sru\*[yyy]. 991275584Sru @result{} test This is a funny. 991375584Sru@endExample 991469626Sru 991575584SruUsually, it is not predictable whether a diversion contains one or 991675584Srumore output lines, so this mechanism should be avoided. With 991775584Sru@acronym{UNIX} @code{troff}, this was the only solution to strip off a 991875584Srufinal newline from a diversion. Another disadvantage is that the 991975584Sruspaces in the copied string are already formatted, making them 992075584Sruunstretchable. This can cause ugly results. 992155839Sasmodai 9922104862Sru@cindex stripping final newline in diversions 9923104862Sru@cindex diversion, stripping final newline 9924104862Sru@cindex final newline, stripping in diversions 9925104862Sru@cindex newline, final, stripping in diversions 9926104862Sru@cindex horizontal space, unformatting 9927104862Sru@cindex space, horizontal, unformatting 9928104862Sru@cindex unformatting horizontal space 992975584SruA clean solution to this problem is available in GNU @code{troff}, 993075584Sruusing the requests @code{chop} to remove the final newline of a 993175584Srudiversion, and @code{unformat} to make the horizontal spaces 993275584Srustretchable again. 993369626Sru 993475584Sru@Example 993575584Sru.box xxx 993675584Srua funny 993775584Sru.br 993875584Srutest 993975584Sru.br 994075584Sru.box 994175584Sru.chop xxx 994275584Sru.unformat xxx 994375584SruThis is \*[xxx]. 994475584Sru @result{} This is a funny test. 994575584Sru@endExample 994655839Sasmodai 994775584Sru@xref{Gtroff Internals}, for more information. 994875584Sru@endDefreq 994969626Sru 9950104862Sru@DefreqList {as, name [@Var{string}]} 9951104862Sru@DefreqListEnd {as1, name [@Var{string}]} 9952104862Sru@cindex appending to a string (@code{as}) 9953104862Sru@cindex string, appending (@code{as}) 995475584SruThe @code{as} request is similar to @code{ds} but appends @var{string} 995575584Sruto the string stored as @var{name} instead of redefining it. If 995675584Sru@var{name} doesn't exist yet, it is created. 995755839Sasmodai 995875584Sru@Example 995975584Sru.as sign " with shallots, onions and garlic, 996075584Sru@endExample 9961104862Sru 9962104862SruThe @code{as1} request is similar to @code{as}, but compatibility mode 9963104862Sruis switched off while the appended string is interpreted. To be more 9964104862Sruprecise, a @dfn{compatibility save} input token is inserted at the 9965104862Srubeginning of the appended string, and a @dfn{compatibility restore} 9966104862Sruinput token at the end. 996775584Sru@endDefreq 996855839Sasmodai 996975584SruRudimentary string manipulation routines are given with the next two 997075584Srurequests. 997169626Sru 997275584Sru@Defreq {substring, str n1 [@Var{n2}]} 9973104862Sru@cindex substring (@code{substring}) 9974104862SruReplace the string named @var{str} with the substring 9975114402Srudefined by the indices @var{n1} and@tie{}@var{n2}. The first character 9976114402Sruin the string has index@tie{}0. If @var{n2} is omitted, it is taken to 997775584Srube equal to the string's length. If the index value @var{n1} or 9978104862Sru@var{n2} is negative, it is counted from the end of the 9979114402Srustring, going backwards: The last character has index@tie{}@minus{}1, the 9980114402Srucharacter before the last character has index@tie{}@minus{}2, etc. 998175584Sru 998275584Sru@Example 998375584Sru.ds xxx abcdefgh 9984104862Sru.substring xxx 1 -4 998575584Sru\*[xxx] 998675584Sru @result{} bcde 998775584Sru@endExample 998875584Sru@endDefreq 998975584Sru 999075584Sru@Defreq {length, reg str} 9991104862Sru@cindex length of a string (@code{length}) 9992104862Sru@cindex string, length of (@code{length}) 9993104862SruCompute the number of characters of @var{str} and return it in the 9994104862Srunumber register @var{reg}. If @var{reg} doesn't exist, it is created. 9995104862Sru@code{str} is read in copy mode. 999675584Sru 999775584Sru@Example 9998104862Sru.ds xxx abcd\h'3i'efgh 9999114402Sru.length yyy \*[xxx] 1000075584Sru\n[yyy] 10001104862Sru @result{} 14 1000275584Sru@endExample 1000375584Sru@endDefreq 1000475584Sru 1000575584Sru@Defreq {rn, xx yy} 10006104862Sru@cindex renaming request (@code{rn}) 10007104862Sru@cindex request, renaming (@code{rn}) 10008104862Sru@cindex renaming macro (@code{rn}) 10009104862Sru@cindex macro, renaming (@code{rn}) 10010104862Sru@cindex renaming string (@code{rn}) 10011104862Sru@cindex string, renaming (@code{rn}) 10012104862Sru@cindex renaming diversion (@code{rn}) 10013104862Sru@cindex diversion, renaming (@code{rn}) 10014104862SruRename the request, macro, diversion, or string @var{xx} to @var{yy}. 1001575584Sru@endDefreq 1001675584Sru 1001775584Sru@Defreq {rm, xx} 10018104862Sru@cindex removing request (@code{rm}) 10019104862Sru@cindex request, removing (@code{rm}) 10020104862Sru@cindex removing macro (@code{rm}) 10021104862Sru@cindex macro, removing (@code{rm}) 10022104862Sru@cindex removing string (@code{rm}) 10023104862Sru@cindex string, removing (@code{rm}) 10024104862Sru@cindex removing diversion (@code{rm}) 10025104862Sru@cindex diversion, removing (@code{rm}) 10026104862SruRemove the request, macro, diversion, or string @var{xx}. @code{gtroff} 10027104862Srutreats subsequent invocations as if the object had never been defined. 1002875584Sru@endDefreq 1002975584Sru 1003075584Sru@Defreq {als, new old} 10031104862Sru@cindex alias, string, creating (@code{als}) 10032104862Sru@cindex alias, macro, creating (@code{als}) 10033104862Sru@cindex alias, diversion, creating (@code{als}) 10034104862Sru@cindex creating alias, for string (@code{als}) 10035104862Sru@cindex creating alias, for macro (@code{als}) 10036104862Sru@cindex creating alias, for diversion (@code{als}) 10037104862Sru@cindex string, creating alias (@code{als}) 10038104862Sru@cindex macro, creating alias (@code{als}) 10039104862Sru@cindex diversion, creating alias (@code{als}) 1004075584SruCreate an alias named @var{new} for the request, string, macro, or 1004175584Srudiversion object named @var{old}. The new name and the old name are 1004275584Sruexactly equivalent (it is similar to a hard rather than a soft 1004375584Srulink). If @var{old} is undefined, @code{gtroff} generates a warning of 1004475584Srutype @samp{mac} and ignores the request. 1004575584Sru@endDefreq 1004675584Sru 1004775584Sru@Defreq {chop, xx} 1004875584SruRemove (chop) the last character from the macro, string, or diversion 10049104862Srunamed @var{xx}. This is useful for removing the newline from the end 1005075584Sruof diversions that are to be interpolated as strings. This command 1005175584Srucan be used repeatedly; see @ref{Gtroff Internals}, for details on 10052104862Srunodes inserted additionally by @code{gtroff}. 1005375584Sru@endDefreq 1005475584Sru 1005569626Sru@xref{Identifiers}, and @ref{Comments}. 1005669626Sru 1005769626Sru 1005869626Sru@c ===================================================================== 1005969626Sru 1006075584Sru@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 1006155839Sasmodai@section Conditionals and Loops 1006255839Sasmodai@cindex conditionals and loops 1006355839Sasmodai@cindex loops and conditionals 1006455839Sasmodai 1006575584Sru@menu 1006675584Sru* Operators in Conditionals:: 1006775584Sru* if-else:: 1006875584Sru* while:: 1006975584Sru@end menu 1007055839Sasmodai 1007175584Sru@c --------------------------------------------------------------------- 1007275584Sru 1007375584Sru@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 1007475584Sru@subsection Operators in Conditionals 1007575584Sru 10076104862Sru@cindex @code{if} request, operators to use with 10077104862Sru@cindex @code{while} request, operators to use with 1007875584SruIn @code{if} and @code{while} requests, there are several more 1007975584Sruoperators available: 1008075584Sru 1008155839Sasmodai@table @code 1008255839Sasmodai@item e 1008355839Sasmodai@itemx o 1008469626SruTrue if the current page is even or odd numbered (respectively). 1008569626Sru 1008655839Sasmodai@item n 1008775584SruTrue if the document is being processed in nroff mode (i.e., the 1008875584Sru@code{.nroff} command has been issued). 1008969626Sru 1009069626Sru@item t 1009175584SruTrue if the document is being processed in troff mode (i.e., the 1009275584Sru@code{.troff} command has been issued). 1009369626Sru 1009475584Sru@item v 10095104862SruAlways false. This condition is for compatibility with other 10096104862Sru@code{troff} versions only. 1009775584Sru 1009855839Sasmodai@item '@var{xxx}'@var{yyy}' 1009969626SruTrue if the string @var{xxx} is equal to the string @var{yyy}. Other 1010075584Srucharacters can be used in place of the single quotes; the same set of 1010175584Srudelimiters as for the @code{\D} escape is used (@pxref{Escapes}). 1010275584Sru@code{gtroff} formats the strings before being compared: 1010369626Sru 1010475584Sru@Example 1010575584Sru.ie "|"\fR|\fP" \ 1010675584Srutrue 1010775584Sru.el \ 1010875584Srufalse 1010975584Sru @result{} true 1011075584Sru@endExample 1011175584Sru 1011275584Sru@noindent 10113104862SruThe resulting motions, glyph sizes, and fonts have to 1011475584Srumatch,@footnote{The created output nodes must be identical. 1011575584Sru@xref{Gtroff Internals}.} and not the individual motion, size, and 1011675584Srufont requests. In the previous example, @samp{|} and @samp{\fR|\fP} 10117104862Sruboth result in a roman @samp{|} glyph with the same point size and 1011875584Sruat the same location on the page, so the strings are equal. If 10119114402Sru@samp{.ft@tie{}I} had been added before the @samp{.ie}, the result 1012075584Sruwould be ``false'' because (the first) @samp{|} produces an italic 1012175584Sru@samp{|} rather than a roman one. 1012275584Sru 1012375584Sru@item r @var{xxx} 1012455839SasmodaiTrue if there is a number register named @var{xxx}. 1012569626Sru 1012675584Sru@item d @var{xxx} 1012755839SasmodaiTrue if there is a string, macro, diversion, or request named @var{xxx}. 1012869626Sru 10129104862Sru@item m @var{xxx} 10130104862SruTrue if there is a color named @var{xxx}. 10131104862Sru 10132104862Sru@item c @var{g} 10133104862SruTrue if there is a glyph @var{g} available@footnote{The name of this 10134104862Sruconditional operator is a misnomer since it tests names of output 10135104862Sruglyphs.}; @var{g} is either an @acronym{ASCII} character or a special 10136104862Srucharacter (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition 10137104862Sruis also true if @var{g} has been defined by the @code{char} request. 1013855839Sasmodai@end table 1013955839Sasmodai 1014075584SruNote that these operators can't be combined with other operators like 1014175584Sru@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 1014275584Srubetween the exclamation mark and the operator) can be used to negate 1014375584Sruthe result. 1014455839Sasmodai 1014575584Sru@Example 1014675584Sru.nr xxx 1 1014775584Sru.ie !r xxx \ 1014875584Srutrue 1014975584Sru.el \ 1015075584Srufalse 1015175584Sru @result{} false 1015275584Sru@endExample 1015375584Sru 1015475584SruA whitespace after @samp{!} always evaluates to zero (this bizarre 1015575584Srubehaviour is due to compatibility with @acronym{UNIX} @code{troff}). 1015675584Sru 1015775584Sru@Example 1015875584Sru.nr xxx 1 1015975584Sru.ie ! r xxx \ 1016075584Srutrue 1016175584Sru.el \ 1016275584Srufalse 1016375584Sru @result{} r xxx true 1016475584Sru@endExample 1016575584Sru 1016675584SruIt is possible to omit the whitespace before the argument to the 1016775584Sru@samp{r}, @samp{d}, and @samp{c} operators. 1016875584Sru 1016975584Sru@xref{Expressions}. 1017075584Sru 1017169626Sru@c --------------------------------------------------------------------- 1017269626Sru 1017375584Sru@node if-else, while, Operators in Conditionals, Conditionals and Loops 1017455839Sasmodai@subsection if-else 1017555839Sasmodai@cindex if-else 1017655839Sasmodai 1017769626Sru@code{gtroff} has if-then-else constructs like other languages, although 1017855839Sasmodaithe formatting can be painful. 1017955839Sasmodai 1018075584Sru@Defreq {if, expr anything} 1018175584SruEvaluate the expression @var{expr}, and executes @var{anything} (the 1018275584Sruremainder of the line) if @var{expr} evaluates to non-zero (true). 1018375584Sru@var{anything} is interpreted as though it was on a line by itself 1018475584Sru(except that leading spaces are swallowed). @xref{Expressions}, for 1018575584Srumore info. 1018655839Sasmodai 1018775584Sru@Example 1018875584Sru.nr xxx 1 1018975584Sru.nr yyy 2 1019075584Sru.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 1019175584Sru @result{} true 1019275584Sru@endExample 1019375584Sru@endDefreq 1019469626Sru 10195104862Sru@Defreq{nop, anything} 10196104862SruExecutes @var{anything}. 10197114402SruThis is similar to @code{.if@tie{}1}. 10198104862Sru@endDefreq 1019969626Sru 10200104862Sru@DefreqList {ie, expr anything} 10201104862Sru@DefreqListEnd {el, anything} 1020275584SruUse the @code{ie} and @code{el} requests to write an if-then-else. 1020369626SruThe first request is the `if' part and the latter is the `else' part. 1020455839Sasmodai 1020575584Sru@Example 10206104862Sru.ie n .ls 2 \" double-spacing in nroff 10207104862Sru.el .ls 1 \" single-spacing in troff 1020875584Sru@endExample 1020975584Sru@endDefreq 1021069626Sru 10211104862Sru@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument 10212104862Sru@c to @deffn 10213104862Sru@c 10214104862Sru@c and in 4.2 you still can't use @{ in macros. 1021555839Sasmodai 10216104862Sru@c @DefescList {\@{, , , } 10217104862Sru@c @DefescListEnd {\@}, , , } 10218104862Sru@deffn Escape @t{\@{} 10219104862Sru@deffnx Escape @t{\@}} 1022075584Sru@esindex \@{ 1022175584Sru@esindex \@} 10222104862Sru@cindex begin of conditional block (@code{\@{}) 10223104862Sru@cindex end of conditional block (@code{\@}}) 10224104862Sru@cindex conditional block, begin (@code{\@{}) 10225104862Sru@cindex conditional block, end (@code{\@}}) 10226104862Sru@cindex block, conditional, begin (@code{\@{}) 10227104862Sru@cindex block, condititional, end (@code{\@}}) 1022875584SruIn many cases, an if (or if-else) construct needs to execute more than 1022975584Sruone request. This can be done using the @code{\@{} and @code{\@}} 1023069626Sruescapes. The following example shows the possible ways to use these 1023169626Sruescapes (note the position of the opening and closing braces). 1023255839Sasmodai 1023375584Sru@Example 1023455839Sasmodai.ie t \@{\ 1023555839Sasmodai. ds lq `` 1023655839Sasmodai. ds rq '' 1023755839Sasmodai.\@} 1023855839Sasmodai.el \ 1023955839Sasmodai.\@{\ 1024055839Sasmodai. ds lq " 1024155839Sasmodai. ds rq "\@} 1024275584Sru@endExample 1024375584Sru@c @endDefesc 10244104862Sru@end deffn 1024555839Sasmodai 1024669626Sru@xref{Expressions}. 1024755839Sasmodai 1024869626Sru@c --------------------------------------------------------------------- 1024955839Sasmodai 1025055839Sasmodai@node while, , if-else, Conditionals and Loops 1025155839Sasmodai@subsection while 1025255839Sasmodai@cindex while 1025355839Sasmodai 1025469626Sru@code{gtroff} provides a looping construct using the @code{while} 1025569626Srurequest, which is used much like the @code{if} (and related) requests. 1025655839Sasmodai 1025775584Sru@Defreq {while, expr anything} 1025875584SruEvaluate the expression @var{expr}, and repeatedly execute 1025975584Sru@var{anything} (the remainder of the line) until @var{expr} evaluates 10260114402Sruto@tie{}0. 1026175584Sru 1026275584Sru@Example 1026355839Sasmodai.nr a 0 1 1026475584Sru.while (\na < 9) \@{\ 1026575584Sru\n+a, 1026675584Sru.\@} 1026775584Sru\n+a 1026875584Sru @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 1026975584Sru@endExample 1027055839Sasmodai 1027175584SruSome remarks. 1027275584Sru 10273104862Sru@cindex @code{de} request, and @code{while} 1027475584Sru@itemize @bullet 1027575584Sru@item 1027675584SruThe body of a @code{while} request is treated like the body of a 1027775584Sru@code{de} request: @code{gtroff} temporarily stores it in a macro 1027875584Sruwhich is deleted after the loop has been exited. It can considerably 1027975584Sruslow down a macro if the body of the @code{while} request (within the 1028075584Srumacro) is large. Each time the macro is executed, the @code{while} 1028175584Srubody is parsed and stored again as a temporary macro. 1028275584Sru 1028375584Sru@Example 1028475584Sru.de xxx 1028575584Sru. nr num 10 1028675584Sru. while (\\n[num] > 0) \@{\ 1028775584Sru. \" many lines of code 1028875584Sru. nr num -1 1028975584Sru. \@} 1029075584Sru.. 1029175584Sru@endExample 1029275584Sru 1029375584Sru@cindex recursive macros 1029475584Sru@cindex macros, recursive 1029569626Sru@noindent 1029675584SruThe traditional and ofter better solution (@acronym{UNIX} @code{troff} 1029775584Srudoesn't have the @code{while} request) is to use a recursive macro 1029875584Sruinstead which is parsed only once during its definition. 1029955839Sasmodai 1030075584Sru@Example 1030175584Sru.de yyy 1030275584Sru. if (\\n[num] > 0) \@{\ 1030375584Sru. \" many lines of code 1030475584Sru. nr num -1 1030575584Sru. yyy 1030675584Sru. \@} 1030775584Sru.. 1030875584Sru. 1030975584Sru.de xxx 1031075584Sru. nr num 10 1031175584Sru. yyy 1031275584Sru.. 1031375584Sru@endExample 1031455839Sasmodai 1031569626Sru@noindent 10316114402SruNote that the number of available recursion levels is set to@tie{}1000 1031775584Sru(this is a compile-time constant value of @code{gtroff}). 1031855839Sasmodai 1031975584Sru@item 1032075584SruThe closing brace of a @code{while} body must end a line. 1032155839Sasmodai 1032275584Sru@Example 1032375584Sru.if 1 \@{\ 1032475584Sru. nr a 0 1 1032575584Sru. while (\n[a] < 10) \@{\ 1032675584Sru. nop \n+[a] 1032775584Sru.\@}\@} 1032875584Sru @result{} unbalanced \@{ \@} 1032975584Sru@endExample 1033075584Sru@end itemize 1033175584Sru@endDefreq 1033275584Sru 1033375584Sru@Defreq {break, } 10334104862Sru@cindex @code{while} request, confusing with @code{br} 10335104862Sru@cindex @code{break} request, in a @code{while} loop 10336104862Sru@cindex @code{continue} request, in a @code{while} loop 1033775584SruBreak out of a @code{while} loop. Be sure not to confuse this with 1033875584Sruthe @code{br} request (causing a line break). 1033975584Sru@endDefreq 1034075584Sru 1034175584Sru@Defreq {continue, } 10342104862SruFinish the current iteration of a @code{while} loop, immediately 1034375584Srurestarting the next iteration. 1034475584Sru@endDefreq 1034575584Sru 1034669626Sru@xref{Expressions}. 1034769626Sru 1034869626Sru 1034969626Sru@c ===================================================================== 1035069626Sru 1035175584Sru@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 1035255839Sasmodai@section Writing Macros 1035355839Sasmodai@cindex writing macros 1035455839Sasmodai@cindex macros, writing 1035555839Sasmodai 1035675584SruA @dfn{macro} is a collection of text and embedded commands which can 1035775584Srube invoked multiple times. Use macros to define common operations. 1035855839Sasmodai 10359104862Sru@DefreqList {de, name [@Var{end}]} 10360104862Sru@DefreqItem {de1, name [@Var{end}]} 10361104862Sru@DefreqListEnd {dei, name [@Var{end}]} 1036275584SruDefine a new macro named @var{name}. @code{gtroff} copies subsequent 1036375584Srulines (starting with the next one) into an internal buffer until it 1036475584Sruencounters the line @samp{..} (two dots). The optional second 1036575584Sruargument to @code{de} changes this to a macro to @samp{.@var{end}}. 1036655839Sasmodai 10367104862SruThere can be whitespace after the first dot in the line containing the 10368104862Sruending token (either @samp{.} or macro @samp{@var{end}}). 1036975584Sru 1037075584SruHere a small example macro called @samp{P} which causes a break and 1037175584Sruinserts some vertical space. It could be used to separate paragraphs. 1037275584Sru 1037375584Sru@Example 1037455839Sasmodai.de P 1037575584Sru. br 1037675584Sru. sp .8v 1037755839Sasmodai.. 1037875584Sru@endExample 1037955839Sasmodai 10380104862SruThe following example defines a macro within another. Remember that 10381104862Sruexpansion must be protected twice; once for reading the macro and 10382104862Sruonce for executing. 1038375584Sru 10384104862Sru@Example 10385104862Sru\# a dummy macro to avoid a warning 10386104862Sru.de end 10387104862Sru.. 10388104862Sru. 10389104862Sru.de foo 10390104862Sru. de bar end 10391104862Sru. nop \f[B]Hallo \\\\$1!\f[] 10392104862Sru. end 10393104862Sru.. 10394104862Sru. 10395104862Sru.foo 10396104862Sru.bar Joe 10397104862Sru @result{} @b{Hallo Joe!} 10398104862Sru@endExample 1039975584Sru 10400104862Sru@noindent 10401104862SruSince @code{\f} has no expansion, it isn't necessary to protect its 10402104862Srubackslash. Had we defined another macro within @code{bar} which takes 10403104862Srua parameter, eight backslashes would be necessary before @samp{$1}. 1040475584Sru 10405104862SruThe @code{de1} request turns off compatibility mode 10406104862Sruwhile executing the macro. On entry, the current compatibility mode 10407104862Sruis saved and restored at exit. 10408104862Sru 10409104862Sru@Example 10410104862Sru.nr xxx 12345 10411104862Sru. 10412104862Sru.de aa 10413104862SruThe value of xxx is \\n[xxx]. 10414104862Sru.. 10415104862Sru.de1 bb 10416104862SruThe value of xxx ix \\n[xxx]. 10417104862Sru.. 10418104862Sru. 10419104862Sru.cp 1 10420104862Sru. 10421104862Sru.aa 10422104862Sru @result{} warning: number register ' not defined 10423104862Sru @result{} The value of xxx is 0xxx]. 10424104862Sru.bb 10425104862Sru @result{} The value of xxx ix 12345. 10426104862Sru@endExample 10427104862Sru 10428104862SruThe @code{dei} request defines a macro indirectly. 10429104862SruThat is, it expands strings whose names 10430104862Sruare @var{name} or @var{end} before performing the append. 10431104862Sru 10432104862SruThis: 10433104862Sru 10434104862Sru@Example 10435104862Sru.ds xx aa 10436104862Sru.ds yy bb 10437104862Sru.dei xx yy 10438104862Sru@endExample 10439104862Sru 10440104862Sru@noindent 10441104862Sruis equivalent to: 10442104862Sru 10443104862Sru@Example 10444104862Sru.de aa bb 10445104862Sru@endExample 10446104862Sru 10447104862Sru@pindex trace.tmac 10448104862SruUsing @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}. 10449104862Sru 10450104862SruNote that macro identifiers are shared with identifiers for strings and 10451104862Srudiversions. 1045275584Sru@endDefreq 1045375584Sru 10454114402Sru@DefreqList {am, name [@Var{end}]} 10455114402Sru@DefreqItem {am1, name [@Var{end}]} 10456114402Sru@DefreqListEnd {ami, name [@Var{end}]} 10457104862Sru@cindex appending to a macro (@code{am}) 10458104862Sru@cindex macro, appending (@code{am}) 1045975584SruWorks similarly to @code{de} except it appends onto the macro named 10460114402Sru@var{name}. So, to make the previously defined @samp{P} macro actually 1046175584Srudo indented instead of block paragraphs, add the necessary code to the 1046275584Sruexisting macro like this: 1046355839Sasmodai 1046475584Sru@Example 1046555839Sasmodai.am P 1046655839Sasmodai.ti +5n 1046755839Sasmodai.. 1046875584Sru@endExample 10469104862Sru 10470104862SruThe @code{am1} request turns off compatibility mode 10471104862Sruwhile executing the appended macro piece. To be more precise, a 10472104862Sru@dfn{compatibility save} input token is inserted at the beginning of 10473104862Sruthe appended code, and a @dfn{compatibility restore} input token at 10474104862Sruthe end. 10475104862Sru 10476104862SruThe @code{ami} request appends indirectly, 10477104862Srumeaning that @code{gtroff} expands strings whose names 10478114402Sruare @var{name} or @var{end} before performing the append. 10479104862Sru 10480104862Sru@pindex trace.tmac 10481104862SruUsing @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. 1048275584Sru@endDefreq 1048355839Sasmodai 10484104862Sru@xref{Strings}, for the @code{als} request to rename a macro. 1048555839Sasmodai 10486104862SruThe @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and 10487104862Sru@code{as} requests (together with its variants) only create a new object 10488104862Sruif the name of the macro, diversion or string diversion is currently 10489104862Sruundefined or if it is defined to be a request; normally they modify the 10490104862Sruvalue of an existing object. 10491104862Sru 10492104862Sru@Defreq {return, } 10493104862SruExit a macro, immediately returning to the caller. 1049475584Sru@endDefreq 1049555839Sasmodai 1049655839Sasmodai@menu 1049775584Sru* Copy-in Mode:: 1049875584Sru* Parameters:: 1049955839Sasmodai@end menu 1050055839Sasmodai 1050169626Sru@c --------------------------------------------------------------------- 1050269626Sru 1050355839Sasmodai@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 1050455839Sasmodai@subsection Copy-in Mode 1050555839Sasmodai@cindex copy-in mode 1050655839Sasmodai@cindex mode, copy-in 1050755839Sasmodai 1050875584Sru@cindex @code{\n}, when reading text for a macro 1050975584Sru@cindex @code{\$}, when reading text for a macro 1051075584Sru@cindex @code{\*}, when reading text for a macro 1051175584Sru@cindex @code{\\}, when reading text for a macro 1051275584Sru@cindex \@key{RET}, when reading text for a macro 10513104862SruWhen @code{gtroff} reads in the text for a macro, string, or diversion, 10514104862Sruit copies the text (including request lines, but excluding escapes) into 10515104862Sruan internal buffer. Escapes are converted into an internal form, 1051669626Sruexcept for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 1051769626Sru@code{\@key{RET}} which are evaluated and inserted into the text where 1051869626Sruthe escape was located. This is known as @dfn{copy-in} mode or 1051969626Sru@dfn{copy} mode. 1052055839Sasmodai 1052155839SasmodaiWhat this means is that you can specify when these escapes are to be 1052269626Sruevaluated (either at copy-in time or at the time of use) by insulating 1052369626Sruthe escapes with an extra backslash. Compare this to the @code{\def} 1052469626Sruand @code{\edef} commands in @TeX{}. 1052555839Sasmodai 10526114402SruThe following example prints the numbers 20 and@tie{}10: 1052755839Sasmodai 1052875584Sru@Example 1052955839Sasmodai.nr x 20 1053055839Sasmodai.de y 1053155839Sasmodai.nr x 10 1053255839Sasmodai\&\nx 1053355839Sasmodai\&\\nx 1053455839Sasmodai.. 1053555839Sasmodai.y 1053675584Sru@endExample 1053755839Sasmodai 1053869626Sru@c --------------------------------------------------------------------- 1053955839Sasmodai 1054055839Sasmodai@node Parameters, , Copy-in Mode, Writing Macros 1054155839Sasmodai@subsection Parameters 1054255839Sasmodai@cindex parameters 1054355839Sasmodai 10544104862SruThe arguments to a macro or string can be examined using a variety of 10545104862Sruescapes. 10546104862Sru 10547104862Sru@Defreg {.$} 10548104862Sru@cindex number of arguments register (@code{.$}) 10549104862SruThe number of arguments passed to a macro or string. This is a read-only 10550104862Srunumber register. 10551104862Sru@endDefreg 10552104862Sru 1055355839SasmodaiAny individual argument can be retrieved with one of the following 1055455839Sasmodaiescapes: 1055555839Sasmodai 10556104862Sru@DefescList {\\$, , n, } 10557104862Sru@DefescItem {\\$, @lparen{}, nn, } 10558104862Sru@DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}} 1055969626Sru@cindex copy-in mode, and macro arguments 10560104862Sru@cindex macro, arguments (@code{\$}) 10561104862Sru@cindex arguments, macro (@code{\$}) 10562104862SruRetrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} 10563104862Sruargument. As usual, the first form only accepts a single number 10564104862Sru(larger than zero), the second a two-digit number (larger or equal 10565114402Sruto@tie{}10), and the third any positive integer value (larger 10566104862Sruthan zero). Macros and strings can have an unlimited number of arguments. 10567104862SruNote that due to copy-in mode, use two backslashes on these in actual use 10568104862Sruto prevent interpolation until the macro is actually invoked. 1056975584Sru@endDefesc 1057055839Sasmodai 1057175584Sru@Defreq {shift, [@Var{n}]} 10572114402SruShift the arguments 1@tie{}position, or as 1057369626Srumany positions as specified by its argument. After executing this 10574114402Srurequest, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}}; 10575114402Sruarguments 1 to@tie{}@var{n} are no longer available. Shifting by 1057669626Srunegative amounts is currently undefined. 1057775584Sru@endDefreq 1057855839Sasmodai 10579104862Sru@DefescList {\\$*, , , } 10580104862Sru@DefescListEnd {\\$@@, , , } 1058169626SruIn some cases it is convenient to use all of the arguments at once (for 1058269626Sruexample, to pass the arguments along to another macro). The @code{\$*} 1058375584Sruescape concatenates all the arguments separated by spaces. A 1058475584Srusimilar escape is @code{\$@@}, which concatenates all the 1058569626Sruarguments with each surrounded by double quotes, and separated by 10586104862Sruspaces. If not in compatibility mode, the input level of double quotes 10587114402Sruis preserved (see @ref{Request and Macro Arguments}). 1058875584Sru@endDefesc 1058955839Sasmodai 1059075584Sru@Defesc {\\$0, , , } 10591104862Sru@cindex macro name register (@code{\$0}) 10592104862Sru@cindex @code{als} request, and @code{\$0} 1059375584SruThe name used to invoke the current macro. 1059475584SruThe @code{als} request can make a macro have more than one name. 1059555839Sasmodai 1059675584Sru@Example 10597104862Sru.de generic-macro 10598104862Sru. ... 10599104862Sru. if \\n[error] \@{\ 10600104862Sru. tm \\$0: Houston, we have a problem. 10601104862Sru. return 10602104862Sru. \@} 1060355839Sasmodai.. 10604104862Sru. 10605104862Sru.als foo generic-macro 10606104862Sru.als bar generic-macro 1060775584Sru@endExample 1060875584Sru@endDefesc 1060955839Sasmodai 10610114402Sru@xref{Request and Macro Arguments}. 1061155839Sasmodai 1061255839Sasmodai 1061369626Sru@c ===================================================================== 1061469626Sru 1061575584Sru@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 1061655839Sasmodai@section Page Motions 1061755839Sasmodai@cindex page motions 1061855839Sasmodai@cindex motions, page 1061955839Sasmodai 10620104862Sru@xref{Manipulating Spacing}, for a discussion of the main request for 10621104862Sruvertical motion, @code{sp}. 1062255839Sasmodai 10623104862Sru@DefreqList {mk, [@Var{reg}]} 10624104862Sru@DefreqListEnd {rt, [@Var{dist}]} 10625104862Sru@cindex marking vertical page location (@code{mk}) 10626104862Sru@cindex page location, vertical, marking (@code{mk}) 10627104862Sru@cindex location, vertical, page, marking (@code{mk}) 10628104862Sru@cindex vertical page location, marking (@code{mk}) 10629104862Sru@cindex returning to marked vertical page location (@code{rt}) 10630104862Sru@cindex page location, vertical, returning to marked (@code{rt}) 10631104862Sru@cindex location, vertical, page, returning to marked (@code{rt}) 10632104862Sru@cindex vertical page location, returning to marked (@code{rt}) 1063355839SasmodaiThe request @code{mk} can be used to mark a location on a page, for 10634104862Srumovement to later. This request takes a register name as an argument 10635104862Sruin which to store the current page location. With no argument it 10636104862Srustores the location in an internal register. The results of this can 10637104862Srube used later by the @code{rt} or the @code{sp} request (or the 10638104862Sru@code{\v} escape). 1063955839Sasmodai 10640104862SruThe @code{rt} request returns @emph{upwards} to the location marked 10641104862Sruwith the last @code{mk} request. If used with an argument, return to 10642104862Srua position which distance from the top of the page is @var{dist} (no 10643104862Sruprevious call to @code{mk} is necessary in this case). Default scaling 10644104862Sruindicator is @samp{v}. 10645104862Sru 10646104862SruHere a primitive solution for a two-column macro. 10647104862Sru 1064875584Sru@Example 10649104862Sru.nr column-length 1.5i 10650104862Sru.nr column-gap 4m 10651104862Sru.nr bottom-margin 1m 10652104862Sru. 1065375584Sru@endExample 10654104862Sru@Example 10655104862Sru.de 2c 10656104862Sru. br 10657104862Sru. mk 10658104862Sru. ll \\n[column-length]u 10659104862Sru. wh -\\n[bottom-margin]u 2c-trap 10660104862Sru. nr right-side 0 10661104862Sru.. 10662104862Sru. 10663104862Sru@endExample 10664104862Sru@Example 10665104862Sru.de 2c-trap 10666104862Sru. ie \\n[right-side] \@{\ 10667104862Sru. nr right-side 0 10668104862Sru. po -(\\n[column-length]u + \\n[column-gap]u) 10669104862Sru. \" remove trap 10670104862Sru. wh -\\n[bottom-margin]u 10671104862Sru. \@} 10672104862Sru. el \@{\ 10673104862Sru. \" switch to right side 10674104862Sru. nr right-side 1 10675104862Sru. po +(\\n[column-length]u + \\n[column-gap]u) 10676104862Sru. rt 10677104862Sru. \@} 10678104862Sru.. 10679104862Sru. 10680104862Sru@endExample 10681104862Sru@Example 10682104862Sru.pl 1.5i 10683104862Sru.ll 4i 10684104862SruThis is a small test which shows how the 10685104862Srurt request works in combination with mk. 10686104862Sru 10687104862Sru.2c 10688104862SruStarting here, text is typeset in two columns. 10689104862SruNote that this implementation isn't robust 10690104862Sruand thus not suited for a real two-column 10691104862Srumacro. 10692104862Sru@endExample 10693104862Sru 10694104862SruResult: 10695104862Sru 10696104862Sru@Example 10697104862SruThis is a small test which shows how the 10698104862Srurt request works in combination with mk. 10699104862Sru 10700104862SruStarting here, isn't robust 10701104862Srutext is typeset and thus not 10702104862Sruin two columns. suited for a 10703104862SruNote that this real two-column 10704104862Sruimplementation macro. 10705104862Sru@endExample 1070675584Sru@endDefreq 1070755839Sasmodai 1070869626SruThe following escapes give fine control of movements about the page. 1070955839Sasmodai 1071075584Sru@Defesc {\\v, ', e, '} 10711104862Sru@cindex vertical motion (@code{\v}) 10712104862Sru@cindex motion, vertical (@code{\v}) 10713104862SruMove vertically, usually from the current location on the page (if no 10714104862Sruabsolute position operator @samp{|} is used). The 10715114402Sruargument@tie{}@var{e} specifies the distance to move; positive is 10716104862Srudownwards and negative upwards. The default scaling indicator for this 10717104862Sruescape is @samp{v}. Beware, however, that @code{gtroff} continues text 10718104862Sruprocessing at the point where the motion ends, so you should always 10719104862Srubalance motions to avoid interference with text processing. 10720104862Sru 10721104862Sru@code{\v} doesn't trigger a trap. This can be quite useful; for example, 10722104862Sruconsider a page bottom trap macro which prints a marker in the margin to 10723104862Sruindicate continuation of a footnote or something similar. 1072475584Sru@endDefesc 1072555839Sasmodai 10726104862SruThere are some special-case escapes for vertical motion. 1072755839Sasmodai 10728104862Sru@Defesc {\\r, , , } 10729114402SruMove upwards@tie{}1@dmn{v}. 10730104862Sru@endDefesc 1073169626Sru 10732104862Sru@Defesc {\\u, , , } 10733114402SruMove upwards@tie{}.5@dmn{v}. 10734104862Sru@endDefesc 1073569626Sru 10736104862Sru@Defesc {\\d, , , } 10737114402SruMove down@tie{}.5@dmn{v}. 10738104862Sru@endDefesc 1073955839Sasmodai 1074075584Sru@Defesc {\\h, ', e, '} 10741104862Sru@cindex inserting horizontal space (@code{\h}) 10742104862Sru@cindex horizontal space (@code{\h}) 10743104862Sru@cindex space, horizontal (@code{\h}) 10744104862Sru@cindex horizontal motion (@code{\h}) 10745104862Sru@cindex motion, horizontal (@code{\h}) 10746104862SruMove horizontally, usually from the current location (if no absolute 10747114402Sruposition operator @samp{|} is used). The expression@tie{}@var{e} 10748104862Sruindicates how far to move: positive is rightwards and negative 10749104862Sruleftwards. The default scaling indicator for this escape is @samp{m}. 10750114402Sru 10751114402SruThis horizontal space is not discarded at the end of a line. To insert 10752114402Srudiscardable space of a certain length use the @code{ss} request. 1075375584Sru@endDefesc 1075455839Sasmodai 10755104862SruThere are a number of special-case escapes for horizontal motion. 1075655839Sasmodai 10757104862Sru@Defesc {\\@key{SP}, , , } 10758104862Sru@cindex space, unbreakable 10759104862Sru@cindex unbreakable space 1076075584SruAn unbreakable and unpaddable (i.e.@: not expanded during filling) 1076169626Sruspace. (Note: This is a backslash followed by a space.) 10762104862Sru@endDefesc 1076369626Sru 10764104862Sru@Defesc {\\~, , , } 1076575584SruAn unbreakable space that stretches like a normal inter-word space 1076675584Sruwhen a line is adjusted. 10767104862Sru@endDefesc 1076869626Sru 10769104862Sru@Defesc {\\|, , , } 10770104862SruA 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to 1077175584Sruzero). 10772104862Sru@endDefesc 1077369626Sru 10774104862Sru@Defesc {\\^, , , } 10775104862SruA 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to 1077675584Sruzero). 10777104862Sru@endDefesc 1077869626Sru 10779104862Sru@Defesc {\\0, , , } 10780104862Sru@cindex space, width of a digit (@code{\0}) 10781104862Sru@cindex digit width space (@code{\0}) 1078275584SruA space the size of a digit. 10783104862Sru@endDefesc 1078469626Sru 1078575584SruThe following string sets the @TeX{} logo: 1078669626Sru 1078775584Sru@Example 1078875584Sru.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 1078975584Sru@endExample 1079055839Sasmodai 10791104862Sru@DefescList {\\w, ', text, '} 10792104862Sru@DefregItem {st} 10793104862Sru@DefregItem {sb} 10794104862Sru@DefregItem {rst} 10795104862Sru@DefregItem {rsb} 10796104862Sru@DefregItem {ct} 10797104862Sru@DefregItem {ssc} 10798104862Sru@DefregListEnd {skw} 10799104862Sru@cindex width escape (@code{\w}) 10800104862SruReturn the width of the specified @var{text} in basic units. 1080175584SruThis allows horizontal movement based on the width of some 1080275584Sruarbitrary text (e.g.@: given as an argument to a macro). 1080355839Sasmodai 1080475584Sru@Example 10805104862SruThe length of the string `abc' is \w'abc'u. 10806104862Sru @result{} The length of the string `abc' is 72u. 1080775584Sru@endExample 1080855839Sasmodai 1080969626SruFont changes may occur in @var{text} which don't affect current 1081069626Srusettings. 1081155839Sasmodai 1081269626SruAfter use, @code{\w} sets several registers: 1081355839Sasmodai 1081455839Sasmodai@table @code 1081555839Sasmodai@item st 1081669626Sru@itemx sb 10817104862SruThe highest and lowest point of the baseline, respectively, in @var{text}. 1081869626Sru 1081955839Sasmodai@item rst 1082069626Sru@itemx rsb 1082155839SasmodaiLike the @code{st} and @code{sb} registers, but takes account of the 10822104862Sruheights and depths of glyphs. With other words, this gives the 10823114402Sruhighest and lowest point of @var{text}. Values below the baseline are 10824114402Srunegative. 1082569626Sru 1082655839Sasmodai@item ct 10827104862SruDefines the kinds of glyphs occurring in @var{text}: 1082869626Sru 1082955839Sasmodai@table @asis 1083055839Sasmodai@item 0 10831104862Sruonly short glyphs, no descenders or tall glyphs. 1083269626Sru 1083355839Sasmodai@item 1 1083475584Sruat least one descender. 1083569626Sru 1083655839Sasmodai@item 2 10837104862Sruat least one tall glyph. 1083869626Sru 1083955839Sasmodai@item 3 10840104862Sruat least one each of a descender and a tall glyph. 1084155839Sasmodai@end table 1084269626Sru 1084355839Sasmodai@item ssc 1084469626SruThe amount of horizontal space (possibly negative) that should be added 10845104862Sruto the last glyph before a subscript. 1084669626Sru 1084755839Sasmodai@item skw 10848104862SruHow far to right of the center of the last glyph in the @code{\w} 1084975584Sruargument, the center of an accent from a roman font should be placed 10850104862Sruover that glyph. 1085155839Sasmodai@end table 1085275584Sru@endDefesc 1085355839Sasmodai 10854104862Sru@DefescList {\\k, , p, } 10855104862Sru@DefescItem {\\k, @lparen{}, ps, } 10856104862Sru@DefescListEnd {\\k, @lbrack{}, position, @rbrack} 10857104862Sru@cindex saving horizontal input line position (@code{\k}) 10858104862Sru@cindex horizontal input line position, saving (@code{\k}) 10859104862Sru@cindex input line position, horizontal, saving (@code{\k}) 10860104862Sru@cindex position, horizontal input line, saving (@code{\k}) 10861104862Sru@cindex line, input, horizontal position, saving (@code{\k}) 10862104862SruStore the current horizontal position in the @emph{input} line in 10863114402Srunumber register with name @var{position} (one-character name@tie{}@var{p}, 10864104862Srutwo-character name @var{ps}). Use this, for example, to return to the 10865104862Srubeginning of a string for highlighting or other decoration. 1086675584Sru@endDefesc 1086769626Sru 10868104862Sru@Defreg {hp} 10869104862Sru@cindex horizontal input line position register (@code{hp}) 10870104862Sru@cindex input line, horizontal position, register (@code{hp}) 10871104862Sru@cindex position, horizontal, in input line, register (@code{hp}) 10872104862Sru@cindex line, input, horizontal position, register (@code{hp}) 10873104862SruThe current horizontal position at the input line. 10874104862Sru@endDefreg 10875104862Sru 1087675584Sru@Defreg {.k} 10877104862Sru@cindex horizontal output line position register (@code{.k}) 10878104862Sru@cindex output line, horizontal position, register (@code{.k}) 10879104862Sru@cindex position, horizontal, in output line, register (@code{.k}) 10880104862Sru@cindex line, output, horizontal position, register (@code{.k}) 1088175584SruA read-only number register containing the current horizontal output 1088275584Sruposition. 1088375584Sru@endDefreg 1088455839Sasmodai 10885114402Sru@Defesc {\\o, ', abc, '} 10886104862Sru@cindex overstriking glyphs (@code{\o}) 10887104862Sru@cindex glyphs, overstriking (@code{\o}) 10888104862SruOverstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs 10889104862Sruare centered, and the resulting spacing is the largest width of the 10890104862Sruaffected glyphs. 10891104862Sru@endDefesc 1089255839Sasmodai 10893104862Sru@Defesc {\\z, , g, , } 10894104862Sru@cindex zero-width printing (@code{\z}, @code{\Z}) 10895104862Sru@cindex printing, zero-width (@code{\z}, @code{\Z}) 10896104862SruPrint glyph @var{g} with zero width, i.e., without spacing. Use 10897104862Sruthis to overstrike glyphs left-aligned. 10898104862Sru@endDefesc 1089955839Sasmodai 10900104862Sru@Defesc {\\Z, ', anything, '} 10901104862Sru@cindex zero-width printing (@code{\z}, @code{\Z}) 10902104862Sru@cindex printing, zero-width (@code{\z}, @code{\Z}) 10903104862SruPrint @var{anything}, then restore the horizontal and vertical position. 10904104862SruThe argument may not contain tabs or leaders. 10905104862Sru 10906104862SruThe following is an example of a strike-through macro: 10907104862Sru 10908104862Sru@Example 10909104862Sru.de ST 10910104862Sru.nr ww \w'\\$1' 10911104862Sru\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1 10912104862Sru.. 10913104862Sru. 10914104862SruThis is 10915104862Sru.ST "a test" 10916104862Sruan actual emergency! 10917104862Sru@endExample 10918104862Sru@endDefesc 10919104862Sru 10920104862Sru 1092169626Sru@c ===================================================================== 1092255839Sasmodai 1092375584Sru@node Drawing Requests, Traps, Page Motions, gtroff Reference 1092469626Sru@section Drawing Requests 1092569626Sru@cindex drawing requests 1092669626Sru@cindex requests for drawing 1092769626Sru 1092869626Sru@code{gtroff} provides a number of ways to draw lines and other figures 1092969626Sruon the page. Used in combination with the page motion commands (see 1093069626Sru@ref{Page Motions}, for more info), a wide variety of figures can be 1093169626Srudrawn. However, for complex drawings these operations can be quite 1093269626Srucumbersome, and it may be wise to use graphic preprocessors like 1093369626Sru@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 1093469626Sruinformation. 1093569626Sru 1093655839SasmodaiAll drawing is done via escapes. 1093755839Sasmodai 10938114402Sru@DefescList {\\l, ', l, '} 10939114402Sru@DefescListEnd {\\l, ', lg, '} 10940104862Sru@cindex drawing horizontal lines (@code{\l}) 10941104862Sru@cindex horizontal line, drawing (@code{\l}) 10942104862Sru@cindex line, horizontal, drawing (@code{\l}) 10943104862SruDraw a line horizontally. @var{l} is the length of the line to be 10944104862Srudrawn. If it is positive, start the line at the current location and 10945104862Srudraw to the right; its end point is the new current location. Negative 10946104862Sruvalues are handled differently: The line starts at the current location 10947104862Sruand draws to the left, but the current location doesn't move. 1094855839Sasmodai 10949104862Sru@var{l} can also be specified absolutely (i.e.@: with a leading 10950104862Sru@samp{|}) which draws back to the beginning of the input line. 10951104862SruDefault scaling indicator is @samp{m}. 1095269626Sru 10953104862Sru@cindex underscore glyph (@code{\[ru]}) 10954104862Sru@cindex glyph, underscore (@code{\[ru]}) 10955104862Sru@cindex line drawing glyph 10956104862Sru@cindex glyph, for line drawing 10957114402SruThe optional second parameter@tie{}@var{g} is a glyph to draw the line 1095875584Sruwith. If this second argument is not specified, @code{gtroff} uses 10959104862Sruthe underscore glyph, @code{\[ru]}. 1096055839Sasmodai 10961104862Sru@cindex zero width space character (@code{\&}) 10962104862Sru@cindex character, zero width space (@code{\&}) 10963104862Sru@cindex space character, zero width (@code{\&}) 1096469626SruTo separate the two arguments (to prevent @code{gtroff} from 10965104862Sruinterpreting a drawing glyph as a scaling indicator if the glyph is 10966104862Srurepresented by a single character) use @code{\&}. 1096755839Sasmodai 1096869626SruHere a small useful example: 1096955839Sasmodai 1097075584Sru@Example 1097155839Sasmodai.de box 10972104862Sru\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 1097355839Sasmodai.. 1097475584Sru@endExample 1097555839Sasmodai 1097669626Sru@noindent 1097769626SruNote that this works by outputting a box rule (a vertical line), then 10978104862Sruthe text given as an argument and then another box rule. Finally, the 10979104862Sruline drawing escapes both draw from the current location to the 10980104862Srubeginning of the @emph{input} line -- this works because the line 10981104862Srulength is negative, not moving the current point. 1098275584Sru@endDefesc 1098355839Sasmodai 10984114402Sru@DefescList {\\L, ', l, '} 10985114402Sru@DefescListEnd {\\L, ', lg, '} 10986104862Sru@cindex drawing vertical lines (@code{\L}) 10987104862Sru@cindex vertical line drawing (@code{\L}) 10988104862Sru@cindex line, vertical, drawing (@code{\L}) 10989104862Sru@cindex line drawing glyph 10990104862Sru@cindex glyph for line drawing 10991104862Sru@cindex box rule glyph (@code{\[br]}) 10992104862Sru@cindex glyph, box rule (@code{\[br]}) 10993104862SruDraw vertical lines. Its parameters are 10994104862Srusimilar to the @code{\l} escape, except that the default scaling 10995104862Sruindicator is @samp{v}. The movement is downwards for positive values, 10996104862Sruand upwards for negative values. The default glyph is the box rule 10997104862Sruglyph, @code{\[br]}. As with the vertical motion escapes, text 10998104862Sruprocessing blindly continues where the line ends. 1099955839Sasmodai 11000104862Sru@Example 11001104862SruThis is a \L'3v'test. 11002104862Sru@endExample 1100369626Sru 11004104862Sru@noindent 11005104862SruHere the result, produced with @code{grotty}. 11006104862Sru 1100775584Sru@Example 11008104862SruThis is a 11009104862Sru | 11010104862Sru | 11011104862Sru |test. 1101275584Sru@endExample 1101375584Sru@endDefesc 1101455839Sasmodai 1101575584Sru@Defesc {\\D, ', command arg @dots{}, '} 1101675584SruThe @code{\D} escape provides a variety of drawing functions. 11017104862SruNote that on character devices, only vertical and horizontal lines are 11018104862Srusupported within @code{grotty}; other devices may only support a subset 11019104862Sruof the available drawing functions. 1102055839Sasmodai 11021104862SruThe default scaling indicator for all subcommands of @code{\D} is 11022104862Sru@samp{m} for horizontal distances and @samp{v} for vertical ones. 11023104862SruExceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} 11024114402Sruwhich use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}} 11025114402Sruwhich arguments are treated similar to the @code{defcolor} request. 11026104862Sru 1102755839Sasmodai@table @code 1102869626Sru@item \D'l @var{dx} @var{dy}' 11029104862Sru@cindex line, drawing (@w{@code{\D'l @dots{}'}}) 11030104862Sru@cindex drawing a line (@w{@code{\D'l @dots{}'}}) 1103169626SruDraw a line from the current location to the relative point specified by 1103269626Sru(@var{dx},@var{dy}). 1103355839Sasmodai 11034104862SruThe following example is a macro for creating a box around a text string; 11035104862Srufor simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}. 1103669626Sru 1103775584Sru@Example 11038104862Sru.de BOX 11039104862Sru. nr @@wd \w'\\$1' 11040104862Sru\h'.2m'\ 11041104862Sru\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11042104862Sru\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 11043104862Sru\D'l (\\n[@@wd]u + .4m) 0'\ 11044104862Sru\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 11045104862Sru\D'l -(\\n[@@wd]u + .4m) 0'\ 11046104862Sru\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11047104862Sru\\$1\ 11048104862Sru\h'.2m' 11049104862Sru.. 1105075584Sru@endExample 1105155839Sasmodai 11052104862Sru@noindent 11053104862SruFirst, the width of the string is stored in register @code{@@wd}. Then, 11054104862Srufour lines are drawn to form a box, properly offset by the box margin. 11055104862SruThe registers @code{rst} and @code{rsb} are set by the @code{\w} escape, 11056104862Srucontaining the largest height and depth of the whole string. 11057104862Sru 1105855839Sasmodai@item \D'c @var{d}' 11059104862Sru@cindex circle, drawing (@w{@code{\D'c @dots{}'}}) 11060104862Sru@cindex drawing a circle (@w{@code{\D'c @dots{}'}}) 11061114402SruDraw a circle with a diameter of@tie{}@var{d} with the leftmost point at the 11062114402Srucurrent position. After drawing, the current location is positioned at the 11063114402Srurightmost point of the circle. 1106469626Sru 1106555839Sasmodai@item \D'C @var{d}' 11066104862Sru@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) 11067104862Sru@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) 11068104862Sru@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) 11069114402SruDraw a solid circle with the same parameters and behaviour as an outlined 11070114402Srucircle. No outline is drawn. 1107169626Sru 11072104862Sru@item \D'e @var{x} @var{y}' 11073104862Sru@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) 11074104862Sru@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) 11075104862SruDraw an ellipse with a horizontal diameter of @var{x} and a vertical 11076104862Srudiameter of @var{y} with the leftmost point at the current position. 11077114402SruAfter drawing, the current location is positioned at the rightmost point of 11078114402Sruthe ellipse. 1107969626Sru 11080104862Sru@item \D'E @var{x} @var{y}' 11081104862Sru@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) 11082104862Sru@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) 11083104862Sru@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) 11084114402SruDraw a solid ellipse with the same parameters and behaviour as an 11085114402Sruoutlined ellipse. No outline is drawn. 1108669626Sru 1108755839Sasmodai@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 11088104862Sru@cindex arc, drawing (@w{@code{\D'a @dots{}'}}) 11089104862Sru@cindex drawing an arc (@w{@code{\D'a @dots{}'}}) 1109055839SasmodaiDraw an arc clockwise from the current location through the two 11091104862Sruspecified relative locations (@var{dx1},@var{dy1}) and 11092104862Sru(@var{dx2},@var{dy2}). The coordinates of the first point are relative 11093104862Sruto the current position, and the coordinates of the second point are 11094114402Srurelative to the first point. After drawing, the current position is moved 11095114402Sruto the final point of the arc. 1109669626Sru 11097104862Sru@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11098104862Sru@cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) 11099104862Sru@cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) 11100104862SruDraw a spline from the current location to the relative point 11101104862Sru(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. 11102114402SruThe current position is moved to the terminal point of the drawn curve. 1110369626Sru 1110455839Sasmodai@item \D'f @var{n}' 11105104862Sru@cindex gray shading (@w{@code{\D'f @dots{}'}}) 11106104862Sru@cindex shading filled objects (@w{@code{\D'f @dots{}'}}) 11107114402SruSet the shade of gray to be used for filling solid objects to@tie{}@var{n}; 11108114402Sru@var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0 1110969626Srucorresponds solid white and 1000 to solid black, and values in between 1111069626Srucorrespond to intermediate shades of gray. This applies only to solid 11111104862Srucircles, solid ellipses, and solid polygons. By default, a level of 11112104862Sru1000 is used. 1111355839Sasmodai 11114114402SruDespite of being silly, the current point is moved horizontally to the 11115114402Sruright by@tie{}@var{n}. 11116114402Sru 11117114402Sru@cindex @w{@code{\D'f @dots{}'}} and horizontal resolution 11118114402SruDon't use this command! It has the serious drawback that it will be 11119114402Srualways rounded to the next integer multiple of the horizontal resolution 11120114402Sru(the value of the @code{hor} keyword in the @file{DESC} file). Use 11121114402Sru@code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead. 11122114402Sru 11123104862Sru@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11124104862Sru@cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) 11125104862Sru@cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) 11126104862SruDraw a polygon from the current location to the relative position 11127104862Sru(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. 11128104862SruWhen the specified data points are exhausted, a line is drawn back 11129114402Sruto the starting point. The current position is changed by adding the 11130114402Srusum of all arguments with odd index to the actual horizontal position and 11131114402Sruthe even ones to the vertical position. 1113269626Sru 11133104862Sru@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11134104862Sru@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) 11135104862Sru@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) 11136104862Sru@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) 11137114402SruDraw a solid polygon with the same parameters and behaviour as an 11138114402Sruoutlined polygon. No outline is drawn. 1113955839Sasmodai 11140104862SruHere a better variant of the box macro to fill the box with some color. 11141104862SruNote that the box must be drawn before the text since colors in 11142104862Sru@code{gtroff} are not transparent; the filled polygon would hide the 11143104862Srutext completely. 1114469626Sru 1114575584Sru@Example 11146104862Sru.de BOX 11147104862Sru. nr @@wd \w'\\$1' 11148104862Sru\h'.2m'\ 11149104862Sru\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11150104862Sru\M[lightcyan]\ 11151104862Sru\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 11152104862Sru (\\n[@@wd]u + .4m) 0 \ 11153104862Sru 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 11154104862Sru -(\\n[@@wd]u + .4m) 0'\ 11155104862Sru\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11156104862Sru\M[]\ 11157104862Sru\\$1\ 11158104862Sru\h'.2m' 11159104862Sru.. 1116075584Sru@endExample 1116155839Sasmodai 1116255839Sasmodai@item \D't @var{n}' 11163104862Sru@cindex line thickness (@w{@code{\D't @dots{}'}}) 11164104862Sru@cindex thickness of lines (@w{@code{\D't @dots{}'}}) 11165114402SruSet the current line thickness to @var{n}@tie{}machine units. A value of 1116669626Sruzero selects the smallest available line thickness. A negative value 1116769626Srumakes the line thickness proportional to the current point size (this is 11168104862Sruthe default behaviour of @acronym{AT&T} @code{troff}). 11169114402Sru 11170114402SruDespite of being silly, the current point is moved horizontally to the 11171114402Sruright by@tie{}@var{n}. 11172114402Sru 11173114402Sru@item \D'F@var{scheme} @var{color_components}' 11174114402Sru@cindex unnamed fill colors (@code{\D'F@dots{}'}) 11175114402Sru@cindex fill colors, unnamed (@code{\D'F@dots{}'}) 11176114402Sru@cindex colors, fill, unnamed (@code{\D'F@dots{}'}) 11177114402SruChange current fill color. @var{scheme} is a single letter denoting the 11178114402Srucolor scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g} 11179114402Sru(gray), or @samp{d} (default color). The color components use exactly 11180114402Sruthe same syntax as in the @code{defcolor} request (@pxref{Colors}); the 11181114402Srucommand @code{\D'Fd'} doesn't take an argument. 11182114402Sru 11183114402Sru@emph{No} position changing! 11184114402Sru 11185114402SruExamples: 11186114402Sru 11187114402Sru@Example 11188114402Sru@endExample 11189114402Sru\D'Fg .3' \" same gray as \D'f 700' 11190114402Sru\D'Fr #0000ff' \" blue 1119155839Sasmodai@end table 1119275584Sru@endDefesc 1119355839Sasmodai 11194104862Sru@xref{Graphics Commands}. 11195104862Sru 1119675584Sru@Defesc {\\b, ', string, '} 11197104862Sru@cindex pile, glyph (@code{\b}) 11198104862Sru@cindex glyph pile (@code{\b}) 11199104862Sru@cindex stacking glyphs (@code{\b}) 11200104862Sru@dfn{Pile} a sequence of glyphs vertically, and center it vertically 11201104862Sruon the current line. Use it to build large brackets and braces. 1120255839Sasmodai 11203104862SruHere an example how to create a large opening brace: 11204104862Sru 1120575584Sru@Example 11206104862Sru\b'\[lt]\[bv]\[lk]\[bv]\[lb]' 1120775584Sru@endExample 11208104862Sru 11209104862Sru@cindex @code{\b}, limitations 11210104862Sru@cindex limitations of @code{\b} escape 11211104862SruThe first glyph is on the top, the last glyph in @var{string} is 11212104862Sruat the bottom. Note that @code{gtroff} separates the glyphs 11213104862Sruvertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m} 11214104862Sruabove the current baseline; the largest glyph width is used as the 11215104862Sruwidth for the whole object. This rather unflexible positioning 11216104862Srualgorithm doesn't work with @option{-Tdvi} since the bracket pieces vary 11217104862Sruin height for this device. Instead, use the @code{eqn} preprocessor. 11218104862Sru 11219104862Sru@xref{Manipulating Spacing}, how to adjust the vertical spacing with 11220104862Sruthe @code{\x} escape. 1122175584Sru@endDefesc 1122255839Sasmodai 1122355839Sasmodai 1122469626Sru@c ===================================================================== 1122555839Sasmodai 1122675584Sru@node Traps, Diversions, Drawing Requests, gtroff Reference 1122755839Sasmodai@section Traps 1122855839Sasmodai@cindex traps 1122955839Sasmodai 1123075584Sru@dfn{Traps} are locations, which, when reached, call a specified 1123169626Srumacro. These traps can occur at a given location on the page, at a 11232104862Srugiven location in the current diversion, at a blank line, 11233104862Sruafter a certain number of input lines, or at the end of input. 1123455839Sasmodai 11235104862Sru@cindex planting a trap 11236104862Sru@cindex trap, planting 11237104862SruSetting a trap is also called @dfn{planting}. 11238104862Sru@cindex trap, springing 11239104862Sru@cindex springing a trap 11240104862SruIt is also said that a trap is @dfn{sprung} if the associated macro 11241104862Sruis executed. 11242104862Sru 1124355839Sasmodai@menu 1124475584Sru* Page Location Traps:: 1124575584Sru* Diversion Traps:: 1124675584Sru* Input Line Traps:: 11247104862Sru* Blank Line Traps:: 1124875584Sru* End-of-input Traps:: 1124955839Sasmodai@end menu 1125055839Sasmodai 1125169626Sru@c --------------------------------------------------------------------- 1125269626Sru 1125355839Sasmodai@node Page Location Traps, Diversion Traps, Traps, Traps 1125455839Sasmodai@subsection Page Location Traps 1125555839Sasmodai@cindex page location traps 1125655839Sasmodai@cindex traps, page location 1125755839Sasmodai 1125875584Sru@dfn{Page location traps} perform an action when @code{gtroff} 11259104862Srureaches or passes a certain vertical location on the page. Page 11260104862Srulocation traps have a variety of purposes, including: 1126155839Sasmodai 1126275584Sru@itemize 1126375584Sru@item 1126475584Srusetting headers and footers 1126575584Sru 1126675584Sru@item 1126775584Srusetting body text in multiple columns 1126875584Sru 1126975584Sru@item 1127075584Srusetting footnotes 1127175584Sru@end itemize 1127275584Sru 11273104862Sru@DefreqList {vpt, flag} 11274104862Sru@DefregListEnd {.vpt} 11275104862Sru@cindex enabling vertical position traps (@code{vpt}) 11276104862Sru@cindex vertical position traps, enabling (@code{vpt}) 11277104862Sru@cindex vertical position trap enable register (@code{.vpt}) 11278104862SruEnable vertical position traps if @var{flag} is non-zero, or disables 1127975584Sruthem otherwise. Vertical position traps are traps set by the @code{wh} 1128075584Sruor @code{dt} requests. Traps set by the @code{it} request are not 1128175584Sruvertical position traps. The parameter that controls whether vertical 1128275584Sruposition traps are enabled is global. Initially vertical position traps 1128375584Sruare enabled. The current setting of this is available in the 1128475584Sru@code{.vpt} read-only number register. 11285114402Sru 11286114402SruNote that a page can't be ejected if @code{vpt} is set to zero. 1128775584Sru@endDefreq 1128875584Sru 11289104862Sru@Defreq {wh, dist [@Var{macro}]} 11290114402SruSet a page location trap. Non-negative values for @var{dist} set 1129175584Sruthe trap relative to the top of the page; negative values set 11292104862Sruthe trap relative to the bottom of the page. Default scaling 11293104862Sruindicator is @samp{v}. 1129475584Sru 1129575584Sru@var{macro} is the name of the macro to execute when the 11296104862Srutrap is sprung. If @var{macro} is missing, remove the first trap 11297104862Sru(if any) at @var{dist}. 1129875584Sru 1129969626Sru@cindex page headers 1130069626Sru@cindex page footers 1130169626Sru@cindex headers 1130269626Sru@cindex footers 1130375584SruThe following is a simple example of how many macro packages 1130475584Sruset headers and footers. 1130555839Sasmodai 1130675584Sru@Example 1130769626Sru.de hd \" Page header 11308104862Sru' sp .5i 11309104862Sru. tl 'Title''date' 11310104862Sru' sp .3i 1131155839Sasmodai.. 11312104862Sru. 1131369626Sru.de fo \" Page footer 11314104862Sru' sp 1v 11315104862Sru. tl ''%'' 11316104862Sru' bp 1131755839Sasmodai.. 11318104862Sru. 1131969626Sru.wh 0 hd \" trap at top of the page 1132069626Sru.wh -1i fo \" trap one inch from bottom 1132175584Sru@endExample 11322104862Sru 11323104862SruA trap at or below the bottom of the page is ignored; it can be made 11324104862Sruactive by either moving it up or increasing the page length so that the 11325104862Srutrap is on the page. 11326104862Sru 11327104862SruIt is possible to have more than one trap at the same location; to do so, 11328104862Sruthe traps must be defined at different locations, then moved together with 11329104862Sruthe @code{ch} request; otherwise the second trap would replace the first 11330104862Sruone. Earlier defined traps hide later defined traps if moved to the same 11331114402Sruposition (the many empty lines caused by the @code{bp} request are omitted 11332114402Sruin the following example): 11333104862Sru 11334104862Sru@Example 11335104862Sru.de a 11336104862Sru. nop a 11337104862Sru.. 11338104862Sru.de b 11339104862Sru. nop b 11340104862Sru.. 11341104862Sru.de c 11342104862Sru. nop c 11343104862Sru.. 11344104862Sru. 11345104862Sru.wh 1i a 11346104862Sru.wh 2i b 11347104862Sru.wh 3i c 11348104862Sru.bp 11349104862Sru @result{} a b c 11350104862Sru@endExample 11351104862Sru@Example 11352104862Sru.ch b 1i 11353104862Sru.ch c 1i 11354104862Sru.bp 11355104862Sru @result{} a 11356104862Sru@endExample 11357104862Sru@Example 11358104862Sru.ch a 0.5i 11359104862Sru.bp 11360104862Sru @result{} a b 11361104862Sru@endExample 1136275584Sru@endDefreq 1136355839Sasmodai 1136475584Sru@Defreg {.t} 11365104862Sru@cindex distance to next trap register (@code{.t}) 11366104862Sru@cindex trap, distance, register (@code{.t}) 1136775584SruA read-only number register holding the distance to the next trap. 11368104862Sru 11369104862SruIf there are no traps between the current position and the bottom of the 11370104862Srupage, it contains the distance to the page bottom. In a diversion, the 11371104862Srudistance to the page bottom is infinite (the returned value is the biggest 11372104862Sruinteger which can be represented in @code{groff}) if there are no diversion 11373104862Srutraps. 1137475584Sru@endDefreg 1137555839Sasmodai 11376114402Sru@Defreq {ch, macro [@Var{dist}]} 11377104862Sru@cindex changing trap location (@code{ch}) 11378104862Sru@cindex trap, changing location (@code{ch}) 11379104862SruChange the location of a trap. 1138075584SruThe first argument is the name of the macro to be invoked at 1138175584Sruthe trap, and the second argument is the new location for the trap 11382114402Sru(note that the parameters are specified in opposite order as in the 11383114402Sru@code{wh} request). This is useful for building up footnotes in a 11384114402Srudiversion to allow more space at the bottom of the page for them. 1138555839Sasmodai 11386104862SruDefault scaling indicator for @var{dist} is @samp{v}. If @var{dist} 11387104862Sruis missing, the trap is removed. 11388104862Sru 1138969626Sru@c XXX 1139069626Sru 1139169626Sru@ignore 1139275584Sru@Example 1139355839Sasmodai... (simplified) footnote example ... 1139475584Sru@endExample 1139569626Sru@end ignore 1139675584Sru@endDefreq 1139755839Sasmodai 1139875584Sru@Defreg {.ne} 1139975584SruThe read-only number register @code{.ne} contains the amount of space 1140075584Sruthat was needed in the last @code{ne} request that caused a trap to be 1140175584Srusprung. Useful in conjunction with the @code{.trunc} register. 1140275584Sru@xref{Page Control}, for more information. 11403114402Sru 11404114402SruSince the @code{.ne} register is only set by traps it doesn't make 11405114402Srumuch sense to use it outside of trap macros. 1140675584Sru@endDefreg 1140755839Sasmodai 1140875584Sru@Defreg {.trunc} 11409104862Sru@cindex @code{ne} request, and the @code{.trunc} register 11410104862Sru@cindex truncated vertical space register (@code{.trunc}) 1141175584SruA read-only register containing the amount of vertical space truncated 1141275584Sruby the most recently sprung vertical position trap, or, if the trap was 1141375584Srusprung by an @code{ne} request, minus the amount of vertical motion 1141475584Sruproduced by the @code{ne} request. In other words, at the point a trap 1141575584Sruis sprung, it represents the difference of what the vertical position 1141675584Sruwould have been but for the trap, and what the vertical position 1141775584Sruactually is. 11418114402Sru 11419114402SruSince the @code{.trunc} register is only set by traps and it doesn't make 11420114402Srumuch sense to use it outside of trap macros. 1142175584Sru@endDefreg 1142255839Sasmodai 11423114402Sru@Defreg {.pe} 11424114402Sru@cindex @code{bp} request, and traps (@code{.pe}) 11425114402Sru@cindex traps, sprung by @code{bp} request (@code{.pe}) 11426114402Sru@cindex page ejecting register (@code{.pe}) 11427114402SruA read-only register which is set to@tie{}1 while a page is ejected with 11428114402Sruthe @code{bp} request (or by the end of input). 11429114402Sru 11430114402SruOutside of traps this register is always zero. In the following example, 11431114402Sruonly the second call to@tie{}@code{x} is caused by @code{bp}. 11432114402Sru 11433114402Sru@Example 11434114402Sru.de x 11435114402Sru\&.pe=\\n[.pe] 11436114402Sru.br 11437114402Sru.. 11438114402Sru.wh 1v x 11439114402Sru.wh 4v x 11440114402SruA line. 11441114402Sru.br 11442114402SruAnother line. 11443114402Sru.br 11444114402Sru @result{} A line. 11445114402Sru .pe=0 11446114402Sru Another line. 11447114402Sru 11448114402Sru .pe=1 11449114402Sru@endExample 11450114402Sru@endDefreg 11451114402Sru 11452114402Sru@cindex diversions, and traps 11453114402Sru@cindex traps, and diversions 11454114402SruAn important fact to consider while designing macros is that diversions and 11455114402Srutraps do not interact normally. For example, if a trap invokes a header 11456114402Srumacro (while outputting a diversion) which tries to change the font on the 11457114402Srucurrent page, the effect will not be visible before the diversion has 11458114402Srucompletely been printed (except for input protected with @code{\!} or 11459114402Sru@code{\?}) since the data in the diversion is already formatted. In most 11460114402Srucases, this is not the expected behaviour. 11461114402Sru 1146269626Sru@c --------------------------------------------------------------------- 1146355839Sasmodai 1146455839Sasmodai@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 1146555839Sasmodai@subsection Diversion Traps 1146655839Sasmodai@cindex diversion traps 1146755839Sasmodai@cindex traps, diversion 1146855839Sasmodai 1146975584Sru@Defreq {dt, dist macro} 11470104862Sru@cindex @code{.t} register, and diversions 11471104862Sru@cindex setting diversion trap (@code{dt}) 11472104862Sru@cindex diversion trap, setting (@code{dt}) 11473104862Sru@cindex trap, diversion, setting (@code{dt}) 11474104862SruSet a trap @emph{within} a diversion. 11475104862Sru@var{dist} is the location of the trap 11476114402Sru(identical to the @code{wh} request; default scaling indicator is 11477104862Sru@samp{v}) and @var{macro} is the name of the macro to be invoked. The 1147875584Srunumber register @code{.t} still works within diversions. 1147955839Sasmodai@xref{Diversions}, for more information. 1148075584Sru@endDefreq 1148155839Sasmodai 1148269626Sru@c --------------------------------------------------------------------- 1148369626Sru 11484104862Sru@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps 1148555839Sasmodai@subsection Input Line Traps 1148655839Sasmodai@cindex input line traps 1148755839Sasmodai@cindex traps, input line 1148855839Sasmodai 11489104862Sru@DefreqList {it, n macro} 11490104862Sru@DefreqItem {itc, n macro} 11491104862Sru@cindex setting input line trap (@code{it}) 11492104862Sru@cindex input line trap, setting (@code{it}) 11493104862Sru@cindex trap, input line, setting (@code{it}) 11494104862SruSet an input line trap. 11495114402Sru@var{n}@tie{}is the number of lines of input which may be read before 11496104862Sruspringing the trap, @var{macro} is the macro to be invoked. 1149769626SruRequest lines are not counted as input lines. 1149869626Sru 1149975584SruFor example, one possible use is to have a macro which prints the 11500114402Srunext @var{n}@tie{}lines in a bold font. 1150155839Sasmodai 1150275584Sru@Example 1150355839Sasmodai.de B 11504104862Sru. it \\$1 B-end 11505104862Sru. ft B 1150655839Sasmodai.. 11507104862Sru. 1150855839Sasmodai.de B-end 11509104862Sru. ft R 1151055839Sasmodai.. 1151175584Sru@endExample 11512104862Sru 11513104862Sru@cindex input line traps and interrupted lines (@code{itc}) 11514104862Sru@cindex interrupted lines and input line traps (@code{itc}) 11515104862Sru@cindex traps, input line, and interrupted lines (@code{itc}) 11516104862Sru@cindex lines, interrupted, and input line traps (@code{itc}) 11517114402SruThe @code{itc} request is identical 11518114402Sruexcept that an interrupted text line (ending with @code{\c}) 11519114402Sruis not counted as a separate line. 11520104862Sru 11521104862SruBoth requests are associated with the current environment 11522104862Sru(@pxref{Environments}); switching to another environment disables the 11523104862Srucurrent input trap, and going back reactivates it, restoring the number 11524104862Sruof already processed lines. 1152575584Sru@endDefreq 1152655839Sasmodai 1152769626Sru@c --------------------------------------------------------------------- 1152869626Sru 11529104862Sru@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps 11530104862Sru@subsection Blank Line Traps 11531104862Sru@cindex blank line traps 11532104862Sru@cindex traps, blank line 11533104862Sru 11534104862Sru@Defreq {blm, macro} 11535104862Sru@cindex blank line macro (@code{blm}) 11536104862SruSet a blank line trap. 11537104862Sru@code{gtroff} executes @var{macro} when it encounters a blank line in 11538104862Sruthe input file. 11539104862Sru@endDefreq 11540104862Sru 11541104862Sru@c --------------------------------------------------------------------- 11542104862Sru 11543104862Sru@node End-of-input Traps, , Blank Line Traps, Traps 1154455839Sasmodai@subsection End-of-input Traps 1154555839Sasmodai@cindex end-of-input traps 1154655839Sasmodai@cindex traps, end-of-input 1154755839Sasmodai 1154875584Sru@Defreq {em, macro} 11549104862Sru@cindex setting end-of-input trap (@code{em}) 11550104862Sru@cindex end-of-input trap, setting (@code{em}) 11551104862Sru@cindex trap, end-of-input, setting (@code{em}) 11552104862Sru@cindex end-of-input macro (@code{em}) 11553104862Sru@cindex macro, end-of-input (@code{em}) 11554104862SruSet a trap at the end of input. @var{macro} is executed after the 11555104862Srulast line of the input file has been processed. 1155655839Sasmodai 1155769626SruFor example, if the document had to have a section at the bottom of the 1155869626Srulast page for someone to approve it, the @code{em} request could be 1155969626Sruused. 1156055839Sasmodai 1156175584Sru@Example 1156255839Sasmodai.de approval 11563104862Sru. ne 5v 11564104862Sru. sp |(\\n[.t] - 6v) 11565104862Sru. in +4i 11566104862Sru. lc _ 11567104862Sru. br 1156855839SasmodaiApproved:\t\a 11569104862Sru. sp 1157055839SasmodaiDate:\t\t\a 1157155839Sasmodai.. 11572104862Sru. 1157355839Sasmodai.em approval 1157475584Sru@endExample 1157575584Sru@endDefreq 1157655839Sasmodai 1157755839Sasmodai 1157869626Sru@c ===================================================================== 1157969626Sru 1158075584Sru@node Diversions, Environments, Traps, gtroff Reference 1158155839Sasmodai@section Diversions 1158255839Sasmodai@cindex diversions 1158355839Sasmodai 1158469626SruIn @code{gtroff} it is possible to @dfn{divert} text into a named 1158569626Srustorage area. Due to the similarity to defining macros it is sometimes 1158669626Srusaid to be stored in a macro. This is used for saving text for output 1158769626Sruat a later time, which is useful for keeping blocks of text on the same 11588104862Srupage, footnotes, tables of contents, and indices. 1158955839Sasmodai 11590104862Sru@cindex top-level diversion 11591104862Sru@cindex diversion, top-level 11592104862SruFor orthogonality it is said that @code{gtroff} is in the @dfn{top-level 11593104862Srudiversion} if no diversion is active (i.e., the data is diverted to the 11594104862Sruoutput device). 1159575584Sru 11596104862Sru@DefreqList {di, macro} 11597104862Sru@DefreqListEnd {da, macro} 11598104862Sru@cindex beginning diversion (@code{di}) 11599104862Sru@cindex diversion, beginning (@code{di}) 11600104862Sru@cindex ending diversion (@code{di}) 11601104862Sru@cindex diversion, ending (@code{di}) 11602104862Sru@cindex appending to a diversion (@code{da}) 11603104862Sru@cindex diversion, appending (@code{da}) 11604104862SruBegin a diversion. Like the @code{de} 1160569626Srurequest, it takes an argument of a macro name to divert subsequent text 1160675584Sruinto. The @code{da} macro appends to an existing diversion. 1160755839Sasmodai 1160875584Sru@code{di} or @code{da} without an argument ends the diversion. 11609104862Sru@endDefreq 1161069626Sru 11611104862Sru@DefreqList {box, macro} 11612104862Sru@DefreqListEnd {boxa, macro} 11613104862SruBegin (or appends to) a diversion like the 11614104862Sru@code{di} and @code{da} requests. 11615104862SruThe difference is that @code{box} and @code{boxa} 11616104862Srudo not include a partially-filled line in the diversion. 1161769626Sru 11618104862SruCompare this: 11619104862Sru 1162075584Sru@Example 11621104862SruBefore the box. 11622104862Sru.box xxx 11623104862SruIn the box. 11624104862Sru.br 11625104862Sru.box 11626104862SruAfter the box. 11627104862Sru.br 11628104862Sru @result{} Before the box. After the box. 11629104862Sru.xxx 11630104862Sru @result{} In the box. 1163175584Sru@endExample 11632104862Sru 11633104862Sru@noindent 11634104862Sruwith this: 11635104862Sru 11636104862Sru@Example 11637104862SruBefore the diversion. 11638104862Sru.di yyy 11639104862SruIn the diversion. 11640104862Sru.br 11641104862Sru.di 11642104862SruAfter the diversion. 11643104862Sru.br 11644104862Sru @result{} After the diversion. 11645104862Sru.yyy 11646104862Sru @result{} Before the diversion. In the diversion. 11647104862Sru@endExample 11648104862Sru 11649104862Sru@code{box} or @code{boxa} without an argument ends the diversion. 1165075584Sru@endDefreq 1165155839Sasmodai 11652104862Sru@DefregList {.z} 11653104862Sru@DefregListEnd {.d} 11654104862Sru@cindex @code{nl} register, and @code{.d} 1165569626Sru@cindex nested diversions 1165669626Sru@cindex diversion, nested 11657104862Sru@cindex diversion name register (@code{.z}) 11658104862Sru@cindex vertical position in diversion register (@code{.d}) 11659104862Sru@cindex position, vertical, in diversion, register (@code{.d}) 11660104862Sru@cindex diversion, vertical position in, register (@code{.d}) 1166175584SruDiversions may be nested. The read-only number register @code{.z} 1166275584Srucontains the name of the current diversion (this is a string-valued 1166375584Sruregister). The read-only number register @code{.d} contains the current 1166475584Sruvertical place in the diversion. If not in a diversion it is the same 11665114402Sruas register @code{nl}. 1166675584Sru@endDefreg 1166769626Sru 1166875584Sru@Defreg {.h} 11669104862Sru@cindex high-water mark register (@code{.h}) 11670104862Sru@cindex mark, high-water, register (@code{.h}) 11671104862Sru@cindex position of lowest text line (@code{.h}) 11672104862Sru@cindex text line, position of lowest (@code{.h}) 1167375584SruThe @dfn{high-water mark} on the current page. It corresponds to the 1167475584Srutext baseline of the lowest line on the page. This is a read-only 1167575584Sruregister. 11676104862Sru 11677104862Sru@Example 11678104862Sru.tm .h==\n[.h], nl==\n[nl] 11679104862Sru @result{} .h==0, nl==-1 11680104862SruThis is a test. 11681104862Sru.br 11682104862Sru.sp 2 11683104862Sru.tm .h==\n[.h], nl==\n[nl] 11684104862Sru @result{} .h==40, nl==120 11685104862Sru@endExample 11686104862Sru 11687104862Sru@cindex @code{.h} register, difference to @code{nl} 11688104862Sru@cindex @code{nl} register, difference to @code{.h} 11689104862Sru@noindent 11690104862SruAs can be seen in the previous example, empty lines are not considered 11691104862Sruin the return value of the @code{.h} register. 1169275584Sru@endDefreg 1169355839Sasmodai 11694104862Sru@DefregList {dn} 11695104862Sru@DefregListEnd {dl} 11696114402Sru@cindex @code{dn} register, and @code{da} (@code{boxa}) 11697114402Sru@cindex @code{dl} register, and @code{da} (@code{boxa}) 11698114402Sru@cindex @code{da} request, and @code{dn} (@code{dl}) 11699114402Sru@cindex @code{boxa} request, and @code{dn} (@code{dl}) 1170075584SruAfter completing a diversion, the read-write number registers @code{dn} 1170155839Sasmodaiand @code{dl} contain the vertical and horizontal size of the diversion. 11702114402SruNote that only the just processed lines are counted: For the computation 11703114402Sruof @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are 11704114402Sruhandled as if @code{di} and @code{box} had been used -- lines which have 11705114402Srubeen already stored in a macro are not taken into account. 1170655839Sasmodai 11707104862Sru@Example 1170855839Sasmodai.\" Center text both horizontally & vertically 11709104862Sru. 11710104862Sru.\" Enclose macro definitions in .eo and .ec 11711104862Sru.\" to avoid the doubling of the backslash 11712104862Sru.eo 11713104862Sru.\" macro .(c starts centering mode 1171455839Sasmodai.de (c 11715104862Sru. br 11716104862Sru. ev (c 11717104862Sru. evc 0 11718104862Sru. in 0 11719104862Sru. nf 11720104862Sru. di @@c 1172155839Sasmodai.. 11722104862Sru@endExample 11723104862Sru@Example 11724104862Sru.\" macro .)c terminates centering mode 1172555839Sasmodai.de )c 11726104862Sru. br 11727104862Sru. ev 11728104862Sru. di 11729104862Sru. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 11730104862Sru. sp \n[@@s]u 11731104862Sru. ce 1000 11732104862Sru. @@c 11733104862Sru. ce 0 11734104862Sru. sp \n[@@s]u 11735104862Sru. br 11736104862Sru. fi 11737104862Sru. rr @@s 11738104862Sru. rm @@s 11739104862Sru. rm @@c 1174055839Sasmodai.. 11741104862Sru.\" End of macro definitions, restore escape mechanism 11742104862Sru.ec 11743104862Sru@endExample 1174475584Sru@endDefreg 1174555839Sasmodai 11746104862Sru@DefescList {\\!, , , } 11747114402Sru@DefescListEnd {\\?, , anything, \\?} 11748104862Sru@cindex transparent output (@code{\!}, @code{\?}) 11749104862Sru@cindex output, transparent (@code{\!}, @code{\?}) 11750104862SruPrevent requests, macros, and escapes from being 11751114402Sruinterpreted when read into a diversion. Both escapes take the given text 11752114402Sruand @dfn{transparently} embed it into the diversion. This is useful for 1175369626Srumacros which shouldn't be invoked until the diverted text is actually 1175469626Sruoutput. 1175555839Sasmodai 1175675584SruThe @code{\!} escape transparently embeds text up to 1175775584Sruand including the end of the line. 1175875584SruThe @code{\?} escape transparently embeds text until the next 11759114402Sruoccurrence of the @code{\?} escape. Example: 1176055839Sasmodai 1176175584Sru@Example 1176269626Sru\?@var{anything}\? 1176375584Sru@endExample 1176469626Sru 1176569626Sru@noindent 1176669626Sru@var{anything} may not contain newlines; use @code{\!} to embed 1176769626Srunewlines in a diversion. The escape sequence @code{\?} is also 1176869626Srurecognized in copy mode and turned into a single internal code; it is 11769104862Sruthis code that terminates @var{anything}. Thus the following example 11770114402Sruprints@tie{}4. 1177169626Sru 1177275584Sru@Example 1177355839Sasmodai.nr x 1 1177455839Sasmodai.nf 1177555839Sasmodai.di d 1177655839Sasmodai\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 1177755839Sasmodai.di 1177855839Sasmodai.nr x 2 1177955839Sasmodai.di e 1178055839Sasmodai.d 1178155839Sasmodai.di 1178255839Sasmodai.nr x 3 1178355839Sasmodai.di f 1178455839Sasmodai.e 1178555839Sasmodai.di 1178655839Sasmodai.nr x 4 1178755839Sasmodai.f 1178875584Sru@endExample 11789104862Sru 11790104862SruBoth escapes read the data in copy mode. 11791104862Sru 11792104862Sru@cindex @code{\!}, in top-level diversion 11793104862Sru@cindex top-level diversion, and @code{\!} 11794104862Sru@cindex diversion, top-level, and @code{\!} 11795104862SruIf @code{\!} is used in the top-level diversion, its argument is 11796104862Srudirectly embedded into the @code{gtroff} intermediate output. This can 11797104862Srube used for example to control a postprocessor which processes the data 11798104862Srubefore it is sent to the device driver. 11799104862Sru 11800104862Sru@cindex @code{\?}, in top-level diversion 11801104862Sru@cindex top-level diversion, and @code{\?} 11802104862Sru@cindex diversion, top-level, and @code{\?} 11803104862SruThe @code{\?} escape used in the top-level diversion produces no output 11804104862Sruat all; its argument is simply ignored. 1180575584Sru@endDefesc 1180655839Sasmodai 11807104862Sru@cindex @code{\!}, and @code{output} 11808104862Sru@cindex @code{output} request, and @code{\!} 11809104862Sru@Defreq {output, string} 11810104862SruEmit @var{string} directly to the @code{gtroff} intermediate output 11811114402Sru(subject to copy-mode interpretation); this is similar to @code{\!} used 11812104862Sruat the top level. An initial double quote in @var{string} is stripped off 11813104862Sruto allow initial blanks. 11814104862Sru 11815104862SruThis request can't be used before the first page has started -- if you get 11816104862Sruan error, simply insert @code{.br} before the @code{output} request. 11817104862Sru 11818104862SruWithout argument, @code{output} is ignored. 11819104862Sru 11820104862SruUse with caution! It is normally only needed for mark-up used by a 11821104862Srupostprocessor which does something with the output before sending it to 11822114402Sruthe output device, filtering out @var{string} again. 11823104862Sru@endDefreq 11824104862Sru 1182575584Sru@Defreq {asciify, div} 11826104862Sru@cindex unformatting diversions (@code{asciify}) 11827104862Sru@cindex diversion, unformatting (@code{asciify}) 11828104862Sru@cindex @code{trin} request, and @code{asciify} 11829104862Sru@dfn{Unformat} the diversion specified by @var{div} 11830104862Sruin such a way that @acronym{ASCII} characters, characters translated with 11831104862Sruthe @code{trin} request, space characters, and some escape sequences that 1183275584Sruwere formatted and diverted are treated like ordinary input 1183375584Srucharacters when the diversion is reread. It can be also used for gross 11834114402Sruhacks; for example, the following sets register@tie{}@code{n} to@tie{}1. 1183555839Sasmodai 1183675584Sru@Example 1183769626Sru.tr @@. 1183869626Sru.di x 1183975584Sru@@nr n 1 1184055839Sasmodai.br 1184155839Sasmodai.di 1184269626Sru.tr @@@@ 1184369626Sru.asciify x 1184455839Sasmodai.x 1184575584Sru@endExample 1184655839Sasmodai 1184769626Sru@xref{Copy-in Mode}. 1184875584Sru@endDefreq 1184955839Sasmodai 11850104862Sru@Defreq {unformat, div} 11851104862SruLike @code{asciify}, unformat the specified diversion. 11852104862SruHowever, @code{unformat} only unformats spaces and tabs 11853104862Srubetween words. 11854104862SruUnformatted tabs are treated as input tokens, 11855104862Sruand spaces are stretchable again. 1185655839Sasmodai 11857104862SruThe vertical size of lines is not preserved; glyph information (font, 11858104862Srufont size, space width, etc.)@: is retained. 11859104862Sru@endDefreq 11860104862Sru 11861104862Sru 1186269626Sru@c ===================================================================== 1186369626Sru 1186475584Sru@node Environments, Suppressing output, Diversions, gtroff Reference 1186555839Sasmodai@section Environments 1186655839Sasmodai@cindex environments 1186755839Sasmodai 1186869626SruIt happens frequently that some text should be printed in a certain 1186969626Sruformat regardless of what may be in effect at the time, for example, in 1187069626Srua trap invoked macro to print headers and footers. To solve this 1187175584Sru@code{gtroff} processes text in @dfn{environments}. An 1187269626Sruenvironment contains most of the parameters that control text 1187369626Sruprocessing. It is possible to switch amongst these environments; by 11874114402Srudefault @code{gtroff} processes text in environment@tie{}0. The 1187569626Srufollowing is the information kept in an environment. 1187655839Sasmodai 1187769626Sru@itemize @bullet 1187869626Sru@item 11879104862Srufont parameters (size, family, style, glyph height and slant, space 1188069626Sruand sentence space size) 1188155839Sasmodai 1188255839Sasmodai@item 1188369626Srupage parameters (line length, title length, vertical spacing, 11884104862Sruline spacing, indentation, line numbering, centering, right-justifying, 11885104862Sruunderlining, hyphenation data) 1188669626Sru 1188755839Sasmodai@item 1188869626Srufill and adjust mode 1188969626Sru 1189055839Sasmodai@item 11891104862Srutab stops, tab and leader characters, escape character, 11892104862Sruno-break and hyphen indicators, margin character data 1189369626Sru 1189455839Sasmodai@item 1189569626Srupartially collected lines 11896104862Sru 11897104862Sru@item 11898104862Sruinput traps 11899104862Sru 11900104862Sru@item 11901104862Srudrawing and fill colours 1190255839Sasmodai@end itemize 1190355839Sasmodai 1190469626SruThese environments may be given arbitrary names (see @ref{Identifiers}, 1190569626Srufor more info). Old versions of @code{troff} only had environments 11906104862Srunamed @samp{0}, @samp{1}, and @samp{2}. 1190755839Sasmodai 11908104862Sru@DefreqList {ev, [@Var{env}]} 11909104862Sru@DefregListEnd {.ev} 11910104862Sru@cindex switching environments (@code{ev}) 11911104862Sru@cindex environment, switching (@code{ev}) 11912104862Sru@cindex environment number/name register (@code{.ev}) 11913104862SruSwitch to another environment. The argument @var{env} is the name of 1191475584Sruthe environment to switch to. With no argument, @code{gtroff} switches 1191575584Sruback to the previous environment. There is no limit on the number of 1191675584Srunamed environments; they are created the first time that they are 1191775584Srureferenced. The @code{.ev} read-only register contains the name or 1191875584Srunumber of the current environment. This is a string-valued register. 1191955839Sasmodai 1192075584SruNote that a call to @code{ev} (with argument) pushes the previously 1192169626Sruactive environment onto a stack. If, say, environments @samp{foo}, 1192269626Sru@samp{bar}, and @samp{zap} are called (in that order), the first 1192375584Sru@code{ev} request without parameter switches back to environment 1192475584Sru@samp{bar} (which is popped off the stack), and a second call 1192575584Sruswitches back to environment @samp{foo}. 1192669626Sru 1192775584SruHere is an example: 1192869626Sru 1192975584Sru@Example 1193055839Sasmodai.ev footnote-env 1193155839Sasmodai.fam N 1193255839Sasmodai.ps 6 1193355839Sasmodai.vs 8 1193455839Sasmodai.ll -.5i 1193555839Sasmodai.ev 1193675584Sru 1193755839Sasmodai... 1193875584Sru 1193955839Sasmodai.ev footnote-env 1194055839Sasmodai\(dg Note the large, friendly letters. 1194155839Sasmodai.ev 1194275584Sru@endExample 1194375584Sru@endDefreq 1194455839Sasmodai 1194575584Sru@Defreq {evc, env} 11946104862Sru@cindex copying environment (@code{evc}) 11947104862Sru@cindex environment, copying (@code{evc}) 11948104862SruCopy the environment @var{env} into the current environment. 11949104862Sru 11950104862SruThe following environment data is not copied: 11951104862Sru 11952104862Sru@itemize @bullet 11953104862Sru@item 11954104862SruPartially filled lines. 11955104862Sru 11956104862Sru@item 11957104862SruThe status whether the previous line was interrupted. 11958104862Sru 11959104862Sru@item 11960104862SruThe number of lines still to center, or to right-justify, or to underline 11961104862Sru(with or without underlined spaces); they are set to zero. 11962104862Sru 11963104862Sru@item 11964104862SruThe status whether a temporary indent is active. 11965104862Sru 11966104862Sru@item 11967104862SruInput traps and its associated data. 11968104862Sru 11969104862Sru@item 11970104862SruLine numbering mode is disabled; it can be reactivated with 11971104862Sru@w{@samp{.nm +0}}. 11972104862Sru 11973104862Sru@item 11974104862SruThe number of consecutive hyphenated lines (set to zero). 11975104862Sru@end itemize 1197675584Sru@endDefreq 1197755839Sasmodai 11978114402Sru@DefregList {.w} 11979114402Sru@DefregItem {.cht} 11980104862Sru@DefregItem {.cdp} 11981104862Sru@DefregListEnd {.csk} 11982114402Sru@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 11983114402Sru@cindex width, of last glyph (@code{.w}) 11984114402Sru@cindex height, of last glyph (@code{.cht}) 11985114402Sru@cindex depth, of last glyph (@code{.cdp}) 11986114402Sru@cindex skew, of last glyph (@code{.csk}) 11987114402Sru@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 11988114402Sru@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 11989114402SruThe @code{\n[.w]} register contains the 11990114402Sruwidth of the last glyph added to the current environment. 11991114402Sru 11992104862SruThe @code{\n[.cht]} register contains the 11993114402Sruheight of the last glyph added to the current environment. 1199455839Sasmodai 11995104862SruThe @code{\n[.cdp]} register contains the 11996114402Srudepth of the last glyph added to the current environment. 11997114402SruIt is positive for glyphs extending below the baseline. 11998104862Sru 11999104862SruThe @code{\n[.csk]} register contains the 12000104862Sru@dfn{skew} (how far to the right of the glyph's center 12001114402Sruthat @code{gtroff} should place an accent) 12002104862Sruof the last glyph added to the current environment. 12003104862Sru@endDefreg 12004104862Sru 12005114402Sru@Defreg {.n} 12006114402Sru@cindex environment, previous line length (@code{.n}) 12007114402Sru@cindex line length, previous (@code{.n}) 12008114402Sru@cindex length of previous line (@code{.n}) 12009114402Sru@cindex previous line length (@code{.n}) 12010114402SruThe @code{\n[.n]} register contains the 12011114402Srulength of the previous output line in the current environment. 12012114402Sru@endDefreg 12013104862Sru 12014114402Sru 1201569626Sru@c ===================================================================== 1201655839Sasmodai 12017104862Sru@node Suppressing output, Colors, Environments, gtroff Reference 1201875584Sru@section Suppressing output 1201975584Sru 1202075584Sru@Defesc {\\O, , num, } 12021104862Sru@cindex suppressing output (@code{\O}) 12022104862Sru@cindex output, suppressing (@code{\O}) 12023104862SruDisable or enable output depending on the value of @var{num}: 1202475584Sru 1202575584Sru@table @samp 1202675584Sru@item \O0 12027104862SruDisable any glyphs from being emitted to the device driver, provided that 12028104862Sruthe escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}). 12029104862SruMotion is not suppressed so effectively @code{\O[0]} means @emph{pen up}. 1203075584Sru 1203175584Sru@item \O1 12032104862SruEnable output of glyphs, provided that the escape occurs at the outer 12033104862Srulevel. 1203475584Sru@end table 1203575584Sru 1203675584Sru@vindex opminx 1203775584Sru@vindex opminy 1203875584Sru@vindex opmaxx 1203975584Sru@vindex opmaxy 1204075584Sru@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 1204175584Sru@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 1204275584Sru@xref{Register Index}. These four registers mark the top left and 1204375584Srubottom right hand corners of a box which encompasses all written glyphs. 1204475584Sru 12045104862SruFor example the input text: 1204675584Sru 12047104862Sru@Example 12048104862SruHello \O[0]world \O[1]this is a test. 12049104862Sru@endExample 12050104862Sru 12051104862Sru@noindent 12052104862Sruproduces the following output: 12053104862Sru 12054104862Sru@Example 12055104862SruHello this is a test. 12056104862Sru@endExample 12057104862Sru 1205875584Sru@table @samp 1205975584Sru@item \O2 12060104862SruProvided that the escape occurs at the outer level, enable output of 12061104862Sruglyphs and also write out to @code{stderr} the page number and four 12062104862Sruregisters encompassing the glyphs previously written since the last call 12063104862Sruto @code{\O}. 1206475584Sru 1206575584Sru@item \O3 12066104862SruBegin a nesting level. At start-up, @code{gtroff} is at outer level. 12067104862Sru 12068104862Sru@item \O4 12069104862SruEnd a nesting level. 12070104862Sru 12071104862Sru@item \O[5@var{P}@var{filename}] 12072104862SruThis escape is @code{grohtml} specific. Provided that this escape 12073104862Sruoccurs at the outer nesting level write the @code{filename} to 12074104862Sru@code{stderr}. The position of the image, @var{P}, must be specified 12075114402Sruand must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left, 12076104862Sruright, centered, inline). @var{filename} will be associated with the 12077104862Sruproduction of the next inline image. 1207875584Sru@end table 1207975584Sru@endDefesc 1208075584Sru 12081104862Sru@c ===================================================================== 1208275584Sru 12083104862Sru@node Colors, I/O, Suppressing output, gtroff Reference 12084104862Sru@section Colors 12085104862Sru@cindex colors 12086104862Sru 12087104862Sru@DefreqList {color, [@Var{n}]} 12088104862Sru@DefregListEnd {.color} 12089104862SruIf @var{n} is missing or non-zero, activate colors (this is the default); 12090104862Sruotherwise, turn it off. 12091104862Sru 12092114402SruThe read-only number register @code{.color} is@tie{}1 if colors are active, 12093114402Sru0@tie{}otherwise. 12094104862Sru 12095104862SruInternally, @code{color} sets a global flag; it does not produce a token. 12096104862SruSimilar to the @code{cp} request, you should use it at the beginning of 12097104862Sruyour document to control color output. 12098104862Sru 12099104862SruColors can be also turned off with the @option{-c} command line option. 12100104862Sru@endDefreq 12101104862Sru 12102104862Sru@Defreq {defcolor, ident scheme color_components} 12103104862SruDefine color with name @var{ident}. @var{scheme} can be one of the 12104114402Srufollowing values: @code{rgb} (three components), @code{cmy} (three 12105104862Srucomponents), @code{cmyk} (four components), and @code{gray} or 12106104862Sru@code{grey} (one component). 12107104862Sru 12108104862Sru@cindex default color 12109104862Sru@cindex color, default 12110104862SruColor components can be given either as a hexadecimal string or as 12111104862Srupositive decimal integers in the range 0--65535. A hexadecimal string 12112104862Srucontains all color components concatenated. It must start with either 12113104862Sru@code{#} or @code{##}; the former specifies hex values in the range 12114114402Sru0--255 (which are internally multiplied by@tie{}257), the latter in the 12115104862Srurange 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} 12116104862Sru(magenta). The default color name @c{default} can't be redefined; its 12117104862Sruvalue is device-specific (usually black). It is possible that the 12118104862Srudefault color for @code{\m} and @code{\M} is not identical. 12119104862Sru 12120104862Sru@cindex @code{f} unit, and colors 12121104862Sru@cindex unit, @code{f}, and colors 12122114402SruA new scaling indicator@tie{}@code{f} has been introduced which multiplies 12123104862Sruits value by 65536; this makes it convenient to specify color components 12124114402Sruas fractions in the range 0 to@tie{}1 (1f equals 65536u). Example: 12125104862Sru 12126104862Sru@Example 12127104862Sru.defcolor darkgreen rgb 0.1f 0.5f 0.2f 12128104862Sru@endExample 12129104862Sru 12130104862SruNote that @code{f} is the default scaling indicator for the 12131104862Sru@code{defcolor} request, thus the above statement is equivalent to 12132104862Sru 12133104862Sru@Example 12134104862Sru.defcolor darkgreen rgb 0.1 0.5 0.2 12135104862Sru@endExample 12136104862Sru@endDefreq 12137104862Sru 12138104862Sru@DefescList {\\m, , c, } 12139104862Sru@DefescItem {\\m, @lparen{}, co, } 12140104862Sru@DefescListEnd {\\m, @lbrack{}, color, @rbrack} 12141104862SruSet drawing color. The following example shows how to turn the next four 12142104862Sruwords red. 12143104862Sru 12144104862Sru@Example 12145104862Sru\m[red]these are in red\m[] and these words are in black. 12146104862Sru@endExample 12147104862Sru 12148104862SruThe escape @code{\m[]} returns to the previous color. 12149104862Sru 12150104862SruThe drawing color is associated with the current environment 12151104862Sru(@pxref{Environments}). 12152104862Sru 12153104862SruNote that @code{\m} doesn't produce an input token in @code{gtroff}. 12154104862SruAs a consequence, it can be used in requests like @code{mc} (which 12155104862Sruexpects a single character as an argument) to change the color on 12156104862Sruthe fly: 12157104862Sru 12158104862Sru@Example 12159104862Sru.mc \m[red]x\m[] 12160104862Sru@endExample 12161104862Sru@endDefesc 12162104862Sru 12163104862Sru@DefescList {\\M, , c, } 12164104862Sru@DefescItem {\\M, @lparen{}, co, } 12165104862Sru@DefescListEnd {\\M, @lbrack{}, color, @rbrack} 12166104862SruSet background color for filled objects drawn with the 12167104862Sru@code{\D'@dots{}'} commands. 12168104862Sru 12169104862SruA red ellipse can be created with the following code: 12170104862Sru 12171104862Sru@Example 12172104862Sru\M[red]\h'0.5i'\D'E 2i 1i'\M[] 12173104862Sru@endExample 12174104862Sru 12175104862SruThe escape @code{\M[]} returns to the previous fill color. 12176104862Sru 12177104862SruThe fill color is associated with the current environment 12178104862Sru(@pxref{Environments}). 12179104862Sru 12180104862SruNote that @code{\M} doesn't produce an input token in @code{gtroff}. 12181104862Sru@endDefesc 12182104862Sru 12183104862Sru 1218475584Sru@c ===================================================================== 1218575584Sru 12186104862Sru@node I/O, Postprocessor Access, Colors, gtroff Reference 1218755839Sasmodai@section I/O 1218855839Sasmodai@cindex i/o 1218969626Sru@cindex input and output requests 1219069626Sru@cindex requests for input and output 1219169626Sru@cindex output and input requests 1219255839Sasmodai 1219375584Sru@code{gtroff} has several requests for including files: 1219475584Sru 1219575584Sru@Defreq {so, file} 12196104862Sru@cindex including a file (@code{so}) 12197104862Sru@cindex file, inclusion (@code{so}) 12198104862SruRead in the specified @var{file} and 1219975584Sruincludes it in place of the @code{so} request. This is quite useful for 1220075584Srularge documents, e.g.@: keeping each chapter in a separate file. 1220155839Sasmodai@xref{gsoelim}, for more information. 12202104862Sru 12203104862SruSince @code{gtroff} replaces the @code{so} request with the contents 12204104862Sruof @code{file}, it makes a difference whether the data is terminated with 12205104862Srua newline or not: Assuming that file @file{xxx} contains the word 12206104862Sru@samp{foo} without a final newline, this 12207104862Sru 12208104862Sru@Example 12209104862SruThis is 12210104862Sru.so xxx 12211104862Srubar 12212104862Sru@endExample 12213104862Sru 12214104862Sru@noindent 12215104862Sruyields @samp{This is foobar}. 1221675584Sru@endDefreq 1221755839Sasmodai 12218104862Sru@Defreq {pso, command} 12219104862SruRead the standard output from the specified @var{command} 12220104862Sruand includes it in place of the @code{pso} request. 12221104862Sru 12222104862Sru@cindex safer mode 12223104862Sru@cindex mode, safer 12224104862Sru@cindex unsafe mode 12225104862Sru@cindex mode, unsafe 12226104862SruThis request causes an error if used in safer mode (which is the default). 12227104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12228104862Srumode. 12229104862Sru 12230104862SruThe comment regarding a final newline for the @code{so} request is valid 12231104862Srufor @code{pso} also. 12232104862Sru@endDefreq 12233104862Sru 1223475584Sru@Defreq {mso, file} 12235104862SruIdentical to the @code{so} request except that @code{gtroff} searches for 12236104862Sruthe specified @var{file} in the same directories as macro files for the 1223775584Sruthe @option{-m} command line option. If the file name to be included 1223875584Sruhas the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 1223975584Sruto include @file{tmac.@var{name}} and vice versa. 1224075584Sru@endDefreq 1224155839Sasmodai 12242104862Sru@DefreqList {trf, file} 12243104862Sru@DefreqListEnd {cf, file} 12244104862Sru@cindex transparent output (@code{cf}, @code{trf}) 12245104862Sru@cindex output, transparent (@code{cf}, @code{trf}) 12246104862SruTransparently output the contents of @var{file}. Each line is output 12247104862Sruas if it were preceded by @code{\!}; however, the lines are not subject 12248104862Sruto copy mode interpretation. If the file does not end with a newline, 12249104862Sruthen a newline is added (@code{trf} only). For example, to define a 12250114402Srumacro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use 1225155839Sasmodai 1225275584Sru@Example 1225355839Sasmodai.di x 1225455839Sasmodai.trf f 1225555839Sasmodai.di 1225675584Sru@endExample 1225755839Sasmodai 12258104862SruBoth @code{trf} and @code{cf}, when used in a diversion, 1225975584Sruembeds an object in the diversion which, when reread, causes the 12260104862Srucontents of @var{file} to be transparently copied through to the 12261104862Sruoutput. In @acronym{UNIX} @code{troff}, the contents of @var{file} 1226269626Sruis immediately copied through to the output regardless of whether there 1226369626Sruis a current diversion; this behaviour is so anomalous that it must be 12264104862Sruconsidered a bug. 1226555839Sasmodai 12266104862Sru@cindex @code{trf} request, and invalid characters 12267104862Sru@cindex characters, invalid for @code{trf} request 12268104862Sru@cindex invalid characters for @code{trf} request 12269104862SruWhile @code{cf} copies the contents of @var{file} completely unprocessed, 12270104862Sru@code{trf} disallows characters such as NUL that are not valid 12271104862Sru@code{gtroff} input characters (@pxref{Identifiers}). 12272104862Sru 12273104862SruBoth requests cause a line break. 1227475584Sru@endDefreq 1227555839Sasmodai 12276104862Sru@Defreq {nx, [@Var{file}]} 12277104862Sru@cindex processing next file (@code{nx}) 12278104862Sru@cindex file, processing next (@code{nx}) 12279104862Sru@cindex next file, processing (@code{nx}) 12280104862SruForce @code{gtroff} to continue processing of 12281104862Sruthe file specified as an argument. If no argument is given, immediately 12282104862Srujump to the end of file. 1228375584Sru@endDefreq 1228455839Sasmodai 12285104862Sru@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]} 12286104862Sru@cindex reading from standard input (@code{rd}) 12287104862Sru@cindex standard input, reading from (@code{rd}) 12288104862Sru@cindex input, standard, reading from (@code{rd}) 12289104862SruRead from standard input, and include what is read as though it 12290104862Sruwere part of the input file. Text is read until a blank line 12291104862Sruis encountered. 12292104862Sru 12293104862SruIf standard input is a TTY input device (keyboard), write @var{prompt} 12294104862Sruto standard error, followed by a colon (or send BEL for a beep if no 12295104862Sruargument is given). 12296104862Sru 12297104862SruArguments after @var{prompt} are available for the input. For example, 12298104862Sruthe line 12299104862Sru 12300104862Sru@Example 12301104862Sru.rd data foo bar 12302104862Sru@endExample 12303104862Sru 12304104862Sruwith the input @w{@samp{This is \$2.}} prints 12305104862Sru 12306104862Sru@Example 12307104862SruThis is bar. 12308104862Sru@endExample 1230975584Sru@endDefreq 1231055839Sasmodai 1231155839Sasmodai@cindex form letters 1231255839Sasmodai@cindex letters, form 1231375584SruUsing the @code{nx} and @code{rd} requests, 1231475584Sruit is easy to set up form letters. The form 12315104862Sruletter template is constructed like this, putting the following lines 12316104862Sruinto a file called @file{repeat.let}: 1231755839Sasmodai 1231875584Sru@Example 1231955839Sasmodai.ce 1232055839Sasmodai\*(td 1232155839Sasmodai.sp 2 1232255839Sasmodai.nf 1232355839Sasmodai.rd 1232455839Sasmodai.sp 1232555839Sasmodai.rd 1232655839Sasmodai.fi 1232755839SasmodaiBody of letter. 1232855839Sasmodai.bp 1232955839Sasmodai.nx repeat.let 1233075584Sru@endExample 1233155839Sasmodai 12332104862Sru@cindex @code{ex} request, used with @code{nx} and @code{rd} 1233369626Sru@noindent 12334104862SruWhen this is run, a file containing the following lines should be 12335104862Sruredirected in. Note that requests included in this file are executed 12336104862Sruas though they were part of the form letter. The last block of input 12337104862Sruis the @code{ex} request which tells @code{groff} to stop processing. If 12338104862Sruthis was not there, @code{groff} would not know when to stop. 1233955839Sasmodai 1234075584Sru@Example 1234155839SasmodaiTrent A. Fisher 1234255839Sasmodai708 NW 19th Av., #202 1234355839SasmodaiPortland, OR 97209 1234455839Sasmodai 1234555839SasmodaiDear Trent, 1234655839Sasmodai 1234755839SasmodaiLen Adollar 1234855839Sasmodai4315 Sierra Vista 1234955839SasmodaiSan Diego, CA 92103 1235055839Sasmodai 1235155839SasmodaiDear Mr. Adollar, 1235255839Sasmodai 1235355839Sasmodai.ex 1235475584Sru@endExample 1235555839Sasmodai 1235675584Sru@Defreq {pi, pipe} 12357104862SruPipe the output of @code{gtroff} to the shell command(s) 1235875584Sruspecified by @var{pipe}. This request must occur before 1235975584Sru@code{gtroff} has a chance to print anything. 12360104862Sru 12361104862Sru@cindex safer mode 12362104862Sru@cindex mode, safer 12363104862Sru@cindex unsafe mode 12364104862Sru@cindex mode, unsafe 12365104862Sru@code{pi} causes an error if used in safer mode (which is the default). 12366104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12367104862Srumode. 12368104862Sru 12369104862SruMultiple calls to @code{pi} are allowed, acting as a chain. For example, 12370104862Sru 12371104862Sru@Example 12372104862Sru.pi foo 12373104862Sru.pi bar 12374104862Sru... 12375104862Sru@endExample 12376104862Sru 12377104862Sruis the same as @w{@samp{.pi foo | bar}}. 12378104862Sru 12379104862Sru@cindex @code{groff}, and @code{pi} request 12380104862Sru@cindex @code{pi} request, and @code{groff} 12381104862SruNote that the intermediate output format of @code{gtroff} is piped to 12382104862Sruthe specified commands. Consequently, calling @code{groff} without the 12383104862Sru@option{-Z} option normally causes a fatal error. 1238475584Sru@endDefreq 1238555839Sasmodai 12386104862Sru@DefreqList {sy, cmds} 12387104862Sru@DefregListEnd {systat} 12388104862SruExecute the shell command(s) specified by @var{cmds}. The output is not 12389104862Srusaved anyplace, so it is up to the user to do so. 1239069626Sru 12391104862Sru@cindex safer mode 12392104862Sru@cindex mode, safer 12393104862Sru@cindex unsafe mode 12394104862Sru@cindex mode, unsafe 12395104862SruThis request causes an error if used in safer mode (which is the default). 12396104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12397104862Srumode. 1239869626Sru 12399104862SruFor example, the following code fragment introduces the current time into a 12400104862Srudocument: 1240155839Sasmodai 1240269626Sru@cindex time, current 1240369626Sru@cindex current time 1240455839Sasmodai@pindex perl 1240575584Sru@Example 1240655839Sasmodai.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 12407114402Sru (localtime(time))[2,1,0]' > /tmp/x\n[$$] 1240855839Sasmodai.so /tmp/x\n[$$] 1240955839Sasmodai.sy rm /tmp/x\n[$$] 1241055839Sasmodai\nH:\nM:\nS 1241175584Sru@endExample 1241255839Sasmodai 1241369626Sru@noindent 1241469626SruNote that this works by having the @code{perl} script (run by @code{sy}) 1241575584Sruprint out the @code{nr} requests which set the number registers 12416104862Sru@code{H}, @code{M}, and @code{S}, and then reads those commands in with 1241769626Sruthe @code{so} request. 1241855839Sasmodai 12419104862SruFor most practical purposes, the number registers @code{seconds}, 12420104862Sru@code{minutes}, and @code{hours} which are initialized at start-up of 12421104862Sru@code{gtroff} should be sufficient. Use the @code{af} request to get a 12422104862Sruformatted output: 12423104862Sru 12424104862Sru@Example 12425104862Sru.af hours 00 12426104862Sru.af minutes 00 12427104862Sru.af seconds 00 12428104862Sru\n[hours]:\n[minutes]:\n[seconds] 12429104862Sru@endExample 12430104862Sru 12431104862Sru@cindex @code{system()} return value register (@code{systat}) 1243275584SruThe @code{systat} read-write number register contains the return value 1243375584Sruof the @code{system()} function executed by the last @code{sy} request. 1243475584Sru@endDefreq 1243555839Sasmodai 12436104862Sru@DefreqList {open, stream file} 12437104862Sru@DefreqListEnd {opena, stream file} 12438104862Sru@cindex opening file (@code{open}) 12439104862Sru@cindex file, opening (@code{open}) 12440104862Sru@cindex appending to a file (@code{opena}) 12441104862Sru@cindex file, appending to (@code{opena}) 12442104862SruOpen the specified @var{file} for writing and 1244375584Sruassociates the specified @var{stream} with it. 1244455839Sasmodai 12445104862SruThe @code{opena} request is like @code{open}, but if the file exists, 12446104862Sruappend to it instead of truncating it. 12447104862Sru 12448104862Sru@cindex safer mode 12449104862Sru@cindex mode, safer 12450104862Sru@cindex unsafe mode 12451104862Sru@cindex mode, unsafe 12452104862SruBoth @code{open} and @code{opena} cause an error if used in safer mode 12453104862Sru(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U} 12454104862Sruoption to activate unsafe mode. 1245575584Sru@endDefreq 1245655839Sasmodai 12457104862Sru@DefreqList {write, stream data} 12458104862Sru@DefreqListEnd {writec, stream data} 1245969626Sru@cindex copy-in mode, and @code{write} requests 1246069626Sru@cindex mode, copy-in, and @code{write} requests 12461104862Sru@cindex writing to file (@code{write}) 12462104862Sru@cindex file, writing to (@code{write}) 12463104862SruWrite to the file associated with the specified @var{stream}. 1246475584SruThe stream must previously have 1246569626Srubeen the subject of an open request. The remainder of the line is 1246669626Sruinterpreted as the @code{ds} request reads its second argument: A 1246775584Sruleading @samp{"} is stripped, and it is read in copy-in mode. 12468104862Sru 12469104862SruThe @code{writec} request is like @code{write}, but only 12470104862Sru@code{write} appends a newline to the data. 1247175584Sru@endDefreq 1247255839Sasmodai 12473104862Sru@Defreq {writem, stream xx} 12474104862Sru@cindex @code{asciify} request, and @code{writem} 12475104862SruWrite the contents of the macro or string @var{xx} 12476104862Sruto the file associated with the specified @var{stream}. 12477104862Sru 12478104862Sru@var{xx} is read in copy mode, i.e., already formatted elements are 12479104862Sruignored. Consequently, diversions must be unformatted with the 12480104862Sru@code{asciify} request before calling @code{writem}. Usually, this 12481104862Srumeans a loss of information. 12482104862Sru@endDefreq 12483104862Sru 1248475584Sru@Defreq {close, stream} 12485104862Sru@cindex closing file (@code{close}) 12486104862Sru@cindex file, closing (@code{close}) 12487104862SruClose the specified @var{stream}; 1248875584Sruthe stream is no longer an acceptable argument to the 1248969626Sru@code{write} request. 1249055839Sasmodai 12491104862SruHere a simple macro to write an index entry. 1249269626Sru 1249375584Sru@Example 12494104862Sru.open idx test.idx 12495104862Sru. 12496104862Sru.de IX 12497104862Sru. write idx \\n[%] \\$* 12498104862Sru.. 12499104862Sru. 12500104862Sru.IX test entry 12501104862Sru. 12502104862Sru.close idx 1250375584Sru@endExample 1250475584Sru@endDefreq 1250555839Sasmodai 12506104862Sru@DefescList {\\V, , e, } 12507104862Sru@DefescItem {\\V, @lparen{}, ev, } 12508104862Sru@DefescListEnd {\\V, @lbrack{}, env, @rbrack} 12509104862SruInterpolate the contents of the specified environment variable 12510114402Sru@var{env} (one-character name@tie{}@var{e}, two-character name @var{ev}) 12511104862Sruas returned by the function @code{getenv}. @code{\V} is interpreted 12512104862Sruin copy-in mode. 1251375584Sru@endDefesc 1251455839Sasmodai 1251555839Sasmodai 1251669626Sru@c ===================================================================== 1251769626Sru 1251875584Sru@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 1251955839Sasmodai@section Postprocessor Access 1252055839Sasmodai@cindex postprocessor access 1252155839Sasmodai@cindex access of postprocessor 1252255839Sasmodai 1252375584SruThere are two escapes which give information directly to the 1252475584Srupostprocessor. This is particularly useful for embedding 1252569626Sru@sc{PostScript} into the final document. 1252655839Sasmodai 1252775584Sru@Defesc {\\X, ', xxx, '} 1252875584SruEmbeds its argument into the @code{gtroff} 1252969626Sruoutput preceded with @w{@samp{x X}}. 12530104862Sru 12531104862Sru@cindex @code{\&}, in @code{\X} 12532104862Sru@cindex @code{\)}, in @code{\X} 12533104862Sru@cindex @code{\%}, in @code{\X} 12534104862Sru@ifnotinfo 12535104862Sru@cindex @code{\:}, in @code{\X} 12536104862Sru@end ifnotinfo 12537104862Sru@ifinfo 12538104862Sru@cindex @code{\@r{<colon>}}, in @code{\X} 12539104862Sru@end ifinfo 12540104862SruThe escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored 12541104862Sruwithin @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single 12542104862Sruspace characters. All other escapes (except @code{\\} which produces a 12543104862Srubackslash) cause an error. 12544104862Sru 12545104862Sru@kindex use_charnames_in_special 12546104862Sru@pindex DESC@r{, and @code{use_charnames_in_special}} 12547104862Sru@cindex @code{\X}, and special characters 12548104862SruIf the @samp{use_charnames_in_special} keyword is set in the @file{DESC} 12549104862Srufile, special characters no longer cause an error; the name @var{xx} is 12550104862Srurepresented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command. 12551104862SruAdditionally, the backslash is represented as @code{\\}. 12552104862Sru 12553104862Sru@samp{use_charnames_in_special} is currently used by @code{grohtml} only. 1255475584Sru@endDefesc 1255555839Sasmodai 12556104862Sru@DefescList {\\Y, , n, } 12557104862Sru@DefescItem {\\Y, @lparen{}, nm, } 12558104862Sru@DefescListEnd {\\Y, @lbrack{}, name, @rbrack} 12559104862SruThis is approximately equivalent to @samp{\X'\*[@var{name}]'} 12560114402Sru(one-character name@tie{}@var{n}, two-character name @var{nm}). 12561104862SruHowever, the contents of the string or macro @var{name} are not 12562104862Sruinterpreted; also it is permitted for @var{name} to have been defined 12563104862Sruas a macro and thus contain newlines (it is not permitted for the 12564104862Sruargument to @code{\X} to contain newlines). The inclusion of 12565104862Srunewlines requires an extension to the @acronym{UNIX} @code{troff} 12566104862Sruoutput format, and confuses drivers that do not know about this 12567104862Sruextension (@pxref{Device Control Commands}). 1256875584Sru@endDefesc 1256955839Sasmodai 1257069626Sru@xref{Output Devices}. 1257155839Sasmodai 1257255839Sasmodai 1257369626Sru@c ===================================================================== 1257455839Sasmodai 1257575584Sru@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 1257669626Sru@section Miscellaneous 1257755839Sasmodai 1257869626SruThis section documents parts of @code{gtroff} which cannot (yet) be 1257955839Sasmodaicategorized elsewhere in this manual. 1258055839Sasmodai 12581104862Sru@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]} 12582104862Sru@cindex printing line numbers (@code{nm}) 12583104862Sru@cindex line numbers, printing (@code{nm}) 12584104862Sru@cindex numbers, line, printing (@code{nm}) 12585104862SruPrint line numbers. 1258675584Sru@var{start} is the line number of the @emph{next} 12587104862Sruoutput line. @var{inc} indicates which line numbers are printed. 12588114402SruFor example, the value@tie{}5 means to emit only line numbers which 12589114402Sruare multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the 12590104862Sruspace to be left between the number and the text; this defaults to 12591104862Sruone digit space. The fourth argument is the indentation of the line 12592104862Srunumbers, defaulting to zero. Both @var{space} and @var{indent} are 12593104862Srugiven as multiples of digit spaces; they can be negative also. 12594104862SruWithout any arguments, line numbers are turned off. 1259555839Sasmodai 12596104862Sru@code{gtroff} reserves three digit spaces for the line number (which is 12597104862Sruprinted right-justified) plus the amount given by @var{indent}; the 12598104862Sruoutput lines are concatenated to the line numbers, separated by 12599104862Sru@var{space}, and @emph{without} reducing the line length. Depending 12600104862Sruon the value of the horizontal page offset (as set with the 12601104862Sru@code{po} request), line numbers which are longer than the reserved 12602104862Sruspace stick out to the left, or the whole line is moved to the right. 1260369626Sru 12604104862SruParameters corresponding to missing arguments are not changed; any 12605104862Srunon-digit argument (to be more precise, any argument starting with a 12606104862Srucharacter valid as a delimiter for identifiers) is also treated as 12607104862Srumissing. 1260855839Sasmodai 12609104862SruIf line numbering has been disabled with a call to @code{nm} without 12610104862Sruan argument, it can be reactivated with @samp{.nm +0}, using the 12611104862Srupreviously active line numbering parameters. 1261269626Sru 12613104862SruThe parameters of @code{nm} are associated with the current environment 12614104862Sru(@pxref{Environments}). The current output line number is available 12615104862Sruin the number register @code{ln}. 1261669626Sru 1261775584Sru@Example 12618104862Sru.po 1m 12619104862Sru.ll 2i 12620104862SruThis test shows how line numbering works with groff. 12621104862Sru.nm 999 12622104862SruThis test shows how line numbering works with groff. 12623104862Sru.br 12624104862Sru.nm xxx 3 2 12625104862Sru.ll -\w'0'u 12626104862SruThis test shows how line numbering works with groff. 12627104862Sru.nn 2 12628104862SruThis test shows how line numbering works with groff. 1262975584Sru@endExample 12630104862Sru 12631104862Sru@noindent 12632104862SruAnd here the result: 12633104862Sru 12634104862Sru@Example 12635104862Sru This test shows how 12636104862Sru line numbering works 12637104862Sru 999 with groff. This 12638104862Sru1000 test shows how line 12639104862Sru1001 numbering works with 12640104862Sru1002 groff. 12641104862Sru This test shows how 12642104862Sru line numbering 12643104862Sru works with groff. 12644104862Sru This test shows how 12645104862Sru1005 line numbering 12646104862Sru works with groff. 12647104862Sru@endExample 1264875584Sru@endDefreq 1264955839Sasmodai 12650104862Sru@Defreq {nn, [@Var{skip}]} 12651104862SruTemporarily turn off line numbering. The argument is the number 12652114402Sruof lines not to be numbered; this defaults to@tie{}1. 12653104862Sru@endDefreq 1265455839Sasmodai 12655104862Sru@Defreq {mc, glyph [@Var{dist}]} 12656104862Sru@cindex margin glyph (@code{mc}) 12657104862Sru@cindex glyph, for margins (@code{mc}) 12658104862SruPrint a @dfn{margin character} to the right of the 12659104862Srutext.@footnote{@dfn{Margin character} is a misnomer since it is an 12660104862Sruoutput glyph.} The first argument is the glyph to be 12661104862Sruprinted. The second argument is the distance away from the right 12662104862Srumargin. If missing, the previously set value is used; default is 12663104862Sru10@dmn{pt}). For text lines that are too long (that is, longer than 12664104862Sruthe text length plus @var{dist}), the margin character is directly 12665104862Sruappended to the lines. 12666104862Sru 12667104862SruWith no arguments the margin character is turned off. 12668104862SruIf this occurs before a break, no margin character is printed. 12669104862Sru 12670104862Sru@cindex @code{tl} request, and @code{mc} 12671104862SruFor empty lines and lines produced by the @code{tl} request no margin 12672104862Srucharacter is emitted. 12673104862Sru 12674104862SruThe margin character is associated with the current environment 12675104862Sru(@pxref{Environments}). 12676104862Sru 1267769626Sru@pindex nrchbar 1267869626Sru@pindex changebar 1267969626SruThis is quite useful for indicating text that has changed, and, in fact, 1268069626Sruthere are programs available for doing this (they are called 1268155839Sasmodai@code{nrchbar} and @code{changebar} and can be found in any 1268255839Sasmodai@samp{comp.sources.unix} archive. 1268355839Sasmodai 1268475584Sru@Example 12685104862Sru.ll 3i 12686104862Sru.mc | 12687104862SruThis paragraph is highlighted with a margin 12688104862Srucharacter. 12689104862Sru.sp 12690104862SruNote that vertical space isn't marked. 12691104862Sru.br 12692104862Sru\& 12693104862Sru.br 12694104862SruBut we can fake it with `\&'. 1269575584Sru@endExample 1269655839Sasmodai 12697104862SruResult: 1269855839Sasmodai 12699104862Sru@Example 12700104862SruThis paragraph is highlighted | 12701104862Sruwith a margin character. | 1270269626Sru 12703104862SruNote that vertical space isn't | 12704104862Srumarked. | 12705104862Sru | 12706104862SruBut we can fake it with `\&'. | 1270775584Sru@endExample 1270875584Sru@endDefreq 1270955839Sasmodai 12710104862Sru@DefreqList {psbb, filename} 12711104862Sru@DefregItem {llx} 12712104862Sru@DefregItem {lly} 12713104862Sru@DefregItem {urx} 12714104862Sru@DefregListEnd {ury} 12715104862Sru@cindex PostScript, bounding box 12716104862Sru@cindex bounding box 12717104862SruRetrieve the bounding box of the PostScript image 12718104862Srufound in @var{filename}. 12719104862SruThe file must conform to 12720104862SruAdobe's @dfn{Document Structuring Conventions} (DSC); 12721104862Sruthe command searches for a @code{%%BoundingBox} comment 12722104862Sruand extracts the bounding box values into the number registers 12723104862Sru@code{llx}, @code{lly}, @code{urx}, and @code{ury}. 12724104862SruIf an error occurs (for example, @code{psbb} cannot find 12725104862Sruthe @code{%%BoundingBox} comment), 12726104862Sruit sets the four number registers to zero. 12727104862Sru@endDefreq 1272869626Sru 12729104862Sru 1273069626Sru@c ===================================================================== 1273169626Sru 1273275584Sru@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 1273375584Sru@section @code{gtroff} Internals 1273475584Sru 1273575584Sru@cindex input token 1273675584Sru@cindex token, input 1273775584Sru@cindex output node 1273875584Sru@cindex node, output 1273975584Sru@code{gtroff} processes input in three steps. One or more input 12740104862Srucharacters are converted to an @dfn{input token}.@footnote{Except the 12741104862Sruescapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R}, 12742104862Sru@code{\s}, and @code{\S} which are processed immediately if not in 12743104862Srucopy-in mode.} Then, one or more input tokens are converted to an 12744104862Sru@dfn{output node}. Finally, output nodes are converted to the 12745104862Sruintermediate output language understood by all output devices. 1274675584Sru 12747104862SruActually, before step one happens, @code{gtroff} converts certain 12748104862Sruescape sequences into reserved input characters (not accessible by 12749104862Sruthe user); such reserved characters are used for other internal 12750104862Sruprocessing also -- this is the very reason why not all characters 12751104862Sruare valid input. @xref{Identifiers}, for more on this topic. 12752104862Sru 12753104862SruFor example, the input string @samp{fi\[:u]} is converted into a 1275475584Srucharacter token @samp{f}, a character token @samp{i}, and a special 12755114402Srutoken @samp{:u} (representing u@tie{}umlaut). Later on, the character 1275675584Srutokens @samp{f} and @samp{i} are merged to a single output node 12757104862Srurepresenting the ligature glyph @samp{fi} (provided the current font 12758104862Sruhas a glyph for this ligature); the same happens with @samp{:u}. All 12759104862Sruoutput glyph nodes are `processed' which means that they are invariably 12760104862Sruassociated with a given font, font size, advance width, etc. During 12761104862Sruthe formatting process, @code{gtroff} itself adds various nodes to 12762104862Srucontrol the data flow. 1276375584Sru 1276475584SruMacros, diversions, and strings collect elements in two chained lists: 1276575584Srua list of input tokens which have been passed unprocessed, and a list 1276675584Sruof output nodes. Consider the following the diversion. 1276775584Sru 1276875584Sru@Example 1276975584Sru.di xxx 1277075584Srua 1277175584Sru\!b 1277275584Sruc 1277375584Sru.br 1277475584Sru.di 1277575584Sru@endExample 1277675584Sru 1277775584Sru@noindent 1277875584SruIt contains these elements. 1277975584Sru 1278075584Sru@multitable {@i{vertical size node}} {token list} {element number} 1278175584Sru@item node list @tab token list @tab element number 1278275584Sru 1278375584Sru@item @i{line start node} @tab --- @tab 1 1278475584Sru@item @i{glyph node @code{a}} @tab --- @tab 2 1278575584Sru@item @i{word space node} @tab --- @tab 3 1278675584Sru@item --- @tab @code{b} @tab 4 1278775584Sru@item --- @tab @code{\n} @tab 5 1278875584Sru@item @i{glyph node @code{c}} @tab --- @tab 6 1278975584Sru@item @i{vertical size node} @tab --- @tab 7 1279075584Sru@item @i{vertical size node} @tab --- @tab 8 1279175584Sru@item --- @tab @code{\n} @tab 9 1279275584Sru@end multitable 1279375584Sru 12794104862Sru@cindex @code{\v}, internal representation 1279575584Sru@noindent 12796114402SruElements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two 1279775584Sru(which are always present) specify the vertical extent of the last 12798104862Sruline, possibly modified by @code{\x}. The @code{br} request finishes 1279975584Sruthe current partial line, inserting a newline input token which is 1280075584Srusubsequently converted to a space when the diversion is reread. Note 1280175584Sruthat the word space node has a fixed width which isn't stretchable 1280275584Sruanymore. To convert horizontal space nodes back to input tokens, use 1280375584Sruthe @code{unformat} request. 1280475584Sru 1280575584SruMacros only contain elements in the token list (and the node list is 1280675584Sruempty); diversions and strings can contain elements in both lists. 1280775584Sru 12808104862SruNote that the @code{chop} request simply reduces the number of elements in a 12809104862Srumacro, string, or diversion by one. Exceptions are @dfn{compatibility save} 12810104862Sruand @dfn{compatibility ignore} input tokens which are ignored. The 12811104862Sru@code{substring} request also ignores those input tokens. 1281275584Sru 12813104862SruSome requests like @code{tr} or @code{cflags} work on glyph 12814104862Sruidentifiers only; this means that the associated glyph can be changed 12815104862Sruwithout destroying this association. This can be very helpful for 12816104862Srusubstituting glyphs. In the following example, we assume that 12817104862Sruglyph @samp{foo} isn't available by default, so we provide a 12818104862Srusubstitution using the @code{fchar} request and map it to input 12819104862Srucharacter @samp{x}. 12820104862Sru 12821104862Sru@Example 12822104862Sru.fchar \[foo] foo 12823104862Sru.tr x \[foo] 12824104862Sru@endExample 12825104862Sru 12826104862Sru@noindent 12827104862SruNow let us assume that we install an additional special font 12828104862Sru@samp{bar} which has glyph @samp{foo}. 12829104862Sru 12830104862Sru@Example 12831104862Sru.special bar 12832104862Sru.rchar \[foo] 12833104862Sru@endExample 12834104862Sru 12835104862Sru@noindent 12836104862SruSince glyphs defined with @code{fchar} are searched before glyphs 12837104862Sruin special fonts, we must call @code{rchar} to remove the definition 12838104862Sruof the fallback glyph. Anyway, the translation is still active; 12839104862Sru@samp{x} now maps to the real glyph @samp{foo}. 12840104862Sru 12841104862Sru 1284275584Sru@c ===================================================================== 1284375584Sru 1284475584Sru@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 1284555839Sasmodai@section Debugging 1284655839Sasmodai@cindex debugging 1284755839Sasmodai 1284869626Sru@code{gtroff} is not easy to debug, but there are some useful features 1284969626Sruand strategies for debugging. 1285055839Sasmodai 12851114402Sru@Defreq {lf, line [@Var{filename}]} 12852104862Sru@pindex soelim 12853104862Sru@cindex multi-file documents 12854104862Sru@cindex documents, multi-file 12855104862Sru@cindex setting input line number (@code{lf}) 12856104862Sru@cindex input line number, setting (@code{lf}) 12857104862Sru@cindex number, input line, setting (@code{lf}) 12858114402SruChange the line number and optionally the file name @code{gtroff} shall 12859114402Sruuse for error and warning messages. @var{line} is the input line number 12860114402Sruof the @emph{next} line. 12861104862Sru 12862104862SruWithout argument, the request is ignored. 12863104862Sru 12864104862SruThis is a debugging aid for documents which are split into many files, 12865104862Sruthen put together with @code{soelim} and other preprocessors. Usually, 12866104862Sruit isn't invoked manually. 12867114402Sru 12868114402SruNote that other @code{troff} implementations (including the original 12869114402Sru@acronym{AT&T} version) handle @code{lf} differently. For them, 12870114402Sru@var{line} changes the line number of the @emph{current} line. 1287175584Sru@endDefreq 1287269626Sru 12873104862Sru@DefreqList {tm, string} 12874104862Sru@DefreqItem {tm1, string} 12875104862Sru@DefreqListEnd {tmc, string} 12876104862Sru@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc}) 12877104862Sru@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc}) 12878104862SruSend @var{string} to the standard error output; 12879104862Sruthis is very useful for printing debugging messages among other things. 12880104862Sru 12881104862Sru@var{string} is read in copy mode. 12882104862Sru 12883104862SruThe @code{tm} request ignores leading spaces of @var{string}; @code{tm1} 12884104862Sruhandles its argument similar to the @code{ds} request: a leading double 12885104862Sruquote in @var{string} is stripped to allow initial blanks. 12886104862Sru 12887104862SruThe @code{tmc} request is similar to @code{tm1} but does 12888104862Srunot append a newline (as is done in @code{tm} and @code{tm1}). 12889104862Sru@endDefreq 12890104862Sru 1289175584Sru@Defreq {ab, [@Var{string}]} 12892104862Sru@cindex aborting (@code{ab}) 1289375584SruSimilar to the @code{tm} request, except that 1289475584Sruit causes @code{gtroff} to stop processing. With no argument it 12895104862Sruprints @samp{User Abort.} to standard error. 1289675584Sru@endDefreq 1289775584Sru 1289875584Sru@Defreq {ex, } 12899104862Sru@cindex @code{ex} request, use in debugging 12900104862Sru@cindex exiting (@code{ex}) 12901104862SruThe @code{ex} request also causes @code{gtroff} to stop processing; 12902104862Srusee also @ref{I/O}. 1290375584Sru@endDefreq 1290475584Sru 1290555839SasmodaiWhen doing something involved it is useful to leave the debugging 1290669626Srustatements in the code and have them turned on by a command line flag. 1290755839Sasmodai 1290875584Sru@Example 1290955839Sasmodai.if \n(DB .tm debugging output 1291075584Sru@endExample 1291155839Sasmodai 1291269626Sru@noindent 1291369626SruTo activate these statements say 1291455839Sasmodai 1291575584Sru@Example 1291655839Sasmodaigroff -rDB=1 file 1291775584Sru@endExample 1291855839Sasmodai 1291969626SruIf it is known in advance that there will be many errors and no useful 1292069626Sruoutput, @code{gtroff} can be forced to suppress formatted output with 1292169626Sruthe @option{-z} flag. 1292269626Sru 1292375584Sru@Defreq {pm, } 12924104862Sru@cindex dumping symbol table (@code{pm}) 12925104862Sru@cindex symbol table, dumping (@code{pm}) 12926104862SruPrint the entire symbol table on @code{stderr}. Names of all defined 12927104862Srumacros, strings, and diversions are print together with their size in 12928104862Srubytes. Since @code{gtroff} sometimes adds nodes by itself, the 12929104862Srureturned size can be larger than expected. 12930104862Sru 12931104862SruThis request differs from @acronym{UNIX} @code{troff}: @code{gtroff} 12932104862Srureports the sizes of diversions, ignores an additional argument to 12933104862Sruprint only the total of the sizes, and the size isn't returned in 12934104862Srublocks of 128 characters. 1293575584Sru@endDefreq 1293669626Sru 1293775584Sru@Defreq {pnr, } 12938104862Sru@cindex dumping number registers (@code{pnr}) 12939104862Sru@cindex number registers, dumping (@code{pnr}) 12940104862SruPrint the names and contents of all 1294175584Srucurrently defined number registers on @code{stderr}. 1294275584Sru@endDefreq 1294369626Sru 1294475584Sru@Defreq {ptr, } 12945104862Sru@cindex dumping traps (@code{ptr}) 12946104862Sru@cindex traps, dumping (@code{ptr}) 12947104862SruPrint the names and positions of all traps 1294875584Sru(not including input line traps and diversion traps) on @code{stderr}. 1294975584SruEmpty slots in the page trap list are printed as well, because they can 1295075584Sruaffect the priority of subsequently planted traps. 1295175584Sru@endDefreq 1295269626Sru 12953104862Sru@Defreq {fl, } 12954104862Sru@cindex flush output (@code{fl}) 12955104862Sru@cindex output, flush (@code{fl}) 1295669626Sru@cindex interactive use of @code{gtroff} 1295769626Sru@cindex @code{gtroff}, interactive use 12958104862SruInstruct @code{gtroff} to flush its output immediately. The intent 12959104862Sruis for interactive use, but this behaviour is currently not 12960104862Sruimplemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff}, 12961104862SruTTY output is sent to a device driver also (@code{grotty}), making it 12962104862Srunon-trivial to communicate interactively. 12963104862Sru 12964104862SruThis request causes a line break. 1296575584Sru@endDefreq 1296669626Sru 1296775584Sru@Defreq {backtrace, } 12968104862Sru@cindex backtrace of input stack (@code{backtrace}) 12969104862Sru@cindex input stack, backtrace (@code{backtrace}) 12970104862SruPrint a backtrace of the input stack to the standard error stream. 12971104862Sru 12972104862SruConsider the following in file @file{test}: 12973104862Sru 12974104862Sru@Example 12975104862Sru.de xxx 12976104862Sru. backtrace 12977104862Sru.. 12978104862Sru.de yyy 12979104862Sru. xxx 12980104862Sru.. 12981104862Sru. 12982104862Sru.yyy 12983104862Sru@endExample 12984104862Sru 12985104862Sru@noindent 12986104862SruOn execution, @code{gtroff} prints the following: 12987104862Sru 12988104862Sru@Example 12989104862Srutest:2: backtrace: macro `xxx' 12990104862Srutest:5: backtrace: macro `yyy' 12991104862Srutest:8: backtrace: file `test' 12992104862Sru@endExample 12993104862Sru 12994104862SruThe option @option{-b} of @code{gtroff} internally calls a variant of 12995104862Sruthis request on each error and warning. 1299675584Sru@endDefreq 1299769626Sru 12998104862Sru@Defreg {slimit} 12999104862Sru@cindex input stack, setting limit 13000104862SruUse the @code{slimit} number register 13001104862Sruto set the maximum number of objects on the input stack. 13002114402SruIf @code{slimit} is less than or equal to@tie{}0, 13003104862Sruthere is no limit set. 13004104862SruWith no limit, a buggy recursive macro can exhaust virtual memory. 13005104862Sru 13006104862SruThe default value is 1000; this is a compile-time constant. 13007104862Sru@endDefreg 13008104862Sru 13009104862Sru@Defreq {warnscale, si} 13010104862SruSet the scaling indicator used in warnings to @var{si}. Valid values for 13011104862Sru@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At 13012104862Srustartup, it is set to @samp{i}. 13013104862Sru@endDefreq 13014104862Sru 13015104862Sru@Defreq {spreadwarn, [@Var{limit}]} 13016104862SruMake @code{gtroff} emit a warning if the additional space inserted for 13017104862Srueach space between words in an output line is larger or equal to 13018104862Sru@var{limit}. A negative value is changed to zero; no argument toggles the 13019104862Sruwarning on and off without changing @var{limit}. The default scaling 13020104862Sruindicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and 13021104862Sru@var{limit} is set to 3@dmn{m}. 13022104862Sru 13023104862SruFor example, 13024104862Sru 13025104862Sru@Example 13026104862Sru.spreadwarn 0.2m 13027104862Sru@endExample 13028104862Sru 13029104862Sru@noindent 13030104862Sruwill cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each 13031104862Sruinterword space in a line. 13032104862Sru 13033104862SruThis request is active only if text is justified to both margins (using 13034104862Sru@w{@samp{.ad b}}). 13035104862Sru@endDefreq 13036104862Sru 1303769626Sru@cindex warnings 1303869626Sru@code{gtroff} has command line options for printing out more warnings 1303969626Sru(@option{-w}) and for printing backtraces (@option{-b}) when a warning 1304069626Sruor an error occurs. The most verbose level of warnings is @option{-ww}. 1304169626Sru 13042104862Sru@DefreqList {warn, [@Var{flags}]} 13043104862Sru@DefregListEnd {.warn} 13044104862Sru@cindex level of warnings (@code{warn}) 13045104862Sru@cindex warnings, level (@code{warn}) 13046104862SruControl the level of warnings checked for. The @var{flags} are the sum 1304775584Sruof the numbers associated with each warning that is to be enabled; all 1304875584Sruother warnings are disabled. The number associated with each warning is 1304975584Srulisted below. For example, @w{@code{.warn 0}} disables all warnings, 1305075584Sruand @w{@code{.warn 1}} disables all warnings except that about missing 13051104862Sruglyphs. If no argument is given, all warnings are enabled. 1305255839Sasmodai 1305375584SruThe read-only number register @code{.warn} contains the current warning 1305475584Srulevel. 1305575584Sru@endDefreq 1305669626Sru 1305769626Sru@menu 1305875584Sru* Warnings:: 1305969626Sru@end menu 1306069626Sru 1306175584Sru@c --------------------------------------------------------------------- 1306275584Sru 1306369626Sru@node Warnings, , Debugging, Debugging 1306455839Sasmodai@subsection Warnings 1306555839Sasmodai@cindex warnings 1306655839Sasmodai 1306769626SruThe warnings that can be given to @code{gtroff} are divided into the 1306869626Srufollowing categories. The name associated with each warning is used by 1306969626Sruthe @option{-w} and @option{-W} options; the number is used by the 1307069626Sru@code{warn} request and by the @code{.warn} register. 1307155839Sasmodai 1307255839Sasmodai@table @samp 1307369626Sru@item char 1307455839Sasmodai@itemx 1 13075104862SruNon-existent glyphs.@footnote{@code{char} is a misnomer since it reports 13076104862Srumissing glyphs -- there aren't missing input characters, only invalid 13077104862Sruones.} This is enabled by default. 1307869626Sru 1307969626Sru@item number 1308055839Sasmodai@itemx 2 1308155839SasmodaiInvalid numeric expressions. This is enabled by default. 1308269626Sru@xref{Expressions}. 1308369626Sru 1308469626Sru@item break 1308555839Sasmodai@itemx 4 1308669626Sru@cindex fill mode 1308769626Sru@cindex mode, fill 1308869626SruIn fill mode, lines which could not be broken so that their length was 1308969626Sruless than the line length. This is enabled by default. 1309069626Sru 1309169626Sru@item delim 1309255839Sasmodai@itemx 8 1309355839SasmodaiMissing or mismatched closing delimiters. 1309469626Sru 1309569626Sru@item el 1309655839Sasmodai@itemx 16 13097104862Sru@cindex @code{ie} request, and warnings 13098104862Sru@cindex @code{el} request, and warnings 1309955839SasmodaiUse of the @code{el} request with no matching @code{ie} request. 1310069626Sru@xref{if-else}. 1310169626Sru 1310269626Sru@item scale 1310355839Sasmodai@itemx 32 1310455839SasmodaiMeaningless scaling indicators. 1310569626Sru 1310669626Sru@item range 1310755839Sasmodai@itemx 64 1310855839SasmodaiOut of range arguments. 1310969626Sru 1311069626Sru@item syntax 1311155839Sasmodai@itemx 128 1311255839SasmodaiDubious syntax in numeric expressions. 1311369626Sru 1311469626Sru@item di 1311555839Sasmodai@itemx 256 13116104862Sru@cindex @code{di} request, and warnings 13117104862Sru@cindex @code{da} request, and warnings 1311855839SasmodaiUse of @code{di} or @code{da} without an argument when there is no 1311955839Sasmodaicurrent diversion. 1312069626Sru 1312169626Sru@item mac 1312255839Sasmodai@itemx 512 13123104862Sru@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings 13124104862Sru@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings 13125104862Sru@cindex @code{ds}, @code{ds1} requests, and warnings 13126104862Sru@cindex @code{as}, @code{as1} requests, and warnings 13127104862Sru@cindex @code{di} request, and warnings 13128104862Sru@cindex @code{da} request, and warnings 13129104862Sru@cindex @code{box}, @code{boxa} requests, and warnings 13130104862Sru@cindex @code{\*}, and warnings 1313169626SruUse of undefined strings, macros and diversions. When an undefined 13132104862Srustring, macro, or diversion is used, that string is automatically 13133104862Srudefined as empty. So, in most cases, at most one warning is given 13134104862Srufor each name. 1313569626Sru 13136104862Sru@item reg 1313755839Sasmodai@itemx 1024 13138104862Sru@cindex @code{nr} request, and warnings 13139104862Sru@cindex @code{\R}, and warnings 13140104862Sru@cindex @code{\n}, and warnings 1314169626SruUse of undefined number registers. When an undefined number register is 13142114402Sruused, that register is automatically defined to have a value of@tie{}0. 13143104862SruSo, in most cases, at most one warning is given for use of a particular 13144104862Sruname. 1314569626Sru 13146104862Sru@item tab 1314755839Sasmodai@itemx 2048 13148104862Sru@cindex @code{\t}, and warnings 1314955839SasmodaiUse of a tab character where a number was expected. 1315069626Sru 13151104862Sru@item right-brace 1315255839Sasmodai@itemx 4096 13153104862Sru@cindex @code{\@}}, and warnings 1315455839SasmodaiUse of @code{\@}} where a number was expected. 1315569626Sru 13156104862Sru@item missing 1315755839Sasmodai@itemx 8192 1315855839SasmodaiRequests that are missing non-optional arguments. 1315969626Sru 13160104862Sru@item input 1316155839Sasmodai@itemx 16384 13162104862SruInvalid input characters. 1316369626Sru 13164104862Sru@item escape 1316555839Sasmodai@itemx 32768 13166104862SruUnrecognized escape sequences. When an unrecognized escape sequence 13167104862Sru@code{\@var{X}} is encountered, the escape character is ignored, and 13168104862Sru@var{X} is printed. 1316969626Sru 13170104862Sru@item space 1317155839Sasmodai@itemx 65536 1317269626Sru@cindex compatibility mode 1317369626SruMissing space between a request or macro and its argument. This warning 1317475584Sruis given when an undefined name longer than two characters is 1317569626Sruencountered, and the first two characters of the name make a defined 1317675584Sruname. The request or macro is not invoked. When this warning is 1317769626Srugiven, no macro is automatically defined. This is enabled by default. 1317875584SruThis warning never occurs in compatibility mode. 1317969626Sru 13180104862Sru@item font 1318155839Sasmodai@itemx 131072 1318269626SruNon-existent fonts. This is enabled by default. 1318369626Sru 13184104862Sru@item ig 13185104862Sru@itemx 262144 13186104862SruInvalid escapes in text ignored with the @code{ig} request. These are 13187104862Sruconditions that are errors when they do not occur in ignored text. 13188104862Sru 13189104862Sru@item color 13190104862Sru@itemx 524288 13191104862SruColor related warnings. 13192104862Sru 1319355839Sasmodai@item all 1319469626SruAll warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 1319569626Sruintended that this covers all warnings that are useful with traditional 1319669626Srumacro packages. 1319769626Sru 1319855839Sasmodai@item w 1319955839SasmodaiAll warnings. 1320055839Sasmodai@end table 1320155839Sasmodai 1320255839Sasmodai 1320369626Sru@c ===================================================================== 1320469626Sru 13205104862Sru@node Implementation Differences, , Debugging, gtroff Reference 1320655839Sasmodai@section Implementation Differences 1320755839Sasmodai@cindex implementation differences 1320855839Sasmodai@cindex differences in implementation 13209104862Sru@cindex incompatibilities with @acronym{AT&T} @code{troff} 1321069626Sru@cindex compatibility mode 1321169626Sru@cindex mode, compatibility 1321255839Sasmodai 1321369626SruGNU @code{troff} has a number of features which cause incompatibilities 1321469626Sruwith documents written with old versions of @code{troff}. 1321555839Sasmodai 1321669626Sru@cindex long names 1321769626Sru@cindex names, long 1321869626SruLong names cause some incompatibilities. @acronym{UNIX} @code{troff} 1321975584Sruinterprets 1322055839Sasmodai 1322175584Sru@Example 1322255839Sasmodai.dsabcd 1322375584Sru@endExample 1322455839Sasmodai 13225104862Sru@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff} 13226104862Sru@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff} 1322769626Sru@noindent 1322869626Sruas defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 1322975584Sru@code{troff} interprets this as a call of a macro named 1323075584Sru@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 1323169626Sru@code{\*[} or @code{\n[} as references to a string or number register 1323275584Srucalled @samp{[}. In GNU @code{troff}, however, this is normally 1323369626Sruinterpreted as the start of a long name. In compatibility mode GNU 1323475584Sru@code{troff} interprets long names in the traditional way 1323575584Sru(which means that they are not recognized as names). 1323655839Sasmodai 13237104862Sru@DefreqList {cp, [@Var{n}]} 13238104862Sru@DefreqItem {do, cmd} 13239104862Sru@DefregListEnd {.C} 13240104862SruIf @var{n} is missing or non-zero, turn on compatibility mode; 13241104862Sruotherwise, turn it off. 13242104862Sru 13243114402SruThe read-only number register @code{.C} is@tie{}1 if compatibility mode is 13244114402Sruon, 0@tie{}otherwise. 13245104862Sru 13246104862SruCompatibility mode can be also turned on with the @option{-C} command line 13247104862Sruoption. 13248104862Sru 13249104862SruThe @code{do} request turns off compatibility mode 13250104862Sruwhile executing its arguments as a @code{gtroff} command. 13251104862Sru 13252104862Sru@Example 13253104862Sru.do fam T 13254104862Sru@endExample 13255104862Sru 13256104862Sru@noindent 13257104862Sruexecutes the @code{fam} request when compatibility mode 13258104862Sruis enabled. 13259104862Sru 13260104862Sru@code{gtroff} restores the previous compatibility setting 13261104862Srubefore interpreting any files sourced by the @var{cmd}. 13262104862Sru@endDefreq 13263104862Sru 13264104862Sru@cindex input level in delimited arguments 13265104862Sru@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff} 13266104862SruTwo other features are controlled by @option{-C}. If not in 13267104862Srucompatibility mode, GNU @code{troff} preserves the input level in 13268104862Srudelimited arguments: 13269104862Sru 13270104862Sru@Example 13271104862Sru.ds xx ' 13272104862Sru\w'abc\*(xxdef' 13273104862Sru@endExample 13274104862Sru 13275104862Sru@noindent 13276104862SruIn compatibility mode, the string @samp{72def'} is returned; without 13277104862Sru@option{-C} the resulting string is @samp{168} (assuming a TTY output 13278104862Srudevice). 13279104862Sru 13280104862Sru@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff} 13281104862Sru@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff} 13282104862Sru@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff} 13283104862Sru@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff} 13284104862SruFinally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M}, 13285104862Sru@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the 13286104862Srubeginning of a line only in compatibility mode (this is a rather obscure 13287104862Srufeature). For example, the code 13288104862Sru 13289104862Sru@Example 13290104862Sru.de xx 13291104862SruHallo! 13292104862Sru.. 13293104862Sru\fB.xx\fP 13294104862Sru@endExample 13295104862Sru 13296114402Sru@noindent 13297104862Sruprints @samp{Hallo!} in bold face if in compatibility mode, and 13298104862Sru@samp{.xx} in bold face otherwise. 13299104862Sru 13300104862Sru@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff} 13301104862Sru@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff} 13302104862Sru@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff} 13303104862Sru@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff} 13304104862Sru@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff} 13305104862Sru@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff} 13306104862Sru@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff} 13307104862Sru@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff} 13308104862Sru@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff} 13309104862Sru@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff} 13310104862Sru@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff} 13311104862Sru@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13312104862Sru@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff} 13313104862Sru@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff} 1331469626SruGNU @code{troff} does not allow the use of the escape sequences 1331575584Sru@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 1331669626Sru@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 1331769626Sru@code{\%}, and @code{\c} in names of strings, macros, diversions, number 1331869626Sruregisters, fonts or environments; @acronym{UNIX} @code{troff} does. The 1331969626Sru@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 1332069626Sruavoiding use of these escape sequences in names. 1332155839Sasmodai 1332255839Sasmodai@cindex fractional point sizes 13323104862Sru@cindex fractional type sizes 1332455839Sasmodai@cindex point sizes, fractional 13325104862Sru@cindex type sizes, fractional 13326104862Sru@cindex sizes, fractional 13327104862Sru@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff} 1332869626SruFractional point sizes cause one noteworthy incompatibility. In 1332969626Sru@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 1333069626Sruindicators and thus 1333155839Sasmodai 1333275584Sru@Example 1333355839Sasmodai.ps 10u 1333475584Sru@endExample 1333555839Sasmodai 1333669626Sru@noindent 13337114402Srusets the point size to 10@tie{}points, whereas in GNU @code{troff} it 13338114402Srusets the point size to 10@tie{}scaled points. @xref{Fractional Type 1333969626SruSizes}, for more information. 1334055839Sasmodai 13341104862Sru@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} 13342104862Sru@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff} 13343104862Sru@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff} 13344104862Sru@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff} 13345104862Sru@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13346104862Sru@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff} 13347104862Sru@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13348104862Sru@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff} 1334969626SruIn GNU @code{troff} there is a fundamental difference between 13350104862Sru(unformatted) input characters and (formatted) output glyphs. 13351104862SruEverything that affects how a glyph is output is stored 13352104862Sruwith the glyph node; once a glyph node has been constructed it is 1335355839Sasmodaiunaffected by any subsequent requests that are executed, including 1335469626Sru@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 13355104862SruNormally glyphs are constructed from input characters at the 13356104862Srumoment immediately before the glyph is added to the current output 1335769626Sruline. Macros, diversions and strings are all, in fact, the same type of 13358104862Sruobject; they contain lists of input characters and glyph nodes in 13359104862Sruany combination. A glyph node does not behave like an input 1336069626Srucharacter for the purposes of macro processing; it does not inherit any 1336169626Sruof the special properties that the input character from which it was 1336269626Sruconstructed might have had. For example, 1336355839Sasmodai 1336475584Sru@Example 1336555839Sasmodai.di x 1336655839Sasmodai\\\\ 1336755839Sasmodai.br 1336855839Sasmodai.di 1336955839Sasmodai.x 1337075584Sru@endExample 1337155839Sasmodai 13372104862Sru@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13373104862Sru@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13374104862Sru@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff} 13375104862Sru@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13376104862Sru@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff} 13377104862Sru@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff} 13378104862Sru@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff} 1337969626Sru@noindent 1338075584Sruprints @samp{\\} in GNU @code{troff}; each pair of input backslashes 1338169626Sruis turned into one output backslash and the resulting output backslashes 1338269626Sruare not interpreted as escape characters when they are reread. 1338369626Sru@acronym{UNIX} @code{troff} would interpret them as escape characters 1338469626Sruwhen they were reread and would end up printing one @samp{\}. The 1338569626Srucorrect way to obtain a printable backslash is to use the @code{\e} 1338675584Sruescape sequence: This always prints a single instance of the current 1338769626Sruescape character, regardless of whether or not it is used in a 1338875584Srudiversion; it also works in both GNU @code{troff} and @acronym{UNIX} 13389104862Sru@code{troff}.@footnote{To be completely independent of the current 13390104862Sruescape character, use @code{\(rs} which represents a reverse solidus 13391104862Sru(backslash) glyph.} To store, for some reason, an escape sequence in a 1339269626Srudiversion that will be interpreted when the diversion is reread, either 1339369626Sruuse the traditional @code{\!} transparent output facility, or, if this 1339469626Sruis unsuitable, the new @code{\?} escape sequence. 1339555839Sasmodai 13396104862Sru@xref{Diversions}, and @ref{Gtroff Internals}, for more information. 1339775584Sru 1339855839Sasmodai 1339969626Sru 1340069626Sru@c ===================================================================== 1340169626Sru@c ===================================================================== 1340269626Sru 1340375584Sru@node Preprocessors, Output Devices, gtroff Reference, Top 1340469626Sru@chapter Preprocessors 1340569626Sru@cindex preprocessors 1340669626Sru 1340769626SruThis chapter describes all preprocessors that come with @code{groff} or 1340869626Sruwhich are freely available. 1340969626Sru 1341069626Sru@menu 1341175584Sru* geqn:: 1341275584Sru* gtbl:: 1341375584Sru* gpic:: 1341475584Sru* ggrn:: 1341575584Sru* grap:: 1341675584Sru* grefer:: 1341775584Sru* gsoelim:: 1341869626Sru@end menu 1341969626Sru 1342069626Sru 1342169626Sru@c ===================================================================== 1342269626Sru 1342369626Sru@node geqn, gtbl, Preprocessors, Preprocessors 1342469626Sru@section @code{geqn} 13425104862Sru@cindex @code{eqn}, the program 13426104862Sru@cindex @code{geqn}, the program 1342755839Sasmodai 1342869626Sru@c XXX 1342955839Sasmodai 1343055839Sasmodai@menu 1343175584Sru* Invoking geqn:: 1343255839Sasmodai@end menu 1343355839Sasmodai 1343469626Sru@c --------------------------------------------------------------------- 1343569626Sru 1343655839Sasmodai@node Invoking geqn, , geqn, geqn 1343769626Sru@subsection Invoking @code{geqn} 1343855839Sasmodai@cindex invoking @code{geqn} 1343955839Sasmodai@cindex @code{geqn}, invoking 1344055839Sasmodai 1344169626Sru@c XXX 1344255839Sasmodai 1344355839Sasmodai 1344469626Sru@c ===================================================================== 1344569626Sru 1344669626Sru@node gtbl, gpic, geqn, Preprocessors 1344769626Sru@section @code{gtbl} 13448104862Sru@cindex @code{tbl}, the program 13449104862Sru@cindex @code{gtbl}, the program 1345055839Sasmodai 1345169626Sru@c XXX 1345255839Sasmodai 1345355839Sasmodai@menu 1345475584Sru* Invoking gtbl:: 1345555839Sasmodai@end menu 1345655839Sasmodai 1345769626Sru@c --------------------------------------------------------------------- 1345869626Sru 1345955839Sasmodai@node Invoking gtbl, , gtbl, gtbl 1346069626Sru@subsection Invoking @code{gtbl} 1346155839Sasmodai@cindex invoking @code{gtbl} 1346255839Sasmodai@cindex @code{gtbl}, invoking 1346355839Sasmodai 1346469626Sru@c XXX 1346555839Sasmodai 1346669626Sru 1346769626Sru@c ===================================================================== 1346869626Sru 1346969626Sru@node gpic, ggrn, gtbl, Preprocessors 1347069626Sru@section @code{gpic} 13471104862Sru@cindex @code{pic}, the program 13472104862Sru@cindex @code{gpic}, the program 1347355839Sasmodai 1347469626Sru@c XXX 1347555839Sasmodai 1347655839Sasmodai@menu 1347775584Sru* Invoking gpic:: 1347855839Sasmodai@end menu 1347955839Sasmodai 1348069626Sru@c --------------------------------------------------------------------- 1348169626Sru 1348255839Sasmodai@node Invoking gpic, , gpic, gpic 1348369626Sru@subsection Invoking @code{gpic} 1348455839Sasmodai@cindex invoking @code{gpic} 1348555839Sasmodai@cindex @code{gpic}, invoking 1348655839Sasmodai 1348769626Sru@c XXX 1348855839Sasmodai 1348955839Sasmodai 1349069626Sru@c ===================================================================== 1349169626Sru 1349269626Sru@node ggrn, grap, gpic, Preprocessors 1349369626Sru@section @code{ggrn} 13494104862Sru@cindex @code{grn}, the program 13495104862Sru@cindex @code{ggrn}, the program 1349669626Sru 1349769626Sru@c XXX 1349869626Sru 1349969626Sru@menu 1350075584Sru* Invoking ggrn:: 1350169626Sru@end menu 1350269626Sru 1350369626Sru@c --------------------------------------------------------------------- 1350469626Sru 1350569626Sru@node Invoking ggrn, , ggrn, ggrn 1350669626Sru@subsection Invoking @code{ggrn} 1350769626Sru@cindex invoking @code{ggrn} 1350869626Sru@cindex @code{ggrn}, invoking 1350969626Sru 1351069626Sru@c XXX 1351169626Sru 1351269626Sru 1351369626Sru@c ===================================================================== 1351469626Sru 1351569626Sru@node grap, grefer, ggrn, Preprocessors 1351669626Sru@section @code{grap} 13517104862Sru@cindex @code{grap}, the program 1351855839Sasmodai 1351969626SruA free implementation of @code{grap}, written by Ted Faber, 1352069626Sruis available as an extra package from the following address: 1352155839Sasmodai 1352269626Sru@display 13523114402Sru@uref{http://www.lunabase.org/~faber/Vault/software/grap/} 1352469626Sru@end display 1352555839Sasmodai 1352669626Sru 1352769626Sru@c ===================================================================== 1352869626Sru 1352969626Sru@node grefer, gsoelim, grap, Preprocessors 1353069626Sru@section @code{grefer} 13531104862Sru@cindex @code{refer}, the program 13532104862Sru@cindex @code{grefer}, the program 1353355839Sasmodai 1353469626Sru@c XXX 1353555839Sasmodai 1353655839Sasmodai@menu 1353775584Sru* Invoking grefer:: 1353855839Sasmodai@end menu 1353955839Sasmodai 1354069626Sru@c --------------------------------------------------------------------- 1354169626Sru 1354255839Sasmodai@node Invoking grefer, , grefer, grefer 1354369626Sru@subsection Invoking @code{grefer} 1354455839Sasmodai@cindex invoking @code{grefer} 1354555839Sasmodai@cindex @code{grefer}, invoking 1354655839Sasmodai 1354769626Sru@c XXX 1354855839Sasmodai 1354955839Sasmodai 1355069626Sru@c ===================================================================== 1355169626Sru 1355269626Sru@node gsoelim, , grefer, Preprocessors 1355369626Sru@section @code{gsoelim} 13554104862Sru@cindex @code{soelim}, the program 13555104862Sru@cindex @code{gsoelim}, the program 1355655839Sasmodai 1355769626Sru@c XXX 1355855839Sasmodai 1355955839Sasmodai@menu 1356075584Sru* Invoking gsoelim:: 1356155839Sasmodai@end menu 1356255839Sasmodai 1356369626Sru@c --------------------------------------------------------------------- 1356469626Sru 1356555839Sasmodai@node Invoking gsoelim, , gsoelim, gsoelim 1356669626Sru@subsection Invoking @code{gsoelim} 1356755839Sasmodai@cindex invoking @code{gsoelim} 1356855839Sasmodai@cindex @code{gsoelim}, invoking 1356955839Sasmodai 1357069626Sru@c XXX 1357155839Sasmodai 1357255839Sasmodai 1357355839Sasmodai 1357469626Sru@c ===================================================================== 1357569626Sru@c ===================================================================== 1357655839Sasmodai 1357769626Sru@node Output Devices, File formats, Preprocessors, Top 1357869626Sru@chapter Output Devices 1357969626Sru@cindex output devices 1358069626Sru@cindex devices for output 1358155839Sasmodai 1358269626Sru@c XXX 1358369626Sru 1358455839Sasmodai@menu 1358575584Sru* Special Characters:: 1358675584Sru* grotty:: 1358775584Sru* grops:: 1358875584Sru* grodvi:: 1358975584Sru* grolj4:: 1359075584Sru* grolbp:: 1359175584Sru* grohtml:: 1359275584Sru* gxditview:: 1359355839Sasmodai@end menu 1359455839Sasmodai 1359569626Sru 1359669626Sru@c ===================================================================== 1359769626Sru 1359869626Sru@node Special Characters, grotty, Output Devices, Output Devices 1359955839Sasmodai@section Special Characters 1360055839Sasmodai@cindex special characters 1360155839Sasmodai@cindex characters, special 1360255839Sasmodai 1360369626Sru@c XXX 1360455839Sasmodai 1360569626Sru@xref{Font Files}. 1360655839Sasmodai 1360769626Sru 1360869626Sru@c ===================================================================== 1360969626Sru 1361069626Sru@node grotty, grops, Special Characters, Output Devices 1361155839Sasmodai@section @code{grotty} 13612104862Sru@cindex @code{grotty}, the program 1361355839Sasmodai 1361469626Sru@c XXX 1361555839Sasmodai 1361655839Sasmodai@menu 1361775584Sru* Invoking grotty:: 1361855839Sasmodai@end menu 1361955839Sasmodai 1362069626Sru@c --------------------------------------------------------------------- 1362169626Sru 1362255839Sasmodai@node Invoking grotty, , grotty, grotty 1362355839Sasmodai@subsection Invoking @code{grotty} 1362455839Sasmodai@cindex invoking @code{grotty} 1362555839Sasmodai@cindex @code{grotty}, invoking 1362655839Sasmodai 1362769626Sru@c XXX 1362855839Sasmodai 13629104862Sru@c The following is no longer true; fix and extend it. 1363055839Sasmodai 13631104862Sru@c @pindex less 13632104862Sru@c @cindex Teletype 13633104862Sru@c @cindex ISO 6249 SGR 13634104862Sru@c @cindex terminal control sequences 13635104862Sru@c @cindex control sequences, for terminals 13636104862Sru@c For TTY output devices, underlining is done by emitting sequences of 13637104862Sru@c @samp{_} and @samp{\b} (the backspace character) before the actual 13638104862Sru@c character. Literally, this is printing an underline character, then 13639104862Sru@c moving back one character position, and printing the actual character 13640104862Sru@c at the same position as the underline character (similar to a 13641104862Sru@c typewriter). Usually, a modern terminal can't interpret this (and the 13642104862Sru@c original Teletype machines for which this sequence was appropriate are 13643104862Sru@c no longer in use). You need a pager program like @code{less} which 13644104862Sru@c translates this into ISO 6429 SGR sequences to control terminals. 13645104862Sru 13646104862Sru 1364769626Sru@c ===================================================================== 1364869626Sru 1364969626Sru@node grops, grodvi, grotty, Output Devices 1365055839Sasmodai@section @code{grops} 13651104862Sru@cindex @code{grops}, the program 1365255839Sasmodai 1365369626Sru@c XXX 1365455839Sasmodai 1365555839Sasmodai@menu 1365675584Sru* Invoking grops:: 1365775584Sru* Embedding PostScript:: 1365855839Sasmodai@end menu 1365955839Sasmodai 1366069626Sru@c --------------------------------------------------------------------- 1366169626Sru 1366255839Sasmodai@node Invoking grops, Embedding PostScript, grops, grops 1366355839Sasmodai@subsection Invoking @code{grops} 1366455839Sasmodai@cindex invoking @code{grops} 1366555839Sasmodai@cindex @code{grops}, invoking 1366655839Sasmodai 1366769626Sru@c XXX 1366855839Sasmodai 1366969626Sru@c --------------------------------------------------------------------- 1367055839Sasmodai 1367155839Sasmodai@node Embedding PostScript, , Invoking grops, grops 1367269626Sru@subsection Embedding @sc{PostScript} 13673104862Sru@cindex embedding PostScript 13674104862Sru@cindex PostScript, embedding 1367555839Sasmodai 1367669626Sru@c XXX 1367755839Sasmodai 1367855839Sasmodai 1367969626Sru@c ===================================================================== 1368069626Sru 1368169626Sru@node grodvi, grolj4, grops, Output Devices 1368255839Sasmodai@section @code{grodvi} 13683104862Sru@cindex @code{grodvi}, the program 1368455839Sasmodai 1368569626Sru@c XXX 1368655839Sasmodai 1368755839Sasmodai@menu 1368875584Sru* Invoking grodvi:: 1368955839Sasmodai@end menu 1369055839Sasmodai 1369169626Sru@c --------------------------------------------------------------------- 1369269626Sru 1369355839Sasmodai@node Invoking grodvi, , grodvi, grodvi 1369455839Sasmodai@subsection Invoking @code{grodvi} 1369555839Sasmodai@cindex invoking @code{grodvi} 1369655839Sasmodai@cindex @code{grodvi}, invoking 1369755839Sasmodai 1369869626Sru@c XXX 1369955839Sasmodai 1370055839Sasmodai 1370169626Sru@c ===================================================================== 1370269626Sru 1370369626Sru@node grolj4, grolbp, grodvi, Output Devices 1370455839Sasmodai@section @code{grolj4} 13705104862Sru@cindex @code{grolj4}, the program 1370655839Sasmodai 1370769626Sru@c XXX 1370855839Sasmodai 1370955839Sasmodai@menu 1371075584Sru* Invoking grolj4:: 1371155839Sasmodai@end menu 1371255839Sasmodai 1371369626Sru@c --------------------------------------------------------------------- 1371469626Sru 1371555839Sasmodai@node Invoking grolj4, , grolj4, grolj4 1371655839Sasmodai@subsection Invoking @code{grolj4} 1371755839Sasmodai@cindex invoking @code{grolj4} 1371855839Sasmodai@cindex @code{grolj4}, invoking 1371955839Sasmodai 1372069626Sru@c XXX 1372155839Sasmodai 1372255839Sasmodai 1372369626Sru@c ===================================================================== 1372469626Sru 1372569626Sru@node grolbp, grohtml, grolj4, Output Devices 1372669626Sru@section @code{grolbp} 13727104862Sru@cindex @code{grolbp}, the program 1372869626Sru 1372969626Sru@c XXX 1373069626Sru 1373169626Sru@menu 1373275584Sru* Invoking grolbp:: 1373369626Sru@end menu 1373469626Sru 1373569626Sru@c --------------------------------------------------------------------- 1373669626Sru 1373769626Sru@node Invoking grolbp, , grolbp, grolbp 1373869626Sru@subsection Invoking @code{grolbp} 1373969626Sru@cindex invoking @code{grolbp} 1374069626Sru@cindex @code{grolbp}, invoking 1374169626Sru 1374269626Sru@c XXX 1374369626Sru 1374469626Sru 1374569626Sru@c ===================================================================== 1374669626Sru 1374769626Sru@node grohtml, gxditview, grolbp, Output Devices 1374855839Sasmodai@section @code{grohtml} 13749104862Sru@cindex @code{grohtml}, the program 1375055839Sasmodai 1375169626Sru@c XXX 1375255839Sasmodai 1375355839Sasmodai@menu 1375475584Sru* Invoking grohtml:: 13755104862Sru* grohtml specific registers and strings:: 1375655839Sasmodai@end menu 1375755839Sasmodai 1375869626Sru@c --------------------------------------------------------------------- 1375969626Sru 13760104862Sru@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml 1376155839Sasmodai@subsection Invoking @code{grohtml} 1376255839Sasmodai@cindex invoking @code{grohtml} 1376355839Sasmodai@cindex @code{grohtml}, invoking 1376455839Sasmodai 1376569626Sru@c XXX 1376655839Sasmodai 13767104862Sru@c --------------------------------------------------------------------- 1376855839Sasmodai 13769104862Sru@node grohtml specific registers and strings, , Invoking grohtml, grohtml 13770104862Sru@subsection @code{grohtml} specific registers and strings 13771104862Sru@cindex registers specific to @code{grohtml} 13772104862Sru@cindex strings specific to @code{grohtml} 13773104862Sru@cindex @code{grohtml}, registers and strings 13774104862Sru 13775104862Sru@DefmpregList {ps4html, grohtml} 13776104862Sru@DefstrListEnd {www-image-template, grohtml} 13777104862SruThe registers @code{ps4html} and @code{www-image-template} are defined 13778104862Sruby the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in 13779104862Sruthe @code{troff} input, marks up the inline equations and passes the 13780104862Sruresult firstly to 13781104862Sru 13782104862Sru@Example 13783104862Srutroff -Tps -rps4html=1 -dwww-image-template=@var{template} 13784104862Sru@endExample 13785104862Sru 13786104862Sru@noindent 13787104862Sruand secondly to 13788104862Sru 13789104862Sru@Example 13790104862Srutroff -Thtml 13791104862Sru@endExample 13792104862Sru 13793104862SruThe PostScript device is used to create all the image files, and the 13794104862Sruregister @code{ps4html} enables the macro sets to ignore floating 13795104862Srukeeps, footers, and headings. 13796104862Sru 13797104862SruThe register @code{www-image-template} is set to the user specified 13798104862Srutemplate name or the default name. 13799104862Sru@endDefmpreg 13800104862Sru 13801104862Sru 1380269626Sru@c ===================================================================== 1380369626Sru 1380469626Sru@node gxditview, , grohtml, Output Devices 1380555839Sasmodai@section @code{gxditview} 13806104862Sru@cindex @code{gxditview}, the program 1380755839Sasmodai 1380869626Sru@c XXX 1380955839Sasmodai 1381055839Sasmodai@menu 1381175584Sru* Invoking gxditview:: 1381255839Sasmodai@end menu 1381355839Sasmodai 1381469626Sru@c --------------------------------------------------------------------- 1381569626Sru 1381655839Sasmodai@node Invoking gxditview, , gxditview, gxditview 1381755839Sasmodai@subsection Invoking @code{gxditview} 1381855839Sasmodai@cindex invoking @code{gxditview} 1381955839Sasmodai@cindex @code{gxditview}, invoking 1382055839Sasmodai 1382169626Sru@c XXX 1382269626Sru@c X11's xditview 1382355839Sasmodai 1382455839Sasmodai 1382569626Sru 1382669626Sru@c ===================================================================== 1382769626Sru@c ===================================================================== 1382869626Sru 1382969626Sru@node File formats, Installation, Output Devices, Top 1383055839Sasmodai@chapter File formats 1383155839Sasmodai@cindex file formats 1383255839Sasmodai@cindex formats, file 1383355839Sasmodai 13834104862SruAll files read and written by @code{gtroff} are text files. The 13835104862Srufollowing two sections describe their format. 1383655839Sasmodai 1383755839Sasmodai@menu 1383875584Sru* gtroff Output:: 1383975584Sru* Font Files:: 1384055839Sasmodai@end menu 1384155839Sasmodai 1384269626Sru 1384369626Sru@c ===================================================================== 1384469626Sru 1384555839Sasmodai@node gtroff Output, Font Files, File formats, File formats 1384655839Sasmodai@section @code{gtroff} Output 13847104862Sru@cindex @code{gtroff}, output 1384855839Sasmodai@cindex output, @code{gtroff} 1384955839Sasmodai 13850104862SruThis section describes the intermediate output format of GNU 13851104862Sru@code{troff}. This output is produced by a run of @code{gtroff} 13852104862Srubefore it is fed into a device postprocessor program. 1385355839Sasmodai 13854104862SruAs @code{groff} is a wrapper program around @code{gtroff} that 13855104862Sruautomatically calls a postprocessor, this output does not show up 13856104862Srunormally. This is why it is called @dfn{intermediate}. 13857104862Sru@code{groff} provides the option @option{-Z} to inhibit postprocessing, 13858104862Srusuch that the produced intermediate output is sent to standard output 13859104862Srujust like calling @code{gtroff} manually. 13860104862Sru 13861104862Sru@cindex troff output 13862104862Sru@cindex output, troff 13863104862Sru@cindex intermediate output 13864104862Sru@cindex output, intermediate 13865104862SruHere, the term @dfn{troff output} describes what is output by 13866104862Sru@code{gtroff}, while @dfn{intermediate output} refers to the language 13867104862Sruthat is accepted by the parser that prepares this output for the 13868104862Srupostprocessors. This parser is smarter on whitespace and implements 13869104862Sruobsolete elements for compatibility, otherwise both formats are the 13870104862Srusame.@footnote{The parser and postprocessor for intermediate output 13871104862Srucan be found in the file@* 13872114402Sru@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.} 13873104862Sru 13874104862SruThe main purpose of the intermediate output concept is to facilitate 13875104862Sruthe development of postprocessors by providing a common programming 13876104862Sruinterface for all devices. It has a language of its own that is 13877104862Srucompletely different from the @code{gtroff} language. While the 13878104862Sru@code{gtroff} language is a high-level programming language for text 13879104862Sruprocessing, the intermediate output language is a kind of low-level 13880104862Sruassembler language by specifying all positions on the page for writing 13881104862Sruand drawing. 13882104862Sru 13883104862SruThe intermediate output produced by @code{gtroff} is fairly readable, 13884104862Sruwhile output from @acronym{AT&T} @code{troff} is rather hard to 13885104862Sruunderstand because of strange habits that are still supported, but not 13886104862Sruused any longer by @code{gtroff}. 13887104862Sru 1388869626Sru@menu 13889104862Sru* Language Concepts:: 13890104862Sru* Command Reference:: 13891104862Sru* Intermediate Output Examples:: 13892104862Sru* Output Language Compatibility:: 1389369626Sru@end menu 1389455839Sasmodai 1389569626Sru@c --------------------------------------------------------------------- 1389655839Sasmodai 13897104862Sru@node Language Concepts, Command Reference, gtroff Output, gtroff Output 13898104862Sru@subsection Language Concepts 1389969626Sru 13900104862SruDuring the run of @code{gtroff}, the input data is cracked down to the 13901104862Sruinformation on what has to be printed at what position on the intended 13902104862Srudevice. So the language of the intermediate output format can be quite 13903104862Srusmall. Its only elements are commands with and without arguments. 13904104862SruIn this section, the term @dfn{command} always refers to the intermediate 13905104862Sruoutput language, and never to the @code{gtroff} language used for document 13906104862Sruformatting. There are commands for positioning and text writing, for drawing, and 13907104862Srufor device controlling. 1390869626Sru 13909104862Sru@menu 13910104862Sru* Separation:: 13911104862Sru* Argument Units:: 13912104862Sru* Document Parts:: 13913104862Sru@end menu 1391455839Sasmodai 13915104862Sru@node Separation, Argument Units, Language Concepts, Language Concepts 13916104862Sru@subsubsection Separation 1391755839Sasmodai 13918104862Sru@acronym{AT&T} @code{troff} output has strange requirements on whitespace. 13919104862SruThe @code{gtroff} output parser, however, is smart about whitespace by 13920104862Srumaking it maximally optional. The whitespace characters, i.e., the 13921104862Srutab, space, and newline characters, always have a syntactical meaning. 13922104862SruThey are never printable because spacing within the output is always 13923104862Srudone by positioning commands. 1392455839Sasmodai 13925104862SruAny sequence of space or tab characters is treated as a single 13926104862Sru@dfn{syntactical space}. It separates commands and arguments, but is 13927104862Sruonly required when there would occur a clashing between the command code 13928104862Sruand the arguments without the space. Most often, this happens when 13929104862Sruvariable-length command names, arguments, argument lists, or command 13930104862Sruclusters meet. Commands and arguments with a known, fixed length need 13931104862Srunot be separated by syntactical space. 13932104862Sru 13933104862SruA line break is a syntactical element, too. Every command argument can be 13934104862Srufollowed by whitespace, a comment, or a newline character. Thus a 13935104862Sru@dfn{syntactical line break} is defined to consist of optional 13936104862Srusyntactical space that is optionally followed by a comment, and a 13937104862Srunewline character. 13938104862Sru 13939104862SruThe normal commands, those for positioning and text, consist of a 13940104862Srusingle letter taking a fixed number of arguments. For historical reasons, 13941104862Sruthe parser allows to stack such commands on the same line, but 13942104862Srufortunately, in @code{gtroff}'s intermediate output, every command with 13943104862Sruat least one argument is followed by a line break, thus providing 13944104862Sruexcellent readability. 13945104862Sru 13946104862SruThe other commands -- those for drawing and device controlling -- 13947104862Sruhave a more complicated structure; some recognize long command names, 13948104862Sruand some take a variable number of arguments. So all @samp{D} and 13949104862Sru@samp{x} commands were designed to request a syntactical line break 13950104862Sruafter their last argument. Only one command, @w{@samp{x X}}, 13951104862Sruhas an argument that can stretch over several lines; all other 13952104862Srucommands must have all of their arguments on the same line as the 13953104862Srucommand, i.e., the arguments may not be splitted by a line break. 13954104862Sru 13955104862SruEmpty lines (these are lines containing only space and/or a comment), can 13956104862Sruoccur everywhere. They are just ignored. 13957104862Sru 13958104862Sru@node Argument Units, Document Parts, Separation, Language Concepts 13959104862Sru@subsubsection Argument Units 13960104862Sru 13961104862SruSome commands take integer arguments that are assumed to represent 13962104862Sruvalues in a measurement unit, but the letter for the corresponding 13963104862Sruscale indicator is not written with the output command arguments. 13964104862SruMost commands assume the scale indicator @samp{u}, the basic unit of 13965104862Sruthe device, some use @samp{z}, the scaled point unit of the device, 13966104862Sruwhile others, such as the color commands, expect plain integers. 13967104862Sru 13968104862SruNote that single characters can have the eighth bit set, as can the 13969104862Srunames of fonts and special characters. The names of characters and 13970104862Srufonts can be of arbitrary length. A character that is to be printed 13971104862Sruwill always be in the current font. 13972104862Sru 13973104862SruA string argument is always terminated by the next whitespace 13974104862Srucharacter (space, tab, or newline); an embedded @samp{#} character is 13975104862Sruregarded as part of the argument, not as the beginning of a comment 13976104862Srucommand. An integer argument is already terminated by the next 13977104862Srunon-digit character, which then is regarded as the first character of 13978104862Sruthe next argument or command. 13979104862Sru 13980104862Sru@node Document Parts, , Argument Units, Language Concepts 13981104862Sru@subsubsection Document Parts 13982104862Sru 13983104862SruA correct intermediate output document consists of two parts, the 13984104862Sru@dfn{prologue} and the @dfn{body}. 13985104862Sru 13986104862SruThe task of the prologue is to set the general device parameters 13987104862Sruusing three exactly specified commands. @code{gtroff}'s prologue 13988104862Sruis guaranteed to consist of the following three lines (in that order): 13989104862Sru 13990104862Sru@Example 13991104862Srux T @var{device} 13992104862Srux res @var{n} @var{h} @var{v} 13993104862Srux init 13994104862Sru@endExample 13995104862Sru 13996104862Sru@noindent 13997104862Sruwith the arguments set as outlined in @ref{Device Control Commands}. 13998104862SruNote that the parser for the intermediate output format is able to 13999104862Sruswallow additional whitespace and comments as well even in the 14000104862Sruprologue. 14001104862Sru 14002104862SruThe body is the main section for processing the document data. 14003104862SruSyntactically, it is a sequence of any commands different from the 14004104862Sruones used in the prologue. Processing is terminated as soon as the 14005104862Srufirst @w{@samp{x stop}} command is encountered; the last line of any 14006104862Sru@code{gtroff} intermediate output always contains such a command. 14007104862Sru 14008104862SruSemantically, the body is page oriented. A new page is started by a 14009104862Sru@samp{p} command. Positioning, writing, and drawing commands are 14010104862Srualways done within the current page, so they cannot occur before the 14011104862Srufirst @samp{p} command. Absolute positioning (by the @samp{H} and 14012104862Sru@samp{V} commands) is done relative to the current page; all other 14013104862Srupositioning is done relative to the current location within this page. 14014104862Sru 14015104862Sru@c --------------------------------------------------------------------- 14016104862Sru 14017104862Sru@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output 14018104862Sru@subsection Command Reference 14019104862Sru 14020104862SruThis section describes all intermediate output commands, both from 14021104862Sru@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions. 14022104862Sru 14023104862Sru@menu 14024104862Sru* Comment Command:: 14025104862Sru* Simple Commands:: 14026104862Sru* Graphics Commands:: 14027104862Sru* Device Control Commands:: 14028104862Sru* Obsolete Command:: 14029104862Sru@end menu 14030104862Sru 14031104862Sru@node Comment Command, Simple Commands, Command Reference, Command Reference 14032104862Sru@subsubsection Comment Command 14033104862Sru 1403455839Sasmodai@table @code 14035104862Sru@item #@var{anything}@angles{end of line} 14036104862SruA comment. Ignore any characters from the @samp{#} character up to 14037104862Sruthe next newline character. 1403869626Sru 14039104862SruThis command is the only possibility for commenting in the intermediate 14040104862Sruoutput. Each comment can be preceded by arbitrary syntactical space; 14041104862Sruevery command can be terminated by a comment. 14042104862Sru@end table 1404369626Sru 14044104862Sru@node Simple Commands, Graphics Commands, Comment Command, Command Reference 14045104862Sru@subsubsection Simple Commands 1404669626Sru 14047104862SruThe commands in this subsection have a command code consisting of a 14048104862Srusingle character, taking a fixed number of arguments. Most of them 14049104862Sruare commands for positioning and text writing. These commands are 14050104862Srusmart about whitespace. Optionally, syntactical space can be inserted 14051104862Srubefore, after, and between the command letter and its arguments. 14052104862SruAll of these commands are stackable, i.e., they can be preceded by 14053104862Sruother simple commands or followed by arbitrary other commands on the 14054104862Srusame line. A separating syntactical space is only necessary when two 14055104862Sruinteger arguments would clash or if the preceding argument ends with a 14056104862Srustring argument. 1405769626Sru 14058104862Sru@table @code 14059104862Sru@ignore 14060104862Sru.if (\n[@USE_ENV_STACK] == 1) \{\ 14061104862Sru.command { 14062104862SruOpen a new environment by copying the actual device configuration data 14063104862Sruto the environment stack. 14064104862Sru. 14065104862SruThe current environment is setup by the device specification and 14066104862Srumanipulated by the setting commands. 14067104862Sru. 14068104862Sru. 14069104862Sru.command } 14070104862SruClose the actual environment (opened by a preceding 14071104862Sru.BR { \~command) 14072104862Sruand restore the previous environment from the environment 14073104862Srustack as the actual device configuration data. 14074104862Sru. 14075104862Sru\} \" endif @USE_ENV_STACK 14076104862Sru@end ignore 1407769626Sru 14078104862Sru@item C @var{xxx}@angles{whitespace} 14079104862SruPrint a special character named @var{xxx}. The trailing 14080104862Srusyntactical space or line break is necessary to allow glyph names 14081104862Sruof arbitrary length. The glyph is printed at the current print 14082104862Sruposition; the glyph's size is read from the font file. The print 14083104862Sruposition is not changed. 1408469626Sru 14085104862Sru@item c @var{g} 14086114402SruPrint glyph@tie{}@var{g} at the current print position;@footnote{@samp{c} 14087104862Sruis actually a misnomer since it outputs a glyph.} the glyph's size is 14088104862Sruread from the font file. The print position is not changed. 1408969626Sru 14090104862Sru@item f @var{n} 14091114402SruSet font to font number@tie{}@var{n} (a non-negative integer). 1409255839Sasmodai 14093104862Sru@item H @var{n} 14094114402SruMove right to the absolute vertical position@tie{}@var{n} (a 14095104862Srunon-negative integer in basic units @samp{u} relative to left edge 14096104862Sruof current page. 1409769626Sru 14098104862Sru@item h @var{n} 14099104862SruMove @var{n} (a non-negative integer) basic units @samp{u} horizontally 14100104862Sruto the right. The original @acronym{UNIX} troff manual allows negative 14101104862Sruvalues for @var{n} also, but @code{gtroff} doesn't use this. 1410255839Sasmodai 14103104862Sru@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]} 14104104862SruSet the color for text (glyphs), line drawing, and the outline of 14105104862Srugraphic objects using different color schemes; the analoguous command 14106104862Srufor the filling color of graphic objects is @samp{DF}. The color 14107104862Srucomponents are specified as integer arguments between 0 and 65536. 14108104862SruThe number of color components and their meaning vary for the 14109104862Srudifferent color schemes. These commands are generated by 14110104862Sru@code{gtroff}'s escape sequence @code{\m}. No position changing. 14111104862SruThese commands are a @code{gtroff} extension. 1411269626Sru 14113104862Sru@table @code 14114104862Sru@item mc @var{cyan} @var{magenta} @var{yellow} 14115114402SruSet color using the CMY color scheme, having the 3@tie{}color components 14116104862Sru@var{cyan}, @var{magenta}, and @var{yellow}. 1411769626Sru 14118104862Sru@item md 14119104862SruSet color to the default color value (black in most cases). 14120104862SruNo component arguments. 1412169626Sru 14122104862Sru@item mg @var{gray} 14123104862SruSet color to the shade of gray given by the argument, an integer 14124104862Srubetween 0 (black) and 65536 (white). 1412569626Sru 14126104862Sru@item mk @var{cyan} @var{magenta} @var{yellow} @var{black} 14127114402SruSet color using the CMYK color scheme, having the 4@tie{}color components 14128104862Sru@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. 1412969626Sru 14130104862Sru@item mr @var{red} @var{green} @var{blue} 14131114402SruSet color using the RGB color scheme, having the 3@tie{}color components 14132104862Sru@var{red}, @var{green}, and @var{blue}. 14133104862Sru 1413455839Sasmodai@end table 1413555839Sasmodai 14136104862Sru@item N @var{n} 14137114402SruPrint glyph with index@tie{}@var{n} (a non-negative integer) of the 14138104862Srucurrent font. This command is a @code{gtroff} extension. 1413969626Sru 14140104862Sru@item n @var{b} @var{a} 14141104862SruInform the device about a line break, but no positioning is done by 14142104862Sruthis command. In @acronym{AT&T} @code{troff}, the integer arguments 14143114402Sru@var{b} and@tie{}@var{a} informed about the space before and after the 14144104862Srucurrent line to make the intermediate output more human readable 14145104862Sruwithout performing any action. In @code{groff}, they are just ignored, but 14146104862Sruthey must be provided for compatibility reasons. 1414755839Sasmodai 14148104862Sru@item p @var{n} 14149104862SruBegin a new page in the outprint. The page number is set 14150114402Sruto@tie{}@var{n}. This page is completely independent of pages formerly 14151104862Sruprocessed even if those have the same page number. The vertical 14152114402Sruposition on the outprint is automatically set to@tie{}0. All 14153104862Srupositioning, writing, and drawing is always done relative to a page, 14154104862Sruso a @samp{p} command must be issued before any of these commands. 1415555839Sasmodai 14156104862Sru@item s @var{n} 14157114402SruSet point size to @var{n}@tie{}scaled points (this is unit @samp{z}). 14158104862Sru@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. 14159104862Sru@xref{Output Language Compatibility}. 1416055839Sasmodai 14161104862Sru@item t @var{xxx}@angles{whitespace} 14162104862Sru@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace} 14163104862SruPrint a word, i.e., a sequence of characters @var{xxx} representing 14164104862Sruoutput glyphs which names are single characters, terminated by 14165104862Srua space character or a line break; an optional second integer argument 14166104862Sruis ignored (this allows the formatter to generate an even number of 14167104862Sruarguments). The first glyph should be printed at the current 14168104862Sruposition, the current horizontal position should then be increased by 14169104862Sruthe width of the first glyph, and so on for each glyph. 14170104862SruThe widths of the glyphs are read from the font file, scaled for the 14171104862Srucurrent point size, and rounded to a multiple of the horizontal 14172104862Sruresolution. Special characters cannot be printed using this command 14173104862Sru(use the @samp{C} command for special characters). This command is a 14174104862Sru@code{gtroff} extension; it is only used for devices whose @file{DESC} 14175104862Srufile contains the @code{tcommand} keyword (@pxref{DESC File Format}). 14176104862Sru 14177104862Sru@item u @var{n} @var{xxx}@angles{whitespace} 14178104862SruPrint word with track kerning. This is the same as the @samp{t} 14179104862Srucommand except that after printing each glyph, the current 14180104862Sruhorizontal position is increased by the sum of the width of that 14181114402Sruglyph and@tie{}@var{n} (an integer in basic units @samp{u}). 14182104862SruThis command is a @code{gtroff} extension; it is only used for devices 14183104862Sruwhose @file{DESC} file contains the @code{tcommand} keyword 14184104862Sru(@pxref{DESC File Format}). 14185104862Sru 14186104862Sru@item V @var{n} 14187114402SruMove down to the absolute vertical position@tie{}@var{n} (a 14188104862Srunon-negative integer in basic units @samp{u}) relative to upper edge 14189104862Sruof current page. 14190104862Sru 14191104862Sru@item v @var{n} 14192114402SruMove @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative 14193104862Sruinteger). The original @acronym{UNIX} troff manual allows negative 14194104862Sruvalues for @var{n} also, but @code{gtroff} doesn't use this. 14195104862Sru 14196104862Sru@item w 14197104862SruInforms about a paddable white space to increase readability. 14198104862SruThe spacing itself must be performed explicitly by a move command. 14199104862Sru 14200104862Sru@end table 14201104862Sru 14202104862Sru@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference 14203104862Sru@subsubsection Graphics Commands 14204104862Sru 14205104862SruEach graphics or drawing command in the intermediate output starts 14206104862Sruwith the letter @samp{D}, followed by one or two characters that 14207104862Sruspecify a subcommand; this is followed by a fixed or variable number 14208104862Sruof integer arguments that are separated by a single space character. 14209104862SruA @samp{D} command may not be followed by another command on the same line 14210104862Sru(apart from a comment), so each @samp{D} command is terminated by a 14211104862Srusyntactical line break. 14212104862Sru 14213104862Sru@code{gtroff} output follows the classical spacing rules (no space 14214104862Srubetween command and subcommand, all arguments are preceded by a 14215104862Srusingle space character), but the parser allows optional space between 14216104862Sruthe command letters and makes the space before the first argument 14217104862Sruoptional. As usual, each space can be any sequence of tab and space 14218104862Srucharacters. 14219104862Sru 14220104862SruSome graphics commands can take a variable number of arguments. 14221104862SruIn this case, they are integers representing a size measured in basic 14222104862Sruunits @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{}, 14223104862Sru@var{hn} stand for horizontal distances where positive means right, 14224104862Srunegative left. The arguments called @var{v1}, @var{v2}, @dots{}, 14225104862Sru@var{vn} stand for vertical distances where positive means down, 14226104862Srunegative up. All these distances are offsets relative to the current 14227104862Srulocation. 14228104862Sru 14229114402SruEach graphics command directly corresponds to a similar @code{gtroff} 14230114402Sru@code{\D} escape sequence. @xref{Drawing Requests}. 14231104862Sru 14232104862SruUnknown @samp{D} commands are assumed to be device-specific. 14233104862SruIts arguments are parsed as strings; the whole information is then 14234104862Srusent to the postprocessor. 14235104862Sru 14236104862SruIn the following command reference, the syntax element 14237104862Sru@angles{line break} means a syntactical line break as defined above. 14238104862Sru 1423955839Sasmodai@table @code 14240104862Sru@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14241104862SruDraw B-spline from current position to offset (@var{h1},@var{v1}), 14242104862Sruthen to offset (@var{h2},@var{v2}), if given, etc.@: up to 14243104862Sru(@var{hn},@var{vn}). This command takes a variable number of argument 14244104862Srupairs; the current position is moved to the terminal point of the drawn 14245104862Srucurve. 1424669626Sru 14247104862Sru@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break} 14248104862SruDraw arc from current position to 14249104862Sru(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at 14250104862Sru(@var{h1},@var{v1}); then move the current position to the final point 14251104862Sruof the arc. 1425269626Sru 14253104862Sru@item DC @var{d}@angles{line break} 14254104862Sru@itemx DC @var{d} @var{dummy-arg}@angles{line break} 14255104862SruDraw a solid circle using the current fill color with 14256114402Srudiameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost 14257104862Srupoint at the current position; then move the current position to the 14258104862Srurightmost point of the circle. An optional second integer argument is 14259104862Sruignored (this allows the formatter to generate an even number of 14260104862Sruarguments). This command is a @code{gtroff} extension. 1426169626Sru 14262104862Sru@item Dc @var{d}@angles{line break} 14263114402SruDraw circle line with diameter@tie{}@var{d} (integer in basic units 14264104862Sru@samp{u}) with leftmost point at the current position; then move the 14265104862Srucurrent position to the rightmost point of the circle. 14266104862Sru 14267104862Sru@item DE @var{h} @var{v}@angles{line break} 14268104862SruDraw a solid ellipse in the current fill color with a horizontal 14269114402Srudiameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both 14270104862Sruintegers in basic units @samp{u}) with the leftmost point at the 14271104862Srucurrent position; then move to the rightmost point of the ellipse. 14272104862SruThis command is a @code{gtroff} extension. 14273104862Sru 14274104862Sru@item De @var{h} @var{v}@angles{line break} 14275114402SruDraw an outlined ellipse with a horizontal diameter of@tie{}@var{h} 14276114402Sruand a vertical diameter of@tie{}@var{v} (both integers in basic units 14277104862Sru@samp{u}) with the leftmost point at current position; then move to 14278104862Sruthe rightmost point of the ellipse. 14279104862Sru 14280104862Sru@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break} 14281104862SruSet fill color for solid drawing objects using different color 14282104862Sruschemes; the analoguous command for setting the color of text, line 14283104862Srugraphics, and the outline of graphic objects is @samp{m}. 14284104862SruThe color components are specified as integer arguments between 0 and 14285104862Sru65536. The number of color components and their meaning vary for the 14286104862Srudifferent color schemes. These commands are generated by @code{gtroff}'s 14287104862Sruescape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other 14288104862Srucorresponding graphics commands). No position changing. This command 14289104862Sruis a @code{gtroff} extension. 14290104862Sru 14291104862Sru@table @code 14292104862Sru@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} 14293104862SruSet fill color for solid drawing objects using the CMY color scheme, 14294114402Sruhaving the 3@tie{}color components @var{cyan}, @var{magenta}, and 14295104862Sru@var{yellow}. 14296104862Sru 14297104862Sru@item DFd@angles{line break} 14298104862SruSet fill color for solid drawing objects to the default fill color value 14299104862Sru(black in most cases). No component arguments. 14300104862Sru 14301104862Sru@item DFg @var{gray}@angles{line break} 14302104862SruSet fill color for solid drawing objects to the shade of gray given by 14303104862Sruthe argument, an integer between 0 (black) and 65536 (white). 14304104862Sru 14305104862Sru@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} 14306104862SruSet fill color for solid drawing objects using the CMYK color scheme, 14307114402Sruhaving the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow}, 14308104862Sruand @var{black}. 14309104862Sru 14310104862Sru@item DFr @var{red} @var{green} @var{blue}@angles{line break} 14311104862SruSet fill color for solid drawing objects using the RGB color scheme, 14312114402Sruhaving the 3@tie{}color components @var{red}, @var{green}, and @var{blue}. 14313104862Sru 1431455839Sasmodai@end table 1431555839Sasmodai 14316104862Sru@item Df @var{n}@angles{line break} 14317114402SruThe argument@tie{}@var{n} must be an integer in the range @math{-32767} 14318104862Sruto 32767. 1431955839Sasmodai 14320104862Sru@table @asis 14321104862Sru@item @math{0 @LE @var{n} @LE 1000} 14322104862SruSet the color for filling solid drawing objects to a shade of gray, 14323104862Sruwhere 0 corresponds to solid white, 1000 (the default) to solid black, 14324104862Sruand values in between to intermediate shades of gray; this is 14325104862Sruobsoleted by command @samp{DFg}. 14326104862Sru 14327114402Sru@item @math{@var{n} < 0} or @math{@var{n} > 1000} 14328104862SruSet the filling color to the color that is currently being used for 14329104862Sruthe text and the outline, see command @samp{m}. For example, the 14330104862Srucommand sequence 14331104862Sru 1433275584Sru@Example 14333104862Srumg 0 0 65536 14334104862SruDf -1 1433575584Sru@endExample 1433655839Sasmodai 1433769626Sru@noindent 14338104862Srusets all colors to blue. 1433955839Sasmodai 14340104862Sru@end table 1434169626Sru 1434269626Sru@noindent 14343104862SruNo position changing. This command is a @code{gtroff} extension. 1434469626Sru 14345104862Sru@item Dl @var{h} @var{v}@angles{line break} 14346104862SruDraw line from current position to offset (@var{h},@var{v}) (integers 14347104862Sruin basic units @samp{u}); then set current position to the end of the 14348104862Srudrawn line. 1434969626Sru 14350104862Sru@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14351104862SruDraw a polygon line from current position to offset (@var{h1},@var{v1}), 14352104862Srufrom there to offset (@var{h2},@var{v2}), etc.@: up to offset 14353104862Sru(@var{hn},@var{vn}), and from there back to the starting position. 14354104862SruFor historical reasons, the position is changed by adding the sum of 14355104862Sruall arguments with odd index to the actual horizontal position and the 14356104862Srueven ones to the vertical position. Although this doesn't make sense 14357104862Sruit is kept for compatibility. 1435869626Sru@ignore 14359104862SruAs the polygon is closed, the end of drawing is the starting point, so 14360104862Sruthe position doesn't change. 1436169626Sru@end ignore 14362104862SruThis command is a @code{gtroff} extension. 1436355839Sasmodai 14364104862Sru@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14365104862SruDraw a solid polygon in the current fill color rather than an outlined 14366104862Srupolygon, using the same arguments and positioning as the corresponding 14367104862Sru@samp{Dp} command. 14368104862Sru@ignore 14369104862SruNo position changing. 14370104862Sru@end ignore 14371104862SruThis command is a @code{gtroff} extension. 1437269626Sru 14373104862Sru@item Dt @var{n}@angles{line break} 14374114402SruSet the current line thickness to@tie{}@var{n} (an integer in basic 14375104862Sruunits @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the 14376104862Srusmallest available line thickness; if @math{@var{n}<0} set the line 14377104862Sruthickness proportional to the point size (this is the default before 14378104862Sruthe first @samp{Dt} command was specified). For historical reasons, 14379104862Sruthe horizontal position is changed by adding the argument to the actual 14380104862Sruhorizontal position, while the vertical position is not changed. 14381104862SruAlthough this doesn't make sense it is kept for compatibility. 14382104862Sru@ignore 14383104862SruNo position changing. 14384104862Sru@end ignore 14385104862SruThis command is a @code{gtroff} extension. 1438655839Sasmodai 14387104862Sru@end table 1438855839Sasmodai 14389104862Sru@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference 14390104862Sru@subsubsection Device Control Commands 1439169626Sru 14392104862SruEach device control command starts with the letter @samp{x}, 14393104862Srufollowed by a space character (optional or arbitrary space or tab in 14394104862Sru@code{gtroff}) and a subcommand letter or word; each argument (if any) 14395104862Srumust be preceded by a syntactical space. All @samp{x} commands are 14396104862Sruterminated by a syntactical line break; no device control command can 14397104862Srube followed by another command on the same line (except a comment). 14398104862Sru 14399104862SruThe subcommand is basically a single letter, but to increase 14400104862Srureadability, it can be written as a word, i.e., an arbitrary sequence 14401104862Sruof characters terminated by the next tab, space, or newline character. 14402104862SruAll characters of the subcommand word but the first are simply ignored. 14403104862SruFor example, @code{gtroff} outputs the initialization command 14404104862Sru@w{@samp{x i}} as @w{@samp{x init}} and the resolution command 14405104862Sru@w{@samp{x r}} as @w{@samp{x res}}. 14406104862Sru 14407104862SruIn the following, the syntax element @angles{line break} means a 14408104862Srusyntactical line break (@pxref{Separation}). 14409104862Sru 1441055839Sasmodai@table @code 14411104862Sru@item xF @var{name}@angles{line break} 14412104862SruThe @samp{F} stands for @var{Filename}. 1441369626Sru 14414104862SruUse @var{name} as the intended name for the current file in error 14415104862Srureports. This is useful for remembering the original file name when 14416104862Sru@code{gtroff} uses an internal piping mechanism. The input file is 14417104862Srunot changed by this command. This command is a @code{gtroff} extension. 1441869626Sru 14419104862Sru@item xf @var{n} @var{s}@angles{line break} 14420104862SruThe @samp{f} stands for @var{font}. 1442169626Sru 14422114402SruMount font position@tie{}@var{n} (a non-negative integer) with font 14423114402Srunamed@tie{}@var{s} (a text word). @xref{Font Positions}. 1442469626Sru 14425104862Sru@item xH @var{n}@angles{line break} 14426104862SruThe @samp{H} stands for @var{Height}. 1442769626Sru 14428114402SruSet glyph height to@tie{}@var{n} (a positive integer in scaled 14429104862Srupoints @samp{z}). @acronym{AT&T} @code{troff} uses the unit points 14430104862Sru(@samp{p}) instead. @xref{Output Language Compatibility}. 14431104862Sru 14432104862Sru@item xi@angles{line break} 14433104862SruThe @samp{i} stands for @var{init}. 14434104862Sru 14435104862SruInitialize device. This is the third command of the prologue. 14436104862Sru 14437104862Sru@item xp@angles{line break} 14438104862SruThe @samp{p} stands for @var{pause}. 14439104862Sru 14440104862SruParsed but ignored. The original @acronym{UNIX} troff manual writes 14441104862Sru 14442104862Sru@display 14443104862Srupause device, can be restarted 14444104862Sru@end display 14445104862Sru 14446104862Sru@item xr @var{n} @var{h} @var{v}@angles{line break} 14447104862SruThe @samp{r} stands for @var{resolution}. 14448104862Sru 14449114402SruResolution is@tie{}@var{n}, while @var{h} is the minimal horizontal 14450104862Srumotion, and @var{v} the minimal vertical motion possible with this 14451104862Srudevice; all arguments are positive integers in basic units @samp{u} 14452104862Sruper inch. This is the second command of the prologue. 14453104862Sru 14454104862Sru@item xS @var{n}@angles{line break} 14455104862SruThe @samp{S} stands for @var{Slant}. 14456104862Sru 14457114402SruSet slant to@tie{}@var{n} (an integer in basic units @samp{u}). 14458104862Sru 14459104862Sru@item xs@angles{line break} 14460104862SruThe @samp{s} stands for @var{stop}. 14461104862Sru 14462104862SruTerminates the processing of the current file; issued as the last 14463104862Srucommand of any intermediate troff output. 14464104862Sru 14465104862Sru@item xt@angles{line break} 14466104862SruThe @samp{t} stands for @var{trailer}. 14467104862Sru 14468104862SruGenerate trailer information, if any. In @var{gtroff}, this is 14469104862Sruactually just ignored. 14470104862Sru 14471104862Sru@item xT @var{xxx}@angles{line break} 14472104862SruThe @samp{T} stands for @var{Typesetter}. 14473104862Sru 14474104862SruSet name of device to word @var{xxx}, a sequence of characters ended 14475104862Sruby the next white space character. The possible device names coincide 14476104862Sruwith those from the @code{groff} @option{-T} option. This is the first 14477104862Srucommand of the prologue. 14478104862Sru 14479104862Sru@item xu @var{n}@angles{line break} 14480104862SruThe @samp{u} stands for @var{underline}. 14481104862Sru 14482114402SruConfigure underlining of spaces. If @var{n} is@tie{}1, start 14483114402Sruunderlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces. 14484104862SruThis is needed for the @code{cu} request in nroff mode and is ignored 14485104862Sruotherwise. This command is a @code{gtroff} extension. 14486104862Sru 14487104862Sru@item xX @var{anything}@angles{line break} 14488104862SruThe @samp{x} stands for @var{X-escape}. 14489104862Sru 14490104862SruSend string @var{anything} uninterpreted to the device. If the line 14491104862Srufollowing this command starts with a @samp{+} character this line is 14492104862Sruinterpreted as a continuation line in the following sense. The 14493104862Sru@samp{+} is ignored, but a newline character is sent instead to the 14494104862Srudevice, the rest of the line is sent uninterpreted. The same applies 14495104862Sruto all following lines until the first character of a line is not a 14496104862Sru@samp{+} character. This command is generated by the @code{gtroff} 14497104862Sruescape sequence @code{\X}. The line-continuing feature is a 14498104862Sru@code{gtroff} extension. 14499104862Sru 1450055839Sasmodai@end table 1450155839Sasmodai 14502104862Sru@node Obsolete Command, , Device Control Commands, Command Reference 14503104862Sru@subsubsection Obsolete Command 14504104862SruIn @acronym{AT&T} @code{troff} output, the writing of a single 14505104862Sruglyph is mostly done by a very strange command that combines a 14506104862Sruhorizontal move and a single character giving the glyph name. It 14507104862Srudoesn't have a command code, but is represented by a 3-character 14508114402Sruargument consisting of exactly 2@tie{}digits and a character. 1450955839Sasmodai 14510104862Sru@table @asis 14511104862Sru@item @var{dd}@var{g} 14512104862SruMove right @var{dd} (exactly two decimal digits) basic units @samp{u}, 14513114402Sruthen print glyph@tie{}@var{g} (represented as a single character). 1451455839Sasmodai 14515104862SruIn @code{gtroff}, arbitrary syntactical space around and within this 14516104862Srucommand is allowed to be added. Only when a preceding command on the 14517104862Srusame line ends with an argument of variable length a separating space 14518104862Sruis obligatory. In @acronym{AT&T} @code{troff}, large clusters of these 14519104862Sruand other commands are used, mostly without spaces; this made such output 14520104862Srualmost unreadable. 14521104862Sru 14522104862Sru@end table 14523104862Sru 14524104862SruFor modern high-resolution devices, this command does not make sense 14525104862Srubecause the width of the glyphs can become much larger than two 14526104862Srudecimal digits. In @code{gtroff}, this is only used for the devices 14527104862Sru@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other 14528104862Srudevices, the commands @samp{t} and @samp{u} provide a better 14529104862Srufunctionality. 14530104862Sru 14531104862Sru@c --------------------------------------------------------------------- 14532104862Sru 14533104862Sru@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output 14534104862Sru@subsection Intermediate Output Examples 14535104862Sru 14536104862SruThis section presents the intermediate output generated from the same 14537104862Sruinput for three different devices. The input is the sentence 14538104862Sru@samp{hell world} fed into @code{gtroff} on the command line. 14539104862Sru 14540104862Sru@table @asis 14541104862Sru@item High-resolution device @code{ps} 14542104862Sru 14543104862SruThis is the standard output of @code{gtroff} if no @option{-T} option 14544104862Sruis given. 14545104862Sru 14546104862Sru@example 14547104862Sru@group 14548104862Srushell> echo "hell world" | groff -Z -T ps 14549104862Sru 14550104862Srux T ps 14551104862Srux res 72000 1 1 14552104862Srux init 14553104862Sru@end group 14554104862Srup1 14555104862Srux font 5 TR 14556104862Sruf5 14557104862Srus10000 14558104862SruV12000 14559104862SruH72000 14560104862Sruthell 14561104862Sruwh2500 14562104862Srutw 14563104862SruH96620 14564104862Srutorld 14565104862Srun12000 0 14566104862Sru@group 14567104862Srux trailer 14568104862SruV792000 14569104862Srux stop 14570104862Sru@end group 14571104862Sru@end example 14572104862Sru 1457369626Sru@noindent 14574104862SruThis output can be fed into @code{grops} to get its representation as 14575104862Srua PostScript file. 1457655839Sasmodai 14577104862Sru@item Low-resolution device @code{latin1} 1457855839Sasmodai 14579104862SruThis is similar to the high-resolution device except that the 14580104862Srupositioning is done at a minor scale. Some comments (lines starting 14581104862Sruwith @samp{#}) were added for clarification; they were not generated 14582104862Sruby the formatter. 14583104862Sru 14584104862Sru@example 14585104862Sru@group 14586104862Srushell> echo "hell world" | groff -Z -T latin1 14587104862Sru 14588104862Sru# prologue 14589104862Srux T latin1 14590104862Srux res 240 24 40 14591104862Srux init 14592104862Sru@end group 14593104862Sru# begin a new page 14594104862Srup1 14595104862Sru# font setup 14596104862Srux font 1 R 14597104862Sruf1 14598104862Srus10 14599104862Sru# initial positioning on the page 14600104862SruV40 14601104862SruH0 14602104862Sru# write text `hell' 14603104862Sruthell 14604104862Sru# inform about space, and issue a horizontal jump 14605104862Sruwh24 14606104862Sru# write text `world' 14607104862Srutworld 14608104862Sru# announce line break, but do nothing because ... 14609104862Srun40 0 14610104862Sru@group 14611104862Sru# ... the end of the document has been reached 14612104862Srux trailer 14613104862SruV2640 14614104862Srux stop 14615104862Sru@end group 14616104862Sru@end example 14617104862Sru 1461869626Sru@noindent 14619104862SruThis output can be fed into @code{grotty} to get a formatted text 14620104862Srudocument. 1462155839Sasmodai 14622104862Sru@item @acronym{AT&T} @code{troff} output 14623104862SruSince a computer monitor has a very low resolution compared to modern 14624114402Sruprinters the intermediate output for the X@tie{}Window devices can use 14625104862Sruthe jump-and-write command with its 2-digit displacements. 14626104862Sru 14627104862Sru@example 14628104862Sru@group 14629104862Srushell> echo "hell world" | groff -Z -T X100 14630104862Sru 14631104862Srux T X100 14632104862Srux res 100 1 1 14633104862Srux init 14634104862Sru@end group 14635104862Srup1 14636104862Srux font 5 TR 14637104862Sruf5 14638104862Srus10 14639104862SruV16 14640104862SruH100 14641104862Sru# write text with jump-and-write commands 14642104862Sruch07e07l03lw06w11o07r05l03dh7 14643104862Srun16 0 14644104862Sru@group 14645104862Srux trailer 14646104862SruV1100 14647104862Srux stop 14648104862Sru@end group 14649104862Sru@end example 14650104862Sru 14651104862Sru@noindent 14652104862SruThis output can be fed into @code{xditview} or @code{gxditview} 14653114402Srufor displaying in@tie{}X. 14654104862Sru 14655104862SruDue to the obsolete jump-and-write command, the text clusters in the 14656104862Sru@acronym{AT&T} @code{troff} output are almost unreadable. 14657104862Sru 14658104862Sru@end table 14659104862Sru 1466069626Sru@c --------------------------------------------------------------------- 1466169626Sru 14662104862Sru@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output 14663104862Sru@subsection Output Language Compatibility 1466455839Sasmodai 14665104862SruThe intermediate output language of @acronym{AT&T} @code{troff} 14666104862Sruwas first documented in the @acronym{UNIX} troff manual, with later 14667104862Sruadditions documented in @cite{A Typesetter-indenpendent TROFF}, 14668104862Sruwritten by Brian Kernighan. 1466955839Sasmodai 14670104862SruThe @code{gtroff} intermediate output format is compatible with this 14671104862Sruspecification except for the following features. 1467255839Sasmodai 14673104862Sru@itemize @bullet 14674104862Sru@item 14675104862SruThe classical quasi device independence is not yet implemented. 14676104862Sru 14677104862Sru@item 14678104862SruThe old hardware was very different from what we use today. So the 14679104862Sru@code{groff} devices are also fundamentally different from the ones in 14680104862Sru@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T} 14681104862SruPostScript device is called @code{post} and has a resolution of only 14682104862Sru720 units per inch, suitable for printers 20 years ago, while 14683104862Sru@code{groff}'s @code{ps} device has a resolution of 14684104862Sru72000 units per inch. Maybe, by implementing some rescaling 14685104862Srumechanism similar to the classical quasi device independence, 14686104862Sru@code{groff} could emulate @acronym{AT&T}'s @code{post} device. 14687104862Sru 14688104862Sru@item 14689104862SruThe B-spline command @samp{D~} is correctly handled by the 14690104862Sruintermediate output parser, but the drawing routines aren't 14691104862Sruimplemented in some of the postprocessor programs. 14692104862Sru 14693104862Sru@item 14694104862SruThe argument of the commands @samp{s} and @w{@samp{x H}} has the 14695104862Sruimplicit unit scaled point @samp{z} in @code{gtroff}, while 14696104862Sru@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an 14697104862Sruincompatibility but a compatible extension, for both units coincide 14698104862Srufor all devices without a @code{sizescale} parameter in the @file{DESC} 14699104862Srufile, including all postprocessors from @acronym{AT&T} and 14700104862Sru@code{groff}'s text devices. The few @code{groff} devices with 14701104862Srua @code{sizescale} parameter either do not exist for @acronym{AT&T} 14702104862Sru@code{troff}, have a different name, or seem to have a different 14703104862Sruresolution. So conflicts are very unlikely. 14704104862Sru 14705104862Sru@item 14706104862SruThe position changing after the commands @samp{Dp}, @samp{DP}, and 14707104862Sru@samp{Dt} is illogical, but as old versions of @code{gtroff} used this 14708104862Srufeature it is kept for compatibility reasons. 14709104862Sru 14710104862Sru@ignore 14711104862SruTemporarily, there existed some confusion on the positioning after the 14712104862Sru@samp{D} commands that are groff extensions. This has been clarified 14713104862Sruby establishing the classical rule for all @code{groff} drawing commands: 14714104862Sru 14715104862Sru@itemize 14716104862Sru@item 14717104862SruThe position after a graphic object has been drawn is at its end; 14718104862Srufor circles and ellipses, the `end' is at the right side. 14719104862Sru 14720104862Sru@item 14721104862SruFrom this, the positionings specified for the drawing commands above 14722104862Srufollow quite naturally. 14723104862Sru@end itemize 14724104862Sru@end ignore 14725104862Sru 14726104862Sru@end itemize 14727104862Sru 14728104862Sru 1472969626Sru@c ===================================================================== 1473055839Sasmodai 1473155839Sasmodai@node Font Files, , gtroff Output, File formats 1473255839Sasmodai@section Font Files 1473355839Sasmodai@cindex font files 1473455839Sasmodai@cindex files, font 1473555839Sasmodai 1473669626SruThe @code{gtroff} font format is roughly a superset of the 14737104862Sru@code{ditroff} font format (as used in later versions of @acronym{AT&T} 14738104862Sru@code{troff} and its descendants). Unlike the @code{ditroff} font 14739104862Sruformat, there is no associated binary format; all files are text 14740114402Srufiles.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary 14741104862Sruformat.} The font files for device @var{name} are stored in a directory 1474269626Sru@file{dev@var{name}}. There are two types of file: a device description 14743114402Srufile called @file{DESC} and for each font@tie{}@var{f} a font file 14744114402Srucalled@tie{}@file{@var{f}}. 1474555839Sasmodai 1474669626Sru@menu 1474775584Sru* DESC File Format:: 1474875584Sru* Font File Format:: 1474969626Sru@end menu 1475055839Sasmodai 1475169626Sru@c --------------------------------------------------------------------- 1475269626Sru 1475375584Sru@node DESC File Format, Font File Format, Font Files, Font Files 1475475584Sru@subsection @file{DESC} File Format 14755104862Sru@cindex @file{DESC} file, format 14756104862Sru@cindex font description file, format 1475769626Sru@cindex format of font description file 1475869626Sru@pindex DESC@r{ file format} 1475955839Sasmodai 14760104862SruThe @file{DESC} file can contain the following types of line. Except 14761104862Srufor the @code{charset} keyword which must comes last (if at all), the 14762104862Sruorder of the lines is not important. 1476355839Sasmodai 1476455839Sasmodai@table @code 1476555839Sasmodai@item res @var{n} 1476669626Sru@kindex res 14767114402Sru@cindex device resolution 14768114402Sru@cindex resolution, device 14769114402SruThere are @var{n}@tie{}machine units per inch. 1477069626Sru 1477155839Sasmodai@item hor @var{n} 1477269626Sru@kindex hor 14773114402Sru@cindex horizontal resolution 14774114402Sru@cindex resolution, horizontal 14775114402SruThe horizontal resolution is @var{n}@tie{}machine units. All horizontal 14776114402Sruquantities are rounded to be multiples of this value. 1477769626Sru 1477855839Sasmodai@item vert @var{n} 1477969626Sru@kindex vert 14780114402Sru@cindex vertical resolution 14781114402Sru@cindex resolution, vertical 14782114402SruThe vertical resolution is @var{n}@tie{}machine units. All vertical 14783114402Sruquantities are rounded to be multiples of this value. 1478469626Sru 1478555839Sasmodai@item sizescale @var{n} 1478669626Sru@kindex sizescale 14787114402SruThe scale factor for point sizes. By default this has a value of@tie{}1. 1478869626SruOne scaled point is equal to one point/@var{n}. The arguments to the 1478955839Sasmodai@code{unitwidth} and @code{sizes} commands are given in scaled points. 1479055839Sasmodai@xref{Fractional Type Sizes}, for more information. 1479169626Sru 1479255839Sasmodai@item unitwidth @var{n} 1479369626Sru@kindex unitwidth 1479469626SruQuantities in the font files are given in machine units for fonts whose 14795114402Srupoint size is @var{n}@tie{}scaled points. 1479669626Sru 14797104862Sru@item prepro @var{program} 14798104862Sru@kindex prepro 14799104862SruCall @var{program} as a preprocessor. Currently, this keyword is used 14800104862Sruby @code{groff} with option @option{-Thtml} only. 14801104862Sru 14802104862Sru@item postpro @var{program} 14803104862Sru@kindex postpro 14804104862SruCall @var{program} as a postprocessor. For example, the line 14805104862Sru 14806104862Sru@Example 14807104862Srupostpro grodvi 14808104862Sru@endExample 14809104862Sru 14810104862Sru@noindent 14811104862Sruin the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} 14812104862Sruif option @option{-Tdvi} is given (and @option{-Z} isn't used). 14813104862Sru 1481455839Sasmodai@item tcommand 1481569626Sru@kindex tcommand 1481669626SruThis means that the postprocessor can handle the @samp{t} and @samp{u} 14817104862Sruintermediate output commands. 1481869626Sru 1481969626Sru@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 1482069626Sru@kindex sizes 1482169626SruThis means that the device has fonts at @var{s1}, @var{s2}, @dots{} 14822114402Sru@var{sn} scaled points. The list of sizes must be terminated by@tie{}0 14823104862Sru(this is digit zero). Each @var{si} can also be a range of sizes 14824104862Sru@var{m}-@var{n}. The list can extend over more than one line. 1482569626Sru 1482669626Sru@item styles @var{S1} @var{S2} @dots{} @var{Sm} 1482769626Sru@kindex styles 14828114402SruThe first @var{m}@tie{}font positions are associated with styles 1482969626Sru@var{S1} @dots{} @var{Sm}. 1483069626Sru 1483169626Sru@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 1483269626Sru@kindex fonts 1483375584SruFonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 1483469626Sru@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 1483569626Srustyles. This command may extend over more than one line. A font name 14836114402Sruof@tie{}0 means no font is mounted on the corresponding font position. 1483769626Sru 1483855839Sasmodai@item family @var{fam} 1483969626Sru@kindex family 1484055839SasmodaiThe default font family is @var{fam}. 1484169626Sru 14842104862Sru@item use_charnames_in_special 14843104862Sru@kindex use_charnames_in_special 14844104862SruThis command indicates that @code{gtroff} should encode special 14845104862Srucharacters inside special commands. Currently, this is only used 14846104862Sruby the @acronym{HTML} output device. @xref{Postprocessor Access}. 14847104862Sru 14848104862Sru@item papersize @var{string} @dots{} 14849104862Sru@kindex papersize 14850104862SruSelect a paper size. Valid values for @var{string} are the ISO paper 14851104862Srutypes @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7}, 14852104862Sru@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter}, 14853104862Sru@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, 14854104862Sru@code{executive}, @code{com10}, and @code{monarch}. Case is not significant 14855104862Srufor @var{string} if it holds predefined paper types. Alternatively, 14856104862Sru@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file 14857104862Srucan be opened, @code{groff} reads the first line and tests for the above 14858104862Srupaper sizes. Finally, @var{string} can be a custom paper size in the format 14859104862Sru@code{@var{length},@var{width}} (no spaces before and after the comma). 14860104862SruBoth @var{length} and @var{width} must have a unit appended; valid values 14861104862Sruare @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and 14862104862Sru@samp{P} for picas. Example: @code{12c,235p}. An argument which starts 14863104862Sruwith a digit is always treated as a custom paper format. @code{papersize} 14864104862Srusets both the vertical and horizontal dimension of the output medium. 14865104862Sru 14866104862SruMore than one argument can be specified; @code{groff} scans from left to 14867104862Sruright and uses the first valid paper specification. 14868104862Sru 14869104862Sru@item pass_filenames 14870104862Sru@kindex pass_filenames 14871104862SruTell @code{gtroff} to emit the name of the source file currently 14872104862Srubeing processed. This is achieved by the intermediate output command 14873104862Sru@samp{F}. Currently, this is only used by the @acronym{HTML} output 14874104862Srudevice. 14875104862Sru 14876104862Sru@item print @var{program} 14877104862Sru@kindex print 14878104862SruUse @var{program} as a spooler program for printing. If omitted, 14879104862Sruthe @option{-l} and @option{-L} options of @code{groff} are ignored. 14880104862Sru 1488155839Sasmodai@item charset 1488269626Sru@kindex charset 1488355839SasmodaiThis line and everything following in the file are ignored. It is 1488455839Sasmodaiallowed for the sake of backwards compatibility. 1488555839Sasmodai@end table 1488655839Sasmodai 14887104862SruThe @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines 1488869626Sruare mandatory. Other commands are ignored by @code{gtroff} but may be 1488969626Sruused by postprocessors to store arbitrary information about the device 1489069626Sruin the @file{DESC} file. 1489155839Sasmodai 14892104862Sru@kindex spare1 14893104862Sru@kindex spare2 14894104862Sru@kindex biggestfont 14895104862SruHere a list of obsolete keywords which are recognized by @code{groff} 14896104862Srubut completely ignored: @code{spare1}, @code{spare2}, 14897104862Sru@code{biggestfont}. 1489855839Sasmodai 1489969626Sru@c --------------------------------------------------------------------- 1490069626Sru 1490175584Sru@node Font File Format, , DESC File Format, Font Files 1490275584Sru@subsection Font File Format 14903104862Sru@cindex font file, format 14904104862Sru@cindex font description file, format 1490569626Sru@cindex format of font files 14906104862Sru@cindex format of font description files 1490755839Sasmodai 14908104862SruA @dfn{font file}, also (and probably better) called a @dfn{font 14909104862Srudescription file}, has two sections. The first section is a sequence 14910104862Sruof lines each containing a sequence of blank delimited words; the first 14911104862Sruword in the line is a key, and subsequent words give a value for that 14912104862Srukey. 1491355839Sasmodai 1491455839Sasmodai@table @code 1491569626Sru@item name @var{f} 1491669626Sru@kindex name 14917114402SruThe name of the font is@tie{}@var{f}. 1491869626Sru 1491955839Sasmodai@item spacewidth @var{n} 1492069626Sru@kindex spacewidth 14921114402SruThe normal width of a space is@tie{}@var{n}. 1492269626Sru 1492355839Sasmodai@item slant @var{n} 1492469626Sru@kindex slant 14925114402SruThe glyphs of the font have a slant of @var{n}@tie{}degrees. 1492655839Sasmodai(Positive means forward.) 1492769626Sru 1492869626Sru@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 1492969626Sru@kindex ligatures 14930104862SruGlyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 1493169626Srupossible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 1493269626Sru@samp{ffl}. For backwards compatibility, the list of ligatures may be 14933114402Sruterminated with a@tie{}0. The list of ligatures may not extend over more 1493469626Sruthan one line. 1493569626Sru 1493655839Sasmodai@item special 14937104862Sru@cindex special fonts 1493869626Sru@kindex special 14939104862SruThe font is @dfn{special}; this means that when a glyph is requested 14940104862Sruthat is not present in the current font, it is searched for in any 1494155839Sasmodaispecial fonts that are mounted. 1494255839Sasmodai@end table 1494355839Sasmodai 1494469626SruOther commands are ignored by @code{gtroff} but may be used by 1494569626Srupostprocessors to store arbitrary information about the font in the font 1494669626Srufile. 1494755839Sasmodai 1494869626Sru@cindex comments in font files 1494969626Sru@cindex font files, comments 1495069626Sru@kindex # 1495169626SruThe first section can contain comments which start with the @samp{#} 1495269626Srucharacter and extend to the end of a line. 1495355839Sasmodai 1495455839SasmodaiThe second section contains one or two subsections. It must contain a 1495555839Sasmodai@code{charset} subsection and it may also contain a @code{kernpairs} 1495655839Sasmodaisubsection. These subsections can appear in any order. Each 1495755839Sasmodaisubsection starts with a word on a line by itself. 1495855839Sasmodai 1495969626Sru@kindex charset 14960104862SruThe word @code{charset} starts the character set 14961104862Srusubsection.@footnote{This keyword is misnamed since it starts a list 14962104862Sruof ordered glyphs, not characters.} The @code{charset} line is 14963104862Srufollowed by a sequence of lines. Each line gives information for one 14964104862Sruglyph. A line comprises a number of fields separated by blanks or 14965104862Srutabs. The format is 1496655839Sasmodai 14967104862Sru@quotation 14968104862Sru@var{name} @var{metrics} @var{type} @var{code} 14969104862Sru[@var{entity-name}] [@code{--} @var{comment}] 14970104862Sru@end quotation 1497169626Sru 1497269626Sru@cindex 8-bit input 1497369626Sru@cindex input, 8-bit 14974104862Sru@cindex accessing unnamed glyphs with @code{\N} 14975104862Sru@cindex unnamed glyphs, accessing with @code{\N} 14976104862Sru@cindex characters, unnamed, accessing with @code{\N} 14977104862Sru@cindex glyphs, unnamed, accessing with @code{\N} 1497869626Sru@kindex --- 1497969626Sru@noindent 14980104862Sru@var{name} identifies the glyph name@footnote{The distinction between 14981104862Sruinput, characters, and output, glyphs, is not clearly separated in the 14982104862Sruterminology of @code{groff}; for example, the @code{char} request 14983104862Srushould be called @code{glyph} since it defines an output entity.}: 14984114402SruIf @var{name} is a single character@tie{}@var{c} then it corresponds 14985114402Sruto the @code{gtroff} input character@tie{}@var{c}; if it is of the form 14986104862Sru@samp{\@var{c}} where @var{c} is a single character, then it 14987104862Srucorresponds to the special character @code{\[@var{c}]}; otherwise it 14988104862Srucorresponds to the special character @samp{\[@var{name}]}. If it 14989104862Sruis exactly two characters @var{xx} it can be entered as 14990104862Sru@samp{\(@var{xx}}. Note that single-letter special characters can't 14991104862Srube accessed as @samp{\@var{c}}; the only exception is @samp{\-} which 14992104862Sruis identical to @code{\[-]}. 1499355839Sasmodai 14994104862Sru@code{gtroff} supports 8-bit input characters; however some utilities 14995104862Sruhave difficulties with eight-bit characters. For this reason, there is 14996104862Srua convention that the entity name @samp{char@var{n}} is equivalent to 14997114402Sruthe single input character whose code is@tie{}@var{n}. For example, 14998114402Sru@samp{char163} would be equivalent to the character with code@tie{}163 14999114402Sruwhich is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set. 15000104862SruYou shouldn't use @samp{char@var{n}} entities in font description files 15001104862Srusince they are related to input, not output. Otherwise, you get 15002104862Sruhard-coded connections between input and output encoding which 15003104862Sruprevents use of different (input) character sets. 1500469626Sru 15005104862SruThe name @samp{---} is special and indicates that the glyph is 15006104862Sruunnamed; such glyphs can only be used by means of the @code{\N} 15007104862Sruescape sequence in @code{gtroff}. 1500855839Sasmodai 15009104862SruThe @var{type} field gives the glyph type: 15010104862Sru 1501155839Sasmodai@table @code 1501255839Sasmodai@item 1 15013104862Sruthe glyph has a descender, for example, @samp{p}; 1501469626Sru 1501555839Sasmodai@item 2 15016104862Sruthe glyph has an ascender, for example, @samp{b}; 1501769626Sru 1501855839Sasmodai@item 3 15019104862Sruthe glyph has both an ascender and a descender, for example, @samp{(}. 1502055839Sasmodai@end table 1502155839Sasmodai 1502255839SasmodaiThe @var{code} field gives the code which the postprocessor uses to 15023104862Sruprint the glyph. The glyph can also be input to @code{gtroff} 15024104862Sruusing this code by means of the @code{\N} escape sequence. @var{code} 15025104862Srucan be any integer. If it starts with @samp{0} it is interpreted as 1502675584Sruoctal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 15027104862Sruhexadecimal. Note, however, that the @code{\N} escape sequence only 15028104862Sruaccepts a decimal integer. 1502955839Sasmodai 15030104862SruThe @var{entity-name} field gives an @acronym{ASCII} string 15031104862Sruidentifying the glyph which the postprocessor uses to print the 15032104862Sru@code{gtroff} glyph @var{name}. This field is optional and has been 15033104862Sruintroduced so that the @acronym{HTML} device driver can encode its 15034104862Srucharacter set. For example, the glyph @samp{\[Po]} is 15035104862Srurepresented as @samp{£} in @acronym{HTML} 4.0. 1503655839Sasmodai 15037104862SruAnything on the line after the @var{entity-name} field resp.@: after 15038104862Sru@samp{--} will be ignored. 15039104862Sru 1504055839SasmodaiThe @var{metrics} field has the form: 1504155839Sasmodai 15042104862Sru@display 15043104862Sru@group 15044104862Sru@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction} 15045104862Sru [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]] 15046104862Sru@end group 15047104862Sru@end display 1504855839Sasmodai 1504969626Sru@noindent 1505069626SruThere must not be any spaces between these subfields (it has been split 1505169626Sruhere into two lines for better legibility only). Missing subfields are 15052114402Sruassumed to be@tie{}0. The subfields are all decimal integers. Since 1505369626Sruthere is no associated binary format, these values are not required to 1505469626Srufit into a variable of type @samp{char} as they are in @code{ditroff}. 15055104862SruThe @var{width} subfield gives the width of the glyph. The @var{height} 15056104862Srusubfield gives the height of the glyph (upwards is positive); if a 15057104862Sruglyph does not extend above the baseline, it should be given a zero 15058104862Sruheight, rather than a negative height. The @var{depth} subfield gives 15059104862Sruthe depth of the glyph, that is, the distance from the baseline to the 15060104862Srulowest point below the baseline to which the glyph extends (downwards is 15061104862Srupositive); if a glyph does not extend below the baseline, it should be 15062104862Srugiven a zero depth, rather than a negative depth. The 15063104862Sru@var{italic-correction} subfield gives the amount of space that should 15064104862Srube added after the glyph when it is immediately to be followed by a 15065104862Sruglyph from a roman font. The @var{left-italic-correction} subfield 15066104862Srugives the amount of space that should be added before the glyph when it 15067104862Sruis immediately to be preceded by a glyph from a roman font. The 15068104862Sru@var{subscript-correction} gives the amount of space that should be 15069104862Sruadded after a glyph before adding a subscript. This should be less 1507055839Sasmodaithan the italic correction. 1507155839Sasmodai 1507255839SasmodaiA line in the @code{charset} section can also have the format 1507355839Sasmodai 1507475584Sru@Example 1507555839Sasmodai@var{name} " 1507675584Sru@endExample 1507755839Sasmodai 1507869626Sru@noindent 15079104862SruThis indicates that @var{name} is just another name for the glyph 1508055839Sasmodaimentioned in the preceding line. 1508155839Sasmodai 1508269626Sru@kindex kernpairs 1508355839SasmodaiThe word @code{kernpairs} starts the kernpairs section. This contains a 1508455839Sasmodaisequence of lines of the form: 1508555839Sasmodai 1508675584Sru@Example 1508769626Sru@var{c1} @var{c2} @var{n} 1508875584Sru@endExample 1508955839Sasmodai 1509075584Sru@noindent 15091104862SruThis means that when glyph @var{c1} appears next to glyph @var{c2} 15092114402Sruthe space between them should be increased by@tie{}@var{n}. Most 15093114402Sruentries in the kernpairs section have a negative value for@tie{}@var{n}. 1509455839Sasmodai 1509555839Sasmodai 1509655839Sasmodai 1509769626Sru@c ===================================================================== 1509869626Sru@c ===================================================================== 1509969626Sru 15100104862Sru@node Installation, Copying This Manual, File formats, Top 1510155839Sasmodai@chapter Installation 1510255839Sasmodai@cindex installation 1510355839Sasmodai 1510469626Sru@c XXX 1510555839Sasmodai 1510655839Sasmodai 1510755839Sasmodai 1510869626Sru@c ===================================================================== 1510969626Sru@c ===================================================================== 1511069626Sru 15111104862Sru@node Copying This Manual, Request Index, Installation, Top 15112104862Sru@appendix Copying This Manual 1511369626Sru 15114104862Sru@menu 15115104862Sru* GNU Free Documentation License:: License for copying this manual. 15116104862Sru@end menu 15117104862Sru 15118104862Sru@include fdl.texi 15119104862Sru 15120104862Sru 15121104862Sru 15122104862Sru@c ===================================================================== 15123104862Sru@c ===================================================================== 15124104862Sru 15125104862Sru@node Request Index, Escape Index, Copying This Manual, Top 15126104862Sru@appendix Request Index 15127104862Sru 1512875584SruRequests appear without the leading control character (normally either 1512975584Sru@samp{.} or @samp{'}). 1513069626Sru 1513175584Sru@printindex rq 1513255839Sasmodai 1513355839Sasmodai 1513469626Sru 1513569626Sru@c ===================================================================== 1513669626Sru@c ===================================================================== 1513769626Sru 1513875584Sru@node Escape Index, Operator Index, Request Index, Top 15139104862Sru@appendix Escape Index 1514075584Sru 15141104862SruAny escape sequence @code{\@var{X}} with @var{X} not in the list below 15142104862Sruemits a warning, printing glyph @var{X}. 15143104862Sru 1514475584Sru@printindex es 1514575584Sru 1514675584Sru 1514775584Sru 1514875584Sru@c ===================================================================== 1514975584Sru@c ===================================================================== 1515075584Sru 1515175584Sru@node Operator Index, Register Index, Escape Index, Top 15152104862Sru@appendix Operator Index 1515369626Sru 1515469626Sru@printindex op 1515569626Sru 1515669626Sru 1515769626Sru 1515869626Sru@c ===================================================================== 1515969626Sru@c ===================================================================== 1516069626Sru 1516175584Sru@node Register Index, Macro Index, Operator Index, Top 15162104862Sru@appendix Register Index 1516355839Sasmodai 15164104862SruThe macro package or program a specific register belongs to is appended in 15165104862Srubrackets. 15166104862Sru 15167114402SruA register name@tie{}@code{x} consisting of exactly one character can be 15168104862Sruaccessed as @samp{\nx}. A register name @code{xx} consisting of exactly 15169104862Srutwo characters can be accessed as @samp{\n(xx}. Register names @code{xxx} 15170104862Sruof any length can be accessed as @samp{\n[xxx]}. 15171104862Sru 1517255839Sasmodai@printindex vr 1517355839Sasmodai 1517455839Sasmodai 1517555839Sasmodai 1517669626Sru@c ===================================================================== 1517769626Sru@c ===================================================================== 1517855839Sasmodai 1517975584Sru@node Macro Index, String Index, Register Index, Top 15180104862Sru@appendix Macro Index 1518155839Sasmodai 15182104862SruThe macro package a specific macro belongs to is appended in brackets. 15183104862SruThey appear without the leading control character (normally @samp{.}). 15184104862Sru 1518569626Sru@printindex ma 1518655839Sasmodai 1518755839Sasmodai 1518855839Sasmodai 1518969626Sru@c ===================================================================== 1519069626Sru@c ===================================================================== 1519169626Sru 1519275584Sru@node String Index, Glyph Name Index, Macro Index, Top 15193104862Sru@appendix String Index 1519475584Sru 15195104862SruThe macro package or program a specific string belongs to is appended in 15196104862Srubrackets. 15197104862Sru 15198114402SruA string name@tie{}@code{x} consisting of exactly one character can be 15199104862Sruaccessed as @samp{\*x}. A string name @code{xx} consisting of exactly 15200104862Srutwo characters can be accessed as @samp{\*(xx}. String names @code{xxx} 15201104862Sruof any length can be accessed as @samp{\*[xxx]}. 15202104862Sru 15203104862Sru 1520475584Sru@printindex st 1520575584Sru 1520675584Sru 1520775584Sru 1520875584Sru@c ===================================================================== 1520975584Sru@c ===================================================================== 1521075584Sru 1521175584Sru@node Glyph Name Index, Font File Keyword Index, String Index, Top 15212104862Sru@appendix Glyph Name Index 1521369626Sru 1521469626SruA glyph name @code{xx} consisting of exactly two characters can be 1521569626Sruaccessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 1521669626Sruaccessed as @samp{\[xxx]}. 1521769626Sru 15218104862Sru@c XXX 1521969626Sru 1522069626Sru 1522169626Sru 1522269626Sru@c ===================================================================== 1522369626Sru@c ===================================================================== 1522469626Sru 1522569626Sru@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 15226104862Sru@appendix Font File Keyword Index 1522769626Sru 1522869626Sru@printindex ky 1522969626Sru 1523069626Sru 1523169626Sru 1523269626Sru@c ===================================================================== 1523369626Sru@c ===================================================================== 1523469626Sru 1523569626Sru@node Program and File Index, Concept Index, Font File Keyword Index, Top 15236104862Sru@appendix Program and File Index 1523769626Sru 1523855839Sasmodai@printindex pg 1523955839Sasmodai 1524055839Sasmodai 1524155839Sasmodai 1524269626Sru@c ===================================================================== 1524369626Sru@c ===================================================================== 1524469626Sru 1524569626Sru@node Concept Index, , Program and File Index, Top 15246104862Sru@appendix Concept Index 1524755839Sasmodai 1524855839Sasmodai@printindex cp 1524955839Sasmodai 1525055839Sasmodai 1525155839Sasmodai@bye 15252