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 7151497Sru@c You need texinfo 4.6 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 17151497Sru@documentlanguage en 18151497Sru@documentencoding ISO-8859-1 1955839Sasmodai 20151497Sru 21104862Sru@smallbook 22104862Sru 23104862Sru@finalout 24104862Sru 25104862Sru 26104862Sru@copying 27151497SruThis manual documents GNU @code{troff} version 1.19.2. 28104862Sru 29151497SruCopyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005 30114402SruFree Software Foundation, Inc. 31104862Sru 32104862Sru@quotation 33104862SruPermission is granted to copy, distribute and/or modify this document 34104862Sruunder the terms of the GNU Free Documentation License, Version 1.1 or 35104862Sruany later version published by the Free Software Foundation; with no 36104862SruInvariant Sections, with the Front-Cover texts being `A GNU Manual,'' 37104862Sruand with the Back-Cover Texts as in (a) below. A copy of the 38104862Srulicense is included in the section entitled `GNU Free Documentation 39104862SruLicense.'' 40104862Sru 41104862Sru(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 42104862Sruthis GNU Manual, like GNU software. Copies published by the Free 43104862SruSoftware Foundation raise funds for GNU development.'' 44104862Sru@end quotation 45104862Sru@end copying 46104862Sru 47104862Sru 4869626Sru@c We use the following indices: 4969626Sru@c 5069626Sru@c cindex: concepts 5175584Sru@c rqindex: requests 5275584Sru@c esindex: escapes 5369626Sru@c vindex: registers 5469626Sru@c kindex: commands in font files 5569626Sru@c pindex: programs and files 5669626Sru@c tindex: environment variables 5775584Sru@c maindex: macros 5875584Sru@c stindex: strings 5969626Sru@c opindex: operators 6069626Sru@c 6169626Sru@c tindex and cindex are merged. 6269626Sru 6375584Sru@defcodeindex rq 6475584Sru@defcodeindex es 6569626Sru@defcodeindex ma 6675584Sru@defcodeindex st 6769626Sru@defcodeindex op 6869626Sru@syncodeindex tp cp 6969626Sru 7069626Sru 71114402Sru@c To avoid uppercasing in @deffn while converting to info, we define 72114402Sru@c our special @Var{}. 7375584Sru 7475584Sru@macro Var{arg} 75151497Sru@r{@slanted{\arg\}} 7669626Sru@end macro 7769626Sru 7875584Sru 79104862Sru@c To assure correct HTML translation, some ugly hacks are necessary. 80104862Sru@c While processing a @def... request, the HTML translator looks at the 81104862Sru@c next line to decide whether it should start indentation or not. If 82104862Sru@c it is something starting with @def... (e.g. @deffnx), it doesn't. 83104862Sru@c So we must assure during macro expansion that a @def... is seen. 84104862Sru@c 85104862Sru@c The following macros have to be used: 86104862Sru@c 87104862Sru@c One item: 88104862Sru@c 89104862Sru@c @Def... 90104862Sru@c 91104862Sru@c Two items: 92104862Sru@c 93104862Sru@c @Def...List 94104862Sru@c @Def...ListEnd 95104862Sru@c 96104862Sru@c More than two: 97104862Sru@c 98104862Sru@c @Def...List 99104862Sru@c @Def...Item 100104862Sru@c @Def...Item 101104862Sru@c ... 102104862Sru@c @Def...ListEnd 103104862Sru@c 104104862Sru@c The definition block must end with 105104862Sru@c 106104862Sru@c @endDef... 107104862Sru@c 108114402Sru@c The above is valid for texinfo 4.0f and above. 109104862Sru 110104862Sru 111104862Sru@c a dummy macro to assure the `@def...' 112104862Sru 113104862Sru@macro defdummy 114151497Sru@c 115104862Sru@end macro 116104862Sru 117104862Sru 11875584Sru@c definition of requests 11975584Sru 12075584Sru@macro Defreq{name, arg} 121104862Sru@deffn Request @t{.\name\} \arg\ 12275584Sru@rqindex \name\ 123151497Sru@c 124104862Sru@end macro 125104862Sru 126104862Sru@macro DefreqList{name, arg} 12775584Sru@deffn Request @t{.\name\} \arg\ 128104862Sru@defdummy 129104862Sru@rqindex \name\ 130151497Sru@c 13175584Sru@end macro 13275584Sru 133104862Sru@macro DefreqItem{name, arg} 134104862Sru@deffnx Request @t{.\name\} \arg\ 135104862Sru@defdummy 13675584Sru@rqindex \name\ 137151497Sru@c 138104862Sru@end macro 139104862Sru 140104862Sru@macro DefreqListEnd{name, arg} 14175584Sru@deffnx Request @t{.\name\} \arg\ 142104862Sru@rqindex \name\ 143151497Sru@c 14475584Sru@end macro 14575584Sru 14675584Sru@macro endDefreq 14769626Sru@end deffn 14869626Sru@end macro 14969626Sru 15075584Sru 15175584Sru@c definition of escapes 15275584Sru 15375584Sru@macro Defesc{name, delimI, arg, delimII} 154114402Sru@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 15575584Sru@esindex \name\ 156151497Sru@c 157104862Sru@end macro 158104862Sru 159104862Sru@macro DefescList{name, delimI, arg, delimII} 160114402Sru@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 161104862Sru@defdummy 162104862Sru@esindex \name\ 163151497Sru@c 16469626Sru@end macro 16569626Sru 166104862Sru@macro DefescItem{name, delimI, arg, delimII} 167114402Sru@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 168104862Sru@defdummy 16975584Sru@esindex \name\ 170151497Sru@c 171104862Sru@end macro 172104862Sru 173104862Sru@macro DefescListEnd{name, delimI, arg, delimII} 174114402Sru@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 175104862Sru@esindex \name\ 176151497Sru@c 17769626Sru@end macro 17869626Sru 17975584Sru@macro endDefesc 18075584Sru@end deffn 18175584Sru@end macro 18275584Sru 18375584Sru 18475584Sru@c definition of registers 18575584Sru 18675584Sru@macro Defreg{name} 187104862Sru@deffn Register @t{\\n[\name\]} 18875584Sru@vindex \name\ 189151497Sru@c 190104862Sru@end macro 191104862Sru 192104862Sru@macro DefregList{name} 19375584Sru@deffn Register @t{\\n[\name\]} 194104862Sru@defdummy 195104862Sru@vindex \name\ 196151497Sru@c 19775584Sru@end macro 19875584Sru 199104862Sru@macro DefregItem{name} 200104862Sru@deffnx Register @t{\\n[\name\]} 201104862Sru@defdummy 20275584Sru@vindex \name\ 203151497Sru@c 204104862Sru@end macro 205104862Sru 206104862Sru@macro DefregListEnd{name} 20775584Sru@deffnx Register @t{\\n[\name\]} 208104862Sru@vindex \name\ 209151497Sru@c 21075584Sru@end macro 21175584Sru 21275584Sru@macro endDefreg 21375584Sru@end deffn 21475584Sru@end macro 21575584Sru 21675584Sru 217104862Sru@c definition of registers specific to macro packages, preprocessors, etc. 218104862Sru 219104862Sru@macro Defmpreg{name, package} 220104862Sru@deffn Register @t{\\n[\name\]} 221104862Sru@vindex \name\ @r{[}\package\@r{]} 222151497Sru@c 223104862Sru@end macro 224104862Sru 225104862Sru@macro DefmpregList{name, package} 226104862Sru@deffn Register @t{\\n[\name\]} 227104862Sru@defdummy 228104862Sru@vindex \name\ @r{[}\package\@r{]} 229151497Sru@c 230104862Sru@end macro 231104862Sru 232104862Sru@macro DefmpregItem{name, package} 233104862Sru@deffnx Register @t{\\n[\name\]} 234104862Sru@defdummy 235104862Sru@vindex \name\ @r{[}\package\@r{]} 236151497Sru@c 237104862Sru@end macro 238104862Sru 239104862Sru@macro DefmpregListEnd{name, package} 240104862Sru@deffnx Register @t{\\n[\name\]} 241104862Sru@vindex \name\ @r{[}\package\@r{]} 242151497Sru@c 243104862Sru@end macro 244104862Sru 245104862Sru@macro endDefmpreg 246104862Sru@end deffn 247104862Sru@end macro 248104862Sru 249104862Sru 25075584Sru@c definition of macros 25175584Sru 252104862Sru@macro Defmac{name, arg, package} 25375584Sru@defmac @t{.\name\} \arg\ 254104862Sru@maindex \name\ @r{[}\package\@r{]} 255151497Sru@c 25669626Sru@end macro 25769626Sru 258104862Sru@macro DefmacList{name, arg, package} 259104862Sru@defmac @t{.\name\} \arg\ 260104862Sru@defdummy 261104862Sru@maindex \name\ @r{[}\package\@r{]} 262151497Sru@c 263104862Sru@end macro 264104862Sru 265104862Sru@macro DefmacItem{name, arg, package} 26675584Sru@defmacx @t{.\name\} \arg\ 267104862Sru@defdummy 268104862Sru@maindex \name\ @r{[}\package\@r{]} 269151497Sru@c 27075584Sru@end macro 27175584Sru 272104862Sru@macro DefmacListEnd{name, arg, package} 273104862Sru@defmacx @t{.\name\} \arg\ 274104862Sru@maindex \name\ @r{[}\package\@r{]} 275151497Sru@c 276104862Sru@end macro 277104862Sru 27875584Sru@macro endDefmac 27969626Sru@end defmac 28069626Sru@end macro 28169626Sru 28275584Sru 28375584Sru@c definition of strings 28475584Sru 285104862Sru@macro Defstr{name, package} 286104862Sru@deffn String @t{\\*[\name\]} 287104862Sru@stindex \name\ @r{[}\package\@r{]} 288151497Sru@c 28969626Sru@end macro 29069626Sru 291104862Sru@macro DefstrList{name, package} 292104862Sru@deffn String @t{\\*[\name\]} 293104862Sru@defdummy 294104862Sru@stindex \name\ @r{[}\package\@r{]} 295151497Sru@c 29669626Sru@end macro 29769626Sru 298104862Sru@macro DefstrItem{name, package} 299104862Sru@deffnx String @t{\\*[\name\]} 300104862Sru@defdummy 301104862Sru@stindex \name\ @r{[}\package\@r{]} 302151497Sru@c 303104862Sru@end macro 304104862Sru 305104862Sru@macro DefstrListEnd{name, package} 306104862Sru@deffnx String @t{\\*[\name\]} 307104862Sru@stindex \name\ @r{[}\package\@r{]} 308151497Sru@c 309104862Sru@end macro 310104862Sru 31175584Sru@macro endDefstr 31275584Sru@end deffn 31375584Sru@end macro 31469626Sru 31575584Sru 31675584Sru@c our example macro 31775584Sru 31875584Sru@macro Example 31975584Sru@example 32075584Sru@group 32175584Sru@end macro 32275584Sru 32375584Sru@macro endExample 32475584Sru@end group 32575584Sru@end example 32675584Sru@end macro 32775584Sru 32875584Sru 329104862Sru@c <text> 330104862Sru 331104862Sru@tex 332151497Sru\gdef\Langlemacro{\angleleft} 333151497Sru\gdef\Ranglemacro{\angleright} 334104862Sru@end tex 335104862Sru 336151497Sru@iftex 337151497Sru@set Langlemacro @Langlemacro 338151497Sru@set Ranglemacro @Ranglemacro 339151497Sru@end iftex 340151497Sru 341151497Sru@ifnottex 342151497Sru@set Langlemacro < 343151497Sru@set Ranglemacro > 344151497Sru@end ifnottex 345151497Sru 346104862Sru@macro angles{text} 347151497Sru@value{Langlemacro}@r{\text\}@value{Ranglemacro} 348104862Sru@end macro 349104862Sru 350104862Sru 351104862Sru@c a <= sign 352151497Sru@c 353151497Sru@c A value defined with @set is embedded into three group levels if 354151497Sru@c called with @value, so we need seven \aftergroup to put \le outside 355151497Sru@c of the groups -- this is necessary to get proper mathematical spacing. 356104862Sru 357104862Sru@tex 358151497Sru\gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup 359151497Sru \aftergroup\aftergroup\aftergroup\le} 360104862Sru@end tex 361104862Sru 362151497Sru@iftex 363151497Sru@set LEmacro @LEmacro 364151497Sru@end iftex 365151497Sru 366151497Sru@ifnottex 367151497Sru@set LEmacro <= 368151497Sru@end ifnottex 369151497Sru 370104862Sru@macro LE 371151497Sru@value{LEmacro} 372104862Sru@end macro 373104862Sru 374104862Sru 375151497Sru@c We need special parentheses, brackets, and braces: 37675584Sru@c 37775584Sru@c . Real parentheses in @deffn produce an error while compiling with 378114402Sru@c TeX. 37975584Sru@c . Real brackets use the wrong font in @deffn, overriding @t{}. 38075584Sru@c 381151497Sru@c . @{ and @} fail with info if used in a macro. 382151497Sru@c 383104862Sru@c Since macros aren't expanded in @deffn during -E, the following 384104862Sru@c definitions are for non-TeX only. 385104862Sru@c 386151497Sru@c This is true for texinfo 4.0 and above. 38775584Sru 388151497Sru@iftex 389151497Sru@set Lparenmacro @lparen 390151497Sru@set Rparenmacro @rparen 391151497Sru@set Lbrackmacro @lbrack 392151497Sru@set Rbrackmacro @rbrack 393151497Sru@set Lbracemacro @{ 394151497Sru@set Rbracemacro @} 395151497Sru@end iftex 396151497Sru 397151497Sru@ifnottex 398151497Sru@set Lparenmacro ( 399151497Sru@set Rparenmacro ) 400151497Sru@set Lbrackmacro [ 401151497Sru@set Rbrackmacro ] 402151497Sru@set Lbracemacro @{ 403151497Sru@set Rbracemacro @} 404151497Sru@end ifnottex 405151497Sru 406151497Sru@macro Lparen{} 407151497Sru@value{Lparenmacro} 40875584Sru@end macro 409151497Sru@macro Rparen{} 410151497Sru@value{Rparenmacro} 41175584Sru@end macro 412151497Sru@macro Lbrack{} 413151497Sru@value{Lbrackmacro} 41475584Sru@end macro 415151497Sru@macro Rbrack{} 416151497Sru@value{Rbrackmacro} 41775584Sru@end macro 418151497Sru@macro Lbrace{} 419151497Sru@value{Lbracemacro} 420151497Sru@end macro 421151497Sru@macro Rbrace{} 422151497Sru@value{Rbracemacro} 423151497Sru@end macro 42475584Sru 42575584Sru 426151497Sru@c This suppresses the word `Appendix' in the appendix headers. 427151497Sru 428104862Sru@tex 429104862Sru\gdef\gobblefirst#1#2{#2} 430104862Sru\gdef\putwordAppendix{\gobblefirst} 431104862Sru@end tex 43275584Sru 433104862Sru 434151497Sru@c We map some latin-1 characters to corresponding texinfo macros. 435151497Sru 436151497Sru@tex 437151497Sru\global\catcode`^^e4\active % � 438151497Sru\gdef^^e4{\"a} 439151497Sru\global\catcode`^^c4\active % � 440151497Sru\gdef^^c4{\"A} 441151497Sru\global\catcode`^^e9\active % � 442151497Sru\gdef^^e9{\'e} 443151497Sru\global\catcode`^^c9\active % � 444151497Sru\gdef^^c9{\'E} 445151497Sru\global\catcode`^^f6\active % � 446151497Sru\gdef^^f6{\"o} 447151497Sru\global\catcode`^^d6\active % � 448151497Sru\gdef^^d6{\"O} 449151497Sru\global\catcode`^^fc\active % � 450151497Sru\gdef^^fc{\"u} 451151497Sru\global\catcode`^^dc\active % � 452151497Sru\gdef^^dc{\"U} 453151497Sru\global\catcode`^^e6\active % � 454151497Sru\gdef^^e6{\ae} 455151497Sru\global\catcode`^^c6\active % � 456151497Sru\gdef^^c6{\AE} 457151497Sru\global\catcode`^^df\active % � 458151497Sru\gdef^^df{\ss} 459151497Sru@end tex 460151497Sru 461151497Sru 46275584Sru@c Note: We say `Roman numerals' but `roman font'. 46375584Sru 46475584Sru 465114402Sru@dircategory Typesetting 46655839Sasmodai@direntry 467104862Sru* Groff: (groff). The GNU troff document formatting system. 46855839Sasmodai@end direntry 46955839Sasmodai 47055839Sasmodai 47155839Sasmodai@titlepage 47255839Sasmodai@title groff 47369626Sru@subtitle The GNU implementation of @code{troff} 474151497Sru@subtitle Edition 1.19.2 475151497Sru@subtitle Summer 2005 476114402Sru@author by Trent A.@tie{}Fisher 477104862Sru@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 47855839Sasmodai 47955839Sasmodai@page 48055839Sasmodai@vskip 0pt plus 1filll 481104862Sru@insertcopying 48255839Sasmodai@end titlepage 48355839Sasmodai 48455839Sasmodai 485104862Sru@contents 48655839Sasmodai 48755839Sasmodai@ifinfo 488104862Sru@node Top, Introduction, (dir), (dir) 489104862Sru@top GNU troff 49055839Sasmodai 491104862Sru@insertcopying 49255839Sasmodai@end ifinfo 49355839Sasmodai 494104862Sru@ifhtml 495151497Sru@menu 496151497Sru* Introduction:: 497151497Sru* Invoking groff:: 498151497Sru* Tutorial for Macro Users:: 499151497Sru* Macro Packages:: 500151497Sru* gtroff Reference:: 501151497Sru* Preprocessors:: 502151497Sru* Output Devices:: 503151497Sru* File formats:: 504151497Sru* Installation:: 505151497Sru* Copying This Manual:: 506151497Sru* Request Index:: 507151497Sru* Escape Index:: 508151497Sru* Operator Index:: 509151497Sru* Register Index:: 510151497Sru* Macro Index:: 511151497Sru* String Index:: 512151497Sru* Glyph Name Index:: 513151497Sru* Font File Keyword Index:: 514151497Sru* Program and File Index:: 515151497Sru* Concept Index:: 516151497Sru@end menu 517151497Sru 518104862Sru@node Top, Introduction, (dir), (dir) 519104862Sru@top GNU troff 520104862Sru 521104862Sru@insertcopying 522104862Sru@end ifhtml 523104862Sru 52455839Sasmodai@menu 52575584Sru* Introduction:: 52675584Sru* Invoking groff:: 52775584Sru* Tutorial for Macro Users:: 52875584Sru* Macro Packages:: 52975584Sru* gtroff Reference:: 53075584Sru* Preprocessors:: 53175584Sru* Output Devices:: 53275584Sru* File formats:: 53375584Sru* Installation:: 534104862Sru* Copying This Manual:: 53575584Sru* Request Index:: 53675584Sru* Escape Index:: 53775584Sru* Operator Index:: 53875584Sru* Register Index:: 53975584Sru* Macro Index:: 54075584Sru* String Index:: 54175584Sru* Glyph Name Index:: 54275584Sru* Font File Keyword Index:: 54375584Sru* Program and File Index:: 54475584Sru* Concept Index:: 54555839Sasmodai@end menu 54655839Sasmodai 54755839Sasmodai 54855839Sasmodai 54969626Sru@c ===================================================================== 55069626Sru@c ===================================================================== 55169626Sru 552104862Sru@node Introduction, Invoking groff, Top, Top 55355839Sasmodai@chapter Introduction 55455839Sasmodai@cindex introduction 55555839Sasmodai 55655839SasmodaiGNU @code{troff} (or @code{groff}) is a system for typesetting 55755839Sasmodaidocuments. @code{troff} is very flexible and has been in existence (and 558114402Sruuse) for about 3@tie{}decades. It is quite widespread and firmly 55969626Sruentrenched in the @acronym{UNIX} community. 56055839Sasmodai 56155839Sasmodai@menu 56275584Sru* What Is groff?:: 56375584Sru* History:: 56475584Sru* groff Capabilities:: 56575584Sru* Macro Package Intro:: 56675584Sru* Preprocessor Intro:: 56775584Sru* Output device intro:: 56875584Sru* Credits:: 56955839Sasmodai@end menu 57055839Sasmodai 57169626Sru 57269626Sru@c ===================================================================== 57369626Sru 57455839Sasmodai@node What Is groff?, History, Introduction, Introduction 57555839Sasmodai@section What Is @code{groff}? 57655839Sasmodai@cindex what is @code{groff}? 57755839Sasmodai@cindex @code{groff} -- what is it? 57855839Sasmodai 57969626Sru@code{groff} belongs to an older generation of document preparation 58069626Srusystems, which operate more like compilers than the more recent 58169626Sruinteractive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 58269626Srusystems. @code{groff} and its contemporary counterpart, @TeX{}, both 58369626Sruwork using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 58469626Srunormal text files with embedded formatting commands. These files can 58569626Sruthen be processed by @code{groff} to produce a typeset document on a 58669626Sruvariety of devices. 58755839Sasmodai 58855839SasmodaiLikewise, @code{groff} should not be confused with a @dfn{word 58975584Sruprocessor}, since that term connotes an integrated system that includes 59055839Sasmodaian editor and a text formatter. Also, many word processors follow the 59175584Sru@acronym{WYSIWYG} paradigm discussed earlier. 59255839Sasmodai 59369626SruAlthough @acronym{WYSIWYG} systems may be easier to use, they have a 59469626Srunumber of disadvantages compared to @code{troff}: 59555839Sasmodai 59669626Sru@itemize @bullet 59755839Sasmodai@item 59875584SruThey must be used on a graphics display to work on a document. 59969626Sru 60055839Sasmodai@item 60169626SruMost of the @acronym{WYSIWYG} systems are either non-free or are not 60269626Sruvery portable. 60369626Sru 60455839Sasmodai@item 60569626Sru@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 60669626Sru 60755839Sasmodai@item 60855839SasmodaiIt is difficult to have a wide range of capabilities available within 60955839Sasmodaithe confines of a GUI/window system. 61069626Sru 61155839Sasmodai@item 61255839SasmodaiIt is more difficult to make global changes to a document. 61355839Sasmodai@end itemize 61455839Sasmodai 61555839Sasmodai@quotation 61655839Sasmodai``GUIs normally make it simple to accomplish simple actions and 61755839Sasmodaiimpossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 61855839Sasmodai@code{comp.unix.wizards}) 61955839Sasmodai@end quotation 62055839Sasmodai 62155839Sasmodai 62269626Sru@c ===================================================================== 62355839Sasmodai 62455839Sasmodai@node History, groff Capabilities, What Is groff?, Introduction 62555839Sasmodai@section History 62655839Sasmodai@cindex history 62755839Sasmodai 628104862Sru@cindex @code{runoff}, the program 629104862Sru@cindex @code{rf}, the program 63055839Sasmodai@code{troff} can trace its origins back to a formatting program called 631114402Sru@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS 63269626Sruoperating system in the mid-sixties. This name came from the common 63369626Sruphrase of the time ``I'll run off a document.'' Bob Morris ported it to 63469626Sruthe 635 architecture and called the program @code{roff} (an abbreviation 63575584Sruof @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 63675584Sru(before having @acronym{UNIX}), and at the same time (1969), Doug 63769626SruMcIllroy rewrote an extended and simplified version of @code{roff} in 63869626Sruthe @acronym{BCPL} programming language. 63955839Sasmodai 640104862Sru@cindex @code{roff}, the program 64175584SruThe first version of @acronym{UNIX} was developed on a @w{PDP-7} which 64275584Sruwas sitting around Bell Labs. In 1971 the developers wanted to get a 64375584Sru@w{PDP-11} for further work on the operating system. In order to 64475584Srujustify the cost for this system, they proposed that they would 645104862Sruimplement a document formatting system for the @acronym{AT&T} patents 646104862Srudivision. This first formatting program was a reimplementation of 647114402SruMcIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna. 64855839Sasmodai 649104862Sru@cindex @code{nroff}, the program 65055839SasmodaiWhen they needed a more flexible language, a new version of @code{roff} 65169626Srucalled @code{nroff} (``Newer @code{roff}'') was written. It had a much 65269626Srumore complicated syntax, but provided the basis for all future versions. 65369626SruWhen they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 65475584Sruversion of @code{nroff} that would drive it. It was dubbed 65569626Sru@code{troff}, for ``typesetter @code{roff}'', although many people have 65669626Sruspeculated that it actually means ``Times @code{roff}'' because of the 65769626Sruuse of the Times font family in @code{troff} by default. As such, the 65869626Sruname @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 65955839Sasmodai 66055839SasmodaiWith @code{troff} came @code{nroff} (they were actually the same program 66169626Sruexcept for some @samp{#ifdef}s), which was for producing output for line 66269626Sruprinters and character terminals. It understood everything @code{troff} 66369626Srudid, and ignored the commands which were not applicable (e.g.@: font 66455839Sasmodaichanges). 66555839Sasmodai 66655839SasmodaiSince there are several things which cannot be done easily in 66755839Sasmodai@code{troff}, work on several preprocessors began. These programs would 66855839Sasmodaitransform certain parts of a document into @code{troff}, which made a 66969626Sruvery natural use of pipes in @acronym{UNIX}. 67055839Sasmodai 671151497SruThe @code{eqn} preprocessor allowed mathematical formul� to be 67255839Sasmodaispecified in a much simpler and more intuitive manner. @code{tbl} is a 67355839Sasmodaipreprocessor for formatting tables. The @code{refer} preprocessor (and 67455839Sasmodaithe similar program, @code{bib}) processes citations in a document 67555839Sasmodaiaccording to a bibliographic database. 67655839Sasmodai 67775584SruUnfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 67855839Sasmodailanguage and produced output specifically for the CAT phototypesetter. 679114402SruHe rewrote it in C, although it was now 7000@tie{}lines of uncommented 68055839Sasmodaicode and still dependent on the CAT. As the CAT became less common, and 68155839Sasmodaiwas no longer supported by the manufacturer, the need to make it support 68269626Sruother devices became a priority. However, before this could be done, 683104862SruOssanna was killed in a car accident. 68455839Sasmodai 68555839Sasmodai@pindex ditroff 686104862Sru@cindex @code{ditroff}, the program 68755839SasmodaiSo, Brian Kernighan took on the task of rewriting @code{troff}. The 688104862Srunewly rewritten version produced device independent code which was 68955839Sasmodaivery easy for postprocessors to read and translate to the appropriate 69055839Sasmodaiprinter codes. Also, this new version of @code{troff} (called 69169626Sru@code{ditroff} for ``device independent @code{troff}'') had several 69269626Sruextensions, which included drawing functions. 69355839Sasmodai 69455839SasmodaiDue to the additional abilities of the new version of @code{troff}, 69555839Sasmodaiseveral new preprocessors appeared. The @code{pic} preprocessor 69655839Sasmodaiprovides a wide range of drawing functions. Likewise the @code{ideal} 69755839Sasmodaipreprocessor did the same, although via a much different paradigm. The 69855839Sasmodai@code{grap} preprocessor took specifications for graphs, but, unlike 69955839Sasmodaiother preprocessors, produced @code{pic} code. 70055839Sasmodai 70155839SasmodaiJames Clark began work on a GNU implementation of @code{ditroff} in 702114402Sruearly@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released 703114402SruJune@tie{}1990. @code{groff} included: 70455839Sasmodai 70569626Sru@itemize @bullet 70655839Sasmodai@item 70769626SruA replacement for @code{ditroff} with many extensions. 70869626Sru 70955839Sasmodai@item 71055839SasmodaiThe @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 71169626Sru 71255839Sasmodai@item 71375584SruPostprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 714114402SruX@tie{}Windows. GNU @code{troff} also eliminated the need for a 71569626Sruseparate @code{nroff} program with a postprocessor which would produce 71669626Sru@acronym{ASCII} output. 71769626Sru 71855839Sasmodai@item 71969626SruA version of the @file{me} macros and an implementation of the 72069626Sru@file{man} macros. 72155839Sasmodai@end itemize 72255839Sasmodai 72355839SasmodaiAlso, a front-end was included which could construct the, sometimes 72455839Sasmodaipainfully long, pipelines required for all the post- and preprocessors. 72555839Sasmodai 72655839SasmodaiDevelopment of GNU @code{troff} progressed rapidly, and saw the 72755839Sasmodaiadditions of a replacement for @code{refer}, an implementation of the 72869626Sru@file{ms} and @file{mm} macros, and a program to deduce how to format a 72969626Srudocument (@code{grog}). 73055839Sasmodai 73169626SruIt was declared a stable (i.e.@: non-beta) package with the release of 732114402Sruversion@tie{}1.04 around November@tie{}1991. 73355839Sasmodai 734114402SruBeginning in@tie{}1999, @code{groff} has new maintainers (the package was 73569626Sruan orphan for a few years). As a result, new features and programs like 73675584Sru@code{grn}, a preprocessor for gremlin images, and an output device to 73775584Sruproduce @acronym{HTML} output have been added. 73855839Sasmodai 73955839Sasmodai 74069626Sru@c ===================================================================== 74169626Sru 74269626Sru@node groff Capabilities, Macro Package Intro, History, Introduction 74355839Sasmodai@section @code{groff} Capabilities 74455839Sasmodai@cindex @code{groff} capabilities 74555839Sasmodai@cindex capabilities of @code{groff} 74655839Sasmodai 74755839SasmodaiSo what exactly is @code{groff} capable of doing? @code{groff} provides 74869626Srua wide range of low-level text formatting operations. Using these, it 74969626Sruis possible to perform a wide range of formatting tasks, such as 75069626Srufootnotes, table of contents, multiple columns, etc. Here's a list of 75169626Sruthe most important operations supported by @code{groff}: 75255839Sasmodai 75369626Sru@itemize @bullet 75455839Sasmodai@item 75569626Srutext filling, adjusting, and centering 75669626Sru 75755839Sasmodai@item 75869626Sruhyphenation 75969626Sru 76055839Sasmodai@item 76169626Srupage control 76269626Sru 76355839Sasmodai@item 764104862Srufont and glyph size control 76569626Sru 76655839Sasmodai@item 767104862Sruvertical spacing (e.g.@: double-spacing) 76869626Sru 76955839Sasmodai@item 77069626Sruline length and indenting 77169626Sru 77255839Sasmodai@item 77369626Srumacros, strings, diversions, and traps 77469626Sru 77555839Sasmodai@item 77669626Srunumber registers 77769626Sru 77855839Sasmodai@item 77969626Srutabs, leaders, and fields 78069626Sru 78155839Sasmodai@item 78269626Sruinput and output conventions and character translation 78369626Sru 78455839Sasmodai@item 78569626Sruoverstrike, bracket, line drawing, and zero-width functions 78669626Sru 78755839Sasmodai@item 78869626Srulocal horizontal and vertical motions and the width function 78969626Sru 79055839Sasmodai@item 79169626Sruthree-part titles 79269626Sru 79355839Sasmodai@item 79469626Sruoutput line numbering 79569626Sru 79655839Sasmodai@item 79769626Sruconditional acceptance of input 79869626Sru 79955839Sasmodai@item 80069626Sruenvironment switching 80169626Sru 80255839Sasmodai@item 80369626Sruinsertions from the standard input 80469626Sru 80555839Sasmodai@item 80669626Sruinput/output file switching 80769626Sru 80855839Sasmodai@item 80969626Sruoutput and error messages 81055839Sasmodai@end itemize 81155839Sasmodai 81255839Sasmodai 81369626Sru@c ===================================================================== 81469626Sru 81569626Sru@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 81655839Sasmodai@section Macro Packages 81755839Sasmodai@cindex macro packages 81855839Sasmodai 81969626SruSince @code{groff} provides such low-level facilities, it can be quite 82055839Sasmodaidifficult to use by itself. However, @code{groff} provides a 821114402Sru@dfn{macro} facility to specify how certain routine operations 822114402Sru(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@: 823114402Srushould be done. These macros can be collected together into a @dfn{macro 82469626Srupackage}. There are a number of macro packages available; the most 82569626Srucommon (and the ones described in this manual) are @file{man}, 82669626Sru@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 82755839Sasmodai 82855839Sasmodai 82969626Sru@c ===================================================================== 83069626Sru 83169626Sru@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 83255839Sasmodai@section Preprocessors 83355839Sasmodai@cindex preprocessors 83455839Sasmodai 83555839SasmodaiAlthough @code{groff} provides most functions needed to format a 83669626Srudocument, some operations would be unwieldy (e.g.@: to draw pictures). 837104862SruTherefore, programs called @dfn{preprocessors} were written which 838104862Sruunderstand their own language and produce the necessary @code{groff} 839104862Sruoperations. These preprocessors are able to differentiate their own 840104862Sruinput from the rest of the document via markers. 84155839Sasmodai 84269626SruTo use a preprocessor, @acronym{UNIX} pipes are used to feed the output 84369626Srufrom the preprocessor into @code{groff}. Any number of preprocessors 84469626Srumay be used on a given document; in this case, the preprocessors are 845104862Srulinked together into one pipeline. However, with @code{groff}, the user 84669626Srudoes not need to construct the pipe, but only tell @code{groff} what 84755839Sasmodaipreprocessors to use. 84855839Sasmodai 84955839Sasmodai@code{groff} currently has preprocessors for producing tables 85055839Sasmodai(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 85169626Sru(@code{pic} and @code{grn}), and for processing bibliographies 85269626Sru(@code{refer}). An associated program which is useful when dealing with 85369626Srupreprocessors is @code{soelim}. 85455839Sasmodai 85569626SruA free implementation of @code{grap}, a preprocessor for drawing graphs, 85669626Srucan be obtained as an extra package; @code{groff} can use @code{grap} 85769626Srualso. 85855839Sasmodai 85969626SruThere are other preprocessors in existence, but, unfortunately, no free 86069626Sruimplementations are available. Among them are preprocessors for drawing 86169626Srumathematical pictures (@code{ideal}) and chemical structures 86269626Sru(@code{chem}). 86355839Sasmodai 86469626Sru 86569626Sru@c ===================================================================== 86669626Sru 86769626Sru@node Output device intro, Credits, Preprocessor Intro, Introduction 86869626Sru@section Output Devices 86955839Sasmodai@cindex postprocessors 87069626Sru@cindex output devices 87169626Sru@cindex devices for output 87255839Sasmodai 87375584Sru@code{groff} actually produces device independent code which may be 87475584Srufed into a postprocessor to produce output for a particular device. 87575584SruCurrently, @code{groff} has postprocessors for @sc{PostScript} 876114402Srudevices, character terminals, X@tie{}Windows (for previewing), @TeX{} 877114402SruDVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use 87869626Sru@acronym{CAPSL}), and @acronym{HTML}. 87955839Sasmodai 88055839Sasmodai 88169626Sru@c ===================================================================== 88269626Sru 88369626Sru@node Credits, , Output device intro, Introduction 88455839Sasmodai@section Credits 88555839Sasmodai@cindex credits 88655839Sasmodai 88755839SasmodaiLarge portions of this manual were taken from existing documents, most 88855839Sasmodainotably, the manual pages for the @code{groff} package by James Clark, 88969626Sruand Eric Allman's papers on the @file{me} macro package. 89055839Sasmodai 891114402SruThe section on the @file{man} macro package is partly based on 892114402SruSusan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the 893114402SruDebian GNU/Linux system. 89455839Sasmodai 895104862SruLarry Kollar contributed the section in the @file{ms} macro package. 89655839Sasmodai 89769626Sru 89875584Sru 89969626Sru@c ===================================================================== 90069626Sru@c ===================================================================== 90169626Sru 90255839Sasmodai@node Invoking groff, Tutorial for Macro Users, Introduction, Top 90355839Sasmodai@chapter Invoking @code{groff} 90455839Sasmodai@cindex invoking @code{groff} 90555839Sasmodai@cindex @code{groff} invocation 90655839Sasmodai 90755839SasmodaiThis section focuses on how to invoke the @code{groff} front end. This 90855839Sasmodaifront end takes care of the details of constructing the pipeline among 90955839Sasmodaithe preprocessors, @code{gtroff} and the postprocessor. 91055839Sasmodai 91169626SruIt has become a tradition that GNU programs get the prefix @samp{g} to 91269626Srudistinguish it from its original counterparts provided by the host (see 91369626Sru@ref{Environment}, for more details). Thus, for example, @code{geqn} is 914104862SruGNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 915104862Srudon't contain proprietary versions of @code{troff}, and on 916104862SruMS-DOS/MS-Windows, where @code{troff} and associated programs are not 917104862Sruavailable at all, this prefix is omitted since GNU @code{troff} is the 918104862Sruonly used incarnation of @code{troff}. Exception: @samp{groff} is never 919104862Srureplaced by @samp{roff}. 92055839Sasmodai 921104862SruIn this document, we consequently say @samp{gtroff} when talking about 922104862Sruthe GNU @code{troff} program. All other implementations of @code{troff} 923104862Sruare called @acronym{AT&T} @code{troff} which is the common origin of 924104862Sruall @code{troff} derivates (with more or less compatible changes). 925104862SruSimilarly, we say @samp{gpic}, @samp{geqn}, etc. 926104862Sru 92755839Sasmodai@menu 92875584Sru* Groff Options:: 92975584Sru* Environment:: 930104862Sru* Macro Directories:: 931104862Sru* Font Directories:: 932114402Sru* Paper Size:: 93375584Sru* Invocation Examples:: 93455839Sasmodai@end menu 93555839Sasmodai 93669626Sru 93769626Sru@c ===================================================================== 93869626Sru 93969626Sru@node Groff Options, Environment, Invoking groff, Invoking groff 94055839Sasmodai@section Options 94155839Sasmodai@cindex options 94255839Sasmodai 94355839Sasmodai@pindex groff 94455839Sasmodai@pindex gtroff 94555839Sasmodai@pindex gpic 94655839Sasmodai@pindex geqn 94769626Sru@pindex ggrn 94869626Sru@pindex grap 94955839Sasmodai@pindex gtbl 95055839Sasmodai@pindex grefer 95155839Sasmodai@pindex gsoelim 95269626Sru@code{groff} normally runs the @code{gtroff} program and a postprocessor 95369626Sruappropriate for the selected device. The default device is @samp{ps} 95469626Sru(but it can be changed when @code{groff} is configured and built). It 95569626Srucan optionally preprocess with any of @code{gpic}, @code{geqn}, 95669626Sru@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 95755839Sasmodai 95855839SasmodaiThis section only documents options to the @code{groff} front end. Many 95955839Sasmodaiof the arguments to @code{groff} are passed on to @code{gtroff}, 96055839Sasmodaitherefore those are also included. Arguments to pre- or postprocessors 96155839Sasmodaican be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 96269626Srugtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 96369626Srugsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 96469626Srugrohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 96569626Srugrolbp}, and @ref{Invoking gxditview}. 96655839Sasmodai 96755839SasmodaiThe command line format for @code{groff} is: 96855839Sasmodai 96975584Sru@Example 970104862Srugroff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 97155839Sasmodai [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 97255839Sasmodai [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 97369626Sru [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 97455839Sasmodai [ @var{files}@dots{} ] 97575584Sru@endExample 97655839Sasmodai 97769626SruThe command line format for @code{gtroff} is as follows. 97855839Sasmodai 97975584Sru@Example 980104862Srugtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 98155839Sasmodai [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 98255839Sasmodai [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 98355839Sasmodai [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 98475584Sru@endExample 98555839Sasmodai 98669626Sru@noindent 98775584SruObviously, many of the options to @code{groff} are actually passed on to 98875584Sru@code{gtroff}. 98955839Sasmodai 990114402SruOptions without an argument can be grouped behind a single@tie{}@option{-}. 991114402SruA filename of@tie{}@file{-} denotes the standard input. It is possible to 99269626Sruhave whitespace between an option and its parameter. 99369626Sru 99455839SasmodaiThe @code{grog} command can be used to guess the correct @code{groff} 99569626Srucommand to format a file. 99655839Sasmodai 99769626SruHere's the description of the command-line options: 99869626Sru 99969626Sru@cindex command-line options 100055839Sasmodai@table @samp 100155839Sasmodai@item -h 100255839SasmodaiPrint a help message. 100369626Sru 100455839Sasmodai@item -e 100555839SasmodaiPreprocess with @code{geqn}. 100669626Sru 100755839Sasmodai@item -t 100855839SasmodaiPreprocess with @code{gtbl}. 100969626Sru 101069626Sru@item -g 101169626SruPreprocess with @code{ggrn}. 101269626Sru 101369626Sru@item -G 101469626SruPreprocess with @code{grap}. 101569626Sru 101655839Sasmodai@item -p 101755839SasmodaiPreprocess with @code{gpic}. 101869626Sru 101955839Sasmodai@item -s 102055839SasmodaiPreprocess with @code{gsoelim}. 102169626Sru 1022104862Sru@item -c 1023104862SruSuppress color output. 1024104862Sru 102555839Sasmodai@item -R 102655839SasmodaiPreprocess with @code{grefer}. No mechanism is provided for passing 102755839Sasmodaiarguments to @code{grefer} because most @code{grefer} options have 102855839Sasmodaiequivalent commands which can be included in the file. @xref{grefer}, 102955839Sasmodaifor more details. 103055839Sasmodai 103155839Sasmodai@pindex troffrc 103269626Sru@pindex troffrc-end 103369626SruNote that @code{gtroff} also accepts a @option{-R} option, which is not 103455839Sasmodaiaccessible via @code{groff}. This option prevents the loading of the 103569626Sru@file{troffrc} and @file{troffrc-end} files. 103669626Sru 103755839Sasmodai@item -v 103855839SasmodaiMake programs run by @code{groff} print out their version number. 103969626Sru 104055839Sasmodai@item -V 1041151497SruPrint the pipeline on @code{stdout} instead of executing it. If specified 1042151497Srumore than once, print the pipeline on @code{stderr} and execute it. 104369626Sru 104455839Sasmodai@item -z 104575584SruSuppress output from @code{gtroff}. Only error messages are printed. 104669626Sru 104755839Sasmodai@item -Z 104855839SasmodaiDo not postprocess the output of @code{gtroff}. Normally @code{groff} 104975584Sruautomatically runs the appropriate postprocessor. 105069626Sru 105155839Sasmodai@item -P@var{arg} 105255839SasmodaiPass @var{arg} to the postprocessor. Each argument should be passed 105369626Sruwith a separate @option{-P} option. Note that @code{groff} does not 105469626Sruprepend @samp{-} to @var{arg} before passing it to the postprocessor. 105569626Sru 105655839Sasmodai@item -l 105775584SruSend the output to a spooler for printing. The command used for this is 105875584Sruspecified by the @code{print} command in the device description file 105975584Sru(see @ref{Font Files}, for more info). If not present, @option{-l} is 106075584Sruignored. 106169626Sru 106255839Sasmodai@item -L@var{arg} 106355839SasmodaiPass @var{arg} to the spooler. Each argument should be passed with a 1064104862Sruseparate @option{-L} option. Note that @code{groff} does not prepend 1065104862Srua @samp{-} to @var{arg} before passing it to the postprocessor. 1066104862SruIf the @code{print} keyword in the device description file is missing, 106775584Sru@option{-L} is ignored. 106869626Sru 106955839Sasmodai@item -T@var{dev} 107069626SruPrepare output for device @var{dev}. The default device is @samp{ps}, 107169626Sruunless changed when @code{groff} was configured and built. The 107269626Srufollowing are the output devices currently available: 107369626Sru 107469626Sru@table @code 107555839Sasmodai@item ps 107675584SruFor @sc{PostScript} printers and previewers. 107769626Sru 107855839Sasmodai@item dvi 107969626SruFor @TeX{} DVI format. 108069626Sru 108155839Sasmodai@item X75 108269626SruFor a 75@dmn{dpi} X11 previewer. 108369626Sru 1084104862Sru@item X75-12 1085104862SruFor a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 1086104862Srudocument. 1087104862Sru 108855839Sasmodai@item X100 108969626SruFor a 100@dmn{dpi} X11 previewer. 109069626Sru 1091104862Sru@item X100-12 1092104862SruFor a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 1093104862Srudocument. 1094104862Sru 109555839Sasmodai@item ascii 1096114402Sru@cindex encoding, output, @acronym{ASCII} 1097114402Sru@cindex @acronym{ASCII}, output encoding 1098114402Sru@cindex output encoding, @acronym{ASCII} 1099104862SruFor typewriter-like devices using the (7-bit) @acronym{ASCII} 1100104862Srucharacter set. 110169626Sru 110255839Sasmodai@item latin1 1103114402Sru@cindex encoding, output, @w{latin-1} (ISO @w{8859-1}) 1104114402Sru@cindex @w{latin-1} (ISO @w{8859-1}), output encoding 1105114402Sru@cindex ISO @w{8859-1} (@w{latin-1}), output encoding 1106114402Sru@cindex output encoding, @w{latin-1} (ISO @w{8859-1}) 1107114402SruFor typewriter-like devices that support the @w{Latin-1} 1108114402Sru(ISO@tie{}@w{8859-1}) character set. 110969626Sru 111069626Sru@item utf8 1111114402Sru@cindex encoding, output, @w{utf-8} 1112114402Sru@cindex @w{utf-8}, output encoding 1113114402Sru@cindex output encoding, @w{utf-8} 1114114402SruFor typewriter-like devices which use the Unicode (ISO@tie{}10646) 111569626Srucharacter set with @w{UTF-8} encoding. 111669626Sru 111769626Sru@item cp1047 1118114402Sru@cindex encoding, output, @acronym{EBCDIC} 1119114402Sru@cindex @acronym{EBCDIC}, output encoding 1120114402Sru@cindex output encoding, @acronym{EBCDIC} 1121114402Sru@cindex encoding, output, cp1047 1122114402Sru@cindex cp1047, output encoding 1123114402Sru@cindex output encoding, cp1047 1124114402Sru@cindex IBM cp1047 output encoding 112569626SruFor typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 112669626Srucp1047. 112769626Sru 112855839Sasmodai@item lj4 1129104862SruFor HP LaserJet4-compatible (or other PCL5-compatible) printers. 113069626Sru 113169626Sru@item lbp 113269626SruFor Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 113369626Sruprinters). 113469626Sru 113575584Sru@pindex pre-grohtml 113675584Sru@pindex post-grohtml 1137104862Sru@cindex @code{grohtml}, the program 113855839Sasmodai@item html 113975584SruTo produce @acronym{HTML} output. Note that the @acronym{HTML} driver 114075584Sruconsists of two parts, a preprocessor (@code{pre-grohtml}) and a 114175584Srupostprocessor (@code{post-grohtml}). 114255839Sasmodai@end table 114355839Sasmodai 1144104862Sru@cindex output device name string register (@code{.T}) 1145104862Sru@cindex output device usage number register (@code{.T}) 114669626SruThe predefined @code{gtroff} string register @code{.T} contains the 114769626Srucurrent output device; the read-only number register @code{.T} is set 1148114402Sruto@tie{}1 if this option is used (which is always true if @code{groff} is 114969626Sruused to call @code{gtroff}). @xref{Built-in Registers}. 115069626Sru 115155839SasmodaiThe postprocessor to be used for a device is specified by the 115255839Sasmodai@code{postpro} command in the device description file. (@xref{Font 115369626SruFiles}, for more info.) This can be overridden with the @option{-X} 115455839Sasmodaioption. 115569626Sru 115655839Sasmodai@item -X 115755839SasmodaiPreview with @code{gxditview} instead of using the usual postprocessor. 115869626SruThis is unlikely to produce good results except with @option{-Tps}. 115969626Sru 116069626SruNote that this is not the same as using @option{-TX75} or 116169626Sru@option{-TX100} to view a document with @code{gxditview}: The former 116275584Sruuses the metrics of the specified device, whereas the latter uses 116375584SruX-specific fonts and metrics. 116469626Sru 116555839Sasmodai@item -N 116655839SasmodaiDon't allow newlines with @code{eqn} delimiters. This is the same as 116769626Sruthe @option{-N} option in @code{geqn}. 116869626Sru 116955839Sasmodai@item -S 1170104862Sru@cindex @code{open} request, and safer mode 1171104862Sru@cindex @code{opena} request, and safer mode 1172104862Sru@cindex @code{pso} request, and safer mode 1173104862Sru@cindex @code{sy} request, and safer mode 1174104862Sru@cindex @code{pi} request, and safer mode 1175104862Sru@cindex safer mode 1176104862Sru@cindex mode, safer 117775584SruSafer mode. Pass the @option{-S} option to @code{gpic} and disable the 117875584Sru@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 117975584Srurequests. For security reasons, this is enabled by default. 118069626Sru 118169626Sru@item -U 1182104862Sru@cindex mode, unsafe 1183104862Sru@cindex unsafe mode 1184104862SruUnsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1185104862Sru@code{sy}, and @code{pi} requests. 118669626Sru 118755839Sasmodai@item -a 1188104862Sru@cindex @acronym{ASCII} approximation output register (@code{.A}) 118969626SruGenerate an @acronym{ASCII} approximation of the typeset output. The 1190114402Sruread-only register @code{.A} is then set to@tie{}1. @xref{Built-in 119175584SruRegisters}. A typical example is 119269626Sru 119375584Sru@Example 119475584Srugroff -a -man -Tdvi troff.man | less 119575584Sru@endExample 119675584Sru 119775584Sru@noindent 119875584Sruwhich shows how lines are broken for the DVI device. Note that this 119975584Sruoption is rather useless today since graphic output devices are 120075584Sruavailable virtually everywhere. 120175584Sru 120255839Sasmodai@item -b 120355839SasmodaiPrint a backtrace with each warning or error message. This backtrace 120455839Sasmodaishould help track down the cause of the error. The line numbers given 120569626Sruin the backtrace may not always be correct: @code{gtroff} can get 120669626Sruconfused by @code{as} or @code{am} requests while counting line numbers. 120769626Sru 120855839Sasmodai@item -i 120955839SasmodaiRead the standard input after all the named input files have been 121055839Sasmodaiprocessed. 121169626Sru 121255839Sasmodai@item -w@var{name} 121355839SasmodaiEnable warning @var{name}. Available warnings are described in 121469626Sru@ref{Debugging}. Multiple @option{-w} options are allowed. 121569626Sru 121655839Sasmodai@item -W@var{name} 121769626SruInhibit warning @var{name}. Multiple @option{-W} options are allowed. 121869626Sru 121955839Sasmodai@item -E 122055839SasmodaiInhibit all error messages. 122169626Sru 122255839Sasmodai@item -C 122369626SruEnable compatibility mode. @xref{Implementation Differences}, for the 1224104862Srulist of incompatibilities between @code{groff} and @acronym{AT&T} 122569626Sru@code{troff}. 122669626Sru 1227104862Sru@item -d@var{c}@var{s} 1228104862Sru@itemx -d@var{name}=@var{s} 1229114402SruDefine @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must 1230104862Srube a one-letter name; @var{name} can be of arbitrary length. All string 123175584Sruassignments happen before loading any macro file (including the start-up 123275584Srufile). 123369626Sru 123455839Sasmodai@item -f@var{fam} 123575584SruUse @var{fam} as the default font family. @xref{Font Families}. 123669626Sru 123755839Sasmodai@item -m@var{name} 123875584SruRead in the file @file{@var{name}.tmac}. Normally @code{groff} searches 123975584Srufor this in its macro directories. If it isn't found, it tries 1240104862Sru@file{tmac.@var{name}} (searching in the same directories). 124169626Sru 124255839Sasmodai@item -n@var{num} 124355839SasmodaiNumber the first page @var{num}. 124469626Sru 124555839Sasmodai@item -o@var{list} 1246104862Sru@cindex print current page register (@code{.P}) 124755839SasmodaiOutput only pages in @var{list}, which is a comma-separated list of page 1248114402Sruranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}} 1249114402Srumeans print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} 1250114402Srumeans print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every 1251114402Srupage beginning with@tie{}@var{n}. @code{gtroff} exits after printing the 125269626Srulast page in the list. All the ranges are inclusive on both ends. 125369626Sru 125469626SruWithin @code{gtroff}, this information can be extracted with the 125569626Sru@samp{.P} register. @xref{Built-in Registers}. 125669626Sru 125775584SruIf your document restarts page numbering at the beginning of each 125875584Sruchapter, then @code{gtroff} prints the specified page range for each 125975584Sruchapter. 126075584Sru 1261104862Sru@item -r@var{c}@var{n} 126255839Sasmodai@itemx -r@var{name}=@var{n} 1263114402SruSet number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. 1264114402Sru@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary 1265114402Srulength. @var{n}@tie{}can be any @code{gtroff} numeric expression. All 1266114402Sruregister assignments happen before loading any macro file (including 1267104862Sruthe start-up file). 126869626Sru 126955839Sasmodai@item -F@var{dir} 127069626SruSearch @file{@var{dir}} for subdirectories @file{dev@var{name}} 127169626Sru(@var{name} is the name of the device), for the @file{DESC} file, and 1272104862Srufor font files before looking in the standard directories (@pxref{Font 1273104862SruDirectories}). This option is passed to all pre- and postprocessors 1274104862Sruusing the @env{GROFF_FONT_PATH} environment variable. 127569626Sru 127655839Sasmodai@item -M@var{dir} 127769626SruSearch directory @file{@var{dir}} for macro files before the standard 1278104862Srudirectories (@pxref{Macro Directories}). 127969626Sru 128069626Sru@item -I@var{dir} 1281151497SruThis option may be used to specify a directory to search for files. 1282151497SruIt is passed to the following programs: 1283151497Sru 1284151497Sru@itemize 1285151497Sru@item 1286151497Sru@code{gsoelim} (see @ref{gsoelim} for more details); 1287151497Sruit also implies @code{groff}'s @option{-s} option. 1288151497Sru 1289151497Sru@item 1290151497Sru@code{gtroff}; it is used to search files named in the @code{psbb} and 1291151497Sru@code{so} requests. 1292151497Sru 1293151497Sru@item 1294151497Sru@code{grops}; it is used to search files named in the 1295151497Sru@w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes. 1296151497Sru@end itemize 1297151497Sru 1298151497SruThe current directory is always searched first. This option may be specified 1299151497Srumore than once; the directories will be searched in the order specified. No 1300151497Srudirectory search is performed for files specified using an absolute path. 130155839Sasmodai@end table 130255839Sasmodai 130355839Sasmodai 130469626Sru@c ===================================================================== 130555839Sasmodai 1306104862Sru@node Environment, Macro Directories, Groff Options, Invoking groff 130755839Sasmodai@section Environment 130869626Sru@cindex environment variables 130969626Sru@cindex variables in environment 131055839Sasmodai 131169626SruThere are also several environment variables (of the operating system, 131269626Srunot within @code{gtroff}) which can modify the behavior of @code{groff}. 131355839Sasmodai 131455839Sasmodai@table @code 131555839Sasmodai@item GROFF_COMMAND_PREFIX 1316104862Sru@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1317104862Sru@cindex command prefix 1318104862Sru@cindex prefix, for commands 1319114402SruIf this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff} 132075584Sruinstead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 132175584Sru@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 132275584Sruapply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 132375584Sru@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 132469626Sru 1325104862SruThe default command prefix is determined during the installation process. 1326104862SruIf a non-GNU troff system is found, prefix @samp{g} is used, none 1327104862Sruotherwise. 132875584Sru 132955839Sasmodai@item GROFF_TMAC_PATH 1330104862Sru@tindex GROFF_TMAC_PATH@r{, environment variable} 133175584SruA colon-separated list of directories in which to search for macro files 1332104862Sru(before the default directories are tried). @xref{Macro Directories}. 133369626Sru 133455839Sasmodai@item GROFF_TYPESETTER 1335104862Sru@tindex GROFF_TYPESETTER@r{, environment variable} 133669626SruThe default output device. 133769626Sru 133855839Sasmodai@item GROFF_FONT_PATH 1339104862Sru@tindex GROFF_FONT_PATH@r{, environment variable} 134069626SruA colon-separated list of directories in which to search for the 134175584Sru@code{dev}@var{name} directory (before the default directories are 1342104862Srutried). @xref{Font Directories}. 134369626Sru 134475584Sru@item GROFF_BIN_PATH 1345104862Sru@tindex GROFF_BIN_PATH@r{, environment variable} 134675584SruThis search path, followed by @code{PATH}, is used for commands executed 134775584Sruby @code{groff}. 134869626Sru 134955839Sasmodai@item GROFF_TMPDIR 1350104862Sru@tindex GROFF_TMPDIR@r{, environment variable} 1351104862Sru@tindex TMPDIR@r{, environment variable} 135275584SruThe directory in which @code{groff} creates temporary files. If this is 135375584Srunot set and @env{TMPDIR} is set, temporary files are created in that 135475584Srudirectory. Otherwise temporary files are created in a system-dependent 135575584Srudefault directory (on Unix and GNU/Linux systems, this is usually 135675584Sru@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 135775584Sru@code{post-grohtml} can create temporary files in this directory. 135855839Sasmodai@end table 135955839Sasmodai 136069626SruNote that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 136169626Srurather than colons, to separate the directories in the lists described 136269626Sruabove. 136355839Sasmodai 136469626Sru 136569626Sru@c ===================================================================== 136669626Sru 1367104862Sru@node Macro Directories, Font Directories, Environment, Invoking groff 1368104862Sru@section Macro Directories 1369104862Sru@cindex macro directories 1370104862Sru@cindex directories for macros 1371104862Sru@cindex searching macros 1372104862Sru@cindex macros, searching 1373104862Sru 1374104862SruAll macro file names must be named @code{@var{name}.tmac} or 1375104862Sru@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1376104862Sruoption work. The @code{mso} request doesn't have this restriction; any 1377104862Srufile name can be used, and @code{gtroff} won't try to append or prepend 1378104862Sruthe @samp{tmac} string. 1379104862Sru 1380104862Sru@cindex tmac, directory 1381104862Sru@cindex directory, for tmac files 1382104862Sru@cindex tmac, path 1383104862Sru@cindex path, for tmac files 1384104862Sru@cindex searching macro files 1385104862Sru@cindex macro files, searching 1386104862Sru@cindex files, macro, searching 1387104862SruMacro files are kept in the @dfn{tmac directories}, all of which 1388104862Sruconstitute the @dfn{tmac path}. The elements of the search path for 1389104862Srumacro files are (in that order): 1390104862Sru 1391104862Sru@itemize @bullet 1392104862Sru@item 1393104862SruThe directories specified with @code{gtroff}'s or @code{groff}'s 1394104862Sru@option{-M} command line option. 1395104862Sru 1396104862Sru@item 1397104862Sru@tindex GROFF_TMAC_PATH@r{, environment variable} 1398104862SruThe directories given in the @env{GROFF_TMAC_PATH} environment 1399104862Sruvariable. 1400104862Sru 1401104862Sru@item 1402104862Sru@cindex safer mode 1403104862Sru@cindex mode, safer 1404104862Sru@cindex unsafe mode 1405104862Sru@cindex mode, unsafe 1406104862Sru@cindex current directory 1407104862Sru@cindex directory, current 1408104862SruThe current directory (only if in unsafe mode using the @option{-U} 1409104862Srucommand line switch). 1410104862Sru 1411104862Sru@item 1412104862Sru@cindex home directory 1413104862Sru@cindex directory, home 1414104862SruThe home directory. 1415104862Sru 1416104862Sru@item 1417104862Sru@cindex site-specific directory 1418104862Sru@cindex directory, site-specific 1419104862Sru@cindex platform-specific directory 1420104862Sru@cindex directory, platform-specific 1421104862SruA platform-dependent directory, a site-specific (platform-independent) 1422104862Srudirectory, and the main tmac directory; the default locations are 1423104862Sru 1424104862Sru@Example 1425104862Sru/usr/local/lib/groff/site-tmac 1426104862Sru/usr/local/share/groff/site-tmac 1427114402Sru/usr/local/share/groff/1.18.2/tmac 1428104862Sru@endExample 1429104862Sru 1430104862Sru@noindent 1431114402Sruassuming that the version of @code{groff} is 1.18.2, and the installation 1432104862Sruprefix was @file{/usr/local}. It is possible to fine-tune those 1433104862Srudirectories during the installation process. 1434104862Sru@end itemize 1435104862Sru 1436104862Sru 1437104862Sru@c ===================================================================== 1438104862Sru 1439114402Sru@node Font Directories, Paper Size, Macro Directories, Invoking groff 1440104862Sru@section Font Directories 1441104862Sru@cindex font directories 1442104862Sru@cindex directories for fonts 1443104862Sru@cindex searching fonts 1444104862Sru@cindex fonts, searching 1445104862Sru 1446104862SruBasically, there is no restriction how font files for @code{groff} are 1447104862Srunamed and how long font names are; however, to make the font family 1448104862Srumechanism work (@pxref{Font Families}), fonts within a family should 1449104862Srustart with the family name, followed by the shape. For example, the 1450104862SruTimes family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1451104862Sru@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1452104862Sru`italic', and `bold italic', respectively. Thus the final font names 1453104862Sruare @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1454104862Sru 1455104862Sru@cindex font path 1456104862Sru@cindex path, for font files 1457104862SruAll font files are kept in the @dfn{font directories} which constitute 1458104862Sruthe @dfn{font path}. The file search functions will always append the 1459104862Srudirectory @code{dev}@var{name}, where @var{name} is the name of the 1460104862Sruoutput device. Assuming, say, DVI output, and @file{/foo/bar} as a 1461104862Srufont directory, the font files for @code{grodvi} must be in 1462104862Sru@file{/foo/bar/devdvi}. 1463104862Sru 1464104862SruThe elements of the search path for font files are (in that order): 1465104862Sru 1466104862Sru@itemize @bullet 1467104862Sru@item 1468104862SruThe directories specified with @code{gtroff}'s or @code{groff}'s 1469104862Sru@option{-F} command line option. All device drivers and some 1470104862Srupreprocessors also have this option. 1471104862Sru 1472104862Sru@item 1473104862Sru@tindex GROFF_FONT_PATH@r{, environment variable} 1474104862SruThe directories given in the @env{GROFF_FONT_PATH} environment 1475104862Sruvariable. 1476104862Sru 1477104862Sru@item 1478104862Sru@cindex site-specific directory 1479104862Sru@cindex directory, site-specific 1480104862SruA site-specific directory and the main font directory; the default 1481104862Srulocations are 1482104862Sru 1483104862Sru@Example 1484104862Sru/usr/local/share/groff/site-font 1485114402Sru/usr/local/share/groff/1.18.2/font 1486104862Sru@endExample 1487104862Sru 1488104862Sru@noindent 1489114402Sruassuming that the version of @code{groff} is 1.18.2, and the installation 1490104862Sruprefix was @file{/usr/local}. It is possible to fine-tune those 1491104862Srudirectories during the installation process. 1492104862Sru@end itemize 1493104862Sru 1494104862Sru 1495104862Sru@c ===================================================================== 1496104862Sru 1497114402Sru@node Paper Size, Invocation Examples, Font Directories, Invoking groff 1498114402Sru@section Paper Size 1499114402Sru@cindex paper size 1500114402Sru@cindex size, paper 1501114402Sru@cindex landscape page orientation 1502114402Sru@cindex orientation, landscape 1503114402Sru@cindex page orientation, landscape 1504114402Sru 1505114402SruIn groff, the page size for @code{gtroff} and for output devices are 1506114402Sruhandled separately. @xref{Page Layout}, for vertical manipulation of 1507114402Sruthe page size. @xref{Line Layout}, for horizontal changes. 1508114402Sru 1509114402SruA default paper size can be set in the device's @file{DESC} file. Most 1510114402Sruoutput devices also have a command line option @option{-p} to override 1511114402Sruthe default paper size and option @option{-l} to use landscape 1512114402Sruorientation. @xref{DESC File Format}, for a description of the 1513114402Sru@code{papersize} keyword which takes the same argument as @option{-p}. 1514114402Sru 1515114402Sru@pindex papersize.tmac 1516114402Sru@pindex troffrc 1517114402SruA convenient shorthand to set a particular paper size for @code{gtroff} 1518114402Sruis command line option @option{-dpaper=@var{size}}. This defines string 1519114402Sru@code{paper} which is processed in file @file{papersize.tmac} (loaded in 1520114402Sruthe start-up file @file{troffrc} by default). Possible values for 1521114402Sru@var{size} are the same as the predefined values for the 1522114402Sru@code{papersize} keyword (but only in lowercase) except 1523114402Sru@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes 1524114402Srulandscape orientation. 1525114402Sru 1526114402SruFor example, use the following for PS output on A4 paper in landscape 1527114402Sruorientation: 1528114402Sru 1529114402Sru@Example 1530114402Srugroff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 1531114402Sru@endExample 1532114402Sru 1533114402SruNote that it is up to the particular macro package to respect default 1534114402Srupage dimensions set in this way (most do). 1535114402Sru 1536114402Sru 1537114402Sru@c ===================================================================== 1538114402Sru 1539114402Sru@node Invocation Examples, , Paper Size, Invoking groff 154055839Sasmodai@section Invocation Examples 154155839Sasmodai@cindex invocation examples 154255839Sasmodai@cindex examples of invocation 154355839Sasmodai 154475584SruThis section lists several common uses of @code{groff} and the 154575584Srucorresponding command lines. 154655839Sasmodai 154775584Sru@Example 154855839Sasmodaigroff file 154975584Sru@endExample 155055839Sasmodai 155169626Sru@noindent 155269626SruThis command processes @file{file} without a macro package or a 155369626Srupreprocessor. The output device is the default, @samp{ps}, and the 155475584Sruoutput is sent to @code{stdout}. 155569626Sru 155675584Sru@Example 155769626Srugroff -t -mandoc -Tascii file | less 155875584Sru@endExample 155969626Sru 156069626Sru@noindent 156175584SruThis is basically what a call to the @code{man} program does. 156275584Sru@code{gtroff} processes the manual page @file{file} with the 156375584Sru@file{mandoc} macro file (which in turn either calls the @file{man} or 156475584Sruthe @file{mdoc} macro package), using the @code{tbl} preprocessor and 156575584Sruthe @acronym{ASCII} output device. Finally, the @code{less} pager 156675584Srudisplays the result. 156769626Sru 156875584Sru@Example 156969626Srugroff -X -m me file 157075584Sru@endExample 157169626Sru 157269626Sru@noindent 157369626SruPreview @file{file} with @code{gxditview}, using the @file{me} macro 157469626Srupackage. Since no @option{-T} option is specified, use the default 157569626Srudevice (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 157669626Sru@w{@samp{-me}}; the latter is an anachronism from the early days of 157769626Sru@acronym{UNIX}.@footnote{The same is true for the other main macro 157869626Srupackages that come with @code{groff}: @file{man}, @file{mdoc}, 157969626Sru@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 158075584Srufor example, to load @file{trace.tmac}, either @samp{-mtrace} or 158175584Sru@w{@samp{-m trace}} must be used.} 158269626Sru 158375584Sru@Example 158469626Srugroff -man -rD1 -z file 158575584Sru@endExample 158669626Sru 158769626Sru@noindent 158869626SruCheck @file{file} with the @file{man} macro package, forcing 158969626Srudouble-sided printing -- don't produce any output. 159069626Sru 159169626Sru@menu 159275584Sru* grog:: 159369626Sru@end menu 159469626Sru 159575584Sru@c --------------------------------------------------------------------- 159675584Sru 159769626Sru@node grog, , Invocation Examples, Invocation Examples 159855839Sasmodai@subsection @code{grog} 159955839Sasmodai 160069626Sru@pindex grog 160169626Sru@code{grog} reads files, guesses which of the @code{groff} preprocessors 160269626Sruand/or macro packages are required for formatting them, and prints the 160375584Sru@code{groff} command including those options on the standard output. It 160475584Srugenerates one or more of the options @option{-e}, @option{-man}, 1605104862Sru@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 160675584Sru@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 160775584Sru@option{-s}, and @option{-t}. 160855839Sasmodai 1609114402SruA special file name@tie{}@file{-} refers to the standard input. Specifying 161075584Sruno files also means to read the standard input. Any specified options 161175584Sruare included in the printed command. No space is allowed between 161275584Sruoptions and their arguments. The only options recognized are 161375584Sru@option{-C} (which is also passed on) to enable compatibility mode, and 1614104862Sru@option{-v} to print the version number and exit. 161555839Sasmodai 161675584SruFor example, 161775584Sru 161875584Sru@Example 161955839Sasmodaigrog -Tdvi paper.ms 162075584Sru@endExample 162155839Sasmodai 162269626Sru@noindent 162375584Sruguesses the appropriate command to print @file{paper.ms} and then prints 162475584Sruit to the command line after adding the @option{-Tdvi} option. For 162575584Srudirect execution, enclose the call to @code{grog} in backquotes at the 162675584Sru@acronym{UNIX} shell prompt: 162755839Sasmodai 162875584Sru@Example 162969626Sru`grog -Tdvi paper.ms` > paper.dvi 163075584Sru@endExample 163155839Sasmodai 163269626Sru@noindent 163369626SruAs seen in the example, it is still necessary to redirect the output to 163469626Srusomething meaningful (i.e.@: either a file or a pager program like 163569626Sru@code{less}). 163669626Sru 163769626Sru 163869626Sru 163969626Sru@c ===================================================================== 164069626Sru@c ===================================================================== 164169626Sru 164269626Sru@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 164355839Sasmodai@chapter Tutorial for Macro Users 164455839Sasmodai@cindex tutorial for macro users 164569626Sru@cindex macros, tutorial for users 164655839Sasmodai@cindex user's tutorial for macros 164755839Sasmodai@cindex user's macro tutorial 164855839Sasmodai 164955839SasmodaiMost users tend to use a macro package to format their papers. This 165069626Srumeans that the whole breadth of @code{groff} is not necessary for most 165155839Sasmodaipeople. This chapter covers the material needed to efficiently use a 165255839Sasmodaimacro package. 165355839Sasmodai 165455839Sasmodai@menu 165575584Sru* Basics:: 165675584Sru* Common Features:: 165755839Sasmodai@end menu 165855839Sasmodai 165969626Sru 166069626Sru@c ===================================================================== 166169626Sru 166255839Sasmodai@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 166355839Sasmodai@section Basics 166469626Sru@cindex basics of macros 166569626Sru@cindex macro basics 166655839Sasmodai 166769626SruThis section covers some of the basic concepts necessary to understand 166869626Sruhow to use a macro package.@footnote{This section is derived from 1669114402Sru@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.} 167055839SasmodaiReferences are made throughout to more detailed information, if desired. 167155839Sasmodai 167269626Sru@code{gtroff} reads an input file prepared by the user and outputs a 167369626Sruformatted document suitable for publication or framing. The input 167469626Sruconsists of text, or words to be printed, and embedded commands 167569626Sru(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 167669626Sruformat the output. For more detail on this, see @ref{Embedded 167769626SruCommands}. 167855839Sasmodai 167969626SruThe word @dfn{argument} is used in this chapter to mean a word or number 168069626Sruwhich appears on the same line as a request, and which modifies the 168169626Srumeaning of that request. For example, the request 168255839Sasmodai 168375584Sru@Example 168455839Sasmodai.sp 168575584Sru@endExample 168655839Sasmodai 168755839Sasmodai@noindent 168855839Sasmodaispaces one line, but 168955839Sasmodai 169075584Sru@Example 169155839Sasmodai.sp 4 169275584Sru@endExample 169355839Sasmodai 169455839Sasmodai@noindent 1695114402Sruspaces four lines. The number@tie{}4 is an argument to the @code{sp} 169655839Sasmodairequest which says to space four lines instead of one. Arguments are 169775584Sruseparated from the request and from each other by spaces (@emph{no} 1698114402Srutabs). More details on this can be found in @ref{Request and Macro 1699114402SruArguments}. 170055839Sasmodai 170169626SruThe primary function of @code{gtroff} is to collect words from input 170269626Srulines, fill output lines with those words, justify the right-hand margin 170355839Sasmodaiby inserting extra spaces in the line, and output the result. For 170455839Sasmodaiexample, the input: 170555839Sasmodai 170675584Sru@Example 170755839SasmodaiNow is the time 170855839Sasmodaifor all good men 170955839Sasmodaito come to the aid 171055839Sasmodaiof their party. 171155839SasmodaiFour score and seven 1712104862Sruyears ago, etc. 171375584Sru@endExample 171455839Sasmodai 171555839Sasmodai@noindent 171675584Sruis read, packed onto output lines, and justified to produce: 171755839Sasmodai 171855839Sasmodai@quotation 171955839SasmodaiNow is the time for all good men to come to the aid of their party. 1720104862SruFour score and seven years ago, etc. 172155839Sasmodai@end quotation 172255839Sasmodai 172355839Sasmodai@cindex break 172455839Sasmodai@cindex line break 172569626SruSometimes a new output line should be started even though the current 172669626Sruline is not yet full; for example, at the end of a paragraph. To do 172769626Sruthis it is possible to cause a @dfn{break}, which starts a new output 172875584Sruline. Some requests cause a break automatically, as normally do blank 172975584Sruinput lines and input lines beginning with a space. 173055839Sasmodai 173175584SruNot all input lines are text to be formatted. Some input lines are 173275584Srurequests which describe how to format the text. Requests always have a 173375584Sruperiod (@samp{.}) or an apostrophe (@samp{'}) as the first character of 173475584Sruthe input line. 173555839Sasmodai 173655839SasmodaiThe text formatter also does more complex things, such as automatically 173769626Srunumbering pages, skipping over page boundaries, putting footnotes in the 173855839Sasmodaicorrect place, and so forth. 173955839Sasmodai 174069626SruHere are a few hints for preparing text for input to @code{gtroff}. 174175584Sru 174275584Sru@itemize @bullet 174375584Sru@item 174469626SruFirst, keep the input lines short. Short input lines are easier to 174575584Sruedit, and @code{gtroff} packs words onto longer lines anyhow. 174655839Sasmodai 174775584Sru@item 174875584SruIn keeping with this, it is helpful to begin a new line after every 174975584Srucomma or phrase, since common corrections are to add or delete sentences 175075584Sruor phrases. 175175584Sru 175275584Sru@item 175375584SruEnd each sentence with two spaces -- or better, start each sentence on a 175475584Srunew line. @code{gtroff} recognizes characters that usually end a 175575584Srusentence, and inserts sentence space accordingly. 175675584Sru 175775584Sru@item 175875584SruDo not hyphenate words at the end of lines -- @code{gtroff} is smart 175975584Sruenough to hyphenate words as needed, but is not smart enough to take 176075584Sruhyphens out and join a word back together. Also, words such as 176175584Sru``mother-in-law'' should not be broken over a line, since then a space 176275584Srucan occur where not wanted, such as ``@w{mother- in}-law''. 176375584Sru@end itemize 176475584Sru 1765104862Sru@cindex double-spacing (@code{ls}) 176655839Sasmodai@cindex spacing 1767104862Sru@code{gtroff} double-spaces output text automatically if you use the 1768104862Srurequest @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing 1769104862Sru@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the 1770104862Sruvertical space, use the @code{pvs} request (@pxref{Changing Type 1771104862SruSizes}).} 177255839Sasmodai 177375584SruA number of requests allow to change the way the output looks, 177475584Srusometimes called the @dfn{layout} of the output page. Most of these 1775104862Srurequests adjust the placing of @dfn{whitespace} (blank lines or 177675584Sruspaces). 177755839Sasmodai 1778104862Sru@cindex new page (@code{bp}) 1779104862SruThe @code{bp} request starts a new page, causing a line break. 178055839Sasmodai 1781104862Sru@cindex blank line (@code{sp}) 1782104862Sru@cindex empty line (@code{sp}) 1783104862Sru@cindex line, empty (@code{sp}) 1784114402SruThe request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank 1785114402Sruspace. @var{N}@tie{}can be omitted (meaning skip a single line) or can 1786114402Srube of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for 1787114402Sru@var{N}@tie{}centimeters). For example, the input: 178855839Sasmodai 178975584Sru@Example 179055839Sasmodai.sp 1.5i 179155839SasmodaiMy thoughts on the subject 179255839Sasmodai.sp 179375584Sru@endExample 179455839Sasmodai 179555839Sasmodai@noindent 179655839Sasmodaileaves one and a half inches of space, followed by the line ``My 179775584Sruthoughts on the subject'', followed by a single blank line (more 179875584Srumeasurement units are available, see @ref{Measurements}). 179955839Sasmodai 1800104862Sru@cindex centering lines (@code{ce}) 1801104862Sru@cindex lines, centering (@code{ce}) 180269626SruText lines can be centered by using the @code{ce} request. The line 180369626Sruafter @code{ce} is centered (horizontally) on the page. To center more 180469626Sruthan one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1805114402Sruof lines to center), followed by the @var{N}@tie{}lines. To center many 180669626Srulines without counting them, type: 180755839Sasmodai 180875584Sru@Example 180955839Sasmodai.ce 1000 181055839Sasmodailines to center 181155839Sasmodai.ce 0 181275584Sru@endExample 181355839Sasmodai 181455839Sasmodai@noindent 181569626SruThe @w{@samp{.ce 0}} request tells @code{groff} to center zero more 181669626Srulines, in other words, stop centering. 181755839Sasmodai 1818104862Sru@cindex line break (@code{br}) 1819104862Sru@cindex break (@code{br}) 182055839SasmodaiAll of these requests cause a break; that is, they always start a new 182169626Sruline. To start a new line without performing any other action, use 182269626Sru@code{br}. 182355839Sasmodai 182455839Sasmodai 182569626Sru@c ===================================================================== 182669626Sru 182755839Sasmodai@node Common Features, , Basics, Tutorial for Macro Users 182855839Sasmodai@section Common Features 182955839Sasmodai@cindex common features 183055839Sasmodai@cindex features, common 183155839Sasmodai 183275584Sru@code{gtroff} provides very low-level operations for formatting a 183369626Srudocument. There are many common routine operations which are done in 183469626Sruall documents. These common operations are written into @dfn{macros} 183569626Sruand collected into a @dfn{macro package}. 183655839Sasmodai 183769626SruAll macro packages provide certain common capabilities which fall into 183869626Sruthe following categories. 183955839Sasmodai 184069626Sru@menu 184175584Sru* Paragraphs:: 184275584Sru* Sections and Chapters:: 184375584Sru* Headers and Footers:: 184475584Sru* Page Layout Adjustment:: 184575584Sru* Displays:: 184675584Sru* Footnotes and Annotations:: 184775584Sru* Table of Contents:: 184875584Sru* Indices:: 184975584Sru* Paper Formats:: 185075584Sru* Multiple Columns:: 185175584Sru* Font and Size Changes:: 185275584Sru* Predefined Strings:: 185375584Sru* Preprocessor Support:: 185475584Sru* Configuration and Customization:: 185569626Sru@end menu 185669626Sru 185775584Sru@c --------------------------------------------------------------------- 185875584Sru 185969626Sru@node Paragraphs, Sections and Chapters, Common Features, Common Features 186055839Sasmodai@subsection Paragraphs 186155839Sasmodai@cindex paragraphs 186255839Sasmodai 186375584SruOne of the most common and most used capability is starting a 186475584Sruparagraph. There are a number of different types of paragraphs, any 186575584Sruof which can be initiated with macros supplied by the macro package. 186675584SruNormally, paragraphs start with a blank line and the first line 186775584Sruindented, like the text in this manual. There are also block style 186875584Sruparagraphs, which omit the indentation: 186955839Sasmodai 187075584Sru@Example 187155839SasmodaiSome men look at constitutions with sanctimonious 187255839Sasmodaireverence, and deem them like the ark of the covenant, too 187355839Sasmodaisacred to be touched. 187475584Sru@endExample 187555839Sasmodai 187669626Sru@noindent 187755839SasmodaiAnd there are also indented paragraphs which begin with a tag or label 187855839Sasmodaiat the margin and the remaining text indented. 187955839Sasmodai 1880104862Sru@Example 188155839Sasmodaione This is the first paragraph. Notice how the first 188255839Sasmodai line of the resulting paragraph lines up with the 188355839Sasmodai other lines in the paragraph. 1884104862Sru@endExample 1885104862Sru@Example 188655839Sasmodailonglabel 188755839Sasmodai This paragraph had a long label. The first 188875584Sru character of text on the first line does not line up 188955839Sasmodai with the text on second and subsequent lines, 189075584Sru although they line up with each other. 1891104862Sru@endExample 189255839Sasmodai 189369626SruA variation of this is a bulleted list. 189455839Sasmodai 1895104862Sru@Example 1896104862Sru. Bulleted lists start with a bullet. It is possible 1897104862Sru to use other glyphs instead of the bullet. In nroff 1898104862Sru mode using the ASCII character set for output, a dot 1899104862Sru is used instead of a real bullet. 1900104862Sru@endExample 190169626Sru 190269626Sru@c --------------------------------------------------------------------- 190369626Sru 190469626Sru@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 190555839Sasmodai@subsection Sections and Chapters 190655839Sasmodai 190769626SruMost macro packages supply some form of section headers. The simplest 190869626Srukind is simply the heading on a line by itself in bold type. Others 190969626Srusupply automatically numbered section heading or different heading 191069626Srustyles at different levels. Some, more sophisticated, macro packages 191169626Srusupply macros for starting chapters and appendices. 191255839Sasmodai 191369626Sru@c --------------------------------------------------------------------- 191469626Sru 191569626Sru@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 191655839Sasmodai@subsection Headers and Footers 191755839Sasmodai 1918104862SruEvery macro package gives some way to manipulate the @dfn{headers} and 1919104862Sru@dfn{footers} (also called @dfn{titles}) on each page. This is text 1920104862Sruput at the top and bottom of each page, respectively, which contain 1921104862Srudata like the current page number, the current chapter title, and so 1922104862Sruon. Its appearance is not affected by the running text. Some packages 1923104862Sruallow for different ones on the even and odd pages (for material printed 1924104862Sruin a book form). 192569626Sru 1926104862SruThe titles are called @dfn{three-part titles}, that is, there is a 192769626Sruleft-justified part, a centered part, and a right-justified part. An 192869626Sruautomatically generated page number may be put in any of these fields 192969626Sruwith the @samp{%} character (see @ref{Page Layout}, for more details). 193055839Sasmodai 193169626Sru@c --------------------------------------------------------------------- 193269626Sru 193369626Sru@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 193455839Sasmodai@subsection Page Layout 193555839Sasmodai 193669626SruMost macro packages let the user specify top and bottom margins and 193769626Sruother details about the appearance of the printed pages. 193855839Sasmodai 193969626Sru@c --------------------------------------------------------------------- 194069626Sru 194169626Sru@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 194255839Sasmodai@subsection Displays 194355839Sasmodai@cindex displays 194455839Sasmodai 1945104862Sru@dfn{Displays} are sections of text to be set off from the body of 1946104862Sruthe paper. Major quotes, tables, and figures are types of displays, as 1947104862Sruare all the examples used in this document. 194855839Sasmodai 194955839Sasmodai@cindex quotes, major 195055839Sasmodai@cindex major quotes 195169626Sru@dfn{Major quotes} are quotes which are several lines long, and hence 195269626Sruare set in from the rest of the text without quote marks around them. 195355839Sasmodai 195455839Sasmodai@cindex list 1955104862SruA @dfn{list} is an indented, single-spaced, unfilled display. Lists 195669626Srushould be used when the material to be printed should not be filled and 195769626Srujustified like normal text, such as columns of figures or the examples 195869626Sruused in this paper. 195955839Sasmodai 196055839Sasmodai@cindex keep 196169626SruA @dfn{keep} is a display of lines which are kept on a single page if 196269626Srupossible. An example for a keep might be a diagram. Keeps differ from 196375584Srulists in that lists may be broken over a page boundary whereas keeps are 196475584Srunot. 196555839Sasmodai 196655839Sasmodai@cindex keep, floating 196755839Sasmodai@cindex floating keep 1968104862Sru@dfn{Floating keeps} move relative to the text. Hence, they are good for 1969114402Sruthings which are referred to by name, such as ``See figure@tie{}3''. A 197075584Srufloating keep appears at the bottom of the current page if it fits; 197175584Sruotherwise, it appears at the top of the next page. Meanwhile, the 197275584Srusurrounding text `flows' around the keep, thus leaving no blank areas. 197355839Sasmodai 197469626Sru@c --------------------------------------------------------------------- 197569626Sru 197669626Sru@node Footnotes and Annotations, Table of Contents, Displays, Common Features 197769626Sru@subsection Footnotes and Annotations 197855839Sasmodai@cindex footnotes 197955839Sasmodai@cindex annotations 198055839Sasmodai 198169626SruThere are a number of requests to save text for later printing. 198255839Sasmodai 198369626Sru@dfn{Footnotes} are printed at the bottom of the current page. 198455839Sasmodai 198569626Sru@cindex delayed text 198669626Sru@dfn{Delayed text} is very similar to a footnote except that it is 198769626Sruprinted when called for explicitly. This allows a list of references to 198869626Sruappear (for example) at the end of each chapter, as is the convention in 198969626Srusome disciplines. 199055839Sasmodai 199169626SruMost macro packages which supply this functionality also supply a means 199269626Sruof automatically numbering either type of annotation. 199369626Sru 199469626Sru@c --------------------------------------------------------------------- 199569626Sru 199669626Sru@node Table of Contents, Indices, Footnotes and Annotations, Common Features 199755839Sasmodai@subsection Table of Contents 199869626Sru@cindex table of contents 199969626Sru@cindex contents, table of 200055839Sasmodai 200169626Sru@dfn{Tables of contents} are a type of delayed text having a tag 200269626Sru(usually the page number) attached to each entry after a row of dots. 200369626SruThe table accumulates throughout the paper until printed, usually after 200475584Sruthe paper has ended. Many macro packages provide the ability to have 200575584Sruseveral tables of contents (e.g.@: a standard table of contents, a list 200675584Sruof tables, etc). 200755839Sasmodai 200869626Sru@c --------------------------------------------------------------------- 200955839Sasmodai 201069626Sru@node Indices, Paper Formats, Table of Contents, Common Features 201169626Sru@subsection Indices 201269626Sru@cindex index, in macro package 201355839Sasmodai 201475584SruWhile some macro packages use the term @dfn{index}, none actually 201569626Sruprovide that functionality. The facilities they call indices are 201669626Sruactually more appropriate for tables of contents. 201755839Sasmodai 2018104862Sru@pindex makeindex 2019104862SruTo produce a real index in a document, external tools like the 2020104862Sru@code{makeindex} program are necessary. 2021104862Sru 202269626Sru@c --------------------------------------------------------------------- 202369626Sru 202469626Sru@node Paper Formats, Multiple Columns, Indices, Common Features 202569626Sru@subsection Paper Formats 202669626Sru@cindex paper formats 202769626Sru 202855839SasmodaiSome macro packages provide stock formats for various kinds of 202955839Sasmodaidocuments. Many of them provide a common format for the title and 203069626Sruopening pages of a technical paper. The @file{mm} macros in particular 203169626Sruprovide formats for letters and memoranda. 203255839Sasmodai 203369626Sru@c --------------------------------------------------------------------- 203469626Sru 203569626Sru@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 203655839Sasmodai@subsection Multiple Columns 203755839Sasmodai 203869626SruSome macro packages (but not @file{man}) provide the ability to have two 203969626Sruor more columns on a page. 204055839Sasmodai 204169626Sru@c --------------------------------------------------------------------- 204255839Sasmodai 204369626Sru@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 204469626Sru@subsection Font and Size Changes 204569626Sru 204669626SruThe built-in font and size functions are not always intuitive, so all 204755839Sasmodaimacro packages provide macros to make these operations simpler. 204855839Sasmodai 204969626Sru@c --------------------------------------------------------------------- 205069626Sru 205169626Sru@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 205255839Sasmodai@subsection Predefined Strings 205355839Sasmodai 205469626SruMost macro packages provide various predefined strings for a variety of 205569626Sruuses; examples are sub- and superscripts, printable dates, quotes and 205669626Sruvarious special characters. 205755839Sasmodai 205869626Sru@c --------------------------------------------------------------------- 205969626Sru 206069626Sru@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 206155839Sasmodai@subsection Preprocessor Support 206255839Sasmodai 2063104862SruAll macro packages provide support for various preprocessors and may 206475584Sruextend their functionality. 206555839Sasmodai 206675584SruFor example, all macro packages mark tables (which are processed with 2067104862Sru@code{gtbl}) by placing them between @code{TS} and @code{TE} macros. 2068114402SruThe @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints 206975584Srua caption at the top of a new page (when the table is too long to fit on 207075584Srua single page). 207175584Sru 207269626Sru@c --------------------------------------------------------------------- 207369626Sru 207469626Sru@node Configuration and Customization, , Preprocessor Support, Common Features 207555839Sasmodai@subsection Configuration and Customization 207655839Sasmodai 207775584SruSome macro packages provide means of customizing many of the details of 207875584Sruhow the package behaves. This ranges from setting the default type size 207975584Sruto changing the appearance of section headers. 208055839Sasmodai 208155839Sasmodai 208255839Sasmodai 208369626Sru@c ===================================================================== 208469626Sru@c ===================================================================== 208555839Sasmodai 208675584Sru@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 208769626Sru@chapter Macro Packages 208869626Sru@cindex macro packages 208969626Sru@cindex packages, macros 209055839Sasmodai 209169626SruThis chapter documents the main macro packages that come with 209269626Sru@code{groff}. 209355839Sasmodai 2094114402SruDifferent main macro packages can't be used at the same time; for example 2095114402Sru 2096114402Sru@Example 2097114402Srugroff -m man foo.man -m ms bar.doc 2098114402Sru@endExample 2099114402Sru 2100114402Sru@noindent 2101114402Srudoesn't work. Note that option arguments are processed before non-option 2102114402Sruarguments; the above (failing) sample is thus reordered to 2103114402Sru 2104114402Sru@Example 2105114402Srugroff -m man -m ms foo.man bar.doc 2106114402Sru@endExample 2107114402Sru 210869626Sru@menu 210975584Sru* man:: 211075584Sru* mdoc:: 211175584Sru* ms:: 211275584Sru* me:: 211375584Sru* mm:: 211469626Sru@end menu 211555839Sasmodai 211655839Sasmodai 211769626Sru@c ===================================================================== 211855839Sasmodai 211969626Sru@node man, mdoc, Macro Packages, Macro Packages 212069626Sru@section @file{man} 212169626Sru@cindex manual pages 2122104862Sru@cindex man pages 212375584Sru@pindex an.tmac 212475584Sru@pindex man.tmac 212575584Sru@pindex man-old.tmac 212655839Sasmodai 212769626SruThis is the most popular and probably the most important macro package 212869626Sruof @code{groff}. It is easy to use, and a vast majority of manual pages 212969626Sruare based on it. 213055839Sasmodai 213169626Sru@menu 213275584Sru* Man options:: 213375584Sru* Man usage:: 213475584Sru* Man font macros:: 213575584Sru* Miscellaneous man macros:: 213675584Sru* Predefined man strings:: 213775584Sru* Preprocessors in man pages:: 2138114402Sru* Optional man extensions:: 213969626Sru@end menu 214055839Sasmodai 214169626Sru@c --------------------------------------------------------------------- 214255839Sasmodai 214369626Sru@node Man options, Man usage, man, man 214469626Sru@subsection Options 214555839Sasmodai 214669626SruThe command line format for using the @file{man} macros with 214769626Sru@code{groff} is: 214869626Sru 214975584Sru@Example 2150114402Srugroff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ] 2151114402Sru [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ] 2152114402Sru [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ] 2153114402Sru [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ] 215475584Sru@endExample 215569626Sru 215675584Sru@noindent 215769626SruIt is possible to use @samp{-man} instead of @w{@samp{-m man}}. 215869626Sru 215969626Sru@table @code 216075584Sru@item -rcR=1 2161104862SruThis option (the default if a TTY output device is used) creates a 216275584Srusingle, very long page instead of multiple pages. Use @code{-rcR=0} 216375584Sruto disable it. 216475584Sru 216569626Sru@item -rC1 216669626SruIf more than one manual page is given on the command line, number the 2167114402Srupages continuously, rather than starting each at@tie{}1. 216869626Sru 216969626Sru@item -rD1 217069626SruDouble-sided printing. Footers for even and odd pages are formatted 217169626Srudifferently. 217269626Sru 2173114402Sru@item -rFT=@var{dist} 2174114402SruSet the position of the footer text to @var{dist}. If positive, the 2175114402Srudistance is measured relative to the top of the page, otherwise it is 2176114402Srurelative to the bottom. The default is @minus{}0.5@dmn{i}. 2177114402Sru 2178114402Sru@item -rHY=@var{flags} 2179114402SruSet hyphenation flags. Possible values are 1@tie{}to hyphenate without 2180114402Srurestrictions, 2@tie{} to not hyphenate the last word on a page, 2181114402Sru4@tie{}to not hyphenate the last two characters of a word, and 2182114402Sru8@tie{}to not hyphenate the first two characters of a word. These 2183114402Sruvalues are additive; the default is@tie{}14. 2184114402Sru 2185114402Sru@item -rIN=@var{length} 2186151497SruSet the body text indentation to @var{length}. 2187151497SruIf not specified, the indentation defaults to 7@dmn{n} 2188114402Sru(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. 2189114402SruFor nroff, this value should always be an integer multiple of unit @samp{n} 2190114402Sruto get consistent indentation. 2191114402Sru 2192114402Sru@item -rLL=@var{length} 2193114402SruSet line length to @var{length}. If not specified, the line length 2194151497Sruis set to respect any value set by a prior @samp{ll} request (which 2195151497Sru@emph{must} be in effect when the @samp{TH} macro is invoked), if 2196151497Sruthis differs from the built-in default for the formatter; otherwise it 2197151497Srudefaults to 78@dmn{n} in nroff mode (this is 78 characters per 2198151497Sruline) and 6.5@dmn{i} in troff mode.@footnote{Note that the use of 2199151497Srua @samp{.ll @var{length}} request to initialize the line length, prior 2200151497Sruto use of the @samp{TH} macro, is supported for backward compatibility 2201151497Sruwith some versions of the @code{man} program. @emph{Always} use the 2202151497Sru@option{-rLL=@var{length}} option, or an equivalent @samp{.nr LL @var{length}} 2203151497Srurequest, in preference to such a @samp{.ll @var{length}} request. 2204151497SruIn particular, note that in nroff mode, the request @samp{.ll 65n}, 2205151497Sru(with any @var{length} expression which evaluates equal to 65@dmn{n}, 2206151497Srui.e., the formatter's default line length in nroff mode), will @emph{not} 2207151497Sruset the line length to 65@dmn{n} (it will be adjusted to the @code{man} 2208151497Srumacro package's default setting of 78@dmn{n}), whereas the use of the 2209151497Sru@option{-rLL=65n} option, or the @samp{.nr LL 65n} 2210151497Srurequest @emph{will} establish a line length of 65@dmn{n}.} 2211114402Sru 2212114402Sru@item -rLT=@var{length} 2213114402SruSet title length to @var{length}. If not specified, the title length 2214114402Srudefaults to the line length. 2215114402Sru 221669626Sru@item -rP@var{nnn} 2217114402SruPage numbering starts with @var{nnn} rather than with@tie{}1. 221869626Sru 221969626Sru@item -rS@var{xx} 2220114402SruUse @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base 2221114402Srudocument font size instead of the default value of@tie{}10@dmn{pt}. 222269626Sru 2223114402Sru@item -rSN=@var{length} 2224151497SruSet the indentation for sub-subheadings to @var{length}. 2225151497SruIf not specified, the indentation defaults to 3@dmn{n}. 2226114402Sru 222769626Sru@item -rX@var{nnn} 222869626SruAfter page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 222975584Sru@var{nnn}c, etc. For example, the option @option{-rX2} produces the 223069626Srufollowing page numbers: 1, 2, 2a, 2b, 2c, etc. 223169626Sru@end table 223269626Sru 223369626Sru@c --------------------------------------------------------------------- 223469626Sru 223569626Sru@node Man usage, Man font macros, Man options, man 223669626Sru@subsection Usage 223769626Sru@cindex @code{man} macros 2238104862Sru@cindex macros for manual pages [@code{man}] 223969626Sru 224069626Sru@pindex man.local 224169626SruThis section describes the available macros for manual pages. For 224269626Srufurther customization, put additional macros and requests into the file 224375584Sru@file{man.local} which is loaded immediately after the @file{man} 224475584Srupackage. 224569626Sru 2246104862Sru@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} 224775584SruSet the title of the man page to @var{title} and the section to 2248114402Sru@var{section}, which must have a value between 1 and@tie{}8. The value 224975584Sruof @var{section} may also have a string appended, e.g.@: @samp{.pm}, 225075584Sruto indicate a specific subsection of the man pages. 225169626Sru 225269626SruBoth @var{title} and @var{section} are positioned at the left and right 225369626Sruin the header line (with @var{section} in parentheses immediately 225475584Sruappended to @var{title}. @var{extra1} is positioned in the middle of 225575584Sruthe footer line. @var{extra2} is positioned at the left in the footer 225675584Sruline (or at the left on even pages and at the right on odd pages if 225775584Srudouble-sided printing is active). @var{extra3} is centered in the 225875584Sruheader line. 225969626Sru 226069626SruFor @acronym{HTML} output, headers and footers are completely suppressed. 226169626Sru 2262114402SruAdditionally, this macro starts a new page; the new line number is@tie{}1 226369626Sruagain (except if the @option{-rC1} option is given on the command line) 226469626Sru-- this feature is intended only for formatting multiple man pages; a 226569626Srusingle man page should contain exactly one @code{TH} macro at the 226669626Srubeginning of the file. 226775584Sru@endDefmac 226869626Sru 2269104862Sru@Defmac {SH, [@Var{heading}], man} 227075584SruSet up an unnumbered section heading sticking out to the left. Prints 227175584Sruout all the text following @code{SH} up to the end of the line (or the 227275584Srutext in the next line if there is no argument to @code{SH}) in bold 2273114402Sruface (or the font specified by the string @code{HF}), one size larger than 2274114402Sruthe base document size. Additionally, the left margin and the indentation 2275114402Srufor the following text is reset to its default value. 227675584Sru@endDefmac 227769626Sru 2278104862Sru@Defmac {SS, [@Var{heading}], man} 227975584SruSet up an unnumbered (sub)section heading. Prints out all the text 228075584Srufollowing @code{SS} up to the end of the line (or the text in the next 2281114402Sruline if there is no argument to @code{SS}) in bold face (or the font 2282114402Sruspecified by the string @code{HF}), at the same size as the base document 2283114402Srusize. Additionally, the left margin and the indentation for the 228475584Srufollowing text is reset to its default value. 228575584Sru@endDefmac 228669626Sru 2287104862Sru@Defmac {TP, [@Var{nnn}], man} 228875584SruSet up an indented paragraph with label. The indentation is set to 228975584Sru@var{nnn} if that argument is supplied (the default unit is @samp{n} 2290114402Sruif omitted), otherwise it is set to the previous indentation value 2291114402Sruspecified with @code{TP}, @code{IP}, or @code{HP} (or to the default 2292114402Sruvalue if none of them have been used yet). 229369626Sru 229469626SruThe first line of text following this macro is interpreted as a string 229569626Sruto be printed flush-left, as it is appropriate for a label. It is not 229669626Sruinterpreted as part of a paragraph, so there is no attempt to fill the 229769626Srufirst line with text from the following input lines. Nevertheless, if 2298114402Sruthe label is not as wide as the indentation the paragraph starts 229975584Sruat the same line (but indented), continuing on the following lines. 2300114402SruIf the label is wider than the indentation the descriptive part 230175584Sruof the paragraph begins on the line following the label, entirely 230275584Sruindented. Note that neither font shape nor font size of the label is 230375584Sruset to a default value; on the other hand, the rest of the text has 230475584Srudefault font settings. 230575584Sru@endDefmac 230669626Sru 2307104862Sru@DefmacList {LP, , man} 2308104862Sru@DefmacItem {PP, , man} 2309104862Sru@DefmacListEnd {P, , man} 231075584SruThese macros are mutual aliases. Any of them causes a line break at 231175584Sruthe current position, followed by a vertical space downwards by the 231275584Sruamount specified by the @code{PD} macro. The font size and shape are 2313104862Srureset to the default value (10@dmn{pt} roman if no @option{-rS} option 2314114402Sruis given on the command line). Finally, the current left margin and the 2315114402Sruindentation is restored. 231675584Sru@endDefmac 231769626Sru 2318104862Sru@Defmac {IP, [@Var{designator} [@Var{nnn}]], man} 231975584SruSet up an indented paragraph, using @var{designator} as a tag to mark 232075584Sruits beginning. The indentation is set to @var{nnn} if that argument 2321114402Sruis supplied (default unit is @samp{n}), otherwise it is set to the 2322114402Sruprevious indentation value specified with @code{TP}, @code{IP}, or 2323114402Sru@code{HP} (or the default value if none of them have been used yet). 2324114402SruFont size and face of the paragraph (but not the designator) are reset 2325114402Sruto their default values. 2326114402Sru 2327114402SruTo start an indented paragraph with a particular indentation but without 2328114402Srua designator, use @samp{""} (two double quotes) as the first argument of 232975584Sru@code{IP}. 233069626Sru 233169626SruFor example, to start a paragraph with bullets as the designator and 2332114402Sru4@tie{}en indentation, write 233369626Sru 233475584Sru@Example 233569626Sru.IP \(bu 4 233675584Sru@endExample 233775584Sru@endDefmac 233869626Sru 2339104862Sru@Defmac {HP, [@Var{nnn}], man} 2340104862Sru@cindex hanging indentation [@code{man}] 2341104862Sru@cindex @code{man} macros, hanging indentation 234275584SruSet up a paragraph with hanging left indentation. The indentation is 234369626Sruset to @var{nnn} if that argument is supplied (default unit is 2344114402Sru@samp{n}), otherwise it is set to the previous indentation value 2345114402Sruspecified with @code{TP}, @code{IP}, or @code{HP} (or the default 2346114402Sruvalue if non of them have been used yet). Font size and face are reset 2347114402Sruto their default values. 234875584Sru@endDefmac 234969626Sru 2350104862Sru@Defmac {RS, [@Var{nnn}], man} 2351104862Sru@cindex left margin, how to move [@code{man}] 2352104862Sru@cindex @code{man} macros, moving left margin 235375584SruMove the left margin to the right by the value @var{nnn} if specified 2354114402Sru(default unit is @samp{n}); otherwise it is set to the previous 2355114402Sruindentation value specified with @code{TP}, @code{IP}, or @code{HP} 2356114402Sru(or to the default value if none of them have been used yet). The 2357114402Sruindentation value is then set to the default. 2358114402Sru 2359114402SruCalls to the @code{RS} macro can be nested. 236075584Sru@endDefmac 236169626Sru 2362104862Sru@Defmac {RE, [@Var{nnn}], man} 2363114402SruMove the left margin back to level @var{nnn}, restoring the previous left 2364114402Srumargin. If no argument is given, it moves one level back. The first 2365114402Srulevel (i.e., no call to @code{RS} yet) has number@tie{}1, and each call 2366114402Sruto @code{RS} increases the level by@tie{}1. 236775584Sru@endDefmac 236869626Sru 2369104862Sru@cindex line breaks, with vertical space [@code{man}] 2370104862Sru@cindex @code{man} macros, line breaks with vertical space 237169626SruTo summarize, the following macros cause a line break with the insertion 237269626Sruof vertical space (which amount can be changed with the @code{PD} 237369626Srumacro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 237469626Sru@code{P}), @code{IP}, and @code{HP}. 237569626Sru 2376104862Sru@cindex line breaks, without vertical space [@code{man}] 2377104862Sru@cindex @code{man} macros, line breaks without vertical space 237869626SruThe macros @code{RS} and @code{RE} also cause a break but do not insert 237969626Sruvertical space. 238069626Sru 2381104862Sru@cindex default indentation, resetting [@code{man}] 2382104862Sru@cindex indentaion, resetting to default [@code{man}] 2383104862Sru@cindex @code{man} macros, resetting default indentation 2384104862SruFinally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}), 2385104862Sruand @code{RS} reset the indentation to its default value. 2386104862Sru 238769626Sru@c --------------------------------------------------------------------- 238869626Sru 238975584Sru@node Man font macros, Miscellaneous man macros, Man usage, man 239069626Sru@subsection Macros to set fonts 2391104862Sru@cindex font selection [@code{man}] 2392104862Sru@cindex @code{man} macros, how to set fonts 239369626Sru 2394114402SruThe standard font is roman; the default text size is 10@tie{}point. 2395104862SruIf command line option @option{-rS=@var{n}} is given, use 2396104862Sru@var{n}@dmn{pt} as the default text size. 239769626Sru 2398104862Sru@Defmac {SM, [@Var{text}], man} 239975584SruSet the text on the same line or the text on the next line in a font 240075584Sruthat is one point size smaller than the default font. 240175584Sru@endDefmac 240269626Sru 2403104862Sru@Defmac {SB, [@Var{text}], man} 2404104862Sru@cindex bold face [@code{man}] 2405104862Sru@cindex @code{man} macros, bold face 2406104862SruSet the text on the same line or the text on the next line in bold face 240775584Srufont, one point size smaller than the default font. 240875584Sru@endDefmac 240969626Sru 2410104862Sru@Defmac {BI, text, man} 2411114402SruSet its arguments alternately in bold face and italic, without a space 2412114402Srubetween the arguments. Thus, 241369626Sru 241475584Sru@Example 241569626Sru.BI this "word and" that 241675584Sru@endExample 241769626Sru 241869626Sru@noindent 2419114402Sruproduces ``thisword andthat'' with ``this'' and ``that'' in bold face, 2420114402Sruand ``word and'' in italics. 242175584Sru@endDefmac 242269626Sru 2423104862Sru@Defmac {IB, text, man} 2424114402SruSet its arguments alternately in italic and bold face, without a space 2425114402Srubetween the arguments. 242675584Sru@endDefmac 242769626Sru 2428104862Sru@Defmac {RI, text, man} 2429114402SruSet its arguments alternately in roman and italic, without a space between 2430114402Sruthe arguments. 243175584Sru@endDefmac 243269626Sru 2433104862Sru@Defmac {IR, text, man} 2434114402SruSet its arguments alternately in italic and roman, without a space between 2435114402Sruthe arguments. 243675584Sru@endDefmac 243769626Sru 2438104862Sru@Defmac {BR, text, man} 2439114402SruSet its arguments alternately in bold face and roman, without a space 2440114402Srubetween the arguments. 244175584Sru@endDefmac 244269626Sru 2443104862Sru@Defmac {RB, text, man} 2444114402SruSet its arguments alternately in roman and bold face, without a space 2445114402Srubetween the arguments. 244675584Sru@endDefmac 244769626Sru 2448104862Sru@Defmac {B, [@Var{text}], man} 244975584SruSet @var{text} in bold face. If no text is present on the line where 245075584Sruthe macro is called, then the text of the next line appears in bold 245175584Sruface. 245275584Sru@endDefmac 245369626Sru 2454104862Sru@Defmac {I, [@Var{text}], man} 2455104862Sru@cindex italic fonts [@code{man}] 2456104862Sru@cindex @code{man} macros, italic fonts 245775584SruSet @var{text} in italic. If no text is present on the line where the 245875584Srumacro is called, then the text of the next line appears in italic. 245975584Sru@endDefmac 246069626Sru 246169626Sru@c --------------------------------------------------------------------- 246269626Sru 246375584Sru@node Miscellaneous man macros, Predefined man strings, Man font macros, man 246475584Sru@subsection Miscellaneous macros 246569626Sru 246669626Sru@pindex grohtml 2467104862Sru@cindex @code{man} macros, default indentation 2468104862Sru@cindex default indentation [@code{man}] 2469114402SruThe default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in 2470114402Srunroff mode except for @code{grohtml} which ignores indentation. 247169626Sru 2472104862Sru@Defmac {DT, , man} 2473104862Sru@cindex tab stops [@code{man}] 2474104862Sru@cindex @code{man} macros, tab stops 2475114402SruSet tabs every 0.5@tie{}inches. Since this macro is always executed 2476104862Sruduring a call to the @code{TH} macro, it makes sense to call it only if 2477104862Sruthe tab positions have been changed. 247875584Sru@endDefmac 247969626Sru 2480104862Sru@Defmac {PD, [@Var{nnn}], man} 2481104862Sru@cindex empty space before a paragraph [@code{man}] 2482104862Sru@cindex @code{man} macros, empty space before a paragraph 248375584SruAdjust the empty space before a new paragraph (or section). The 248475584Sruoptional argument gives the amount of space (default unit is 248569626Sru@samp{v}); without parameter, the value is reset to its default value 2486114402Sru(1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise). 248769626Sru 248875584SruThis affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 248975584Sruwell as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2490114402Sru@endDefmac 249169626Sru 2492114402SruThe following two macros are included for 2493114402SruBSD compatibility. 2494114402Sru 2495114402Sru@Defmac {AT, [@Var{system} [@Var{release}]], man} 2496114402Sru@cindex @code{man}macros, BSD compatibility 2497114402SruAlter the footer for use with @acronym{AT&T} manpages. 2498114402SruThis command exists only for compatibility; don't use it. 2499114402SruThe first argument @var{system} can be: 2500114402Sru 2501114402Sru@table @code 2502114402Sru@item 3 2503114402Sru7th Edition (the default) 2504114402Sru 2505114402Sru@item 4 2506114402SruSystem III 2507114402Sru 2508114402Sru@item 5 2509114402SruSystem V 2510114402Sru@end table 2511114402Sru 2512114402SruAn optional second argument @var{release} to @code{AT} specifies the 2513114402Srurelease number (such as ``System V Release 3''). 2514114402Sru@endDefmac 2515114402Sru 2516114402Sru@Defmac {UC, [@Var{version}], man} 2517114402Sru@cindex @code{man}macros, BSD compatibility 2518114402SruAlters the footer for use with @acronym{BSD} manpages. 2519114402SruThis command exists only for compatibility; don't use it. 2520114402SruThe argument can be: 2521114402Sru 2522114402Sru@table @code 2523114402Sru@item 3 2524114402Sru3rd Berkeley Distribution (the default) 2525114402Sru 2526114402Sru@item 4 2527114402Sru4th Berkeley Distribution 2528114402Sru 2529114402Sru@item 5 2530114402Sru4.2 Berkeley Distribution 2531114402Sru 2532114402Sru@item 6 2533114402Sru4.3 Berkeley Distribution 2534114402Sru 2535114402Sru@item 7 2536114402Sru4.4 Berkeley Distribution 2537114402Sru@end table 2538114402Sru@endDefmac 2539114402Sru 254075584Sru@c --------------------------------------------------------------------- 254175584Sru 254275584Sru@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 254375584Sru@subsection Predefined strings 254475584Sru 254569626SruThe following strings are defined: 254669626Sru 2547104862Sru@Defstr {S, man} 254869626SruSwitch back to the default font size. 254975584Sru@endDefstr 255069626Sru 2551114402Sru@Defstr {HF, man} 2552114402SruThe typeface used for headings. 2553114402SruThe default is @samp{B}. 2554114402Sru@endDefstr 2555114402Sru 2556104862Sru@Defstr {R, man} 255769626SruThe `registered' sign. 255875584Sru@endDefstr 255969626Sru 2560104862Sru@Defstr {Tm, man} 256169626SruThe `trademark' sign. 256275584Sru@endDefstr 256369626Sru 2564104862Sru@DefstrList {lq, man} 2565104862Sru@DefstrListEnd {rq, man} 2566104862Sru@cindex @code{lq} glyph, and @code{lq} string [@code{man}] 2567104862Sru@cindex @code{rq} glyph, and @code{rq} string [@code{man}] 256875584SruLeft and right quote. This is equal to @code{\(lq} and @code{\(rq}, 256975584Srurespectively. 257075584Sru@endDefstr 257169626Sru 257275584Sru@c --------------------------------------------------------------------- 257375584Sru 2574114402Sru@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man 257575584Sru@subsection Preprocessors in @file{man} pages 257675584Sru 257769626Sru@cindex preprocessor, calling convention 257869626Sru@cindex calling convention of preprocessors 257969626SruIf a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 258069626Srubecome common usage to make the first line of the man page look like 258169626Sruthis: 258269626Sru 258375584Sru@Example 2584104862Sru'\" @var{word} 258575584Sru@endExample 258669626Sru 258769626Sru@pindex geqn@r{, invocation in manual pages} 258869626Sru@pindex grefer@r{, invocation in manual pages} 258969626Sru@pindex gtbl@r{, invocation in manual pages} 259069626Sru@pindex man@r{, invocation of preprocessors} 259175584Sru@noindent 259269626SruNote the single space character after the double quote. @var{word} 259369626Sruconsists of letters for the needed preprocessors: @samp{e} for 259469626Sru@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 259569626SruModern implementations of the @code{man} program read this first line 259669626Sruand automatically call the right preprocessor(s). 259769626Sru 2598114402Sru@c --------------------------------------------------------------------- 259969626Sru 2600114402Sru@node Optional man extensions, , Preprocessors in man pages, man 2601114402Sru@subsection Optional @file{man} extensions 2602114402Sru 2603114402Sru@pindex man.local 2604114402SruUse the file @file{man.local} for local extensions 2605114402Sruto the @code{man} macros or for style changes. 2606114402Sru 2607114402Sru@unnumberedsubsubsec Custom headers and footers 2608114402Sru@cindex @code{man} macros, custom headers and footers 2609114402Sru 2610114402SruIn groff versions 1.18.2 and later, you can specify custom 2611114402Sruheaders and footers by redefining the following macros in 2612114402Sru@file{man.local}. 2613114402Sru 2614114402Sru@Defmac {PT, , man} 2615114402SruControl the content of the headers. 2616114402SruNormally, the header prints the command name 2617114402Sruand section number on either side, and the 2618114402Sruoptional fifth argument to @code{TH} in the center. 2619114402Sru@endDefmac 2620114402Sru 2621114402Sru@Defmac {BT, , man} 2622114402SruControl the content of the footers. 2623114402SruNormally, the footer prints the page number 2624114402Sruand the third and fourth arguments to @code{TH}. 2625114402Sru 2626114402SruUse the @code{FT} number register to specify the 2627114402Srufooter position. 2628114402SruThe default is @minus{}0.5@dmn{i}. 2629114402Sru@endDefmac 2630114402Sru 2631114402Sru@unnumberedsubsubsec Ultrix-specific man macros 2632114402Sru@cindex Ultrix-specific @code{man} macros 2633114402Sru@cindex @code{man} macros, Ultrix-specific 2634114402Sru 2635114402Sru@pindex man.ultrix 2636114402SruThe @code{groff} source distribution includes 2637114402Srua file named @file{man.ultrix}, containing 2638114402Srumacros compatible with the Ultrix variant of 2639114402Sru@code{man}. 2640114402SruCopy this file into @file{man.local} (or use the @code{mso} request to 2641114402Sruload it) to enable the following macros. 2642114402Sru 2643114402Sru@Defmac {CT, @Var{key}, man} 2644114402SruPrint @samp{<CTRL/@var{key}>}. 2645114402Sru@endDefmac 2646114402Sru 2647114402Sru@Defmac {CW, , man} 2648114402SruPrint subsequent text using the constant width (Courier) typeface. 2649114402Sru@endDefmac 2650114402Sru 2651114402Sru@Defmac {Ds, , man} 2652114402SruBegin a non-filled display. 2653114402Sru@endDefmac 2654114402Sru 2655114402Sru@Defmac {De, , man} 2656114402SruEnd a non-filled display started with @code{Ds}. 2657114402Sru@endDefmac 2658114402Sru 2659114402Sru@Defmac {EX, [@Var{indent}], man} 2660114402SruBegins a non-filled display 2661114402Sruusing the constant width (Courier) typeface. 2662114402SruUse the optional @var{indent} argument to 2663114402Sruindent the display. 2664114402Sru@endDefmac 2665114402Sru 2666114402Sru@Defmac {EE, , man} 2667114402SruEnd a non-filled display started with @code{EX}. 2668114402Sru@endDefmac 2669114402Sru 2670114402Sru@Defmac {G, [@Var{text}], man} 2671114402SruSets @var{text} in Helvetica. 2672114402SruIf no text is present on the line where 2673114402Sruthe macro is called, then the text of the 2674114402Srunext line appears in Helvetica. 2675114402Sru@endDefmac 2676114402Sru 2677114402Sru@Defmac {GL, [@Var{text}], man} 2678114402SruSets @var{text} in Helvetica Oblique. 2679114402SruIf no text is present on the line where 2680114402Sruthe macro is called, then the text of the 2681114402Srunext line appears in Helvetica Oblique. 2682114402Sru@endDefmac 2683114402Sru 2684114402Sru@Defmac {HB, [@Var{text}], man} 2685114402SruSets @var{text} in Helvetica Bold. 2686114402SruIf no text is present on the line where 2687114402Sruthe macro is called, then all text up to 2688114402Sruthe next @code{HB} appears in Helvetica Bold. 2689114402Sru@endDefmac 2690114402Sru 2691114402Sru@Defmac {TB, [@Var{text}], man} 2692114402SruIdentical to @code{HB}. 2693114402Sru@endDefmac 2694114402Sru 2695114402Sru@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} 2696114402SruSet a manpage reference in Ultrix format. 2697114402SruThe @var{title} is in Courier instead of italic. 2698114402SruOptional punctuation follows the section number without 2699114402Sruan intervening space. 2700114402Sru@endDefmac 2701114402Sru 2702114402Sru@Defmac {NT, [@code{C}] [@Var{title}], man} 2703114402SruBegin a note. 2704114402SruPrint the optional @Var{title}, or the word ``Note'', 2705114402Srucentered on the page. 2706114402SruText following the macro makes up the body of the note, 2707114402Sruand is indented on both sides. 2708114402SruIf the first argument is @code{C}, the body of the 2709114402Srunote is printed centered (the second argument replaces 2710114402Sruthe word ``Note'' if specified). 2711114402Sru@endDefmac 2712114402Sru 2713114402Sru@Defmac {NE, , man} 2714114402SruEnd a note begun with @code{NT}. 2715114402Sru@endDefmac 2716114402Sru 2717114402Sru@Defmac {PN, @Var{path} [@Var{punct}], man} 2718114402SruSet the path name in constant width (Courier), 2719114402Srufollowed by optional punctuation. 2720114402Sru@endDefmac 2721114402Sru 2722114402Sru@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} 2723114402SruWhen called with two arguments, identical to @code{PN}. 2724114402SruWhen called with three arguments, 2725114402Sruset the second argument in constant width (Courier), 2726114402Srubracketed by the first and third arguments in the current font. 2727114402Sru@endDefmac 2728114402Sru 2729114402Sru@Defmac {R, , man} 2730114402SruSwitch to roman font and turn off any underlining in effect. 2731114402Sru@endDefmac 2732114402Sru 2733114402Sru@Defmac {RN, , man} 2734114402SruPrint the string @samp{<RETURN>}. 2735114402Sru@endDefmac 2736114402Sru 2737114402Sru@Defmac {VS, [@code{4}], man} 2738114402SruStart printing a change bar in the margin if 2739114402Sruthe number @code{4} is specified. 2740114402SruOtherwise, this macro does nothing. 2741114402Sru@endDefmac 2742114402Sru 2743114402Sru@Defmac {VE, , man} 2744114402SruEnd printing the change bar begun by @code{VS}. 2745114402Sru@endDefmac 2746114402Sru 2747114402Sru@unnumberedsubsubsec Simple example 2748114402Sru 2749114402SruThe following example @file{man.local} file 2750114402Srualters the @code{SH} macro to add some extra 2751114402Sruvertical space before printing the heading. 2752114402SruHeadings are printed in Helvetica Bold. 2753114402Sru 2754114402Sru@Example 2755114402Sru.\" Make the heading fonts Helvetica 2756114402Sru.ds HF HB 2757114402Sru. 2758114402Sru.\" Put more whitespace in front of headings. 2759114402Sru.rn SH SH-orig 2760114402Sru.de SH 2761114402Sru. if t .sp (u;\\n[PD]*2) 2762114402Sru. SH-orig \\$* 2763114402Sru.. 2764114402Sru@endExample 2765114402Sru 276669626Sru@c ===================================================================== 276769626Sru 276869626Sru@node mdoc, ms, man, Macro Packages 276969626Sru@section @file{mdoc} 2770104862Sru@cindex @code{mdoc} macros 277169626Sru 277269626Sru@c XXX documentation 2773104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 2774104862SruSee the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc} 2775104862Sruat the command line). 277669626Sru 277769626Sru 277869626Sru@c ===================================================================== 277969626Sru 278069626Sru@node ms, me, mdoc, Macro Packages 278169626Sru@section @file{ms} 2782104862Sru@cindex @code{ms} macros 278369626Sru 2784151497SruThe @file{-ms} macros are suitable for reports, letters, books, user 2785151497Srumanuals, and so forth. The package provides macros for cover pages, 2786151497Srusection headings, paragraphs, lists, footnotes, pagination, and a 2787151497Srutable of contents. 278869626Sru 2789104862Sru@menu 2790104862Sru* ms Intro:: 2791104862Sru* General ms Structure:: 2792104862Sru* ms Document Control Registers:: 2793104862Sru* ms Cover Page Macros:: 2794104862Sru* ms Body Text:: 2795104862Sru* ms Page Layout:: 2796104862Sru* Differences from AT&T ms:: 2797151497Sru* Naming Conventions:: 2798104862Sru@end menu 279969626Sru 2800104862Sru@c --------------------------------------------------------------------- 2801104862Sru 2802104862Sru@node ms Intro, General ms Structure, ms, ms 2803104862Sru@subsection Introduction to @file{ms} 2804104862Sru 2805151497SruThe original @file{-ms} macros were included with @acronym{AT&T} 2806151497Sru@code{troff} as well as the @file{man} macros. While the @file{man} 2807151497Srupackage is intended for brief documents that can be read on-line as 2808151497Sruwell as printed, the @file{ms} macros are suitable for longer 2809151497Srudocuments that are meant to be printed rather than read on-line. 2810104862Sru 2811151497SruThe @file{ms} macro package included with @code{groff} is a complete, 2812151497Srubottom-up re-implementation. Several macros (specific to 2813151497Sru@acronym{AT&T} or Berkeley) are not included, while several new 2814151497Srucommands are. @xref{Differences from AT&T ms}, for more information. 2815104862Sru 2816104862Sru@c --------------------------------------------------------------------- 2817104862Sru 2818104862Sru@node General ms Structure, ms Document Control Registers, ms Intro, ms 2819104862Sru@subsection General structure of an @file{ms} document 2820104862Sru@cindex @code{ms} macros, general structure 2821104862Sru 2822151497SruThe @file{ms} macro package expects a certain amount of structure, but 2823151497Srunot as much as packages such as @file{man} or @file{mdoc}. 2824104862Sru 2825151497SruThe simplest documents can begin with a paragraph macro (such as 2826151497Sru@code{LP} or @code{PP}), and consist of text separated by paragraph 2827151497Srumacros or even blank lines. Longer documents have a structure as 2828151497Srufollows: 2829104862Sru 2830104862Sru@table @strong 2831104862Sru@item Document type 2832151497SruIf you invoke the @code{RP} (report) macro on the first line of the 2833151497Srudocument, @code{groff} prints the cover page information on its own 2834151497Srupage; otherwise it prints the information on the first page with your 2835151497Srudocument text immediately following. Other document formats found in 2836151497Sru@acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or 2837151497SruBerkeley, and are not supported in @code{groff}. 2838104862Sru 2839104862Sru@item Format and layout 2840151497SruBy setting number registers, you can change your document's type (font 2841151497Sruand size), margins, spacing, headers and footers, and footnotes. 2842104862Sru@xref{ms Document Control Registers}, for more details. 2843104862Sru 2844104862Sru@item Cover page 2845104862SruA cover page consists of a title, the author's name and institution, 2846151497Sruan abstract, and the date.@footnote{Actually, only the title is 2847151497Srurequired.} @xref{ms Cover Page Macros}, for more details. 2848104862Sru 2849104862Sru@item Body 2850151497SruFollowing the cover page is your document. You can use the @file{ms} 2851151497Srumacros to write reports, letters, books, and so forth. The package is 2852151497Srudesigned for structured documents, consisting of paragraphs 2853151497Sruinterspersed with headings and augmented by lists, footnotes, tables, 2854151497Sruand other common constructs. @xref{ms Body Text}, for more details. 2855104862Sru 2856104862Sru@item Table of contents 2857151497SruLonger documents usually include a table of contents, which you can 2858151497Sruinvoke by placing the @code{TC} macro at the end of your document. 2859151497SruThe @file{ms} macros have minimal indexing facilities, consisting of 2860151497Sruthe @code{IX} macro, which prints an entry on standard error. 2861104862SruPrinting the table of contents at the end is necessary since 2862151497Sru@code{groff} is a single-pass text formatter, thus it cannot determine 2863151497Sruthe page number of each section until that section has actually been 2864151497Sruset and printed. Since @file{ms} output is intended for hardcopy, you 2865151497Srucan manually relocate the pages containing the table of contents 2866151497Srubetween the cover page and the body text after printing. 2867104862Sru@end table 2868104862Sru 2869104862Sru@c --------------------------------------------------------------------- 2870104862Sru 2871104862Sru@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms 2872104862Sru@subsection Document control registers 2873104862Sru@cindex @code{ms} macros, document control registers 2874104862Sru 2875151497SruThe following is a list of document control number registers. For the 2876151497Srusake of consistency, set registers related to margins at the beginning 2877151497Sruof your document, or just after the @code{RP} macro. You can set 2878151497Sruother registers later in your document, but you should keep them 2879151497Srutogether at the beginning to make them easy to find and edit as 2880151497Srunecessary. 2881104862Sru 2882104862Sru@unnumberedsubsubsec Margin Settings 2883104862Sru 2884104862Sru@Defmpreg {PO, ms} 2885151497SruDefines the page offset (i.e., the left margin). There is no explicit 2886151497Sruright margin setting; the combination of the @code{PO} and @code{LL} 2887151497Sruregisters implicitly define the right margin width. 2888104862Sru 2889104862SruEffective: next page. 2890104862Sru 2891104862SruDefault value: 1@dmn{i}. 2892104862Sru@endDefmpreg 2893104862Sru 2894104862Sru@Defmpreg {LL, ms} 2895151497SruDefines the line length (i.e., the width of the body text). 2896104862Sru 2897104862SruEffective: next paragraph. 2898104862Sru 2899104862SruDefault: 6@dmn{i}. 2900104862Sru@endDefmpreg 2901104862Sru 2902104862Sru@Defmpreg {LT, ms} 2903151497SruDefines the title length (i.e., the header and footer width). This 2904151497Sruis usually the same as @code{LL}, but not necessarily. 2905104862Sru 2906104862SruEffective: next paragraph. 2907104862Sru 2908104862SruDefault: 6@dmn{i}. 2909104862Sru@endDefmpreg 2910104862Sru 2911104862Sru@Defmpreg {HM, ms} 2912104862SruDefines the header margin height at the top of the page. 2913104862Sru 2914104862SruEffective: next page. 2915104862Sru 2916104862SruDefault: 1@dmn{i}. 2917104862Sru@endDefmpreg 2918104862Sru 2919104862Sru@Defmpreg {FM, ms} 2920104862SruDefines the footer margin height at the bottom of the page. 2921104862Sru 2922104862SruEffective: next page. 2923104862Sru 2924104862SruDefault: 1@dmn{i}. 2925104862Sru@endDefmpreg 2926104862Sru 2927104862Sru@unnumberedsubsubsec Text Settings 2928104862Sru 2929104862Sru@Defmpreg {PS, ms} 2930151497SruDefines the point size of the body text. If the value is larger than 2931151497Sruor equal to 1000, divide it by 1000 to get a fractional point size. 2932151497SruFor example, @samp{.nr PS 10250} sets the document's point size to 2933151497Sru10.25@dmn{p}. 2934104862Sru 2935104862SruEffective: next paragraph. 2936104862Sru 2937104862SruDefault: 10@dmn{p}. 2938104862Sru@endDefmpreg 2939104862Sru 2940104862Sru@Defmpreg {VS, ms} 2941151497SruDefines the space between lines (line height plus leading). If the 2942151497Sruvalue is larger than or equal to 1000, divide it by 1000 to get a 2943151497Srufractional point size. Due to backwards compatibility, @code{VS} must 2944151497Srube smaller than 40000 (this is 40.0@dmn{p}). 2945104862Sru 2946104862SruEffective: next paragraph. 2947104862Sru 2948104862SruDefault: 12@dmn{p}. 2949104862Sru@endDefmpreg 2950104862Sru 2951151497Sru@Defmpreg {PSINCR, ms} 2952151497SruDefines an increment in point size, which will be applied to section 2953151497Sruheadings at nesting levels below the value specified in @code{GROWPS}. 2954151497SruThe value of @code{PSINCR} should be specified in points, with the 2955151497Sru@dmn{p} scaling factor, and may include a fractional component; for 2956151497Sruexample, @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 2957151497Sru1.5@dmn{p}. 2958151497Sru 2959151497SruEffective: next section heading. 2960151497Sru 2961151497SruDefault: 1@dmn{p}. 2962151497Sru@endDefmpreg 2963151497Sru 2964151497Sru@Defmpreg {GROWPS, ms} 2965151497SruDefines the heading level below which the point size increment set by 2966151497Sru@code{PSINCR} becomes effective. Section headings at and above the 2967151497Srulevel specified by @code{GROWPS} will be printed at the point size set 2968151497Sruby @code{PS}; for each level below the value of @code{GROWPS}, the 2969151497Srupoint size will be increased in steps equal to the value of 2970151497Sru@code{PSINCR}. Setting @code{GROWPS} to any value less than@tie{}2 2971151497Srudisables the incremental heading size feature. 2972151497Sru 2973151497SruEffective: next section heading. 2974151497Sru 2975151497SruDefault: 0. 2976151497Sru@endDefmpreg 2977151497Sru 2978151497Sru@Defmpreg {HY, ms} 2979151497SruDefines the hyphenation level. @code{HY} sets safely the value of the 2980151497Srulow-level @code{hy} register. Setting the value of @code{HY} 2981151497Sruto@tie{}0 is equivalent to using the @code{nh} request. 2982151497Sru 2983151497SruEffective: next paragraph. 2984151497Sru 2985151497SruDefault: 14. 2986151497Sru@endDefmpreg 2987151497Sru 2988151497Sru@Defmpreg {FAM, ms} 2989151497SruDefines the font family used to typeset the document. 2990151497Sru 2991151497SruEffective: next paragraph. 2992151497Sru 2993151497SruDefault: as defined in the output device. 2994151497Sru@endDefmpreg 2995151497Sru 2996104862Sru@unnumberedsubsubsec Paragraph Settings 2997104862Sru 2998104862Sru@Defmpreg {PI, ms} 2999151497SruDefines the initial indentation of a (@code{PP} macro) paragraph. 3000104862Sru 3001104862SruEffective: next paragraph. 3002104862Sru 3003104862SruDefault: 5@dmn{n}. 3004104862Sru@endDefmpreg 3005104862Sru 3006104862Sru@Defmpreg {PD, ms} 3007104862SruDefines the space between paragraphs. 3008104862Sru 3009104862SruEffective: next paragraph. 3010104862Sru 3011104862SruDefault: 0.3@dmn{v}. 3012104862Sru@endDefmpreg 3013104862Sru 3014104862Sru@Defmpreg {QI, ms} 3015151497SruDefines the indentation on both sides of a quoted (@code{QP} macro) 3016151497Sruparagraph. 3017104862Sru 3018104862SruEffective: next paragraph. 3019104862Sru 3020104862SruDefault: 5@dmn{n}. 3021104862Sru@endDefmpreg 3022104862Sru 3023151497Sru@Defmpreg {PORPHANS, ms} 3024151497SruDefines the minimum number of initial lines of any paragraph which 3025151497Srushould be kept together, to avoid orphan lines at the bottom of a 3026151497Srupage. If a new paragraph is started close to the bottom of a page, 3027151497Sruand there is insufficient space to accommodate @code{PORPHANS} lines 3028151497Srubefore an automatic page break, then the page break will be forced, 3029151497Srubefore the start of the paragraph. 3030151497Sru 3031151497SruEffective: next paragraph. 3032151497Sru 3033151497SruDefault: 1. 3034151497Sru@endDefmpreg 3035151497Sru 3036151497Sru@Defmpreg {HORPHANS, ms} 3037151497SruDefines the minimum number of lines of the following paragraph which 3038151497Srushould be kept together with any section heading introduced by the 3039151497Sru@code{NH} or @code{SH} macros. If a section heading is placed close 3040151497Sruto the bottom of a page, and there is insufficient space to 3041151497Sruaccommodate both the heading and at least @code{HORPHANS} lines of the 3042151497Srufollowing paragraph, before an automatic page break, then the page 3043151497Srubreak will be forced before the heading. 3044151497Sru 3045151497SruEffective: next paragraph. 3046151497Sru 3047151497SruDefault: 1. 3048151497Sru@endDefmpreg 3049151497Sru 3050104862Sru@unnumberedsubsubsec Footnote Settings 3051104862Sru 3052104862Sru@Defmpreg {FL, ms} 3053104862SruDefines the length of a footnote. 3054104862Sru 3055104862SruEffective: next footnote. 3056104862Sru 3057104862SruDefault: @math{@code{@\n[LL]} * 5 / 6}. 3058104862Sru@endDefmpreg 3059104862Sru 3060104862Sru@Defmpreg {FI, ms} 3061151497SruDefines the footnote indentation. 3062104862Sru 3063104862SruEffective: next footnote. 3064104862Sru 3065104862SruDefault: 2@dmn{n}. 3066104862Sru@endDefmpreg 3067104862Sru 3068104862Sru@Defmpreg {FF, ms} 3069104862SruThe footnote format: 3070104862Sru@table @code 3071104862Sru@item 0 3072151497SruPrint the footnote number as a superscript; indent the footnote 3073151497Sru(default). 3074104862Sru 3075104862Sru@item 1 3076151497SruPrint the number followed by a period (like 1.@:) and indent the 3077151497Srufootnote. 3078104862Sru 3079104862Sru@item 2 3080151497SruLike 1, without an indentation. 3081104862Sru 3082104862Sru@item 3 3083151497SruLike 1, but print the footnote number as a hanging paragraph. 3084104862Sru@end table 3085104862Sru 3086104862SruEffective: next footnote. 3087104862Sru 3088104862SruDefault: 0. 3089104862Sru@endDefmpreg 3090104862Sru 3091151497Sru@Defmpreg {FPS, ms} 3092151497SruDefines the footnote point size. If the value is larger than or equal 3093151497Sruto 1000, divide it by 1000 to get a fractional point size. 3094151497Sru 3095151497SruEffective: next footnote. 3096151497Sru 3097151497SruDefault: @math{@code{@\n[PS]} - 2}. 3098151497Sru@endDefmpreg 3099151497Sru 3100151497Sru@Defmpreg {FVS, ms} 3101151497SruDefines the footnote vertical spacing. If the value is larger than or 3102151497Sruequal to 1000, divide it by 1000 to get a fractional point size. 3103151497Sru 3104151497SruEffective: next footnote. 3105151497Sru 3106151497SruDefault: @math{@code{@\n[FPS]} + 2}. 3107151497Sru@endDefmpreg 3108151497Sru 3109151497Sru@Defmpreg {FPD, ms} 3110151497SruDefines the footnote paragraph spacing. 3111151497Sru 3112151497SruEffective: next footnote. 3113151497Sru 3114151497SruDefault: @math{@code{@\n[PD]} / 2}. 3115151497Sru@endDefmpreg 3116151497Sru 3117104862Sru@unnumberedsubsubsec Miscellaneous Number Registers 3118104862Sru 3119104862Sru@Defmpreg {MINGW, ms} 3120104862SruDefines the minimum width between columns in a multi-column document. 3121104862Sru 3122104862SruEffective: next page. 3123104862Sru 3124104862SruDefault: 2@dmn{n}. 3125104862Sru@endDefmpreg 3126104862Sru 3127104862Sru@c --------------------------------------------------------------------- 3128104862Sru 3129104862Sru@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms 3130104862Sru@subsection Cover page macros 3131104862Sru@cindex @code{ms} macros, cover page 3132104862Sru@cindex cover page macros, [@code{ms}] 3133104862Sru 3134151497SruUse the following macros to create a cover page for your document in 3135151497Sruthe order shown. 3136104862Sru 3137104862Sru@Defmac {RP, [@code{no}], ms} 3138151497SruSpecifies the report format for your document. The report format 3139151497Srucreates a separate cover page. The default action (no @code{RP} 3140151497Srumacro) is to print a subset of the cover page on page@tie{}1 of your 3141151497Srudocument. 3142104862Sru 3143151497SruIf you use the word @code{no} as an optional argument, @code{groff} 3144151497Sruprints a title page but does not repeat any of the title page 3145151497Sruinformation (title, author, abstract, etc.@:) on page@tie{}1 of the 3146151497Srudocument. 3147104862Sru@endDefmac 3148104862Sru 3149151497Sru@Defmac {P1, , ms} 3150151497Sru(P-one) Prints the header on page@tie{}1. The default is to suppress 3151151497Sruthe header. 3152151497Sru@endDefmac 3153151497Sru 3154104862Sru@Defmac {DA, [@dots{}], ms} 3155151497Sru(optional) Prints the current date, or the arguments to the macro if 3156151497Sruany, on the title page (if specified) and in the footers. This is the 3157151497Srudefault for @code{nroff}. 3158104862Sru@endDefmac 3159104862Sru 3160104862Sru@Defmac {ND, [@dots{}], ms} 3161151497Sru(optional) Prints the current date, or the arguments to the macro if 3162151497Sruany, on the title page (if specified) but not in the footers. This is 3163151497Sruthe default for @code{troff}. 3164104862Sru@endDefmac 3165104862Sru 3166104862Sru@Defmac {TL, , ms} 3167151497SruSpecifies the document title. @code{groff} collects text following 3168151497Sruthe @code{TL} macro into the title, until reaching the author name or 3169151497Sruabstract. 3170104862Sru@endDefmac 3171104862Sru 3172104862Sru@Defmac {AU, , ms} 3173151497SruSpecifies the author's name, which appears on the line (or lines) 3174151497Sruimmediately following. You can specify multiple authors as follows: 3175104862Sru 3176104862Sru@Example 3177104862Sru.AU 3178104862SruJohn Doe 3179104862Sru.AI 3180104862SruUniversity of West Bumblefuzz 3181104862Sru.AU 3182104862SruMartha Buck 3183104862Sru.AI 3184104862SruMonolithic Corporation 3185104862Sru 3186104862Sru... 3187104862Sru@endExample 3188104862Sru@endDefmac 3189104862Sru 3190104862Sru@Defmac {AI, , ms} 3191151497SruSpecifies the author's institution. You can specify multiple 3192151497Sruinstitutions in the same way that you specify multiple authors. 3193104862Sru@endDefmac 3194104862Sru 3195104862Sru@Defmac {AB, [@code{no}], ms} 3196151497SruBegins the abstract. The default is to print the word 3197151497Sru@acronym{ABSTRACT}, centered and in italics, above the text of the 3198151497Sruabstract. The word @code{no} as an optional argument suppresses this 3199151497Sruheading. 3200104862Sru@endDefmac 3201104862Sru 3202104862Sru@Defmac {AE, , ms} 3203151497SruEnds the abstract. 3204104862Sru@endDefmac 3205104862Sru 3206104862SruThe following is example mark-up for a title page. 3207104862Sru@cindex title page, example markup 3208104862Sru@cindex example markup, title page 3209104862Sru 3210104862Sru@Example 3211104862Sru@cartouche 3212104862Sru.RP 3213104862Sru.TL 3214104862SruThe Inevitability of Code Bloat 3215104862Sruin Commercial and Free Software 3216104862Sru.AU 3217104862SruJ. Random Luser 3218104862Sru.AI 3219104862SruUniversity of West Bumblefuzz 3220104862Sru.AB 3221104862SruThis report examines the long-term growth 3222104862Sruof the code bases in two large, popular software 3223104862Srupackages; the free Emacs and the commercial 3224104862SruMicrosoft Word. 3225104862SruWhile differences appear in the type or order 3226104862Sruof features added, due to the different 3227104862Srumethodologies used, the results are the same 3228104862Sruin the end. 3229104862Sru.PP 3230104862SruThe free software approach is shown to be 3231104862Srusuperior in that while free software can 3232104862Srubecome as bloated as commercial offerings, 3233104862Srufree software tends to have fewer serious 3234104862Srubugs and the added features are in line with 3235104862Sruuser demand. 3236104862Sru.AE 3237104862Sru 3238104862Sru... the rest of the paper follows ... 3239104862Sru@end cartouche 3240104862Sru@endExample 3241104862Sru 3242104862Sru@c --------------------------------------------------------------------- 3243104862Sru 3244104862Sru@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms 3245104862Sru@subsection Body text 3246104862Sru@cindex @code{ms} macros, body text 3247104862Sru 3248151497SruThis section describes macros used to mark up the body of your 3249151497Srudocument. Examples include paragraphs, sections, and other groups. 3250104862Sru 3251104862Sru@menu 3252104862Sru* Paragraphs in ms:: 3253104862Sru* Headings in ms:: 3254104862Sru* Highlighting in ms:: 3255104862Sru* Lists in ms:: 3256151497Sru* Indentation values in ms:: 3257104862Sru* Tabstops in ms:: 3258104862Sru* ms Displays and Keeps:: 3259104862Sru* ms Insertions:: 3260104862Sru* Example multi-page table:: 3261104862Sru* ms Footnotes:: 3262104862Sru@end menu 3263104862Sru 3264104862Sru@c --------------------------------------------------------------------- 3265104862Sru 3266104862Sru@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text 3267104862Sru@subsubsection Paragraphs 3268104862Sru@cindex @code{ms} macros, paragraph handling 3269104862Sru 3270104862SruThe following paragraph types are available. 3271104862Sru 3272151497Sru@DefmacList {PP, , ms} 3273151497Sru@DefmacListEnd {LP, , ms} 3274151497SruSets a paragraph with an initial indentation. 3275104862Sru@endDefmac 3276104862Sru 3277104862Sru@Defmac {QP, , ms} 3278151497SruSets a paragraph that is indented at both left and right margins. The 3279151497Srueffect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element. 3280104862SruThe next paragraph or heading returns margins to normal. 3281104862Sru@endDefmac 3282104862Sru 3283104862Sru@Defmac {XP, , ms} 3284151497SruSets a paragraph whose lines are indented, except for the first line. 3285104862SruThis is a Berkeley extension. 3286104862Sru@endDefmac 3287104862Sru 3288104862SruThe following markup uses all four paragraph macros. 3289104862Sru 3290104862Sru@Example 3291104862Sru@cartouche 3292104862Sru.NH 2 3293104862SruCases used in the study 3294104862Sru.LP 3295104862SruThe following software and versions were 3296104862Sruconsidered for this report. 3297104862Sru.PP 3298104862SruFor commercial software, we chose 3299104862Sru.B "Microsoft Word for Windows" , 3300104862Srustarting with version 1.0 through the 3301104862Srucurrent version (Word 2000). 3302104862Sru.PP 3303104862SruFor free software, we chose 3304104862Sru.B Emacs , 3305104862Srufrom its first appearance as a standalone 3306104862Srueditor through the current version (v20). 3307104862SruSee [Bloggs 2002] for details. 3308104862Sru.QP 3309104862SruFranklin's Law applied to software: 3310104862Srusoftware expands to outgrow both 3311104862SruRAM and disk space over time. 3312104862Sru.LP 3313104862SruBibliography: 3314104862Sru.XP 3315104862SruBloggs, Joseph R., 3316104862Sru.I "Everyone's a Critic" , 3317104862SruUnderground Press, March 2002. 3318104862SruA definitive work that answers all questions 3319104862Sruand criticisms about the quality and usability of 3320104862Srufree software. 3321104862Sru@end cartouche 3322104862Sru@endExample 3323104862Sru 3324151497SruThe @code{PORPHANS} register (@pxref{ms Document Control Registers}) 3325151497Sruoperates in conjunction with each of these macros, to inhibit the 3326151497Sruprinting of orphan lines at the bottom of any page. 3327151497Sru 3328104862Sru@c --------------------------------------------------------------------- 3329104862Sru 3330104862Sru@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text 3331104862Sru@subsubsection Headings 3332104862Sru@cindex @code{ms} macros, headings 3333104862Sru 3334104862SruUse headings to create a hierarchical structure for your document. 3335151497SruThe @file{ms} macros print headings in @strong{bold}, using the same 3336151497Srufont family and point size as the body text. 3337104862Sru 3338104862SruThe following describes the heading macros: 3339104862Sru 3340104862Sru@DefmacList {NH, @Var{curr-level}, ms} 3341104862Sru@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} 3342151497SruNumbered heading. The argument is either a numeric argument to 3343151497Sruindicate the level of the heading, or the letter@tie{}@code{S} 3344151497Srufollowed by numeric arguments to set the heading level explicitly. 3345104862Sru 3346104862SruIf you specify heading levels out of sequence, such as invoking 3347151497Sru@samp{.NH 3} after @samp{.NH 1}, @code{groff} prints a warning on 3348151497Srustandard error. 3349104862Sru@endDefmac 3350104862Sru 3351151497Sru@DefstrList {SN, ms} 3352151497Sru@DefstrItem {SN-DOT, ms} 3353151497Sru@DefstrListEnd {SN-NO-DOT, ms} 3354151497SruAfter invocation of @code{NH}, the assigned section number is made 3355151497Sruavailable in the strings @code{SN-DOT} (exactly as it appears in the 3356151497Sruprinted section heading) and @code{SN-NO-DOT} (with the final period 3357151497Sruomitted). The string @code{SN} is also defined, as an alias for 3358151497Sru@code{SN-DOT}; if preferred, you may redefine it as an alias for 3359151497Sru@code{SN-NO-DOT}, by including the initialization 3360151497Sru 3361151497Sru@Example 3362151497Sru.ds SN-NO-DOT 3363151497Sru.als SN SN-NO-DOT 3364151497Sru@endExample 3365151497Sru 3366151497Sru@noindent 3367151497Sru@strong{before} your first use of @code{NH}, or simply 3368151497Sru 3369151497Sru@Example 3370151497Sru.als SN SN-NO-DOT 3371151497Sru@endExample 3372151497Sru 3373151497Sru@noindent 3374151497Sru@strong{after} your first use of @code{NH}. 3375151497Sru@endDefstr 3376151497Sru 3377151497Sru@Defmac {SH, [@Var{match-level}], ms} 3378104862SruUnnumbered subheading. 3379151497Sru 3380151497SruThe optional @var{match-level} argument is a GNU extension. It is a 3381151497Srunumber indicating the level of the heading, in a manner analogous to 3382151497Sruthe @var{curr-level} argument to @code{.NH}. Its purpose is to match 3383151497Sruthe point size, at which the heading is printed, to the size of a 3384151497Srunumbered heading at the same level, when the @code{GROWPS} and 3385151497Sru@code{PSINCR} heading size adjustment mechanism is in effect. 3386151497Sru@xref{ms Document Control Registers}. 3387104862Sru@endDefmac 3388104862Sru 3389151497SruThe @code{HORPHANS} register (@pxref{ms Document Control Registers}) 3390151497Sruoperates in conjunction with the @code{NH} and @code{SH} macros, to 3391151497Sruinhibit the printing of orphaned section headings at the bottom of any 3392151497Srupage. 3393151497Sru 3394104862Sru@c --------------------------------------------------------------------- 3395104862Sru 3396104862Sru@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text 3397104862Sru@subsubsection Highlighting 3398104862Sru@cindex @code{ms} macros, highlighting 3399104862Sru 3400151497SruThe @file{ms} macros provide a variety of methods to highlight or 3401151497Sruemphasize text: 3402104862Sru 3403104862Sru@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3404151497SruSets its first argument in @strong{bold type}. If you specify a 3405151497Srusecond argument, @code{groff} prints it in the previous font after the 3406151497Srubold text, with no intervening space (this allows you to set 3407151497Srupunctuation after the highlighted text without highlighting the 3408151497Srupunctuation). Similarly, it prints the third argument (if any) in the 3409151497Sruprevious font @strong{before} the first argument. For example, 3410104862Sru 3411104862Sru@Example 3412104862Sru.B foo ) ( 3413104862Sru@endExample 3414104862Sru 3415104862Sruprints (@strong{foo}). 3416104862Sru 3417151497SruIf you give this macro no arguments, @code{groff} prints all text 3418151497Srufollowing in bold until the next highlighting, paragraph, or heading 3419151497Srumacro. 3420104862Sru@endDefmac 3421104862Sru 3422104862Sru@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3423151497SruSets its first argument in roman (or regular) type. It operates 3424151497Srusimilarly to the @code{B}@tie{}macro otherwise. 3425104862Sru@endDefmac 3426104862Sru 3427104862Sru@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3428151497SruSets its first argument in @emph{italic type}. It operates similarly 3429151497Sruto the @code{B}@tie{}macro otherwise. 3430104862Sru@endDefmac 3431104862Sru 3432104862Sru@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3433151497SruSets its first argument in a @code{constant width face}. It operates 3434151497Srusimilarly to the @code{B}@tie{}macro otherwise. 3435104862Sru@endDefmac 3436104862Sru 3437104862Sru@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3438151497SruSets its first argument in bold italic type. It operates similarly to 3439151497Sruthe @code{B}@tie{}macro otherwise. 3440104862Sru@endDefmac 3441104862Sru 3442104862Sru@Defmac {BX, [@Var{txt}], ms} 3443151497SruPrints its argument and draws a box around it. If you want to box a 3444151497Srustring that contains spaces, use a digit-width space (@code{\0}). 3445104862Sru@endDefmac 3446104862Sru 3447104862Sru@Defmac {UL, [@Var{txt} [@Var{post}]], ms} 3448151497SruPrints its first argument with an underline. If you specify a second 3449151497Sruargument, @code{groff} prints it in the previous font after the 3450151497Sruunderlined text, with no intervening space. 3451104862Sru@endDefmac 3452104862Sru 3453104862Sru@Defmac {LG, , ms} 3454151497SruPrints all text following in larger type (two points larger than the 3455151497Srucurrent point size) until the next font size, highlighting, paragraph, 3456151497Sruor heading macro. You can specify this macro multiple times to 3457151497Sruenlarge the point size as needed. 3458104862Sru@endDefmac 3459104862Sru 3460104862Sru@Defmac {SM, , ms} 3461151497SruPrints all text following in smaller type (two points smaller than the 3462151497Srucurrent point size) until the next type size, highlighting, paragraph, 3463151497Sruor heading macro. You can specify this macro multiple times to reduce 3464151497Sruthe point size as needed. 3465104862Sru@endDefmac 3466104862Sru 3467104862Sru@Defmac {NL, , ms} 3468151497SruPrints all text following in the normal point size (that is, the value 3469151497Sruof the @code{PS} register). 3470104862Sru@endDefmac 3471104862Sru 3472151497Sru@DefstrList {@Lbrace{}, ms} 3473151497Sru@DefstrListEnd {@Rbrace{}, ms} 3474151497SruText enclosed with @code{\*@{} and @code{\*@}} is printed as a 3475151497Srusuperscript. 3476151497Sru@endDefstr 3477151497Sru 3478104862Sru@c --------------------------------------------------------------------- 3479104862Sru 3480151497Sru@node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text 3481104862Sru@subsubsection Lists 3482104862Sru@cindex @code{ms} macros, lists 3483104862Sru 3484151497SruThe @code{IP} macro handles duties for all lists. 3485104862Sru 3486104862Sru@Defmac {IP, [@Var{marker} [@Var{width}]], ms} 3487151497SruThe @var{marker} is usually a bullet glyph (@code{\[bu]}) for 3488151497Sruunordered lists, a number (or auto-incrementing number register) for 3489151497Srunumbered lists, or a word or phrase for indented (glossary-style) 3490151497Srulists. 3491104862Sru 3492151497SruThe @var{width} specifies the indentation for the body of each list 3493151497Sruitem; its default unit is @samp{n}. Once specified, the indentation 3494151497Sruremains the same for all list items in the document until specified 3495151497Sruagain. 3496151497Sru 3497151497SruThe @code{PORPHANS} register (@pxref{ms Document Control Registers}) 3498151497Sruoperates in conjunction with the @code{IP} macro, to inhibit the 3499151497Sruprinting of orphaned list markers at the bottom of any page. 3500104862Sru@endDefmac 3501104862Sru 3502104862SruThe following is an example of a bulleted list. 3503104862Sru@cindex example markup, bulleted list [@code{ms}] 3504104862Sru@cindex bulleted list, example markup [@code{ms}] 3505104862Sru 3506104862Sru@Example 3507104862SruA bulleted list: 3508104862Sru.IP \[bu] 2 3509104862Srulawyers 3510104862Sru.IP \[bu] 3511104862Sruguns 3512104862Sru.IP \[bu] 3513104862Srumoney 3514104862Sru@endExample 3515104862Sru 3516104862SruProduces: 3517104862Sru 3518104862Sru@Example 3519104862SruA bulleted list: 3520104862Sru 3521104862Sruo lawyers 3522104862Sru 3523104862Sruo guns 3524104862Sru 3525104862Sruo money 3526104862Sru@endExample 3527104862Sru 3528104862SruThe following is an example of a numbered list. 3529104862Sru@cindex example markup, numbered list [@code{ms}] 3530104862Sru@cindex numbered list, example markup [@code{ms}] 3531104862Sru 3532104862Sru@Example 3533104862Sru.nr step 1 1 3534104862SruA numbered list: 3535104862Sru.IP \n[step] 3 3536104862Srulawyers 3537104862Sru.IP \n+[step] 3538104862Sruguns 3539104862Sru.IP \n+[step] 3540104862Srumoney 3541104862Sru@endExample 3542104862Sru 3543104862SruProduces: 3544104862Sru 3545104862Sru@Example 3546104862SruA numbered list: 3547104862Sru 3548104862Sru1. lawyers 3549104862Sru 3550104862Sru2. guns 3551104862Sru 3552104862Sru3. money 3553104862Sru@endExample 3554104862Sru 3555151497SruNote the use of the auto-incrementing number register in this example. 3556104862Sru 3557104862SruThe following is an example of a glossary-style list. 3558104862Sru@cindex example markup, glossary-style list [@code{ms}] 3559104862Sru@cindex glossary-style list, example markup [@code{ms}] 3560104862Sru 3561104862Sru@Example 3562104862SruA glossary-style list: 3563104862Sru.IP lawyers 0.4i 3564104862SruTwo or more attorneys. 3565104862Sru.IP guns 3566104862SruFirearms, preferably 3567104862Srularge-caliber. 3568104862Sru.IP money 3569104862SruGotta pay for those 3570104862Srulawyers and guns! 3571104862Sru@endExample 3572104862Sru 3573104862SruProduces: 3574104862Sru 3575104862Sru@Example 3576104862SruA glossary-style list: 3577104862Sru 3578104862Srulawyers 3579104862Sru Two or more attorneys. 3580104862Sru 3581104862Sruguns Firearms, preferably large-caliber. 3582104862Sru 3583104862Srumoney 3584104862Sru Gotta pay for those lawyers and guns! 3585104862Sru@endExample 3586104862Sru 3587151497SruIn the last example, the @code{IP} macro places the definition on the 3588151497Srusame line as the term if it has enough space; otherwise, it breaks to 3589151497Sruthe next line and starts the definition below the term. This may or 3590151497Srumay not be the effect you want, especially if some of the definitions 3591151497Srubreak and some do not. The following examples show two possible ways 3592151497Sruto force a break. 3593104862Sru 3594151497SruThe first workaround uses the @code{br} request to force a break after 3595151497Sruprinting the term or label. 3596104862Sru 3597104862Sru@Example 3598104862Sru@cartouche 3599104862SruA glossary-style list: 3600104862Sru.IP lawyers 0.4i 3601104862SruTwo or more attorneys. 3602104862Sru.IP guns 3603104862Sru.br 3604104862SruFirearms, preferably large-caliber. 3605104862Sru.IP money 3606104862SruGotta pay for those lawyers and guns! 3607104862Sru@end cartouche 3608104862Sru@endExample 3609104862Sru 3610104862SruThe second workaround uses the @code{\p} escape to force the break. 3611151497SruNote the space following the escape; this is important. If you omit 3612151497Sruthe space, @code{groff} prints the first word on the same line as the 3613151497Sruterm or label (if it fits) @strong{then} breaks the line. 3614104862Sru 3615104862Sru@Example 3616104862Sru@cartouche 3617104862SruA glossary-style list: 3618104862Sru.IP lawyers 0.4i 3619104862SruTwo or more attorneys. 3620104862Sru.IP guns 3621104862Sru\p Firearms, preferably large-caliber. 3622104862Sru.IP money 3623104862SruGotta pay for those lawyers and guns! 3624104862Sru@end cartouche 3625104862Sru@endExample 3626104862Sru 3627104862SruTo set nested lists, use the @code{RS} and @code{RE} macros. 3628151497Sru@xref{Indentation values in ms}, for more information. 3629104862Sru@cindex @code{ms} macros, nested lists 3630104862Sru@cindex nested lists [@code{ms}] 3631104862Sru 3632104862SruFor example: 3633104862Sru 3634104862Sru@Example 3635104862Sru@cartouche 3636104862Sru.IP \[bu] 2 3637104862SruLawyers: 3638104862Sru.RS 3639104862Sru.IP \[bu] 3640104862SruDewey, 3641104862Sru.IP \[bu] 3642104862SruCheatham, 3643104862Sru.IP \[bu] 3644104862Sruand Howe. 3645104862Sru.RE 3646104862Sru.IP \[bu] 3647104862SruGuns 3648104862Sru@end cartouche 3649104862Sru@endExample 3650104862Sru 3651104862SruProduces: 3652104862Sru 3653104862Sru@Example 3654104862Sruo Lawyers: 3655104862Sru 3656104862Sru o Dewey, 3657104862Sru 3658104862Sru o Cheatham, 3659104862Sru 3660104862Sru o and Howe. 3661104862Sru 3662104862Sruo Guns 3663104862Sru@endExample 3664104862Sru 3665104862Sru@c --------------------------------------------------------------------- 3666104862Sru 3667151497Sru@node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text 3668151497Sru@subsubsection Indentation values 3669104862Sru 3670151497SruIn many situations, you may need to indentation a section of text 3671151497Sruwhile still wrapping and filling. @xref{Lists in ms}, for an example 3672151497Sruof nested lists. 3673104862Sru 3674104862Sru@DefmacList {RS, , ms} 3675104862Sru@DefmacListEnd {RE, , ms} 3676151497SruThese macros begin and end an indented section. The @code{PI} 3677151497Sruregister controls the amount of indentation, allowing the indented 3678151497Srutext to line up under hanging and indented paragraphs. 3679104862Sru@endDefmac 3680104862Sru 3681151497Sru@xref{ms Displays and Keeps}, for macros to indentation and turn off 3682151497Srufilling. 3683104862Sru 3684104862Sru@c --------------------------------------------------------------------- 3685104862Sru 3686151497Sru@node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body Text 3687104862Sru@subsubsection Tab Stops 3688104862Sru 3689151497SruUse the @code{ta} request to define tab stops as needed. @xref{Tabs 3690151497Sruand Fields}. 3691104862Sru 3692104862Sru@Defmac{TA, , ms} 3693104862SruUse this macro to reset the tab stops to the default for @file{ms} 3694151497Sru(every 5n). You can redefine the @code{TA} macro to create a 3695151497Srudifferent set of default tab stops. 3696104862Sru@endDefmac 3697104862Sru 3698104862Sru@c --------------------------------------------------------------------- 3699104862Sru 3700104862Sru@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text 3701104862Sru@subsubsection Displays and keeps 3702104862Sru@cindex @code{ms} macros, displays 3703104862Sru@cindex @code{ms} macros, keeps 3704104862Sru@cindex keeps [@code{ms}] 3705104862Sru@cindex displays [@code{ms}] 3706104862Sru 3707151497SruUse displays to show text-based examples or figures (such as code 3708151497Srulistings). 3709104862Sru 3710151497SruDisplays turn off filling, so lines of code are displayed as-is 3711151497Sruwithout inserting @code{br} requests in between each line. Displays 3712151497Srucan be @dfn{kept} on a single page, or allowed to break across pages. 3713104862Sru 3714104862Sru@DefmacList {DS, @t{L}, ms} 3715104862Sru@DefmacItem {LD, , ms} 3716104862Sru@DefmacListEnd {DE, , ms} 3717151497SruLeft-justified display. The @samp{.DS L} call generates a page break, 3718151497Sruif necessary, to keep the entire display on one page. The @code{LD} 3719151497Srumacro allows the display to break across pages. The @code{DE} macro 3720151497Sruends the display. 3721104862Sru@endDefmac 3722104862Sru 3723104862Sru@DefmacList {DS, @t{I}, ms} 3724104862Sru@DefmacItem {ID, , ms} 3725104862Sru@DefmacListEnd {DE, , ms} 3726151497SruIndents the display as defined by the @code{DI} register. The 3727151497Sru@samp{.DS I} call generates a page break, if necessary, to keep the 3728151497Sruentire display on one page. The @code{ID} macro allows the display to 3729151497Srubreak across pages. The @code{DE} macro ends the display. 3730104862Sru@endDefmac 3731104862Sru 3732104862Sru@DefmacList {DS, @t{B}, ms} 3733104862Sru@DefmacItem {BD, , ms} 3734104862Sru@DefmacListEnd {DE, , ms} 3735104862SruSets a block-centered display: the entire display is left-justified, 3736151497Srubut indented so that the longest line in the display is centered on 3737151497Sruthe page. The @samp{.DS B} call generates a page break, if necessary, 3738151497Sruto keep the entire display on one page. The @code{BD} macro allows 3739151497Sruthe display to break across pages. The @code{DE} macro ends the 3740151497Srudisplay. 3741104862Sru@endDefmac 3742104862Sru 3743104862Sru@DefmacList {DS, @t{C}, ms} 3744104862Sru@DefmacItem {CD, , ms} 3745104862Sru@DefmacListEnd {DE, , ms} 3746151497SruSets a centered display: each line in the display is centered. The 3747151497Sru@samp{.DS C} call generates a page break, if necessary, to keep the 3748151497Sruentire display on one page. The @code{CD} macro allows the display to 3749151497Srubreak across pages. The @code{DE} macro ends the display. 3750104862Sru@endDefmac 3751104862Sru 3752104862Sru@DefmacList {DS, @t{R}, ms} 3753104862Sru@DefmacItem {RD, , ms} 3754104862Sru@DefmacListEnd {DE, , ms} 3755151497SruRight-justifies each line in the display. The @samp{.DS R} call 3756151497Srugenerates a page break, if necessary, to keep the entire display on 3757151497Sruone page. The @code{RD} macro allows the display to break across 3758151497Srupages. The @code{DE} macro ends the display. 3759104862Sru@endDefmac 3760104862Sru 3761151497Sru@DefmacList {Ds, , ms} 3762151497Sru@DefmacListEnd {De, , ms} 3763151497SruThese two macros were formerly provided as aliases for @code{DS} and 3764151497Sru@code{DE}, respectively. They have been removed, and should no longer 3765151497Srube used. The original implementations of @code{DS} and @code{DE} are 3766151497Sruretained, and should be used instead. X11 documents which actually 3767151497Sruuse @code{Ds} and @code{De} always load a specific macro file from the 3768151497SruX11 distribution (@file{macros.t}) which provides proper definitions 3769151497Srufor the two macros. 3770151497Sru@endDefmac 3771151497Sru 3772104862SruOn occasion, you may want to @dfn{keep} other text together on a page. 3773151497SruFor example, you may want to keep two paragraphs together, or a 3774151497Sruparagraph that refers to a table (or list, or other item) immediately 3775151497Srufollowing. The @file{ms} macros provide the @code{KS} and @code{KE} 3776104862Srumacros for this purpose. 3777104862Sru 3778104862Sru@DefmacList {KS, , ms} 3779104862Sru@DefmacListEnd {KE, , ms} 3780151497SruThe @code{KS} macro begins a block of text to be kept on a single 3781151497Srupage, and the @code{KE} macro ends the block. 3782104862Sru@endDefmac 3783104862Sru 3784104862Sru@DefmacList {KF, , ms} 3785104862Sru@DefmacListEnd {KE, , ms} 3786151497SruSpecifies a @dfn{floating keep}; if the keep cannot fit on the current 3787151497Srupage, @code{groff} holds the contents of the keep and allows text 3788151497Srufollowing the keep (in the source file) to fill in the remainder of 3789151497Sruthe current page. When the page breaks, whether by an explicit 3790151497Sru@code{bp} request or by reaching the end of the page, @code{groff} 3791151497Sruprints the floating keep at the top of the new page. This is useful 3792151497Srufor printing large graphics or tables that do not need to appear 3793151497Sruexactly where specified. 3794104862Sru@endDefmac 3795104862Sru 3796151497SruYou can also use the @code{ne} request to force a page break if there 3797151497Sruis not enough vertical space remaining on the page. 3798104862Sru 3799151497SruUse the following macros to draw a box around a section of text (such 3800151497Sruas a display). 3801104862Sru 3802104862Sru@DefmacList {B1, , ms} 3803104862Sru@DefmacListEnd {B2, , ms} 3804151497SruMarks the beginning and ending of text that is to have a box drawn 3805151497Sruaround it. The @code{B1} macro begins the box; the @code{B2} macro 3806151497Sruends it. Text in the box is automatically placed in a diversion 3807151497Sru(keep). 3808104862Sru@endDefmac 3809104862Sru 3810104862Sru@c --------------------------------------------------------------------- 3811104862Sru 3812104862Sru@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text 3813104862Sru@subsubsection Tables, figures, equations, and references 3814104862Sru@cindex @code{ms} macros, tables 3815104862Sru@cindex @code{ms} macros, figures 3816104862Sru@cindex @code{ms} macros, equations 3817104862Sru@cindex @code{ms} macros, references 3818104862Sru@cindex tables [@code{ms}] 3819104862Sru@cindex figures [@code{ms}] 3820104862Sru@cindex equations [@code{ms}] 3821104862Sru@cindex references [@code{ms}] 3822104862Sru 3823151497SruThe @file{ms} macros support the standard @code{groff} preprocessors: 3824104862Sru@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. 3825104862Sru@pindex tbl 3826104862Sru@pindex pic 3827104862Sru@pindex eqn 3828104862Sru@pindex refer 3829104862SruYou mark text meant for preprocessors by enclosing it 3830104862Sruin pairs of tags as follows. 3831104862Sru 3832104862Sru@DefmacList {TS, [@code{H}], ms} 3833104862Sru@DefmacListEnd {TE, , ms} 3834151497SruDenotes a table, to be processed by the @code{tbl} preprocessor. The 3835151497Sruoptional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to 3836151497Srucreate a running header with the information up to the @code{TH} 3837151497Srumacro. @code{groff} prints the header at the beginning of the table; 3838151497Sruif the table runs onto another page, @code{groff} prints the header on 3839151497Sruthe next page as well. 3840104862Sru@endDefmac 3841104862Sru 3842104862Sru@DefmacList {PS, , ms} 3843104862Sru@DefmacListEnd {PE, , ms} 3844104862SruDenotes a graphic, to be processed by the @code{pic} preprocessor. 3845104862SruYou can create a @code{pic} file by hand, using the @acronym{AT&T} 3846151497Sru@code{pic} manual available on the Web as a reference, or by using a 3847151497Srugraphics program such as @code{xfig}. 3848104862Sru@endDefmac 3849104862Sru 3850104862Sru@DefmacList {EQ, [@Var{align}], ms} 3851104862Sru@DefmacListEnd {EN, , ms} 3852104862SruDenotes an equation, to be processed by the @code{eqn} preprocessor. 3853114402SruThe optional @var{align} argument can be @code{C}, @code{L}, 3854114402Sruor@tie{}@code{I} to center (the default), left-justify, or indent the 3855114402Sruequation. 3856104862Sru@endDefmac 3857104862Sru 3858104862Sru@DefmacList {[, , ms} 3859104862Sru@DefmacListEnd {], , ms} 3860104862SruDenotes a reference, to be processed by the @code{refer} preprocessor. 3861104862SruThe @acronym{GNU} @cite{refer(1)} man page provides a comprehensive 3862104862Srureference to the preprocessor and the format of the bibliographic 3863104862Srudatabase. 3864104862Sru@endDefmac 3865104862Sru 3866104862Sru@menu 3867104862Sru* Example multi-page table:: 3868104862Sru@end menu 3869104862Sru 3870104862Sru@c --------------------------------------------------------------------- 3871104862Sru 3872104862Sru@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text 3873104862Sru@subsubsection An example multi-page table 3874104862Sru@cindex example markup, multi-page table [@code{ms}] 3875104862Sru@cindex multi-page table, example markup [@code{ms}] 3876104862Sru 3877151497SruThe following is an example of how to set up a table that may print 3878151497Sruacross two or more pages. 3879104862Sru 3880104862Sru@Example 3881104862Sru@cartouche 3882104862Sru.TS H 3883104862Sruallbox expand; 3884104862Srucb | cb . 3885104862SruText ...of heading... 3886104862Sru_ 3887104862Sru.TH 3888104862Sru.T& 3889104862Srul | l . 3890104862Sru... the rest of the table follows... 3891104862Sru.CW 3892104862Sru.TE 3893104862Sru@end cartouche 3894104862Sru@endExample 3895104862Sru 3896104862Sru@c --------------------------------------------------------------------- 3897104862Sru 3898104862Sru@node ms Footnotes, , Example multi-page table, ms Body Text 3899104862Sru@subsubsection Footnotes 3900104862Sru@cindex @code{ms} macros, footnotes 3901104862Sru@cindex footnotes [@code{ms}] 3902104862Sru 3903151497SruThe @file{ms} macro package has a flexible footnote system. You can 3904151497Sruspecify either numbered footnotes or symbolic footnotes (that is, 3905151497Sruusing a marker such as a dagger symbol). 3906104862Sru 3907104862Sru@Defstr {*, ms} 3908104862SruSpecifies the location of a numbered footnote marker in the text. 3909104862Sru@endDefesc 3910104862Sru 3911104862Sru@DefmacList {FS, , ms} 3912104862Sru@DefmacListEnd {FE, , ms} 3913151497SruSpecifies the text of the footnote. The default action is to create a 3914151497Srunumbered footnote; you can create a symbolic footnote by specifying a 3915151497Sru@dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the 3916151497Srubody text and as an argument to the @code{FS} macro, followed by the 3917151497Srutext of the footnote and the @code{FE} macro. 3918104862Sru@endDefmac 3919104862Sru 3920151497SruYou can control how @code{groff} prints footnote numbers by changing 3921151497Sruthe value of the @code{FF} register. @xref{ms Document Control 3922151497SruRegisters}. 3923104862Sru 3924151497Sru@cindex footnotes, and keeps [@code{ms}] 3925151497Sru@cindex keeps, and footnotes [@code{ms}] 3926151497Sru@cindex footnotes, and displays [@code{ms}] 3927151497Sru@cindex displays, and footnotes [@code{ms}] 3928151497SruFootnotes can be safely used within keeps and displays, but you should 3929151497Sruavoid using numbered footnotes within floating keeps. You can set a 3930151497Srusecond @code{\**} marker between a @code{\**} and its corresponding 3931151497Sru@code{.FS} entry; as long as each @code{FS} macro occurs @emph{after} 3932151497Sruthe corresponding @code{\**} and the occurrences of @code{.FS} are in 3933151497Sruthe same order as the corresponding occurrences of @code{\**}. 3934151497Sru 3935104862Sru@c --------------------------------------------------------------------- 3936104862Sru 3937104862Sru@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms 3938104862Sru@subsection Page layout 3939104862Sru@cindex @code{ms} macros, page layout 3940104862Sru@cindex page layout [@code{ms}] 3941104862Sru 3942151497SruThe default output from the @file{ms} macros provides a minimalist 3943151497Srupage layout: it prints a single column, with the page number centered 3944151497Sruat the top of each page. It prints no footers. 3945104862Sru 3946151497SruYou can change the layout by setting the proper number registers and 3947151497Srustrings. 3948104862Sru 3949104862Sru@menu 3950104862Sru* ms Headers and Footers:: 3951104862Sru* ms Margins:: 3952104862Sru* ms Multiple Columns:: 3953104862Sru* ms TOC:: 3954104862Sru* ms Strings and Special Characters:: 3955104862Sru@end menu 3956104862Sru 3957104862Sru@c --------------------------------------------------------------------- 3958104862Sru 3959104862Sru@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout 3960104862Sru@subsubsection Headers and footers 3961104862Sru@cindex @code{ms} macros, headers 3962104862Sru@cindex @code{ms} macros, footers 3963104862Sru@cindex headers [@code{ms}] 3964104862Sru@cindex footers [@code{ms}] 3965104862Sru 3966151497SruFor documents that do not distinguish between odd and even pages, set 3967151497Sruthe following strings: 3968104862Sru 3969104862Sru@DefstrList {LH, ms} 3970104862Sru@DefstrItem {CH, ms} 3971104862Sru@DefstrListEnd {RH, ms} 3972104862SruSets the left, center, and right headers. 3973104862Sru@endDefstr 3974104862Sru 3975104862Sru@DefstrList {LF, ms} 3976104862Sru@DefstrItem {CF, ms} 3977104862Sru@DefstrListEnd {RF, ms} 3978104862SruSets the left, center, and right footers. 3979104862Sru@endDefstr 3980104862Sru 3981151497SruFor documents that need different information printed in the even and 3982151497Sruodd pages, use the following macros: 3983104862Sru 3984104862Sru@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3985104862Sru@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3986104862Sru@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3987104862Sru@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3988151497SruThe @code{OH} and @code{EH} macros define headers for the odd and even 3989151497Srupages; the @code{OF} and @code{EF} macros define footers for the odd 3990151497Sruand even pages. This is more flexible than defining the individual 3991151497Srustrings. 3992104862Sru 3993104862SruYou can replace the quote (@code{'}) marks with any character not 3994104862Sruappearing in the header or footer text. 3995104862Sru@endDefmac 3996104862Sru 3997104862Sru@c --------------------------------------------------------------------- 3998104862Sru 3999104862Sru@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout 4000104862Sru@subsubsection Margins 4001104862Sru@cindex @code{ms} macros, margins 4002104862Sru 4003151497SruYou control margins using a set of number registers. @xref{ms 4004151497SruDocument Control Registers}, for details. 4005104862Sru 4006104862Sru@c --------------------------------------------------------------------- 4007104862Sru 4008104862Sru@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout 4009104862Sru@subsubsection Multiple columns 4010104862Sru@cindex @code{ms} macros, multiple columns 4011104862Sru@cindex multiple columns [@code{ms}] 4012104862Sru 4013104862SruThe @file{ms} macros can set text in as many columns as will 4014151497Srureasonably fit on the page. The following macros are available; all 4015151497Sruof them force a page break if a multi-column mode is already set. 4016104862SruHowever, if the current mode is single-column, starting a multi-column 4017151497Srumode does @emph{not} force a page break. 4018104862Sru 4019104862Sru@Defmac {1C, , ms} 4020104862SruSingle-column mode. 4021104862Sru@endDefmac 4022104862Sru 4023104862Sru@Defmac {2C, , ms} 4024104862SruTwo-column mode. 4025104862Sru@endDefmac 4026104862Sru 4027104862Sru@Defmac {MC, [@Var{width} [@Var{gutter}]], ms} 4028151497SruMulti-column mode. If you specify no arguments, it is equivalent to 4029151497Sruthe @code{2C} macro. Otherwise, @var{width} is the width of each 4030151497Srucolumn and @var{gutter} is the space between columns. The 4031151497Sru@code{MINGW} number register controls the default gutter width. 4032104862Sru@endDefmac 4033104862Sru 4034104862Sru@c --------------------------------------------------------------------- 4035104862Sru 4036104862Sru@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout 4037104862Sru@subsubsection Creating a table of contents 4038104862Sru@cindex @code{ms} macros, creating table of contents 4039104862Sru@cindex table of contents, creating [@code{ms}] 4040104862Sru 4041151497SruThe facilities in the @file{ms} macro package for creating a table of 4042151497Srucontents are semi-automated at best. Assuming that you want the table 4043151497Sruof contents to consist of the document's headings, you need to repeat 4044151497Sruthose headings wrapped in @code{XS} and @code{XE} macros. 4045104862Sru 4046104862Sru@DefmacList {XS, [@Var{page}], ms} 4047104862Sru@DefmacItem {XA, [@Var{page}], ms} 4048104862Sru@DefmacListEnd {XE, , ms} 4049151497SruThese macros define a table of contents or an individual entry in the 4050151497Srutable of contents, depending on their use. The macros are very 4051151497Srusimple; they cannot indent a heading based on its level. The easiest 4052151497Sruway to work around this is to add tabs to the table of contents 4053151497Srustring. The following is an example: 4054104862Sru 4055104862Sru@Example 4056104862Sru@cartouche 4057104862Sru.NH 1 4058104862SruIntroduction 4059104862Sru.XS 4060104862SruIntroduction 4061104862Sru.XE 4062104862Sru.LP 4063104862Sru... 4064104862Sru.CW 4065104862Sru.NH 2 4066104862SruMethodology 4067104862Sru.XS 4068114402SruMethodology 4069104862Sru.XE 4070104862Sru.LP 4071104862Sru... 4072104862Sru@end cartouche 4073104862Sru@endExample 4074104862Sru 4075151497SruYou can manually create a table of contents by beginning with the 4076151497Sru@code{XS} macro for the first entry, specifying the page number for 4077151497Sruthat entry as the argument to @code{XS}. Add subsequent entries using 4078151497Sruthe @code{XA} macro, specifying the page number for that entry as the 4079151497Sruargument to @code{XA}. The following is an example: 4080104862Sru 4081104862Sru@Example 4082104862Sru@cartouche 4083104862Sru.XS 1 4084104862SruIntroduction 4085104862Sru.XA 2 4086104862SruA Brief History of the Universe 4087104862Sru.XA 729 4088104862SruDetails of Galactic Formation 4089104862Sru... 4090104862Sru.XE 4091104862Sru@end cartouche 4092104862Sru@endExample 4093104862Sru@endDefmac 4094104862Sru 4095104862Sru@Defmac {TC, [@code{no}], ms} 4096151497SruPrints the table of contents on a new page, setting the page number 4097151497Sruto@tie{}@strong{i} (Roman lowercase numeral one). You should usually 4098151497Sruplace this macro at the end of the file, since @code{groff} is a 4099151497Srusingle-pass formatter and can only print what has been collected up to 4100151497Sruthe point that the @code{TC} macro appears. 4101104862Sru 4102151497SruThe optional argument @code{no} suppresses printing the title 4103151497Sruspecified by the string register @code{TOC}. 4104104862Sru@endDefmac 4105104862Sru 4106104862Sru@Defmac{PX, [@code{no}], ms} 4107151497SruPrints the table of contents on a new page, using the current page 4108151497Srunumbering sequence. Use this macro to print a manually-generated 4109151497Srutable of contents at the beginning of your document. 4110104862Sru 4111151497SruThe optional argument @code{no} suppresses printing the title 4112151497Sruspecified by the string register @code{TOC}. 4113104862Sru@endDefmac 4114104862Sru 4115151497SruThe @cite{Groff and Friends HOWTO} includes a @code{sed} script that 4116151497Sruautomatically inserts @code{XS} and @code{XE} macro entries after each 4117151497Sruheading in a document. 4118104862Sru 4119151497SruAltering the @code{NH} macro to automatically build the table of 4120151497Srucontents is perhaps initially more difficult, but would save a great 4121151497Srudeal of time in the long run if you use @file{ms} regularly. 4122104862Sru 4123104862Sru@c --------------------------------------------------------------------- 4124104862Sru 4125104862Sru@node ms Strings and Special Characters, , ms TOC, ms Page Layout 4126104862Sru@subsubsection Strings and Special Characters 4127104862Sru@cindex @code{ms} macros, strings 4128104862Sru@cindex @code{ms} macros, special characters 4129104862Sru@cindex @code{ms} macros, accent marks 4130104862Sru@cindex accent marks [@code{ms}] 4131104862Sru@cindex special characters [@code{ms}] 4132104862Sru@cindex strings [@code{ms}] 4133104862Sru 4134151497SruThe @file{ms} macros provide the following predefined strings. You 4135151497Srucan change the string definitions to help in creating documents in 4136151497Srulanguages other than English. 4137104862Sru 4138104862Sru@Defstr {REFERENCES, ms} 4139151497SruContains the string printed at the beginning of the references 4140151497Sru(bibliography) page. The default is @samp{References}. 4141104862Sru@endDefstr 4142104862Sru 4143104862Sru@Defstr {ABSTRACT, ms} 4144151497SruContains the string printed at the beginning of the abstract. The 4145151497Srudefault is @samp{ABSTRACT}. 4146104862Sru@endDefstr 4147104862Sru 4148104862Sru@Defstr {TOC, ms} 4149104862SruContains the string printed at the beginning of the table of contents. 4150104862Sru@endDefstr 4151104862Sru 4152104862Sru@DefstrList {MONTH1, ms} 4153104862Sru@DefstrItem {MONTH2, ms} 4154104862Sru@DefstrItem {MONTH3, ms} 4155104862Sru@DefstrItem {MONTH4, ms} 4156104862Sru@DefstrItem {MONTH5, ms} 4157104862Sru@DefstrItem {MONTH6, ms} 4158104862Sru@DefstrItem {MONTH7, ms} 4159104862Sru@DefstrItem {MONTH8, ms} 4160104862Sru@DefstrItem {MONTH9, ms} 4161104862Sru@DefstrItem {MONTH10, ms} 4162104862Sru@DefstrItem {MONTH11, ms} 4163104862Sru@DefstrListEnd {MONTH12, ms} 4164151497SruPrints the full name of the month in dates. The default is 4165151497Sru@samp{January}, @samp{February}, etc. 4166104862Sru@endDefstr 4167104862Sru 4168104862SruThe following special characters are available@footnote{For an 4169151497Sruexplanation what special characters are see @ref{Special 4170151497SruCharacters}.}: 4171104862Sru 4172104862Sru@Defstr {-, ms} 4173104862SruPrints an em dash. 4174104862Sru@endDefstr 4175104862Sru 4176151497Sru@DefstrList {Q, ms} 4177151497Sru@DefstrListEnd {U, ms} 4178151497SruPrints typographer's quotes in troff, and plain quotes in nroff. 4179151497Sru@code{\*Q} is the left quote and @code{\*U} is the right quote. 4180104862Sru@endDefstr 4181104862Sru 4182104862SruImproved accent marks are available in the @file{ms} macros. 4183104862Sru 4184104862Sru@Defmac {AM, , ms} 4185151497SruSpecify this macro at the beginning of your document to enable 4186151497Sruextended accent marks and special characters. This is a Berkeley 4187151497Sruextension. 4188104862Sru 4189151497SruTo use the accent marks, place them @strong{after} the character being 4190151497Sruaccented. 4191151497Sru 4192151497SruNote that groff's native support for accents is superior to the 4193151497Srufollowing definitions. 4194104862Sru@endDefmac 4195104862Sru 4196151497SruThe following accent marks are available after invoking the @code{AM} 4197151497Srumacro: 4198104862Sru 4199104862Sru@Defstr {\', ms} 4200104862SruAcute accent. 4201104862Sru@endDefstr 4202104862Sru 4203104862Sru@Defstr {\`, ms} 4204104862SruGrave accent. 4205104862Sru@endDefstr 4206104862Sru 4207104862Sru@Defstr {^, ms} 4208104862SruCircumflex. 4209104862Sru@endDefstr 4210104862Sru 4211104862Sru@Defstr {\,, ms} 4212104862SruCedilla. 4213104862Sru@endDefstr 4214104862Sru 4215104862Sru@Defstr {~, ms} 4216104862SruTilde. 4217104862Sru@endDefstr 4218104862Sru 4219104862Sru@deffn String @t{\*[:]} 4220104862Sru@ifnotinfo 4221104862Sru@stindex : @r{[}ms@r{]} 4222104862Sru@end ifnotinfo 4223104862Sru@ifinfo 4224114402Sru@stindex \*[@r{<colon>}] @r{[}ms@r{]} 4225104862Sru@end ifinfo 4226104862SruUmlaut. 4227104862Sru@end deffn 4228104862Sru 4229104862Sru@Defstr {v, ms} 4230104862SruHacek. 4231104862Sru@endDefstr 4232104862Sru 4233104862Sru@Defstr {_, ms} 4234104862SruMacron (overbar). 4235104862Sru@endDefstr 4236104862Sru 4237104862Sru@Defstr {., ms} 4238104862SruUnderdot. 4239104862Sru@endDefstr 4240104862Sru 4241104862Sru@Defstr {o, ms} 4242104862SruRing above. 4243104862Sru@endDefstr 4244104862Sru 4245151497SruThe following are standalone characters available after invoking the 4246151497Sru@code{AM} macro: 4247104862Sru 4248104862Sru@Defstr {?, ms} 4249104862SruUpside-down question mark. 4250104862Sru@endDefstr 4251104862Sru 4252104862Sru@Defstr {!, ms} 4253104862SruUpside-down exclamation point. 4254104862Sru@endDefstr 4255104862Sru 4256104862Sru@Defstr {8, ms} 4257151497SruGerman � ligature. 4258104862Sru@endDefstr 4259104862Sru 4260104862Sru@Defstr {3, ms} 4261104862SruYogh. 4262104862Sru@endDefstr 4263104862Sru 4264104862Sru@Defstr {Th, ms} 4265104862SruUppercase thorn. 4266104862Sru@endDefstr 4267104862Sru 4268104862Sru@Defstr {th, ms} 4269104862SruLowercase thorn. 4270104862Sru@endDefstr 4271104862Sru 4272104862Sru@Defstr {D-, ms} 4273104862SruUppercase eth. 4274104862Sru@endDefstr 4275104862Sru 4276104862Sru@Defstr {d-, ms} 4277104862SruLowercase eth. 4278104862Sru@endDefstr 4279104862Sru 4280104862Sru@Defstr {q, ms} 4281104862SruHooked o. 4282104862Sru@endDefstr 4283104862Sru 4284104862Sru@Defstr {ae, ms} 4285151497SruLowercase � ligature. 4286104862Sru@endDefstr 4287104862Sru 4288104862Sru@Defstr {Ae, ms} 4289151497SruUppercase � ligature. 4290104862Sru@endDefstr 4291104862Sru 4292104862Sru@c --------------------------------------------------------------------- 4293104862Sru 4294151497Sru@node Differences from AT&T ms, Naming Conventions, ms Page Layout, ms 4295104862Sru@subsection Differences from @acronym{AT&T} @file{ms} 4296104862Sru@cindex @code{ms} macros, differences from @acronym{AT&T} 4297104862Sru@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences 4298104862Sru 4299151497SruThis section lists the (minor) differences between the @code{groff 4300151497Sru-ms} macros and @acronym{AT&T} @code{troff -ms} macros. 4301104862Sru 4302151497Sru@itemize @bullet 4303151497Sru@item 4304151497SruThe internals of @code{groff -ms} differ from the internals of 4305151497Sru@acronym{AT&T} @code{troff -ms}. Documents that depend upon 4306151497Sruimplementation details of @acronym{AT&T} @code{troff -ms} may not 4307151497Sruformat properly with @code{groff -ms}. 4308151497Sru 4309151497Sru@item 4310151497SruThe general error-handling policy of @code{groff -ms} is to detect and 4311151497Srureport errors, rather than silently to ignore them. 4312151497Sru 4313151497Sru@item 4314151497Sru@code{groff -ms} does not work in compatibility mode (this is, with 4315151497Sruthe @option{-C} option). 4316151497Sru 4317151497Sru@item 4318151497SruThere is no special support for typewriter-like devices. 4319151497Sru 4320151497Sru@item 4321151497Sru@code{groff -ms} does not provide cut marks. 4322151497Sru 4323151497Sru@item 4324151497SruMultiple line spacing is not supported. Use a larger vertical spacing 4325151497Sruinstead. 4326151497Sru 4327151497Sru@item 4328151497SruSome @acronym{UNIX} @code{ms} documentation says that the @code{CW} 4329151497Sruand @code{GW} number registers can be used to control the column width 4330151497Sruand gutter width, respectively. These number registers are not used in 4331151497Sru@code{groff -ms}. 4332151497Sru 4333151497Sru@item 4334151497SruMacros that cause a reset (paragraphs, headings, etc.@:) may change 4335151497Sruthe indentation. Macros that change the indentation do not increment 4336151497Sruor decrement the indentation, but rather set it absolutely. This can 4337151497Srucause problems for documents that define additional macros of their 4338151497Sruown. The solution is to use not the @code{in} request but instead the 4339151497Sru@code{RS} and @code{RE} macros. 4340151497Sru 4341151497Sru@item 4342151497SruTo make @code{groff -ms} use the default page offset (which also 4343151497Sruspecifies the left margin), the @code{PO} register must stay undefined 4344151497Sruuntil the first @file{-ms} macro is evaluated. This implies that 4345151497Sru@code{PO} should not be used early in the document, unless it is 4346151497Sruchanged also: Remember that accessing an undefined register 4347151497Sruautomatically defines it. 4348151497Sru@end itemize 4349151497Sru 4350151497Sru@Defmpreg {GS, ms} 4351151497SruThis number register is set to@tie{}1 by the @code{groff -ms} macros, 4352151497Srubut it is not used by the @code{AT&T} @code{troff -ms} macros. 4353151497SruDocuments that need to determine whether they are being formatted with 4354151497Sru@code{AT&T} @code{troff -ms} or @code{groff -ms} should use this 4355151497Srunumber register. 4356151497Sru@endDefmpreg 4357151497Sru 4358104862Sru@menu 4359104862Sru* Missing ms Macros:: 4360104862Sru* Additional ms Macros:: 4361104862Sru@end menu 4362104862Sru 4363104862Sru@c --------------------------------------------------------------------- 4364104862Sru 4365104862Sru@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms 4366104862Sru@subsubsection @code{troff} macros not appearing in @code{groff} 4367104862Sru 4368151497SruMacros missing from @code{groff -ms} are cover page macros specific to 4369151497SruBell Labs and Berkeley. The macros known to be missing are: 4370104862Sru 4371104862Sru@table @code 4372104862Sru@item .TM 4373104862SruTechnical memorandum; a cover sheet style 4374104862Sru 4375104862Sru@item .IM 4376104862SruInternal memorandum; a cover sheet style 4377104862Sru 4378104862Sru@item .MR 4379104862SruMemo for record; a cover sheet style 4380104862Sru 4381104862Sru@item .MF 4382104862SruMemo for file; a cover sheet style 4383104862Sru 4384104862Sru@item .EG 4385104862SruEngineer's notes; a cover sheet style 4386104862Sru 4387104862Sru@item .TR 4388104862SruComputing Science Tech Report; a cover sheet style 4389104862Sru 4390104862Sru@item .OK 4391104862SruOther keywords 4392104862Sru 4393104862Sru@item .CS 4394104862SruCover sheet information 4395104862Sru 4396104862Sru@item .MH 4397104862SruA cover sheet macro 4398104862Sru@end table 4399104862Sru 4400104862Sru@c --------------------------------------------------------------------- 4401104862Sru 4402104862Sru@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms 4403104862Sru@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff} 4404104862Sru 4405104862SruThe @code{groff -ms} macros have a few minor extensions 4406104862Srucompared to the @acronym{AT&T} @code{troff -ms} macros. 4407104862Sru 4408104862Sru@Defmac {AM, , ms} 4409104862SruImproved accent marks. 4410104862Sru@xref{ms Strings and Special Characters}, for details. 4411104862Sru@endDefmac 4412104862Sru 4413104862Sru@Defmac {DS, @t{I}, ms} 4414104862SruIndented display. 4415104862SruThe default behavior of @acronym{AT&T} @code{troff -ms} 4416104862Sruwas to indent; the @code{groff} default prints displays 4417104862Sruflush left with the body text. 4418104862Sru@endDefmac 4419104862Sru 4420104862Sru@Defmac {CW, , ms} 4421104862SruPrint text in @code{constant width} (Courier) font. 4422104862Sru@endDefmac 4423104862Sru 4424104862Sru@Defmac {IX, , ms} 4425104862SruIndexing term (printed on standard error). 4426104862SruYou can write a script to capture and process an index 4427104862Srugenerated in this manner. 4428104862Sru@endDefmac 4429104862Sru 4430104862SruThe following additional number registers 4431104862Sruappear in @code{groff -ms}: 4432104862Sru 4433104862Sru@Defmpreg {MINGW, ms} 4434104862SruSpecifies a minimum space 4435104862Srubetween columns (for multi-column output); this takes the 4436104862Sruplace of the @code{GW} register that was documented but apparently 4437104862Srunot implemented in @acronym{AT&T} @code{troff}. 4438104862Sru@endDefmpreg 4439104862Sru 4440104862SruSeveral new string registers are available as well. 4441104862SruYou can change these to handle (for example) the local language. 4442104862Sru@xref{ms Strings and Special Characters}, for details. 4443104862Sru 4444151497Sru@c --------------------------------------------------------------------- 4445104862Sru 4446151497Sru@node Naming Conventions, , Differences from AT&T ms, ms 4447151497Sru@subsection Naming Conventions 4448151497Sru@cindex @code{ms} macros, naming conventions 4449151497Sru@cindex naming conventions, @code{ms} macros 4450151497Sru 4451151497SruThe following conventions are used for names of macros, strings and 4452151497Srunumber registers. External names available to documents that use the 4453151497Sru@code{groff -ms} macros contain only uppercase letters and digits. 4454151497Sru 4455151497SruInternally the macros are divided into modules; naming conventions are 4456151497Sruas follows: 4457151497Sru 4458151497Sru@itemize @bullet 4459151497Sru@item 4460151497SruNames used only within one module are of the form 4461151497Sru@var{module}@code{*}@var{name}. 4462151497Sru 4463151497Sru@item 4464151497SruNames used outside the module in which they are defined are of the 4465151497Sruform @var{module}@code{@@}@var{name}. 4466151497Sru 4467151497Sru@item 4468151497SruNames associated with a particular environment are of the form 4469151497Sru@var{environment}@code{:}@var{name}; these are used only within the 4470151497Sru@code{par} module. 4471151497Sru 4472151497Sru@item 4473151497Sru@var{name} does not have a module prefix. 4474151497Sru 4475151497Sru@item 4476151497SruConstructed names used to implement arrays are of the form 4477151497Sru@var{array}@code{!}@var{index}. 4478151497Sru@end itemize 4479151497Sru 4480151497SruThus the groff ms macros reserve the following names: 4481151497Sru 4482151497Sru@itemize @bullet 4483151497Sru@item 4484151497SruNames containing the characters @code{*}, @code{@@}, 4485151497Sruand@tie{}@code{:}. 4486151497Sru 4487151497Sru@item 4488151497SruNames containing only uppercase letters and digits. 4489151497Sru@end itemize 4490151497Sru 4491151497Sru 449269626Sru@c ===================================================================== 449369626Sru 449469626Sru@node me, mm, ms, Macro Packages 449569626Sru@section @file{me} 4496104862Sru@cindex @code{me} macro package 449769626Sru 449869626Sru@c XXX documentation 4499104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 4500104862SruSee the @file{meintro.me} and @file{meref.me} documents in 4501104862Srugroff's @file{doc} directory. 450269626Sru 450369626Sru 450469626Sru@c ===================================================================== 450569626Sru 450669626Sru@node mm, , me, Macro Packages 450769626Sru@section @file{mm} 4508104862Sru@cindex @code{mm} macro package 450969626Sru 451069626Sru@c XXX documentation 4511104862Sru@c XXX this is a placeholder until we get stuff knocked into shape 4512104862SruSee the @cite{groff_mm(7)} man page (type @command{man groff_mm} at 4513104862Sruthe command line). 451469626Sru 451569626Sru 451669626Sru@c ===================================================================== 451769626Sru@c ===================================================================== 451869626Sru 451975584Sru@node gtroff Reference, Preprocessors, Macro Packages, Top 452075584Sru@chapter @code{gtroff} Reference 452175584Sru@cindex reference, @code{gtroff} 4522104862Sru@cindex @code{gtroff}, reference 452355839Sasmodai 452469626SruThis chapter covers @strong{all} of the facilities of @code{gtroff}. 452569626SruUsers of macro packages may skip it if not interested in details. 452655839Sasmodai 452755839Sasmodai 452855839Sasmodai@menu 452975584Sru* Text:: 453075584Sru* Measurements:: 453175584Sru* Expressions:: 453275584Sru* Identifiers:: 453375584Sru* Embedded Commands:: 453475584Sru* Registers:: 453575584Sru* Manipulating Filling and Adjusting:: 453675584Sru* Manipulating Hyphenation:: 453775584Sru* Manipulating Spacing:: 453875584Sru* Tabs and Fields:: 453975584Sru* Character Translations:: 454075584Sru* Troff and Nroff Mode:: 454175584Sru* Line Layout:: 4542104862Sru* Line Control:: 454375584Sru* Page Layout:: 454475584Sru* Page Control:: 4545114402Sru* Fonts and Symbols:: 454675584Sru* Sizes:: 454775584Sru* Strings:: 454875584Sru* Conditionals and Loops:: 454975584Sru* Writing Macros:: 455075584Sru* Page Motions:: 455175584Sru* Drawing Requests:: 455275584Sru* Traps:: 455375584Sru* Diversions:: 455475584Sru* Environments:: 455575584Sru* Suppressing output:: 4556104862Sru* Colors:: 455775584Sru* I/O:: 455875584Sru* Postprocessor Access:: 455975584Sru* Miscellaneous:: 456075584Sru* Gtroff Internals:: 456175584Sru* Debugging:: 456275584Sru* Implementation Differences:: 456355839Sasmodai@end menu 456455839Sasmodai 456569626Sru 456669626Sru@c ===================================================================== 456769626Sru 4568114402Sru@node Text, Measurements, gtroff Reference, gtroff Reference 456955839Sasmodai@section Text 457069626Sru@cindex text, @code{gtroff} processing 457155839Sasmodai 457269626Sru@code{gtroff} input files contain text with control commands 457369626Sruinterspersed throughout. But, even without control codes, @code{gtroff} 457475584Srustill does several things with the input text: 457555839Sasmodai 457675584Sru@itemize @bullet 457775584Sru@item 457875584Srufilling and adjusting 457975584Sru 458075584Sru@item 458175584Sruadding additional space after sentences 458275584Sru 458375584Sru@item 458475584Sruhyphenating 458575584Sru 458675584Sru@item 458775584Sruinserting implicit line breaks 458875584Sru@end itemize 458975584Sru 459055839Sasmodai@menu 459175584Sru* Filling and Adjusting:: 459275584Sru* Hyphenation:: 459375584Sru* Sentences:: 459475584Sru* Tab Stops:: 459575584Sru* Implicit Line Breaks:: 4596114402Sru* Input Conventions:: 4597114402Sru* Input Encodings:: 459855839Sasmodai@end menu 459955839Sasmodai 460069626Sru@c --------------------------------------------------------------------- 460169626Sru 460255839Sasmodai@node Filling and Adjusting, Hyphenation, Text, Text 460355839Sasmodai@subsection Filling and Adjusting 460469626Sru@cindex filling 460569626Sru@cindex adjusting 460655839Sasmodai 460775584SruWhen @code{gtroff} reads text, it collects words from the input and fits 460869626Sruas many of them together on one output line as it can. This is known as 460955839Sasmodai@dfn{filling}. 461055839Sasmodai 461169626Sru@cindex leading spaces 461269626Sru@cindex spaces, leading and trailing 461369626Sru@cindex extra spaces 461469626Sru@cindex trailing spaces 461575584SruOnce @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 461675584Sruit. This means it widens the spacing between words until the text 461769626Srureaches the right margin (in the default adjustment mode). Extra spaces 461869626Srubetween words are preserved, but spaces at the end of lines are ignored. 461975584SruSpaces at the front of a line cause a @dfn{break} (breaks are 4620104862Sruexplained in @ref{Implicit Line Breaks}). 462155839Sasmodai 462269626Sru@xref{Manipulating Filling and Adjusting}. 462355839Sasmodai 462469626Sru@c --------------------------------------------------------------------- 462569626Sru 462655839Sasmodai@node Hyphenation, Sentences, Filling and Adjusting, Text 462755839Sasmodai@subsection Hyphenation 462855839Sasmodai@cindex hyphenation 462955839Sasmodai 463069626SruSince the odds are not great for finding a set of words, for every 463175584Sruoutput line, which fit nicely on a line without inserting excessive 463275584Sruamounts of space between words, @code{gtroff} hyphenates words so 463375584Sruthat it can justify lines without inserting too much space between 463469626Sruwords. It uses an internal hyphenation algorithm (a simplified version 463569626Sruof the algorithm used within @TeX{}) to indicate which words can be 463675584Sruhyphenated and how to do so. When a word is hyphenated, the first part 463775584Sruof the word is added to the current filled line being output (with 463875584Sruan attached hyphen), and the other portion is added to the next 463969626Sruline to be filled. 464055839Sasmodai 464169626Sru@xref{Manipulating Hyphenation}. 464255839Sasmodai 464369626Sru@c --------------------------------------------------------------------- 464455839Sasmodai 464555839Sasmodai@node Sentences, Tab Stops, Hyphenation, Text 464655839Sasmodai@subsection Sentences 464755839Sasmodai@cindex sentences 464855839Sasmodai 464969626SruAlthough it is often debated, some typesetting rules say there should be 465069626Srudifferent amounts of space after various punctuation marks. For 465169626Sruexample, the @cite{Chicago typsetting manual} says that a period at the 465269626Sruend of a sentence should have twice as much space following it as would 465369626Srua comma or a period as part of an abbreviation. 465455839Sasmodai 465569626Sru@c XXX exact citation of Chicago manual 465655839Sasmodai 465769626Sru@cindex sentence space 465869626Sru@cindex space between sentences 465969626Sru@cindex french-spacing 466069626Sru@code{gtroff} does this by flagging certain characters (normally 4661104862Sru@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters. 466269626SruWhen @code{gtroff} encounters one of these characters at the end of a 466375584Sruline, it appends a normal space followed by a @dfn{sentence space} in 466475584Sruthe formatted output. (This justifies one of the conventions mentioned 466575584Sruin @ref{Input Conventions}.) 466655839Sasmodai 466769626Sru@cindex transparent characters 466869626Sru@cindex character, transparent 4669104862Sru@cindex @code{dg} glyph, at end of sentence 4670104862Sru@cindex @code{rq} glyph, at end of sentence 4671104862Sru@cindex @code{"}, at end of sentence 4672104862Sru@cindex @code{'}, at end of sentence 4673104862Sru@cindex @code{)}, at end of sentence 4674104862Sru@cindex @code{]}, at end of sentence 4675104862Sru@cindex @code{*}, at end of sentence 4676104862SruIn addition, the following characters and symbols are treated 4677104862Srutransparently while handling end-of-sentence characters: @samp{"}, 4678104862Sru@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}. 467955839Sasmodai 468069626SruSee the @code{cflags} request in @ref{Using Symbols}, for more details. 468155839Sasmodai 4682104862Sru@cindex @code{\&}, at end of sentence 4683104862SruTo prevent the insertion of extra space after an end-of-sentence 468469626Srucharacter (at the end of a line), append @code{\&}. 468555839Sasmodai 468669626Sru@c --------------------------------------------------------------------- 468769626Sru 468855839Sasmodai@node Tab Stops, Implicit Line Breaks, Sentences, Text 468955839Sasmodai@subsection Tab Stops 469055839Sasmodai@cindex tab stops 469155839Sasmodai@cindex stops, tabulator 469269626Sru@cindex tab character 469369626Sru@cindex character, tabulator 469455839Sasmodai 469569626Sru@cindex @acronym{EBCDIC} encoding 4696104862Sru@cindex encoding, @acronym{EBCDIC} 469769626Sru@code{gtroff} translates @dfn{tabulator characters}, also called 469875584Sru@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 469969626Sru@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 470069626Srutabulator stop. These tab stops are initially located every half inch 470175584Sruacross the page. Using this, simple tables can be made easily. 470269626SruHowever, it can often be deceptive as the appearance (and width) of the 470369626Srutext on a terminal and the results from @code{gtroff} can vary greatly. 470455839Sasmodai 470555839SasmodaiAlso, a possible sticking point is that lines beginning with tab 470675584Srucharacters are still filled, again producing unexpected results. 470755839SasmodaiFor example, the following input 470855839Sasmodai 470969626Sru@multitable {12345678} {12345678} {12345678} {12345678} 471069626Sru@item 471169626Sru@tab 1 @tab 2 @tab 3 471269626Sru@item 471369626Sru@tab @tab 4 @tab 5 471469626Sru@end multitable 471555839Sasmodai 471655839Sasmodai@noindent 471775584Sruproduces 471855839Sasmodai 471969626Sru@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 472069626Sru@item 472169626Sru@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 472269626Sru@end multitable 472355839Sasmodai 472469626Sru@xref{Tabs and Fields}. 472555839Sasmodai 472669626Sru@c --------------------------------------------------------------------- 472755839Sasmodai 4728114402Sru@node Implicit Line Breaks, Input Conventions, Tab Stops, Text 472955839Sasmodai@subsection Implicit Line Breaks 473055839Sasmodai@cindex implicit line breaks 473155839Sasmodai@cindex implicit breaks of lines 473255839Sasmodai@cindex line, implicit breaks 473355839Sasmodai@cindex break, implicit 473455839Sasmodai@cindex line break 473555839Sasmodai 473669626SruAn important concept in @code{gtroff} is the @dfn{break}. When a break 473775584Sruoccurs, @code{gtroff} outputs the partially filled line 473875584Sru(unjustified), and resumes collecting and filling text on the next output 473969626Sruline. 474055839Sasmodai 474155839Sasmodai@cindex blank line 474255839Sasmodai@cindex empty line 474355839Sasmodai@cindex line, blank 4744104862Sru@cindex blank line macro (@code{blm}) 474575584SruThere are several ways to cause a break in @code{gtroff}. A blank 4746104862Sruline not only causes a break, but it also outputs a one-line vertical 474775584Sruspace (effectively a blank line). Note that this behaviour can be 474875584Srumodified with the blank line macro request @code{blm}. 4749104862Sru@xref{Blank Line Traps}. 475055839Sasmodai 475169626Sru@cindex fill mode 475269626Sru@cindex mode, fill 475375584SruA line that begins with a space causes a break and the space is 475475584Sruoutput at the beginning of the next line. Note that this space isn't 475569626Sruadjusted, even in fill mode. 475655839Sasmodai 475775584SruThe end of file also causes a break -- otherwise the last line of 475869626Sruthe document may vanish! 475955839Sasmodai 476075584SruCertain requests also cause breaks, implicitly or explicitly. This is 476175584Srudiscussed in @ref{Manipulating Filling and Adjusting}. 476255839Sasmodai 4763114402Sru@c --------------------------------------------------------------------- 476455839Sasmodai 4765114402Sru@node Input Conventions, Input Encodings, Implicit Line Breaks, Text 4766114402Sru@subsection Input Conventions 476755839Sasmodai@cindex input conventions 476855839Sasmodai@cindex conventions for input 476955839Sasmodai 477069626SruSince @code{gtroff} does filling automatically, it is traditional in 477169626Sru@code{groff} not to try and type things in as nicely formatted 477269626Sruparagraphs. These are some conventions commonly used when typing 477369626Sru@code{gtroff} text: 477455839Sasmodai 477569626Sru@itemize @bullet 477669626Sru@item 477775584SruBreak lines after punctuation, particularly at the end of a sentence 477869626Sruand in other logical places. Keep separate phrases on lines by 477969626Sruthemselves, as entire phrases are often added or deleted when editing. 478055839Sasmodai 478155839Sasmodai@item 4782114402SruTry to keep lines less than 40-60@tie{}characters, to allow space for 478369626Sruinserting more text. 478469626Sru 478555839Sasmodai@item 478669626SruDo not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 478775584Srudon't try using spaces to get proper indentation). 478855839Sasmodai@end itemize 478955839Sasmodai 4790114402Sru@c --------------------------------------------------------------------- 479155839Sasmodai 4792114402Sru@node Input Encodings, , Input Conventions, Text 4793114402Sru@subsection Input Encodings 4794114402Sru 4795114402SruCurrently, the following input encodings are available. 4796114402Sru 4797114402Sru@table @asis 4798114402Sru@item cp1047 4799114402Sru@cindex encoding, input, @acronym{EBCDIC} 4800114402Sru@cindex @acronym{EBCDIC}, input encoding 4801114402Sru@cindex input encoding, @acronym{EBCDIC} 4802114402Sru@cindex encoding, input, cp1047 4803114402Sru@cindex cp1047, input encoding 4804114402Sru@cindex input encoding, cp1047 4805114402Sru@cindex IBM cp1047 input encoding 4806114402Sru@pindex cp1047.tmac 4807114402SruThis input encoding works only on @acronym{EBCDIC} platforms (and vice 4808114402Sruversa, the other input encodings don't work with @acronym{EBCDIC}); the 4809114402Srufile @file{cp1047.tmac} is by default loaded at start-up. 4810114402Sru 4811114402Sru@item latin-1 4812114402Sru@cindex encoding, input, @w{latin-1} (ISO @w{8859-1}) 4813114402Sru@cindex @w{latin-1} (ISO @w{8859-1}), input encoding 4814114402Sru@cindex ISO @w{8859-1} (@w{latin-1}), input encoding 4815114402Sru@cindex input encoding, @w{latin-1} (ISO @w{8859-1}) 4816114402Sru@pindex latin1.tmac 4817114402SruThis is the default input encoding on non-@acronym{EBCDIC} platforms; 4818114402Sruthe file @file{latin1.tmac} is loaded at start-up. 4819114402Sru 4820114402Sru@item latin-2 4821114402Sru@cindex encoding, input, @w{latin-2} (ISO @w{8859-2}) 4822114402Sru@cindex @w{latin-2} (ISO @w{8859-2}), input encoding 4823114402Sru@cindex ISO @w{8859-2} (@w{latin-2}), input encoding 4824114402Sru@cindex input encoding, @w{latin-2} (ISO @w{8859-2}) 4825114402Sru@pindex latin2.tmac 4826114402SruTo use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very 4827114402Srubeginning of your document or use @samp{-mlatin2} as a command line 4828114402Sruargument for @code{groff}. 4829114402Sru 4830114402Sru@item latin-9 (latin-0) 4831114402Sru@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15}) 4832114402Sru@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding 4833114402Sru@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding 4834114402Sru@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15}) 4835114402Sru@pindex latin9.tmac 4836114402SruThis encoding is intended (at least in Europe) to replace @w{latin-1} 4837114402Sruencoding. The main difference to @w{latin-1} is that @w{latin-9} 4838114402Srucontains the Euro character. To use this encoding, either say 4839114402Sru@w{@samp{.mso latin9.tmac}} at the very beginning of your document or 4840114402Sruuse @samp{-mlatin9} as a command line argument for @code{groff}. 4841114402Sru@end table 4842114402Sru 4843114402SruNote that it can happen that some input encoding characters are not 4844114402Sruavailable for a particular output device. For example, saying 4845114402Sru 4846114402Sru@Example 4847114402Srugroff -Tlatin1 -mlatin9 ... 4848114402Sru@endExample 4849114402Sru 4850114402Sru@noindent 4851114402Sruwill fail if you use the Euro character in the input. Usually, this 4852114402Srulimitation is present only for devices which have a limited set of 4853114402Sruoutput glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other 4854114402Srudevices it is usually sufficient to install proper fonts which contain 4855114402Sruthe necessary glyphs. 4856114402Sru 4857114402Sru@pindex freeeuro.pfa 4858114402Sru@pindex ec.tmac 4859114402SruDue to the importance of the Euro glyph in Europe, the groff package now 4860114402Srucomes with a @sc{PostScript} font called @file{freeeuro.pfa} which 4861114402Sruprovides various glyph shapes for the Euro. With other words, 4862114402Sru@w{latin-9} encoding is supported for the @option{-Tps} device out of 4863114402Sruthe box (@w{latin-2} isn't). 4864114402Sru 4865114402SruBy its very nature, @option{-Tutf8} supports all input encodings; 4866114402Sru@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the 4867114402Srucommand line @option{-mec} is used also to load the file @file{ec.tmac} 4868114402Sru(which flips to the EC fonts). 4869114402Sru 4870114402Sru 487169626Sru@c ===================================================================== 487269626Sru 4873114402Sru@node Measurements, Expressions, Text, gtroff Reference 487455839Sasmodai@section Measurements 487555839Sasmodai@cindex measurements 487655839Sasmodai 487755839Sasmodai@cindex units of measurement 4878104862Sru@cindex basic unit (@code{u}) 4879104862Sru@cindex machine unit (@code{u}) 4880104862Sru@cindex measurement unit 488169626Sru@cindex @code{u} unit 488269626Sru@cindex unit, @code{u} 488375584Sru@code{gtroff} (like many other programs) requires numeric parameters to 488469626Sruspecify various measurements. Most numeric parameters@footnote{those 488569626Sruthat specify vertical or horizontal motion or a type size} may have a 488669626Sru@dfn{measurement unit} attached. These units are specified as a single 488769626Srucharacter which immediately follows the number or expression. Each of 488869626Sruthese units are understood, by @code{gtroff}, to be a multiple of its 488955839Sasmodai@dfn{basic unit}. So, whenever a different measurement unit is 489069626Sruspecified @code{gtroff} converts this into its @dfn{basic units}. This 489169626Srubasic unit, represented by a @samp{u}, is a device dependent measurement 489275584Sruwhich is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 489375584Sruinch. The values may be given as fractional numbers; however, 489475584Srufractional basic units are always rounded to integers. 489555839Sasmodai 489669626SruSome of the measurement units are completely independent of any of the 489769626Srucurrent settings (e.g.@: type size) of @code{gtroff}. 489855839Sasmodai 489969626Sru@table @code 490055839Sasmodai@item i 4901104862Sru@cindex inch unit (@code{i}) 490269626Sru@cindex @code{i} unit 490369626Sru@cindex unit, @code{i} 490455839SasmodaiInches. An antiquated measurement unit still in use in certain 490575584Srubackwards countries with incredibly low-cost computer equipment. One 4906114402Sruinch is equal to@tie{}2.54@dmn{cm}. 490769626Sru 490855839Sasmodai@item c 4909104862Sru@cindex centimeter unit (@code{c}) 491069626Sru@cindex @code{c} unit 491169626Sru@cindex unit, @code{c} 4912114402SruCentimeters. One centimeter is equal to@tie{}0.3937@dmn{in}. 491369626Sru 491455839Sasmodai@item p 4915104862Sru@cindex point unit (@code{p}) 491669626Sru@cindex @code{p} unit 491769626Sru@cindex unit, @code{p} 491855839SasmodaiPoints. This is a typesetter's measurement used for measure type size. 4919114402SruIt is 72@tie{}points to an inch. 492069626Sru 492155839Sasmodai@item P 4922104862Sru@cindex pica unit (@code{P}) 492369626Sru@cindex @code{P} unit 492469626Sru@cindex unit, @code{P} 4925114402SruPica. Another typesetting measurement. 6@tie{}Picas to an inch (and 4926114402Sru12@tie{}points to a pica). 492769626Sru 492855839Sasmodai@item s 492969626Sru@itemx z 493069626Sru@cindex @code{s} unit 493169626Sru@cindex unit, @code{s} 493269626Sru@cindex @code{z} unit 493369626Sru@cindex unit, @code{z} 493469626Sru@xref{Fractional Type Sizes}, for a discussion of these units. 4935104862Sru 4936104862Sru@item f 4937104862Sru@cindex @code{f} unit 4938104862Sru@cindex unit, @code{f} 4939104862SruFractions. Value is 65536. 4940104862Sru@xref{Colors}, for usage. 494155839Sasmodai@end table 494255839Sasmodai 494375584SruThe other measurements understood by @code{gtroff} depend on 494469626Srusettings currently in effect in @code{gtroff}. These are very useful 494569626Srufor specifying measurements which should look proper with any size of 494669626Srutext. 494755839Sasmodai 494869626Sru@table @code 494955839Sasmodai@item m 4950104862Sru@cindex em unit (@code{m}) 495169626Sru@cindex @code{m} unit 495269626Sru@cindex unit, @code{m} 495369626SruEms. This unit is equal to the current font size in points. So called 4954114402Srubecause it is @emph{approximately} the width of the letter@tie{}@samp{m} 495569626Sruin the current font. 495669626Sru 495755839Sasmodai@item n 4958104862Sru@cindex en unit (@code{n}) 495969626Sru@cindex @code{n} unit 496069626Sru@cindex unit, @code{n} 4961104862SruEns. In @code{groff}, this is half of an em. 496269626Sru 496355839Sasmodai@item v 4964104862Sru@cindex vertical space unit (@code{v}) 4965104862Sru@cindex space, vertical, unit (@code{v}) 496669626Sru@cindex @code{v} unit 496769626Sru@cindex unit, @code{v} 496855839SasmodaiVertical space. This is equivalent to the current line spacing. 496955839Sasmodai@xref{Sizes}, for more information about this. 497069626Sru 497155839Sasmodai@item M 497269626Sru@cindex @code{M} unit 497369626Sru@cindex unit, @code{M} 497455839Sasmodai100ths of an em. 497555839Sasmodai@end table 497655839Sasmodai 497755839Sasmodai@menu 497875584Sru* Default Units:: 497955839Sasmodai@end menu 498055839Sasmodai 498169626Sru@c --------------------------------------------------------------------- 498269626Sru 498355839Sasmodai@node Default Units, , Measurements, Measurements 498455839Sasmodai@subsection Default Units 498555839Sasmodai@cindex default units 498655839Sasmodai@cindex units, default 498755839Sasmodai 498869626SruMany requests take a default unit. While this can be helpful at times, 498969626Sruit can cause strange errors in some expressions. For example, the line 499069626Srulength request expects em units. Here are several attempts to get a 4991114402Sruline length of 3.5@tie{}inches and their results: 499255839Sasmodai 499375584Sru@Example 499455839Sasmodai3.5i @result{} 3.5i 499555839Sasmodai7/2 @result{} 0i 499655839Sasmodai7/2i @result{} 0i 4997104862Sru(7 / 2)u @result{} 0i 499869626Sru7i/2 @result{} 0.1i 499955839Sasmodai7i/2u @result{} 3.5i 500075584Sru@endExample 500155839Sasmodai 500269626Sru@noindent 500375584SruEverything is converted to basic units first. In the above example it 5004114402Sruis assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m} 5005114402Sruequals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value 5006114402Sru7@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to 500775584Sru1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 5008104862Sru0.1@dmn{i}. As can be seen, a scaling indicator after a closing 5009104862Sruparenthesis is simply ignored. 501055839Sasmodai 501169626Sru@cindex measurements, specifying safely 501275584SruThus, the safest way to specify measurements is to always 501369626Sruattach a scaling indicator. If you want to multiply or divide by a 501469626Srucertain scalar value, use @samp{u} as the unit for that value. 501569626Sru 501669626Sru 501769626Sru@c ===================================================================== 501869626Sru 501975584Sru@node Expressions, Identifiers, Measurements, gtroff Reference 502055839Sasmodai@section Expressions 502155839Sasmodai@cindex expressions 502255839Sasmodai 502375584Sru@code{gtroff} has most arithmetic operators common to other languages: 502455839Sasmodai 502555839Sasmodai@itemize @bullet 502655839Sasmodai@item 502769626Sru@cindex arithmetic operators 502869626Sru@cindex operators, arithmetic 502969626Sru@opindex + 503069626Sru@opindex - 503169626Sru@opindex / 503269626Sru@opindex * 503369626Sru@opindex % 503469626SruArithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 503569626Sru(division), @samp{*} (multiplication), @samp{%} (modulo). 503669626Sru 503769626Sru@code{gtroff} only provides integer arithmetic. The internal type used 503869626Srufor computing results is @samp{int}, which is usually a 32@dmn{bit} 503969626Srusigned integer. 504069626Sru 504155839Sasmodai@item 504269626Sru@cindex comparison operators 504369626Sru@cindex operators, comparison 504469626Sru@opindex < 504569626Sru@opindex > 504669626Sru@opindex >= 504769626Sru@opindex <= 504869626Sru@opindex = 504969626Sru@opindex == 505069626SruComparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 505169626Sru(less than or equal), @samp{>=} (greater than or equal), @samp{=} 505269626Sru(equal), @samp{==} (the same as @samp{=}). 505369626Sru 505455839Sasmodai@item 505569626Sru@cindex logical operators 505669626Sru@cindex operators, logical 505769626Sru@opindex & 5058104862Sru@ifnotinfo 505969626Sru@opindex : 5060104862Sru@end ifnotinfo 5061104862Sru@ifinfo 5062104862Sru@opindex @r{<colon>} 5063104862Sru@end ifinfo 506469626SruLogical: @samp{&} (logical and), @samp{:} (logical or). 506569626Sru 506655839Sasmodai@item 506769626Sru@cindex unary operators 506869626Sru@cindex operators, unary 506969626Sru@opindex - 507069626Sru@opindex + 507169626Sru@opindex ! 5072104862Sru@cindex @code{if} request, and the @samp{!} operator 5073104862Sru@cindex @code{while} request, and the @samp{!} operator 507469626SruUnary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 507569626Sru(just for completeness; does nothing in expressions), @samp{!} (logical 507669626Srunot; this works only within @code{if} and @code{while} requests). See 507769626Srubelow for the use of unary operators in motion requests. 507869626Sru 507955839Sasmodai@item 5080104862Sru@cindex extremum operators (@code{>?}, @code{<?}) 5081104862Sru@cindex operators, extremum (@code{>?}, @code{<?}) 508269626Sru@opindex >? 508369626Sru@opindex <? 5084104862SruExtrema: @samp{>?} (maximum), @samp{<?} (minimum). 508569626Sru 5086104862SruExample: 508769626Sru 5088104862Sru@Example 5089104862Sru.nr x 5 5090104862Sru.nr y 3 5091104862Sru.nr z (\n[x] >? \n[y]) 5092104862Sru@endExample 5093104862Sru 5094104862Sru@noindent 5095114402SruThe register@tie{}@code{z} now contains@tie{}5. 5096104862Sru 509755839Sasmodai@item 509869626Sru@cindex scaling operator 509969626Sru@cindex operator, scaling 5100114402SruScaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c} 5101104862Sruas the default scaling indicator. If @var{c} is missing, ignore scaling 5102114402Sruindicators in the evaluation of@tie{}@var{e}. 510355839Sasmodai@end itemize 510455839Sasmodai 510569626Sru@cindex parentheses 510669626Sru@cindex order of evaluation in expressions 510769626Sru@cindex expression, order of evaluation 510869626Sru@opindex ( 510969626Sru@opindex ) 511069626SruParentheses may be used as in any other language. However, in 511169626Sru@code{gtroff} they are necessary to ensure order of evaluation. 511269626Sru@code{gtroff} has no operator precedence; expressions are evaluated left 511375584Sruto right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 511469626Sruparenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 511569626Sruexpected. 511655839Sasmodai 5117104862Sru@cindex @code{+}, and page motion 5118104862Sru@cindex @code{-}, and page motion 511969626Sru@cindex motion operators 512069626Sru@cindex operators, motion 512169626SruFor many requests which cause a motion on the page, the unary operators 5122104862Sru@samp{+} and @samp{-} work differently if leading an expression. They 5123104862Sruthen indicate a motion relative to the current position (down or up, 5124104862Srurespectively). 5125104862Sru 5126104862Sru@cindex @code{|}, and page motion 5127104862Sru@cindex absolute position operator (@code{|}) 5128104862Sru@cindex position, absolute, operator (@code{|}) 5129104862SruSimilarly, a leading @samp{|} operator indicates an absolute position. 5130104862SruFor vertical movements, it specifies the distance from the top of the 5131104862Srupage; for horizontal movements, it gives the distance from the beginning 5132104862Sruof the @emph{input} line. 5133104862Sru 5134114402Sru@cindex @code{bp} request, using @code{+} and@tie{}@code{-} 5135114402Sru@cindex @code{in} request, using @code{+} and@tie{}@code{-} 5136114402Sru@cindex @code{ll} request, using @code{+} and@tie{}@code{-} 5137114402Sru@cindex @code{lt} request, using @code{+} and@tie{}@code{-} 5138114402Sru@cindex @code{nm} request, using @code{+} and@tie{}@code{-} 5139114402Sru@cindex @code{nr} request, using @code{+} and@tie{}@code{-} 5140114402Sru@cindex @code{pl} request, using @code{+} and@tie{}@code{-} 5141114402Sru@cindex @code{pn} request, using @code{+} and@tie{}@code{-} 5142114402Sru@cindex @code{po} request, using @code{+} and@tie{}@code{-} 5143114402Sru@cindex @code{ps} request, using @code{+} and@tie{}@code{-} 5144114402Sru@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} 5145114402Sru@cindex @code{rt} request, using @code{+} and@tie{}@code{-} 5146114402Sru@cindex @code{ti} request, using @code{+} and@tie{}@code{-} 5147114402Sru@cindex @code{\H}, using @code{+} and@tie{}@code{-} 5148114402Sru@cindex @code{\R}, using @code{+} and@tie{}@code{-} 5149114402Sru@cindex @code{\s}, using @code{+} and@tie{}@code{-} 515069626Sru@samp{+} and @samp{-} are also treated differently by the following 515169626Srurequests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 515269626Sru@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 5153104862Sru@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}. 5154104862SruHere, leading plus and minus signs indicate increments and decrements. 515555839Sasmodai 5156104862Sru@xref{Setting Registers}, for some examples. 515769626Sru 5158104862Sru@Defesc {\\B, ', anything, '} 5159104862Sru@cindex numeric expression, valid 5160104862Sru@cindex valid numeric expression 5161114402SruReturn@tie{}1 if @var{anything} is a valid numeric expression; 5162114402Sruor@tie{}0 if @var{anything} is empty or not a valid numeric expression. 5163104862Sru@endDefesc 5164104862Sru 5165104862Sru@cindex space characters, in expressions 5166104862Sru@cindex expressions, and space characters 516755839SasmodaiDue to the way arguments are parsed, spaces are not allowed in 516869626Sruexpressions, unless the entire expression is surrounded by parentheses. 516955839Sasmodai 5170114402Sru@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}. 517155839Sasmodai 517269626Sru 517369626Sru@c ===================================================================== 517469626Sru 517575584Sru@node Identifiers, Embedded Commands, Expressions, gtroff Reference 517655839Sasmodai@section Identifiers 517755839Sasmodai@cindex identifiers 517855839Sasmodai 517969626SruLike any other language, @code{gtroff} has rules for properly formed 518069626Sru@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 518169626Srualmost any printable character, with the exception of the following 518269626Srucharacters: 518355839Sasmodai 518469626Sru@itemize @bullet 518569626Sru@item 518669626Sru@cindex whitespace characters 518769626Sru@cindex newline character 518869626Sru@cindex character, whitespace 518975584SruWhitespace characters (spaces, tabs, and newlines). 519069626Sru 519169626Sru@item 519269626Sru@cindex character, backspace 519369626Sru@cindex backspace character 519469626Sru@cindex @acronym{EBCDIC} encoding of backspace 5195114402SruBackspace (@acronym{ASCII}@tie{}@code{0x08} or 5196114402Sru@acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}. 519769626Sru 519869626Sru@item 519969626Sru@cindex invalid input characters 520069626Sru@cindex input characters, invalid 520169626Sru@cindex characters, invalid input 5202104862Sru@cindex Unicode 520375584SruThe following input characters are invalid and are ignored if 520469626Sru@code{groff} runs on a machine based on @acronym{ASCII}, causing a 520569626Sruwarning message of type @samp{input} (see @ref{Debugging}, for more 520669626Srudetails): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 520769626Sru@code{0x80}-@code{0x9F}. 520869626Sru 520969626SruAnd here are the invalid input characters if @code{groff} runs on an 521069626Sru@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 521169626Sru@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 521269626Sru@code{0x30}-@code{0x3F}. 521369626Sru 521469626SruCurrently, some of these reserved codepoints are used internally, thus 521569626Srumaking it non-trivial to extend @code{gtroff} to cover Unicode or other 521675584Srucharacter sets and encodings which use characters of these ranges. 521769626Sru 521875584SruNote that invalid characters are removed before parsing; an 521969626Sruidentifier @code{foo}, followed by an invalid character, followed by 522075584Sru@code{bar} is treated as @code{foobar}. 522169626Sru@end itemize 522269626Sru 522369626SruFor example, any of the following is valid. 522469626Sru 522575584Sru@Example 522655839Sasmodaibr 522755839SasmodaiPP 522855839Sasmodai(l 522955839Sasmodaiend-list 523055839Sasmodai@@_ 523175584Sru@endExample 523255839Sasmodai 5233104862Sru@cindex @code{]}, as part of an identifier 523475584Sru@noindent 523569626SruNote that identifiers longer than two characters with a closing bracket 523669626Sru(@samp{]}) in its name can't be accessed with escape sequences which 523775584Sruexpect an identifier as a parameter. For example, @samp{\[foo]]} 523875584Sruaccesses the glyph @samp{foo}, followed by @samp{]}, whereas 523969626Sru@samp{\C'foo]'} really asks for glyph @samp{foo]}. 524055839Sasmodai 5241104862Sru@cindex @code{refer}, and macro names starting with @code{[} or @code{]} 5242104862Sru@cindex @code{[}, macro names starting with, and @code{refer} 5243104862Sru@cindex @code{]}, macro names starting with, and @code{refer} 5244104862Sru@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} 5245104862SruTo avoid problems with the @code{refer} preprocessor, macro names 5246104862Srushould not start with @samp{[} or @samp{]}. Due to backwards 5247104862Srucompatibility, everything after @samp{.[} and @samp{.]} is handled as 5248104862Srua special argument to @code{refer}. For example, @samp{.[foo} makes 5249104862Sru@code{refer} to start a reference, using @samp{foo} as a parameter. 525055839Sasmodai 525175584Sru@Defesc {\\A, ', ident, '} 525275584SruTest whether an identifier @var{ident} is valid in @code{gtroff}. It 5253114402Sruexpands to the character@tie{}1 or@tie{}0 according to whether its 525475584Sruargument (usually delimited by quotes) is or is not acceptable as the 525575584Sruname of a string, macro, diversion, number register, environment, or 5256114402Srufont. It returns@tie{}0 if no argument is given. This is useful for 525775584Srulooking up user input in some sort of associative table. 525869626Sru 525975584Sru@Example 526069626Sru\A'end-list' 526169626Sru @result{} 1 526275584Sru@endExample 526375584Sru@endDefesc 526469626Sru 526569626Sru@xref{Escapes}, for details on parameter delimiting characters. 526669626Sru 526769626SruIdentifiers in @code{gtroff} can be any length, but, in some contexts, 526869626Sru@code{gtroff} needs to be told where identifiers end and text begins 526969626Sru(and in different ways depending on their length): 527069626Sru 527169626Sru@itemize @bullet 527255839Sasmodai@item 527369626SruSingle character. 527469626Sru 5275104862Sru@cindex @code{(}, starting a two-character identifier 527655839Sasmodai@item 527769626SruTwo characters. Must be prefixed with @samp{(} in some situations. 527869626Sru 5279104862Sru@cindex @code{[}, starting an identifier 5280104862Sru@cindex @code{]}, ending an identifier 528155839Sasmodai@item 528269626SruArbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 5283114402Sruand@tie{}@samp{]} in some situations. Any length identifier can be put 528469626Sruin brackets. 528555839Sasmodai@end itemize 528655839Sasmodai 528769626Sru@cindex undefined identifiers 5288104862Sru@cindex identifiers, undefined 528955839SasmodaiUnlike many other programming languages, undefined identifiers are 529055839Sasmodaisilently ignored or expanded to nothing. 529175584SruWhen @code{gtroff} finds an undefined identifier, it emits a 5292104862Sruwarning, doing the following: 529355839Sasmodai 529475584Sru@itemize @bullet 529575584Sru@item 529675584SruIf the identifier is a string, macro, or diversion, 529775584Sru@code{gtroff} defines it as empty. 529855839Sasmodai 529975584Sru@item 530075584SruIf the identifier is a number register, @code{gtroff} 5301114402Srudefines it with a value of@tie{}0. 530275584Sru@end itemize 530375584Sru 5304104862Sru@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. 530575584Sru 5306104862SruNote that macros, strings, and diversions share the same name space. 530775584Sru 5308104862Sru@Example 5309104862Sru.de xxx 5310104862Sru. nop foo 5311104862Sru.. 5312104862Sru. 5313104862Sru.di xxx 5314104862Srubar 5315104862Sru.br 5316104862Sru.di 5317104862Sru. 5318104862Sru.xxx 5319104862Sru @result{} bar 5320104862Sru@endExample 5321104862Sru 5322104862Sru@noindent 5323104862SruAs can be seen in the previous example, @code{gtroff} reuses the 5324104862Sruidentifier @samp{xxx}, changing it from a macro to a diversion. 5325104862SruNo warning is emitted! The contents of the first macro definition is 5326104862Srulost. 5327104862Sru 532869626Sru@xref{Interpolating Registers}, and @ref{Strings}. 532955839Sasmodai 533069626Sru 533169626Sru@c ===================================================================== 533269626Sru 533375584Sru@node Embedded Commands, Registers, Identifiers, gtroff Reference 533455839Sasmodai@section Embedded Commands 533555839Sasmodai@cindex embedded commands 533655839Sasmodai@cindex commands, embedded 533755839Sasmodai 533869626SruMost documents need more functionality beyond filling, adjusting and 533969626Sruimplicit line breaking. In order to gain further functionality, 534069626Sru@code{gtroff} allows commands to be embedded into the text, in two ways. 534155839Sasmodai 534255839SasmodaiThe first is a @dfn{request} which takes up an entire line, and does 534375584Srusome large-scale operation (e.g.@: break lines, start new pages). 534455839Sasmodai 5345104862SruThe other is an @dfn{escape} which can be usually embedded anywhere 5346104862Sruin the text; most requests can accept it even as an argument. 534769626SruEscapes generally do more minor operations like sub- and superscripts, 534869626Sruprint a symbol, etc. 534955839Sasmodai 535055839Sasmodai@menu 535175584Sru* Requests:: 535275584Sru* Macros:: 535375584Sru* Escapes:: 535455839Sasmodai@end menu 535555839Sasmodai 535669626Sru@c --------------------------------------------------------------------- 535769626Sru 535855839Sasmodai@node Requests, Macros, Embedded Commands, Embedded Commands 535955839Sasmodai@subsection Requests 536055839Sasmodai@cindex requests 536155839Sasmodai 5362104862Sru@cindex control character (@code{.}) 5363104862Sru@cindex character, control (@code{.}) 5364104862Sru@cindex no-break control character (@code{'}) 5365104862Sru@cindex character, no-break control (@code{'}) 5366104862Sru@cindex control character, no-break (@code{'}) 536769626SruA request line begins with a control character, which is either a single 536869626Sruquote (@samp{'}, the @dfn{no-break control character}) or a period 536969626Sru(@samp{.}, the normal @dfn{control character}). These can be changed; 537069626Srusee @ref{Character Translations}, for details. After this there may be 537169626Sruoptional tabs or spaces followed by an identifier which is the name of 537269626Sruthe request. This may be followed by any number of space-separated 537375584Sruarguments (@emph{no} tabs here). 537455839Sasmodai 537575584Sru@cindex structuring source code of documents or macro packages 537675584Sru@cindex documents, structuring the source code 5377104862Sru@cindex macro packages, structuring the source code 537875584SruSince a control character followed by whitespace only is ignored, it 537975584Sruis common practice to use this feature for structuring the source code 538075584Sruof documents or macro packages. 538175584Sru 538275584Sru@Example 538375584Sru.de foo 538475584Sru. tm This is foo. 538575584Sru.. 538675584Sru. 538775584Sru. 538875584Sru.de bar 538975584Sru. tm This is bar. 539075584Sru.. 539175584Sru@endExample 539275584Sru 539375584Sru@cindex blank line 5394104862Sru@cindex blank line macro (@code{blm}) 539575584SruAnother possibility is to use the blank line macro request @code{blm} 539675584Sruby assigning an empty macro to it. 539775584Sru 539875584Sru@Example 539975584Sru.de do-nothing 540075584Sru.. 540175584Sru.blm do-nothing \" activate blank line macro 540275584Sru 540375584Sru.de foo 540475584Sru. tm This is foo. 540575584Sru.. 540675584Sru 540775584Sru 540875584Sru.de bar 540975584Sru. tm This is bar. 541075584Sru.. 541175584Sru 541275584Sru.blm \" deactivate blank line macro 541375584Sru@endExample 541475584Sru 5415104862Sru@xref{Blank Line Traps}. 541675584Sru 5417104862Sru@cindex zero width space character (@code{\&}) 5418104862Sru@cindex character, zero width space (@code{\&}) 5419104862Sru@cindex space character, zero width (@code{\&}) 542075584Sru@cindex @code{\&}, escaping control characters 542169626SruTo begin a line with a control character without it being interpreted, 542269626Sruprecede it with @code{\&}. This represents a zero width space, which 542375584Srumeans it does not affect the output. 542455839Sasmodai 542569626SruIn most cases the period is used as a control character. Several 542675584Srurequests cause a break implicitly; using the single quote control 542775584Srucharacter prevents this. 542855839Sasmodai 542955839Sasmodai@menu 5430114402Sru* Request and Macro Arguments:: 543155839Sasmodai@end menu 543255839Sasmodai 5433114402Sru@node Request and Macro Arguments, , Requests, Requests 5434114402Sru@subsubsection Request and Macro Arguments 543555839Sasmodai@cindex request arguments 5436114402Sru@cindex macro arguments 5437114402Sru@cindex arguments to requests and macros 543855839Sasmodai 5439114402SruArguments to requests and macros are processed much like the shell: 5440104862SruThe line is split into arguments according to 5441114402Sruspaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows 5442104862Srutabs for argument separation -- @code{gtroff} intentionally doesn't 5443114402Srusupport this.} 544455839Sasmodai 5445114402Sru@cindex spaces, in a macro argument 5446114402SruAn argument to a macro which is intended to contain spaces can either be 5447114402Sruenclosed in double quotes, or have the spaces @dfn{escaped} with 5448114402Srubackslashes. This is @emph{not} true for requests. 544955839Sasmodai 5450114402SruHere are a few examples for a hypothetical macro @code{uh}: 5451114402Sru 545275584Sru@Example 545355839Sasmodai.uh The Mouse Problem 545455839Sasmodai.uh "The Mouse Problem" 545555839Sasmodai.uh The\ Mouse\ Problem 545675584Sru@endExample 545755839Sasmodai 5458104862Sru@cindex @code{\~}, difference to @code{\@key{SP}} 5459104862Sru@cindex @code{\@key{SP}}, difference to @code{\~} 546069626Sru@noindent 546169626SruThe first line is the @code{uh} macro being called with 3 arguments, 546269626Sru@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 546375584Srusame effect of calling the @code{uh} macro with one argument, @samp{The 546469626SruMouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 546569626Sruis ``classical'' in the sense that it can be found in most @code{troff} 546669626Srudocuments. Nevertheless, it is not optimal in all situations, since 546769626Sru@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 546869626Srucan't stretch. @code{gtroff} provides a different command @code{\~} to 546969626Sruinsert a stretchable, non-breaking space.} 547055839Sasmodai 5471104862Sru@cindex @code{"}, in a macro argument 5472104862Sru@cindex double quote, in a macro argument 547375584SruA double quote which isn't preceded by a space doesn't start a macro 547475584Sruargument. If not closing a string, it is printed literally. 547575584Sru 547675584SruFor example, 547775584Sru 547875584Sru@Example 547975584Sru.xxx a" "b c" "de"fg" 548075584Sru@endExample 548175584Sru 548275584Sru@noindent 548375584Sruhas the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 5484104862SruDon't rely on this obscure behaviour! 548575584Sru 5486104862SruThere are two possibilities to get a double quote reliably. 5487104862Sru 5488104862Sru@itemize @bullet 5489104862Sru@item 5490104862SruEnclose the whole argument with double quotes and use two consecutive double 5491104862Sruquotes to represent a single one. This traditional solution has the 5492104862Srudisadvantage that double quotes don't survive argument expansion again if 5493104862Srucalled in compatibility mode (using the @option{-C} option of @code{groff}): 5494104862Sru 5495104862Sru@Example 5496104862Sru.de xx 5497104862Sru. tm xx: `\\$1' `\\$2' `\\$3' 5498104862Sru. 5499104862Sru. yy "\\$1" "\\$2" "\\$3" 5500104862Sru.. 5501104862Sru.de yy 5502104862Sru. tm yy: `\\$1' `\\$2' `\\$3' 5503104862Sru.. 5504104862Sru.xx A "test with ""quotes""" . 5505104862Sru @result{} xx: `A' `test with "quotes"' `.' 5506104862Sru @result{} yy: `A' `test with ' `quotes""' 5507104862Sru@endExample 5508104862Sru 5509104862Sru@noindent 5510104862SruIf not in compatibility mode, you get the expected result 5511104862Sru 5512104862Sru@Example 5513104862Sruxx: `A' `test with "quotes"' `.' 5514104862Sruyy: `A' `test with "quotes"' `.' 5515104862Sru@endExample 5516104862Sru 5517104862Sru@noindent 5518104862Srusince @code{gtroff} preserves the input level. 5519104862Sru 5520104862Sru@item 5521104862SruUse the double quote glyph @code{\(dq}. This works with and without 5522104862Srucompatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq} 5523104862Sruback to a double quote input character. 5524104862Sru 5525104862SruNot that this method won't work with @acronym{UNIX} @code{troff} in general 5526104862Srusince the glyph `dq' isn't defined normally. 5527104862Sru@end itemize 5528104862Sru 5529104862Sru@cindex @code{ds} request, and double quotes 5530104862SruDouble quotes in the @code{ds} request are handled differently. 553169626Sru@xref{Strings}, for more details. 553255839Sasmodai 553369626Sru@c --------------------------------------------------------------------- 553455839Sasmodai 553555839Sasmodai@node Macros, Escapes, Requests, Embedded Commands 553655839Sasmodai@subsection Macros 553755839Sasmodai@cindex macros 553855839Sasmodai 553969626Sru@code{gtroff} has a @dfn{macro} facility for defining a series of lines 554069626Sruwhich can be invoked by name. They are called in the same manner as 5541114402Srurequests -- arguments also may be passed basically in the same manner. 554255839Sasmodai 5543114402Sru@xref{Writing Macros}, and @ref{Request and Macro Arguments}. 554455839Sasmodai 554569626Sru@c --------------------------------------------------------------------- 554655839Sasmodai 554755839Sasmodai@node Escapes, , Macros, Embedded Commands 554855839Sasmodai@subsection Escapes 554955839Sasmodai@cindex escapes 555055839Sasmodai 555169626SruEscapes may occur anywhere in the input to @code{gtroff}. They usually 555269626Srubegin with a backslash and are followed by a single character which 555369626Sruindicates the function to be performed. The escape character can be 555469626Sruchanged; see @ref{Character Translations}. 555555839Sasmodai 555669626SruEscape sequences which require an identifier as a parameter accept three 555769626Srupossible syntax forms. 555855839Sasmodai 555969626Sru@itemize @bullet 556069626Sru@item 556169626SruThe next single character is the identifier. 556255839Sasmodai 5563104862Sru@cindex @code{(}, starting a two-character identifier 556469626Sru@item 556569626SruIf this single character is an opening parenthesis, take the following 556669626Srutwo characters as the identifier. Note that there is no closing 556769626Sruparenthesis after the identifier. 556869626Sru 5569104862Sru@cindex @code{[}, starting an identifier 5570104862Sru@cindex @code{]}, ending an identifier 557169626Sru@item 557269626SruIf this single character is an opening bracket, take all characters 557369626Sruuntil a closing bracket as the identifier. 557469626Sru@end itemize 557569626Sru 557669626Sru@noindent 557769626SruExamples: 557869626Sru 557975584Sru@Example 558055839Sasmodai\fB 558155839Sasmodai\n(XX 558255839Sasmodai\*[TeX] 558375584Sru@endExample 558455839Sasmodai 5585104862Sru@cindex @code{'}, delimiting arguments 558669626Sru@cindex argument delimiting characters 558769626Sru@cindex characters, argument delimiting 558869626Sru@cindex delimiting characters for arguments 558969626SruOther escapes may require several arguments and/or some special format. 559069626SruIn such cases the argument is traditionally enclosed in single quotes 559169626Sru(and quotes are always used in this manual for the definitions of escape 559269626Srusequences). The enclosed text is then processed according to what that 559369626Sruescape expects. Example: 559455839Sasmodai 559575584Sru@Example 559655839Sasmodai\l'1.5i\(bu' 559775584Sru@endExample 559855839Sasmodai 5599104862Sru@cindex @code{\o}, possible quote characters 5600104862Sru@cindex @code{\b}, possible quote characters 5601104862Sru@cindex @code{\X}, possible quote characters 560269626SruNote that the quote character can be replaced with any other character 560369626Sruwhich does not occur in the argument (even a newline or a space 560469626Srucharacter) in the following escapes: @code{\o}, @code{\b}, and 560569626Sru@code{\X}. This makes e.g. 560669626Sru 560775584Sru@Example 560869626SruA caf 560969626Sru\o 561069626Srue\' 561169626Sru 561269626Sru 561369626Sruin Paris 5614151497Sru @result{} A caf� in Paris 561575584Sru@endExample 561669626Sru 561769626Sru@noindent 561869626Srupossible, but it is better not to use this feature to avoid confusion. 561969626Sru 5620104862Sru@cindex @code{\%}, used as delimiter 5621104862Sru@cindex @code{\@key{SP}}, used as delimiter 5622104862Sru@cindex @code{\|}, used as delimiter 5623104862Sru@cindex @code{\^}, used as delimiter 5624104862Sru@cindex @code{\@{}, used as delimiter 5625104862Sru@cindex @code{\@}}, used as delimiter 5626104862Sru@cindex @code{\'}, used as delimiter 5627104862Sru@cindex @code{\`}, used as delimiter 5628104862Sru@cindex @code{\-}, used as delimiter 5629104862Sru@cindex @code{\_}, used as delimiter 5630104862Sru@cindex @code{\!}, used as delimiter 5631104862Sru@cindex @code{\?}, used as delimiter 5632104862Sru@cindex @code{\@@}, used as delimiter 5633104862Sru@cindex @code{\)}, used as delimiter 5634104862Sru@cindex @code{\/}, used as delimiter 5635104862Sru@cindex @code{\,}, used as delimiter 5636104862Sru@cindex @code{\&}, used as delimiter 5637104862Sru@ifnotinfo 5638104862Sru@cindex @code{\:}, used as delimiter 5639104862Sru@end ifnotinfo 5640104862Sru@ifinfo 5641104862Sru@cindex @code{\@r{<colon>}}, used as delimiter 5642104862Sru@end ifinfo 5643104862Sru@cindex @code{\~}, used as delimiter 5644104862Sru@cindex @code{\0}, used as delimiter 5645104862Sru@cindex @code{\a}, used as delimiter 5646104862Sru@cindex @code{\c}, used as delimiter 5647104862Sru@cindex @code{\d}, used as delimiter 5648104862Sru@cindex @code{\e}, used as delimiter 5649104862Sru@cindex @code{\E}, used as delimiter 5650104862Sru@cindex @code{\p}, used as delimiter 5651104862Sru@cindex @code{\r}, used as delimiter 5652104862Sru@cindex @code{\t}, used as delimiter 5653104862Sru@cindex @code{\u}, used as delimiter 565469626SruThe following escapes sequences (which are handled similarly to 565569626Srucharacters since they don't take a parameter) are also allowed as 565669626Srudelimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 565769626Sru@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 565869626Sru@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 5659104862Sru@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, 5660104862Sru@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. 5661104862SruAgain, don't use these if possible. 566269626Sru 5663104862Sru@cindex @code{\A}, allowed delimiters 5664104862Sru@cindex @code{\B}, allowed delimiters 5665104862Sru@cindex @code{\Z}, allowed delimiters 5666104862Sru@cindex @code{\C}, allowed delimiters 5667104862Sru@cindex @code{\w}, allowed delimiters 566869626SruNo newline characters as delimiters are allowed in the following 5669104862Sruescapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}. 567069626Sru 5671104862Sru@cindex @code{\D}, allowed delimiters 5672104862Sru@cindex @code{\h}, allowed delimiters 5673104862Sru@cindex @code{\H}, allowed delimiters 5674104862Sru@cindex @code{\l}, allowed delimiters 5675104862Sru@cindex @code{\L}, allowed delimiters 5676104862Sru@cindex @code{\N}, allowed delimiters 5677104862Sru@cindex @code{\R}, allowed delimiters 5678104862Sru@cindex @code{\s}, allowed delimiters 5679104862Sru@cindex @code{\S}, allowed delimiters 5680104862Sru@cindex @code{\v}, allowed delimiters 5681104862Sru@cindex @code{\x}, allowed delimiters 568269626SruFinally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 5683104862Sru@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, 5684104862Sruand @code{\x} can't use the following characters as delimiters: 568569626Sru 568669626Sru@itemize @bullet 568769626Sru@item 5688104862Sru@cindex numbers, and delimiters 5689104862Sru@cindex digits, and delimiters 569069626SruThe digits @code{0}-@code{9}. 569169626Sru 569269626Sru@item 5693104862Sru@cindex operators, as delimiters 5694104862Sru@cindex @code{+}, as delimiter 5695104862Sru@cindex @code{-}, as delimiter 5696104862Sru@cindex @code{/}, as delimiter 5697104862Sru@cindex @code{*}, as delimiter 5698104862Sru@cindex @code{%}, as delimiter 5699104862Sru@cindex @code{<}, as delimiter 5700104862Sru@cindex @code{>}, as delimiter 5701104862Sru@cindex @code{=}, as delimiter 5702104862Sru@cindex @code{&}, as delimiter 5703104862Sru@ifnotinfo 5704104862Sru@cindex @code{:}, as delimiter 5705104862Sru@end ifnotinfo 5706104862Sru@ifinfo 5707104862Sru@cindex <colon>, as delimiter 5708104862Sru@end ifinfo 5709104862Sru@cindex @code{(}, as delimiter 5710104862Sru@cindex @code{)}, as delimiter 5711104862Sru@cindex @code{.}, as delimiter 571269626SruThe (single-character) operators @samp{+-/*%<>=&:().}. 571369626Sru 571469626Sru@item 571569626Sru@cindex space character 571669626Sru@cindex character, space 571769626Sru@cindex tab character 571869626Sru@cindex character, tab 571969626Sru@cindex newline character 572069626Sru@cindex character, newline 572169626SruThe space, tab, and newline characters. 572269626Sru 572369626Sru@item 5724104862Sru@cindex @code{\%}, used as delimiter 5725104862Sru@ifnotinfo 5726104862Sru@cindex @code{\:}, used as delimiter 5727104862Sru@end ifnotinfo 5728104862Sru@ifinfo 5729104862Sru@cindex @code{\@r{<colon>}}, used as delimiter 5730104862Sru@end ifinfo 5731104862Sru@cindex @code{\@{}, used as delimiter 5732104862Sru@cindex @code{\@}}, used as delimiter 5733104862Sru@cindex @code{\'}, used as delimiter 5734104862Sru@cindex @code{\`}, used as delimiter 5735104862Sru@cindex @code{\-}, used as delimiter 5736104862Sru@cindex @code{\_}, used as delimiter 5737104862Sru@cindex @code{\!}, used as delimiter 5738104862Sru@cindex @code{\@@}, used as delimiter 5739104862Sru@cindex @code{\/}, used as delimiter 5740104862Sru@cindex @code{\c}, used as delimiter 5741104862Sru@cindex @code{\e}, used as delimiter 5742104862Sru@cindex @code{\p}, used as delimiter 5743104862SruAll escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}}, 574469626Sru@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 574569626Sru@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 574669626Sru@end itemize 574769626Sru 5748104862Sru@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 5749104862Sru@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 575075584SruTo have a backslash (actually, the current escape character) appear in the 575169626Sruoutput several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 575255839SasmodaiThese are very similar, and only differ with respect to being used in 5753104862Srumacros or diversions. @xref{Character Translations}, for an exact 5754104862Srudescription of those escapes. 575555839Sasmodai 5756104862Sru@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions}, 5757104862Sru@ref{Identifiers}, for more information. 575855839Sasmodai 575955839Sasmodai@menu 576075584Sru* Comments:: 576155839Sasmodai@end menu 576255839Sasmodai 576355839Sasmodai@node Comments, , Escapes, Escapes 576455839Sasmodai@subsubsection Comments 576555839Sasmodai@cindex comments 576655839Sasmodai 576755839SasmodaiProbably one of the most@footnote{Unfortunately, this is a lie. But 576869626Sruhopefully future @code{gtroff} hackers will believe it @code{:-)}} 576955839Sasmodaicommon forms of escapes is the comment. 577055839Sasmodai 577175584Sru@Defesc {\\", , , } 577269626SruStart a comment. Everything to the end of the input line is ignored. 577369626Sru 577455839SasmodaiThis may sound simple, but it can be tricky to keep the comments from 577569626Sruinterfering with the appearance of the final output. 577655839Sasmodai 5777104862Sru@cindex @code{ds}, @code{ds1} requests, and comments 5778104862Sru@cindex @code{as}, @code{as1} requests, and comments 577975584SruIf the escape is to the right of some text or a request, that portion 578075584Sruof the line is ignored, but the space leading up to it is noticed by 5781104862Sru@code{gtroff}. This only affects the @code{ds} and @code{as} 5782104862Srurequest and its variants. 578355839Sasmodai 5784104862Sru@cindex tabs, before comments 578569626Sru@cindex comments, lining up with tabs 578669626SruOne possibly irritating idiosyncracy is that tabs must not be used to 5787104862Sruline up comments. Tabs are not treated as whitespace between the 578869626Srurequest and macro arguments. 578955839Sasmodai 579069626Sru@cindex undefined request 579169626Sru@cindex request, undefined 579275584SruA comment on a line by itself is treated as a blank line, because 579369626Sruafter eliminating the comment, that is all that remains: 579455839Sasmodai 579575584Sru@Example 579669626SruTest 579769626Sru\" comment 579869626SruTest 579975584Sru@endExample 580069626Sru 580169626Sru@noindent 580275584Sruproduces 580369626Sru 580475584Sru@Example 580569626SruTest 580669626Sru 580769626SruTest 580875584Sru@endExample 580969626Sru 581075584SruTo avoid this, it is common to start the line with @code{.\"} which 581175584Srucauses the line to be treated as an undefined request and thus ignored 581275584Srucompletely. 581369626Sru 5814104862Sru@cindex @code{'}, as a comment 581555839SasmodaiAnother commenting scheme seen sometimes is three consecutive single 581669626Sruquotes (@code{'''}) at the beginning of a line. This works, but 581775584Sru@code{gtroff} gives a warning about an undefined macro (namely 581869626Sru@code{''}), which is harmless, but irritating. 581975584Sru@endDefesc 582055839Sasmodai 582175584Sru@Defesc {\\#, , , } 582275584SruTo avoid all this, @code{gtroff} has a new comment mechanism using the 582375584Sru@code{\#} escape. This escape works the same as @code{\"} except that 582475584Sruthe newline is also ignored: 582555839Sasmodai 582675584Sru@Example 582769626SruTest 582869626Sru\# comment 582969626SruTest 583075584Sru@endExample 583169626Sru 583269626Sru@noindent 583375584Sruproduces 583469626Sru 583575584Sru@Example 583669626SruTest Test 583775584Sru@endExample 583869626Sru 583969626Sru@noindent 584069626Sruas expected. 584175584Sru@endDefesc 584269626Sru 5843114402Sru@Defreq {ig, [@Var{end}]} 584475584SruIgnore all input until @code{gtroff} encounters the macro named 5845114402Sru@code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not 584675584Sruspecified). This is useful for commenting out large blocks of text: 584755839Sasmodai 584875584Sru@Example 584975584Srutext text text... 585075584Sru.ig 585175584SruThis is part of a large block 585275584Sruof text that has been 585375584Srutemporarily(?) commented out. 585469626Sru 585575584SruWe can restore it simply by removing 585675584Sruthe .ig request and the ".." at the 585775584Sruend of the block. 585875584Sru.. 585975584SruMore text text text... 586075584Sru@endExample 586169626Sru 586275584Sru@noindent 586375584Sruproduces 586469626Sru 586575584Sru@Example 586675584Srutext text text@dots{} More text text text@dots{} 586775584Sru@endExample 586875584Sru 586975584Sru@noindent 587075584SruNote that the commented-out block of text does not 587175584Srucause a break. 587275584Sru 587375584SruThe input is read in copy-mode; auto-incremented registers @emph{are} 587475584Sruaffected (@pxref{Auto-increment}). 587575584Sru@endDefreq 587675584Sru 587775584Sru 587869626Sru@c ===================================================================== 587969626Sru 588075584Sru@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 588155839Sasmodai@section Registers 588255839Sasmodai@cindex registers 588355839Sasmodai 588469626SruNumeric variables in @code{gtroff} are called @dfn{registers}. There 588569626Sruare a number of built-in registers, supplying anything from the date to 588669626Srudetails of formatting parameters. 588755839Sasmodai 588869626Sru@xref{Identifiers}, for details on register identifiers. 588955839Sasmodai 589055839Sasmodai@menu 589175584Sru* Setting Registers:: 589275584Sru* Interpolating Registers:: 589375584Sru* Auto-increment:: 589475584Sru* Assigning Formats:: 589575584Sru* Built-in Registers:: 589655839Sasmodai@end menu 589755839Sasmodai 589869626Sru@c --------------------------------------------------------------------- 589969626Sru 590055839Sasmodai@node Setting Registers, Interpolating Registers, Registers, Registers 590155839Sasmodai@subsection Setting Registers 5902104862Sru@cindex setting registers (@code{nr}, @code{\R}) 5903104862Sru@cindex registers, setting (@code{nr}, @code{\R}) 590455839Sasmodai 590575584SruDefine or set registers using the @code{nr} request or the 590669626Sru@code{\R} escape. 590755839Sasmodai 5908104862Sru@DefreqList {nr, ident value} 5909104862Sru@DefescListEnd {\\R, ', ident value, '} 591075584SruSet number register @var{ident} to @var{value}. If @var{ident} 591175584Srudoesn't exist, @code{gtroff} creates it. 591255839Sasmodai 591375584SruThe argument to @code{\R} usually has to be enclosed in quotes. 591469626Sru@xref{Escapes}, for details on parameter delimiting characters. 5915104862Sru 5916104862SruThe @code{\R} escape doesn't produce an input token in @code{gtroff}; 5917104862Sruwith other words, it vanishes completely after @code{gtroff} has 5918104862Sruprocessed it. 591975584Sru@endDefreq 592069626Sru 592169626SruFor example, the following two lines are equivalent: 592269626Sru 592375584Sru@Example 5924104862Sru.nr a (((17 + (3 * 4))) % 4) 5925104862Sru\R'a (((17 + (3 * 4))) % 4)' 5926104862Sru @result{} 1 592775584Sru@endExample 592855839Sasmodai 592969626SruBoth @code{nr} and @code{\R} have two additional special forms to 593075584Sruincrement or decrement a register. 593155839Sasmodai 5932104862Sru@DefreqList {nr, ident @t{+}@Var{value}} 5933104862Sru@DefreqItem {nr, ident @t{-}@Var{value}} 5934114402Sru@DefescItem {\\R, ', ident @t{+}value, '} 5935114402Sru@DefescListEnd {\\R, ', ident @t{-}value, '} 593669626SruIncrement (decrement) register @var{ident} by @var{value}. 593755839Sasmodai 593875584Sru@Example 593969626Sru.nr a 1 594069626Sru.nr a +1 594169626Sru\na 594269626Sru @result{} 2 594375584Sru@endExample 594455839Sasmodai 594569626Sru@cindex negating register values 594669626SruTo assign the negated value of a register to another register, some care 594769626Srumust be taken to get the desired result: 594855839Sasmodai 594975584Sru@Example 595069626Sru.nr a 7 595169626Sru.nr b 3 595269626Sru.nr a -\nb 595369626Sru\na 595469626Sru @result{} 4 595569626Sru.nr a (-\nb) 595669626Sru\na 595769626Sru @result{} -3 595875584Sru@endExample 595969626Sru 596069626Sru@noindent 596169626SruThe surrounding parentheses prevent the interpretation of the minus sign 596269626Sruas a decrementing operator. An alternative is to start the assignment 596369626Sruwith a @samp{0}: 596469626Sru 596575584Sru@Example 596669626Sru.nr a 7 596769626Sru.nr b -3 596869626Sru.nr a \nb 596969626Sru\na 597069626Sru @result{} 4 597169626Sru.nr a 0\nb 597269626Sru\na 597369626Sru @result{} -3 597475584Sru@endExample 597575584Sru@endDefreq 597669626Sru 597775584Sru@Defreq {rr, ident} 5978104862Sru@cindex removing number register (@code{rr}) 5979104862Sru@cindex number register, removing (@code{rr}) 5980104862Sru@cindex register, removing (@code{rr}) 598169626SruRemove number register @var{ident}. If @var{ident} doesn't exist, the 598269626Srurequest is ignored. 598375584Sru@endDefreq 598469626Sru 598575584Sru@Defreq {rnn, ident1 ident2} 5986104862Sru@cindex renaming number register (@code{rnn}) 5987104862Sru@cindex number register, renaming (@code{rnn}) 5988104862Sru@cindex register, renaming (@code{rnn}) 598969626SruRename number register @var{ident1} to @var{ident2}. If either 599069626Sru@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 599175584Sru@endDefreq 599269626Sru 599375584Sru@Defreq {aln, ident1 ident2} 5994104862Sru@cindex alias, number register, creating (@code{aln}) 5995104862Sru@cindex creating alias, for number register (@code{aln}) 5996104862Sru@cindex number register, creating alias (@code{aln}) 5997104862Sru@cindex register, creating alias (@code{aln}) 599875584SruCreate an alias @var{ident1} for a number register @var{ident2}. The 599975584Srunew name and the old name are exactly equivalent. If @var{ident1} is 600075584Sruundefined, a warning of type @samp{reg} is generated, and the request 600175584Sruis ignored. @xref{Debugging}, for information about warnings. 600275584Sru@endDefreq 600369626Sru 600469626Sru@c --------------------------------------------------------------------- 600569626Sru 600655839Sasmodai@node Interpolating Registers, Auto-increment, Setting Registers, Registers 600755839Sasmodai@subsection Interpolating Registers 6008104862Sru@cindex interpolating registers (@code{\n}) 6009104862Sru@cindex registers, interpolating (@code{\n}) 601055839Sasmodai 601169626SruNumeric registers can be accessed via the @code{\n} escape. 601255839Sasmodai 6013104862Sru@DefescList {\\n, , i, } 6014151497Sru@DefescItem {\\n, @Lparen{}, id, } 6015151497Sru@DefescListEnd {\\n, @Lbrack{}, ident, @Rbrack{}} 601675584Sru@cindex nested assignments 601775584Sru@cindex assignments, nested 601875584Sru@cindex indirect assignments 601975584Sru@cindex assignments, indirect 6020114402SruInterpolate number register with name @var{ident} (one-character 6021114402Sruname@tie{}@var{i}, two-character name @var{id}). This means that the value 6022114402Sruof the register is expanded in-place while @code{gtroff} is parsing the 6023114402Sruinput line. Nested assignments (also called indirect assignments) are 6024114402Srupossible. 602555839Sasmodai 602675584Sru@Example 602769626Sru.nr a 5 602855839Sasmodai.nr as \na+\na 602955839Sasmodai\n(as 603069626Sru @result{} 10 603175584Sru@endExample 603255839Sasmodai 603375584Sru@Example 603475584Sru.nr a1 5 603575584Sru.nr ab 6 603675584Sru.ds str b 603775584Sru.ds num 1 603875584Sru\n[a\n[num]] 603975584Sru @result{} 5 604075584Sru\n[a\*[str]] 604175584Sru @result{} 6 604275584Sru@endExample 604375584Sru@endDefesc 604475584Sru 604569626Sru@c --------------------------------------------------------------------- 604655839Sasmodai 604755839Sasmodai@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 604855839Sasmodai@subsection Auto-increment 604955839Sasmodai@cindex auto-increment 605055839Sasmodai@cindex increment, automatic 605155839Sasmodai 605275584SruNumber registers can also be auto-incremented and auto-decremented. 605375584SruThe increment or decrement value can be specified with a third 605469626Sruargument to the @code{nr} request or @code{\R} escape. 605555839Sasmodai 605675584Sru@Defreq {nr, ident value incr} 6057104862Sru@cindex @code{\R}, difference to @code{nr} 605869626SruSet number register @var{ident} to @var{value}; the increment for 605975584Sruauto-incrementing is set to @var{incr}. Note that the @code{\R} 606075584Sruescape doesn't support this notation. 606175584Sru@endDefreq 606269626Sru 606375584SruTo activate auto-incrementing, the escape @code{\n} has a special 606475584Srusyntax form. 606569626Sru 6066104862Sru@DefescList {\\n, +, i, } 6067104862Sru@DefescItem {\\n, -, i, } 6068151497Sru@DefescItem {\\n, @Lparen{}+, id, } 6069151497Sru@DefescItem {\\n, @Lparen{}-, id, } 6070151497Sru@DefescItem {\\n, +@Lparen{}, id, } 6071151497Sru@DefescItem {\\n, -@Lparen{}, id, } 6072151497Sru@DefescItem {\\n, @Lbrack{}+, ident, @Rbrack{}} 6073151497Sru@DefescItem {\\n, @Lbrack{}-, ident, @Rbrack{}} 6074151497Sru@DefescItem {\\n, +@Lbrack{}, ident, @Rbrack{}} 6075151497Sru@DefescListEnd {\\n, -@Lbrack{}, ident, @Rbrack{}} 607675584SruBefore interpolating, increment or decrement @var{ident} 6077114402Sru(one-character name@tie{}@var{i}, two-character name @var{id}) by the 607869626Sruauto-increment value as specified with the @code{nr} request (or the 607975584Sru@code{\R} escape). If no auto-increment value has been specified, 608075584Sruthese syntax forms are identical to @code{\n}. 608175584Sru@endDefesc 608269626Sru 608369626SruFor example, 608469626Sru 608575584Sru@Example 608655839Sasmodai.nr a 0 1 608755839Sasmodai.nr xx 0 5 608869626Sru.nr foo 0 -2 608955839Sasmodai\n+a, \n+a, \n+a, \n+a, \n+a 609055839Sasmodai.br 609169626Sru\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 609269626Sru.br 609369626Sru\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 609475584Sru@endExample 609555839Sasmodai 609669626Sru@noindent 609769626Sruproduces 609855839Sasmodai 609975584Sru@Example 610055839Sasmodai1, 2, 3, 4, 5 610169626Sru-5, -10, -15, -20, -25 610269626Sru-2, -4, -6, -8, -10 610375584Sru@endExample 610455839Sasmodai 610569626Sru@cindex increment value without changing the register 6106104862Sru@cindex value, incrementing without changing the register 610775584SruTo change the increment value without changing the value of a register 610875584Sru(@var{a} in the example), the following can be used: 610955839Sasmodai 611075584Sru@Example 611155839Sasmodai.nr a \na 10 611275584Sru@endExample 611355839Sasmodai 611469626Sru@c --------------------------------------------------------------------- 611555839Sasmodai 611669626Sru@node Assigning Formats, Built-in Registers, Auto-increment, Registers 611755839Sasmodai@subsection Assigning Formats 6118104862Sru@cindex assigning formats (@code{af}) 6119104862Sru@cindex formats, assigning (@code{af}) 612055839Sasmodai 612175584SruWhen a register is used in the text of an input file (as opposed to 612275584Srupart of an expression), it is textually replaced (or interpolated) 612375584Sruwith a representation of that number. This output format can be 612475584Sruchanged to a variety of formats (numbers, Roman numerals, etc.). This 612575584Sruis done using the @code{af} request. 612655839Sasmodai 612775584Sru@Defreq {af, ident format} 612869626SruChange the output format of a number register. The first argument 612969626Sru@var{ident} is the name of the number register to be changed, and the 613075584Srusecond argument @var{format} is the output format. The following 613175584Sruoutput formats are available: 613255839Sasmodai 613369626Sru@table @code 613455839Sasmodai@item 1 6135114402SruDecimal arabic numbers. This is the default format: 0, 1, 2, 6136114402Sru3,@tie{}@enddots{} 613769626Sru 613869626Sru@item 0@dots{}0 613969626SruDecimal numbers with as many digits as specified. So, @samp{00} would 6140114402Sruresult in printing numbers as 01, 02, 03,@tie{}@enddots{} 614169626Sru 614269626SruIn fact, any digit instead of zero will do; @code{gtroff} only counts 614369626Sruhow many digits are specified. As a consequence, @code{af}'s default 614469626Sruformat @samp{1} could be specified as @samp{0} also (and exactly this is 614569626Srureturned by the @code{\g} escape, see below). 614669626Sru 614755839Sasmodai@item I 614875584Sru@cindex Roman numerals 614969626Sru@cindex numerals, Roman 6150114402SruUpper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{} 615169626Sru 615255839Sasmodai@item i 6153114402SruLower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{} 615469626Sru 615555839Sasmodai@item A 6156114402SruUpper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{} 615769626Sru 615855839Sasmodai@item a 6159114402SruLower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{} 616055839Sasmodai@end table 616155839Sasmodai 616275584SruOmitting the number register format causes a warning of type 616369626Sru@samp{missing}. @xref{Debugging}, for more details. Specifying a 616469626Srunonexistent format causes an error. 616555839Sasmodai 616675584SruThe following example produces @samp{10, X, j, 010}: 616769626Sru 616875584Sru@Example 616955839Sasmodai.nr a 10 617055839Sasmodai.af a 1 \" the default format 617155839Sasmodai\na, 617255839Sasmodai.af a I 617355839Sasmodai\na, 617455839Sasmodai.af a a 617555839Sasmodai\na, 617655839Sasmodai.af a 001 617755839Sasmodai\na 617875584Sru@endExample 617955839Sasmodai 618075584Sru@cindex Roman numerals, maximum and minimum 618169626Sru@cindex maximum values of Roman numerals 618269626Sru@cindex minimum values of Roman numerals 618369626SruThe largest number representable for the @samp{i} and @samp{I} formats 618475584Sruis 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 618575584Sruand @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 618669626Sru@code{gtroff}. Currently, the correct glyphs of Roman numeral five 618769626Sruthousand and Roman numeral ten thousand (Unicode code points 618869626Sru@code{U+2182} and @code{U+2181}, respectively) are not available. 618955839Sasmodai 619075584SruIf @var{ident} doesn't exist, it is created. 619155839Sasmodai 619269626Sru@cindex read-only register, changing format 6193104862Sru@cindex changing format, and read-only registers 619469626SruChanging the output format of a read-only register causes an error. It 619569626Sruis necessary to first copy the register's value to a writeable register, 619669626Sruthen apply the @code{af} request to this other register. 619775584Sru@endDefreq 619855839Sasmodai 6199104862Sru@DefescList {\\g, , i, } 6200151497Sru@DefescItem {\\g, @Lparen{}, id, } 6201151497Sru@DefescListEnd {\\g, @Lbrack{}, ident, @Rbrack{}} 6202104862Sru@cindex format of register (@code{\g}) 6203104862Sru@cindex register, format (@code{\g}) 620475584SruReturn the current format of the specified register @var{ident} 6205114402Sru(one-character name@tie{}@var{i}, two-character name @var{id}). For 620675584Sruexample, @samp{\ga} after the previous example would produce the 620775584Srustring @samp{000}. If the register hasn't been defined yet, nothing 620875584Sruis returned. 620975584Sru@endDefesc 621055839Sasmodai 621169626Sru@c --------------------------------------------------------------------- 621255839Sasmodai 621369626Sru@node Built-in Registers, , Assigning Formats, Registers 621469626Sru@subsection Built-in Registers 621569626Sru@cindex built-in registers 621669626Sru@cindex registers, built-in 621755839Sasmodai 621869626SruThe following lists some built-in registers which are not described 621969626Sruelsewhere in this manual. Any register which begins with a @samp{.} is 622069626Sruread-only. A complete listing of all built-in registers can be found in 6221151497Sru@ref{Register Index}. 622269626Sru 622355839Sasmodai@table @code 6224151497Sru@item \n[.F] 6225104862Sru@cindex current input file name register (@code{.F}) 6226104862Sru@cindex input file name, current, register (@code{.F}) 6227104862Sru@vindex .F 6228104862SruThis string-valued register returns the current input file name. 6229104862Sru 6230151497Sru@item \n[.H] 6231104862Sru@cindex horizontal resolution register (@code{.H}) 6232104862Sru@cindex resolution, horizontal, register (@code{.H}) 623355839Sasmodai@vindex .H 623455839SasmodaiHorizontal resolution in basic units. 623569626Sru 6236151497Sru@item \n[.U] 6237151497Sru@cindex safer mode 6238151497Sru@cindex mode, safer 6239151497Sru@cindex unsafe mode 6240151497Sru@cindex mode, unsafe 6241151497SruIf @code{gtroff} is called with the @option{-U} command line option, the 6242151497Srunumber register @code{.U} is set to@tie{}1, and zero otherwise. 6243151497Sru@xref{Groff Options}. 6244151497Sru 6245151497Sru@item \n[.V] 6246104862Sru@cindex vertical resolution register (@code{.V}) 6247104862Sru@cindex resolution, vertical, register (@code{.V}) 624855839Sasmodai@vindex .V 624955839SasmodaiVertical resolution in basic units. 625069626Sru 6251151497Sru@item \n[seconds] 6252104862Sru@cindex seconds, current time (@code{seconds}) 6253104862Sru@cindex time, current, seconds (@code{seconds}) 6254104862Sru@cindex current time, seconds (@code{seconds}) 6255104862Sru@vindex seconds 6256114402SruThe number of seconds after the minute, normally in the range@tie{}0 6257114402Sruto@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized 6258104862Sruat start-up of @code{gtroff}. 6259104862Sru 6260151497Sru@item \n[minutes] 6261104862Sru@cindex minutes, current time (@code{minutes}) 6262104862Sru@cindex time, current, minutes (@code{minutes}) 6263104862Sru@cindex current time, minutes (@code{minutes}) 6264104862Sru@vindex minutes 6265114402SruThe number of minutes after the hour, in the range@tie{}0 to@tie{}59. 6266104862SruInitialized at start-up of @code{gtroff}. 6267104862Sru 6268151497Sru@item \n[hours] 6269104862Sru@cindex hours, current time (@code{hours}) 6270104862Sru@cindex time, current, hours (@code{hours}) 6271104862Sru@cindex current time, hours (@code{hours}) 6272104862Sru@vindex hours 6273114402SruThe number of hours past midnight, in the range@tie{}0 to@tie{}23. 6274104862SruInitialized at start-up of @code{gtroff}. 6275104862Sru 6276151497Sru@item \n[dw] 6277104862Sru@cindex day of the week register (@code{dw}) 6278104862Sru@cindex date, day of the week register (@code{dw}) 627955839Sasmodai@vindex dw 628055839SasmodaiDay of the week (1-7). 628169626Sru 6282151497Sru@item \n[dy] 6283104862Sru@cindex day of the month register (@code{dy}) 6284104862Sru@cindex date, day of the month register (@code{dy}) 628555839Sasmodai@vindex dy 628669626SruDay of the month (1-31). 628769626Sru 6288151497Sru@item \n[mo] 6289104862Sru@cindex month of the year register (@code{mo}) 6290104862Sru@cindex date, month of the year register (@code{mo}) 629155839Sasmodai@vindex mo 629255839SasmodaiCurrent month (1-12). 629369626Sru 6294151497Sru@item \n[year] 6295104862Sru@cindex date, year register (@code{year}, @code{yr}) 6296104862Sru@cindex year, current, register (@code{year}, @code{yr}) 629769626Sru@vindex year 629869626SruThe current year. 629969626Sru 6300151497Sru@item \n[yr] 630155839Sasmodai@vindex yr 6302114402SruThe current year minus@tie{}1900. Unfortunately, the documentation of 6303114402Sru@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It 630469626Sruincorrectly claimed that @code{yr} contains the last two digits of the 6305104862Sruyear. That claim has never been true of either @acronym{AT&T} 6306104862Sru@code{troff} or GNU @code{troff}. Old @code{troff} input that looks 6307104862Srulike this: 630869626Sru 630975584Sru@Example 631069626Sru'\" The following line stopped working after 1999 631169626SruThis document was formatted in 19\n(yr. 631275584Sru@endExample 631369626Sru 631469626Sru@noindent 631569626Srucan be corrected as follows: 631669626Sru 631775584Sru@Example 631869626SruThis document was formatted in \n[year]. 631975584Sru@endExample 632069626Sru 632169626Sru@noindent 632269626Sruor, to be portable to older @code{troff} versions, as follows: 632369626Sru 632475584Sru@Example 632569626Sru.nr y4 1900+\n(yr 632669626SruThis document was formatted in \n(y4. 632775584Sru@endExample 632869626Sru 6329151497Sru@item \n[.c] 633055839Sasmodai@vindex .c 6331151497Sru@itemx \n[c.] 633255839Sasmodai@vindex c. 6333104862Sru@cindex input line number register (@code{.c}, @code{c.}) 6334104862Sru@cindex line number, input, register (@code{.c}, @code{c.}) 633569626SruThe current @emph{input} line number. Register @samp{.c} is read-only, 633669626Sruwhereas @samp{c.} (a @code{gtroff} extension) is writable also, 633769626Sruaffecting both @samp{.c} and @samp{c.}. 633869626Sru 6339151497Sru@item \n[ln] 634055839Sasmodai@vindex ln 6341104862Sru@cindex output line number register (@code{ln}) 6342104862Sru@cindex line number, output, register (@code{ln}) 634369626SruThe current @emph{output} line number after a call to the @code{nm} 634469626Srurequest to activate line numbering. 634569626Sru 634675584Sru@xref{Miscellaneous}, for more information about line numbering. 634769626Sru 6348151497Sru@item \n[.x] 634955839Sasmodai@vindex .x 6350104862Sru@cindex major version number register (@code{.x}) 6351104862Sru@cindex version number, major, register (@code{.x}) 6352114402SruThe major version number. For example, if the version number 6353114402Sruis 1.03 then @code{.x} contains@tie{}@samp{1}. 635469626Sru 6355151497Sru@item \n[.y] 635655839Sasmodai@vindex .y 6357104862Sru@cindex minor version number register (@code{.y}) 6358104862Sru@cindex version number, minor, register (@code{.y}) 6359114402SruThe minor version number. For example, if the version number 6360114402Sruis 1.03 then @code{.y} contains@tie{}@samp{03}. 636169626Sru 6362151497Sru@item \n[.Y] 636369626Sru@vindex .Y 6364104862Sru@cindex revision number register (@code{.Y}) 636569626SruThe revision number of @code{groff}. 636669626Sru 6367151497Sru@item \n[$$] 6368104862Sru@vindex $$ 6369104862Sru@cindex process ID of @code{gtroff} register (@code{$$}) 6370104862Sru@cindex @code{gtroff}, process ID register (@code{$$}) 6371104862SruThe process ID of @code{gtroff}. 6372104862Sru 6373151497Sru@item \n[.g] 637455839Sasmodai@vindex .g 6375104862Sru@cindex @code{gtroff}, identification register (@code{.g}) 6376104862Sru@cindex GNU-specific register (@code{.g}) 6377114402SruAlways@tie{}1. Macros should use this to determine whether they are 637869626Srurunning under GNU @code{troff}. 637969626Sru 6380151497Sru@item \n[.A] 638155839Sasmodai@vindex .A 6382104862Sru@cindex @acronym{ASCII} approximation output register (@code{.A}) 638369626SruIf the command line option @option{-a} is used to produce an 6384114402Sru@acronym{ASCII} approximation of the output, this is set to@tie{}1, zero 638569626Sruotherwise. @xref{Groff Options}. 638669626Sru 6387151497Sru@item \n[.P] 638855839Sasmodai@vindex .P 6389114402SruThis register is set to@tie{}1 (and to@tie{}0 otherwise) if the current 639069626Srupage is actually being printed, i.e., if the @option{-o} option is being 639169626Sruused to only print selected pages. @xref{Groff Options}, for more 639269626Sruinformation. 639369626Sru 6394151497Sru@item \n[.T] 639569626Sru@vindex .T 639669626SruIf @code{gtroff} is called with the @option{-T} command line option, the 6397114402Srunumber register @code{.T} is set to@tie{}1, and zero otherwise. 639869626Sru@xref{Groff Options}. 639969626Sru 6400151497Sru@item \*[.T] 640175584Sru@stindex .T 6402104862Sru@cindex output device name string register (@code{.T}) 6403151497SruA single read-write string register which contains the current output 6404151497Srudevice (for example, @samp{latin1} or @samp{ps}). This is the only 6405151497Srustring register defined by @code{gtroff}. 640655839Sasmodai@end table 640755839Sasmodai 640869626Sru 640969626Sru@c ===================================================================== 641069626Sru 641175584Sru@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 641255839Sasmodai@section Manipulating Filling and Adjusting 641355839Sasmodai@cindex manipulating filling and adjusting 641455839Sasmodai@cindex filling and adjusting, manipulating 641555839Sasmodai@cindex adjusting and filling, manipulating 641669626Sru@cindex justifying text 641769626Sru@cindex text, justifying 641855839Sasmodai 641955839Sasmodai@cindex break 642055839Sasmodai@cindex line break 6421104862Sru@cindex @code{bp} request, causing implicit linebreak 6422104862Sru@cindex @code{ce} request, causing implicit linebreak 6423104862Sru@cindex @code{cf} request, causing implicit linebreak 6424104862Sru@cindex @code{fi} request, causing implicit linebreak 6425104862Sru@cindex @code{fl} request, causing implicit linebreak 6426104862Sru@cindex @code{in} request, causing implicit linebreak 6427104862Sru@cindex @code{nf} request, causing implicit linebreak 6428104862Sru@cindex @code{rj} request, causing implicit linebreak 6429104862Sru@cindex @code{sp} request, causing implicit linebreak 6430104862Sru@cindex @code{ti} request, causing implicit linebreak 6431104862Sru@cindex @code{trf} request, causing implicit linebreak 643269626SruVarious ways of causing @dfn{breaks} were given in @ref{Implicit Line 643375584SruBreaks}. The @code{br} request likewise causes a break. Several 643475584Sruother requests also cause breaks, but implicitly. These are 643569626Sru@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 643669626Sru@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 643755839Sasmodai 643875584Sru@Defreq {br, } 643975584SruBreak the current line, i.e., the input collected so far is emitted 644069626Sruwithout adjustment. 644169626Sru 644275584SruIf the no-break control character is used, @code{gtroff} suppresses 644375584Sruthe break: 644469626Sru 644575584Sru@Example 644669626Srua 644769626Sru'br 644869626Srub 644969626Sru @result{} a b 645075584Sru@endExample 645175584Sru@endDefreq 645269626Sru 645375584SruInitially, @code{gtroff} fills and adjusts text to both margins. 645469626SruFilling can be disabled via the @code{nf} request and re-enabled with 645569626Sruthe @code{fi} request. 645669626Sru 6457104862Sru@DefreqList {fi, } 6458104862Sru@DefregListEnd {.u} 6459104862Sru@cindex fill mode (@code{fi}) 6460104862Sru@cindex mode, fill (@code{fi}) 646169626SruActivate fill mode (which is the default). This request implicitly 646275584Sruenables adjusting; it also inserts a break in the text currently being 6463114402Srufilled. The read-only number register @code{.u} is set to@tie{}1. 646455839Sasmodai 646569626SruThe fill mode status is associated with the current environment 646669626Sru(@pxref{Environments}). 6467104862Sru 6468104862SruSee @ref{Line Control}, for interaction with the @code{\c} escape. 646975584Sru@endDefreq 647055839Sasmodai 647175584Sru@Defreq {nf, } 6472104862Sru@cindex no-fill mode (@code{nf}) 6473104862Sru@cindex mode, no-fill (@code{nf}) 647469626SruActivate no-fill mode. Input lines are output as-is, retaining line 647575584Srubreaks and ignoring the current line length. This command implicitly 647675584Srudisables adjusting; it also causes a break. The number register 6477114402Sru@code{.u} is set to@tie{}0. 647869626Sru 647969626SruThe fill mode status is associated with the current environment 648069626Sru(@pxref{Environments}). 6481104862Sru 6482104862SruSee @ref{Line Control}, for interaction with the @code{\c} escape. 648375584Sru@endDefreq 648469626Sru 6485104862Sru@DefreqList {ad, [@Var{mode}]} 6486104862Sru@DefregListEnd {.j} 648769626SruSet adjusting mode. 648869626Sru 648975584SruActivation and deactivation of adjusting is done implicitly with 649075584Srucalls to the @code{fi} or @code{nf} requests. 649169626Sru 649269626Sru@var{mode} can have one of the following values: 649369626Sru 649469626Sru@table @code 649555839Sasmodai@item l 649655839Sasmodai@cindex ragged-right 649755839SasmodaiAdjust text to the left margin. This produces what is traditionally 649855839Sasmodaicalled ragged-right text. 649969626Sru 650055839Sasmodai@item r 650169626Sru@cindex ragged-left 650269626SruAdjust text to the right margin, producing ragged-left text. 650369626Sru 650455839Sasmodai@item c 650569626Sru@cindex centered text 6506114402Sru@cindex @code{ce} request, difference to @samp{.ad@tie{}c} 650769626SruCenter filled text. This is different to the @code{ce} request which 650869626Sruonly centers text without filling. 650969626Sru 651055839Sasmodai@item b 651155839Sasmodai@itemx n 651269626SruJustify to both margins. This is the default used by @code{gtroff}. 651355839Sasmodai@end table 651455839Sasmodai 6515114402SruFinally, @var{mode} can be the numeric argument returned by the @code{.j} 6516114402Sruregister. 6517114402Sru 651875584SruWith no argument, @code{gtroff} adjusts lines in the same way it did 651975584Srubefore adjusting was deactivated (with a call to @code{na}, for 652069626Sruexample). 652155839Sasmodai 652275584Sru@Example 652355839Sasmodaitext 652455839Sasmodai.ad r 6525114402Sru.nr ad \n[.j] 652655839Sasmodaitext 652755839Sasmodai.ad c 652855839Sasmodaitext 652955839Sasmodai.na 653055839Sasmodaitext 6531114402Sru.ad \" back to centering 653255839Sasmodaitext 6533114402Sru.ad \n[ad] \" back to right justifying 653475584Sru@endExample 653555839Sasmodai 6536104862Sru@cindex adjustment mode register (@code{.j}) 653775584SruThe current adjustment mode is available in the read-only number 653875584Sruregister @code{.j}; it can be stored and subsequently used to set 653975584Sruadjustment. 654055839Sasmodai 654169626SruThe adjustment mode status is associated with the current environment 654269626Sru(@pxref{Environments}). 654375584Sru@endDefreq 654455839Sasmodai 654575584Sru@Defreq {na, } 654669626SruDisable adjusting. This request won't change the current adjustment 654775584Srumode: A subsequent call to @code{ad} uses the previous adjustment 654869626Srusetting. 654955839Sasmodai 655069626SruThe adjustment mode status is associated with the current environment 655169626Sru(@pxref{Environments}). 655275584Sru@endDefreq 655369626Sru 6554104862Sru@DefreqList {brp, } 6555104862Sru@DefescListEnd {\\p, , , } 655669626SruAdjust the current line and cause a break. 655769626Sru 6558104862SruIn most cases this produces very ugly results since @code{gtroff} 655969626Srudoesn't have a sophisticated paragraph building algorithm (as @TeX{} 656075584Sruhave, for example); instead, @code{gtroff} fills and adjusts a paragraph 656169626Sruline by line: 656269626Sru 656375584Sru@Example 656469626Sru This is an uninteresting sentence. 656569626Sru This is an uninteresting sentence.\p 656669626Sru This is an uninteresting sentence. 656775584Sru@endExample 656869626Sru 656975584Sru@noindent 657069626Sruis formatted as 657169626Sru 657275584Sru@Example 657369626Sru This is an uninteresting sentence. This is an 657469626Sru uninteresting sentence. 657569626Sru This is an uninteresting sentence. 657675584Sru@endExample 6577104862Sru@endDefreq 657869626Sru 6579104862Sru@DefreqList {ss, word_space_size [@Var{sentence_space_size}]} 6580104862Sru@DefregItem {.ss} 6581104862Sru@DefregListEnd {.sss} 6582104862Sru@cindex word space size register (@code{.ss}) 6583104862Sru@cindex size of word space register (@code{.ss}) 6584104862Sru@cindex space between words register (@code{.ss}) 6585104862Sru@cindex sentence space size register (@code{.sss}) 6586104862Sru@cindex size of sentence space register (@code{.sss}) 6587104862Sru@cindex space between sentences register (@code{.sss}) 6588114402SruChange the size of a space between words. It takes its units as one 6589114402Srutwelfth of the space width parameter for the current font. 6590114402SruInitially both the @var{word_space_size} and @var{sentence_space_size} 6591114402Sruare@tie{}12. In fill mode, the values specify the minimum distance. 659269626Sru 659369626Sru@cindex fill mode 659469626Sru@cindex mode, fill 659575584SruIf two arguments are given to the @code{ss} request, the second 659675584Sruargument sets the sentence space size. If the second argument is not 659775584Srugiven, sentence space size is set to @var{word_space_size}. The 659875584Srusentence space size is used in two circumstances: If the end of a 659975584Srusentence occurs at the end of a line in fill mode, then both an 660075584Sruinter-word space and a sentence space are added; if two spaces follow 660175584Sruthe end of a sentence in the middle of a line, then the second space 660275584Sruis a sentence space. If a second argument is never given to the 660375584Sru@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 660475584Srusame as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 660575584Sruin @acronym{UNIX} @code{troff}, a sentence should always be followed 660675584Sruby either a newline or two spaces. 660769626Sru 660875584SruThe read-only number registers @code{.ss} and @code{.sss} hold the 660975584Sruvalues of the parameters set by the first and second arguments of the 661075584Sru@code{ss} request. 661155839Sasmodai 661269626SruThe word space and sentence space values are associated with the current 661369626Sruenvironment (@pxref{Environments}). 661455839Sasmodai 6615104862SruContrary to @acronym{AT&T} @code{troff}, this request is @emph{not} 6616104862Sruignored if a TTY output device is used; the given values are then 6617114402Srurounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}). 661855839Sasmodai 661975584SruThe request is ignored if there is no parameter. 6620114402Sru 6621114402Sru@cindex discardable horizontal space 6622114402Sru@cindex space, discardable, horizontal 6623114402Sru@cindex horizontal discardable space 6624114402SruAnother useful application of the @code{ss} request is to insert 6625114402Srudiscardable horizontal space, i.e., space which is discarded at a line 6626114402Srubreak. For example, paragraph-style footnotes could be separated this 6627114402Sruway: 6628114402Sru 6629114402Sru@Example 6630114402Sru.ll 4.5i 6631114402Sru1.\ This is the first footnote.\c 6632114402Sru.ss 48 6633114402Sru.nop 6634114402Sru.ss 12 6635114402Sru2.\ This is the second footnote. 6636114402Sru@endExample 6637114402Sru 6638114402Sru@noindent 6639114402SruThe result: 6640114402Sru 6641114402Sru@Example 6642114402Sru1. This is the first footnote. 2. This 6643114402Sruis the second footnote. 6644114402Sru@endExample 6645114402Sru 6646114402Sru@noindent 6647114402SruNote that the @code{\h} escape produces unbreakable space. 664875584Sru@endDefreq 664975584Sru 6650104862Sru@DefreqList {ce, [@Var{nnn}]} 6651104862Sru@DefregListEnd {.ce} 6652104862Sru@cindex centering lines (@code{ce}) 6653104862Sru@cindex lines, centering (@code{ce}) 665475584SruCenter text. While the @w{@samp{.ad c}} request also centers text, 665575584Sruit fills the text as well. @code{ce} does not fill the 6656104862Srutext it affects. This request causes a break. The number of lines 6657104862Srustill to be centered is associated with the current environment 6658104862Sru(@pxref{Environments}). 665955839Sasmodai 666075584SruThe following example demonstrates the differences. 666175584SruHere the input: 666269626Sru 666375584Sru@Example 666475584Sru.ll 4i 666575584Sru.ce 1000 666675584SruThis is a small text fragment which shows the differences 666775584Srubetween the `.ce' and the `.ad c' request. 666875584Sru.ce 0 666975584Sru 667075584Sru.ad c 667175584SruThis is a small text fragment which shows the differences 667275584Srubetween the `.ce' and the `.ad c' request. 667375584Sru@endExample 667475584Sru 667575584Sru@noindent 667675584SruAnd here the result: 667775584Sru 667875584Sru@Example 667975584Sru This is a small text fragment which 668075584Sru shows the differences 668175584Srubetween the `.ce' and the `.ad c' request. 668275584Sru 668375584Sru This is a small text fragment which 668475584Srushows the differences between the `.ce' 668575584Sru and the `.ad c' request. 668675584Sru@endExample 668775584Sru 668875584SruWith no arguments, @code{ce} centers the next line of text. @var{nnn} 668975584Sruspecifies the number of lines to be centered. If the argument is zero 669075584Sruor negative, centering is disabled. 669175584Sru 669269626SruThe basic length for centering text is the line length (as set with the 669369626Sru@code{ll} request) minus the indentation (as set with the @code{in} 669469626Srurequest). Temporary indentation is ignored. 669569626Sru 669675584SruAs can be seen in the previous example, it is a common idiom to turn 669775584Sruon centering for a large number of lines, and to turn off centering 669875584Sruafter text to be centered. This is useful for any request which takes 669975584Srua number of lines as an argument. 670069626Sru 670175584SruThe @code{.ce} read-only number register contains the number of lines 670275584Sruremaining to be centered, as set by the @code{ce} request. 670375584Sru@endDefreq 670455839Sasmodai 6705104862Sru@DefreqList {rj, [@Var{nnn}]} 6706104862Sru@DefregListEnd {.rj} 6707104862Sru@cindex justifying text (@code{rj}) 6708104862Sru@cindex text, justifying (@code{rj}) 6709104862Sru@cindex right-justifying (@code{rj}) 671069626SruJustify unfilled text to the right margin. Arguments are identical to 671175584Sruthe @code{ce} request. The @code{.rj} read-only number register is 671275584Sruthe number of lines to be right-justified as set by the @code{rj} 6713104862Srurequest. This request causes a break. The number of lines still to be 6714104862Sruright-justified is associated with the current environment 6715104862Sru(@pxref{Environments}). 671675584Sru@endDefreq 671755839Sasmodai 671855839Sasmodai 671969626Sru@c ===================================================================== 672055839Sasmodai 672175584Sru@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 672255839Sasmodai@section Manipulating Hyphenation 672355839Sasmodai@cindex manipulating hyphenation 672455839Sasmodai@cindex hyphenation, manipulating 672555839Sasmodai 672655839Sasmodai 6727151497SruHere a description of requests which influence hyphenation. 6728151497Sru 6729104862Sru@DefreqList {hy, [@Var{mode}]} 6730104862Sru@DefregListEnd {.hy} 673169626SruEnable hyphenation. The request has an optional numeric argument, 673269626Sru@var{mode}, to restrict hyphenation if necessary: 673355839Sasmodai 673469626Sru@table @code 673569626Sru@item 1 673669626SruThe default argument if @var{mode} is omitted. Hyphenate without 673769626Srurestrictions. This is also the start-up value of @code{gtroff}. 673855839Sasmodai 673955839Sasmodai@item 2 674055839SasmodaiDo not hyphenate the last word on a page or column. 674169626Sru 674255839Sasmodai@item 4 674355839SasmodaiDo not hyphenate the last two characters of a word. 674469626Sru 674555839Sasmodai@item 8 674655839SasmodaiDo not hyphenate the first two characters of a word. 674755839Sasmodai@end table 674855839Sasmodai 6749114402SruValues in the previous table are additive. For example, the 6750114402Sruvalue@tie{}12 causes @code{gtroff} to neither hyphenate the last 6751114402Srutwo nor the first two characters of a word. 675269626Sru 6753104862Sru@cindex hyphenation restrictions register (@code{.hy}) 675475584SruThe current hyphenation restrictions can be found in the read-only 675575584Srunumber register @samp{.hy}. 675669626Sru 675769626SruThe hyphenation mode is associated with the current environment 675869626Sru(@pxref{Environments}). 675975584Sru@endDefreq 676069626Sru 676175584Sru@Defreq {nh, } 676275584SruDisable hyphenation (i.e., set the hyphenation mode to zero). Note 676375584Sruthat the hyphenation mode of the last call to @code{hy} is not 676475584Sruremembered. 676569626Sru 676669626SruThe hyphenation mode is associated with the current environment 676769626Sru(@pxref{Environments}). 676875584Sru@endDefreq 676969626Sru 6770104862Sru@DefreqList {hlm, [@Var{nnn}]} 6771104862Sru@DefregItem {.hlm} 6772104862Sru@DefregListEnd {.hlc} 6773104862Sru@cindex explicit hyphen (@code{\%}) 6774104862Sru@cindex hyphen, explicit (@code{\%}) 6775104862Sru@cindex consecutive hyphenated lines (@code{hlm}) 6776104862Sru@cindex lines, consecutive hyphenated (@code{hlm}) 6777104862Sru@cindex hyphenated lines, consecutive (@code{hlm}) 677875584SruSet the maximum number of consecutive hyphenated lines to @var{nnn}. 677975584SruIf this number is negative, there is no maximum. The default value 6780114402Sruis@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated 678175584Sruwith the current environment (@pxref{Environments}). Only lines 678275584Sruoutput from a given environment count towards the maximum associated 678375584Sruwith that environment. Hyphens resulting from @code{\%} are counted; 678475584Sruexplicit hyphens are not. 678555839Sasmodai 678669626SruThe current setting of @code{hlm} is available in the @code{.hlm} 678775584Sruread-only number register. Also the number of immediately preceding 678875584Sruconsecutive hyphenated lines are available in the read-only number 678975584Sruregister @samp{.hlc}. 679075584Sru@endDefreq 679155839Sasmodai 679275584Sru@Defreq {hw, word1 word2 @dots{}} 679369626SruDefine how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 679469626Sruwords must be given with hyphens at the hyphenation points. For 679569626Sruexample: 679669626Sru 679775584Sru@Example 679869626Sru.hw in-sa-lub-rious 679975584Sru@endExample 680069626Sru 680169626Sru@noindent 680269626SruBesides the space character, any character whose hyphenation code value 680369626Sruis zero can be used to separate the arguments of @code{hw} (see the 680469626Srudocumentation for the @code{hcode} request below for more information). 680569626SruIn addition, this request can be used more than once. 680669626Sru 680769626SruHyphenation exceptions specified with the @code{hw} request are 680875584Sruassociated with the current hyphenation language; it causes an error 680969626Sruif there is no current hyphenation language. 681069626Sru 681169626SruThis request is ignored if there is no parameter. 681269626Sru 681369626SruIn old versions of @code{troff} there was a limited amount of space to 681469626Srustore such information; fortunately, with @code{gtroff}, this is no 681569626Srulonger a restriction. 681675584Sru@endDefreq 681769626Sru 6818104862Sru@DefescList {\\%, , , } 6819104862Sru@deffnx Escape @t{\:} 6820104862Sru@ifnotinfo 6821104862Sru@esindex \: 6822104862Sru@end ifnotinfo 6823104862Sru@ifinfo 6824114402Sru@esindex \@r{<colon>} 6825104862Sru@end ifinfo 6826104862Sru@cindex hyphenation character (@code{\%}) 6827104862Sru@cindex character, hyphenation (@code{\%}) 6828104862Sru@cindex disabling hyphenation (@code{\%}) 6829104862Sru@cindex hyphenation, disabling (@code{\%}) 683075584SruTo tell @code{gtroff} how to hyphenate words on the fly, use the 683175584Sru@code{\%} escape, also known as the @dfn{hyphenation character}. 683275584SruPreceding a word with this character prevents it from being 683375584Sruhyphenated; putting it inside a word indicates to @code{gtroff} that 683475584Sruthe word may be hyphenated at that point. Note that this mechanism 683575584Sruonly affects that one occurrence of the word; to change the 683675584Sruhyphenation of a word for the entire document, use the @code{hw} 683775584Srurequest. 6838104862Sru 6839104862SruThe @code{\:} escape inserts a zero-width break point 6840104862Sru(that is, the word breaks but without adding a hyphen). 6841104862Sru 6842104862Sru@Example 6843104862Sru... check the /var/log/\:httpd/\:access_log file ... 6844104862Sru@endExample 6845104862Sru 6846104862Sru@cindex @code{\X}, followed by @code{\%} 6847104862Sru@cindex @code{\Y}, followed by @code{\%} 6848104862Sru@cindex @code{\%}, following @code{\X} or @code{\Y} 6849104862SruNote that @code{\X} and @code{\Y} start a word, that is, the @code{\%} 6850114402Sruescape in (say) @w{@samp{\X'...'\%foobar}} and 6851114402Sru@w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts 6852104862Srua hyphenation point at the beginning of @samp{foobar}; most likely 6853104862Sruthis isn't what you want to do. 685475584Sru@endDefesc 685555839Sasmodai 685675584Sru@Defreq {hc, [@Var{char}]} 685775584SruChange the hyphenation character to @var{char}. This character then 685875584Sruworks the same as the @code{\%} escape, and thus, no longer appears in 685975584Sruthe output. Without an argument, @code{hc} resets the hyphenation 686075584Srucharacter to be @code{\%} (the default) only. 686155839Sasmodai 686269626SruThe hyphenation character is associated with the current environment 686369626Sru(@pxref{Environments}). 686475584Sru@endDefreq 686555839Sasmodai 6866104862Sru@DefreqList {hpf, pattern_file} 6867104862Sru@DefreqItem {hpfa, pattern_file} 6868104862Sru@DefreqListEnd {hpfcode, a b [c d @dots{}]} 6869104862Sru@cindex hyphenation patterns (@code{hpf}) 6870104862Sru@cindex patterns for hyphenation (@code{hpf}) 687175584SruRead in a file of hyphenation patterns. This file is searched for in 687275584Sruthe same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 687375584Srusearched for if the @option{-m@var{name}} option is specified. 687455839Sasmodai 6875104862SruIt should have the same format as (simple) @TeX{} patterns files. 6876104862SruMore specifically, the following scanning rules are implemented. 687769626Sru 6878104862Sru@itemize @bullet 6879104862Sru@item 6880104862SruA percent sign starts a comment (up to the end of the line) 6881104862Srueven if preceded by a backslash. 6882104862Sru 6883104862Sru@item 6884104862SruNo support for `digraphs' like @code{\$}. 6885104862Sru 6886104862Sru@item 6887104862Sru@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character 6888104862Srucode of @var{x} in the range 0-127) are recognized; other use of @code{^} 6889104862Srucauses an error. 6890104862Sru 6891104862Sru@item 6892104862SruNo macro expansion. 6893104862Sru 6894104862Sru@item 6895104862Sru@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} 6896104862Sru(possibly with whitespace before and after the braces). 6897104862SruEverything between the braces is taken as hyphenation patterns. 6898104862SruConsequently, @code{@{} and @code{@}} are not allowed in patterns. 6899104862Sru 6900104862Sru@item 6901104862SruSimilarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation 6902104862Sruexceptions. 6903104862Sru 6904104862Sru@item 6905104862Sru@code{\endinput} is recognized also. 6906104862Sru 6907104862Sru@item 6908104862SruFor backwards compatibility, if @code{\patterns} is missing, 6909104862Sruthe whole file is treated as a list of hyphenation patterns 6910104862Sru(only recognizing the @code{%} character as the start of a comment). 6911104862Sru@end itemize 6912104862Sru 691369626SruIf no @code{hpf} request is specified (either in the document or in a 691469626Srumacro package), @code{gtroff} won't hyphenate at all. 691569626Sru 6916104862SruThe @code{hpfa} request appends a file of patterns to the current list. 6917104862Sru 6918104862SruThe @code{hpfcode} request defines mapping values for character codes in 6919104862Sruhyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping 6920104862Sru(after reading the patterns) before replacing or appending them to 6921104862Sruthe current list of patterns. Its arguments are pairs of character codes 6922114402Sru-- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a} 6923114402Sruto code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You 6924104862Srucan use character codes which would be invalid otherwise. 6925104862Sru 692655839Sasmodai@pindex troffrc 692769626Sru@pindex troffrc-end 692869626Sru@pindex hyphen.us 6929114402Sru@pindex hyphenex.us 693069626SruThe set of hyphenation patterns is associated with the current language 693169626Sruset by the @code{hla} request. The @code{hpf} request is usually 693269626Sruinvoked by the @file{troffrc} or @file{troffrc-end} file; by default, 6933114402Sru@file{troffrc} loads hyphenation patterns and exceptions for American 6934114402SruEnglish (in files @file{hyphen.us} and @file{hyphenex.us}). 693555839Sasmodai 6936104862SruA second call to @code{hpf} (for the same language) will replace the 6937104862Sruhyphenation patterns with the new ones. 6938104862Sru 693975584SruInvoking @code{hpf} causes an error if there is no current hyphenation 694069626Srulanguage. 694175584Sru@endDefreq 694255839Sasmodai 6943151497Sru@Defreq {hcode, c1 code1 [c2 code2 @dots{}]} 6944104862Sru@cindex hyphenation code (@code{hcode}) 6945104862Sru@cindex code, hyphenation (@code{hcode}) 694675584SruSet the hyphenation code of character @var{c1} to @var{code1}, that of 694775584Sru@var{c2} to @var{code2}, etc. A hyphenation code must be a single 694875584Sruinput character (not a special character) other than a digit or a 6949151497Sruspace. 695069626Sru 6951151497SruTo make hyphenation work, hyphenation codes must be set up. At 6952151497Srustart-up, groff only assigns hyphenation codes to the letters 6953151497Sru@samp{a}-@samp{z} (mapped to themselves) and to the letters 6954151497Sru@samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation 6955151497Srucodes are set to zero. Normally, hyphenation patterns contain only 6956151497Srulowercase letters which should be applied regardless of case. With 6957151497Sruother words, the words `FOO' and `Foo' should be hyphenated exactly the 6958151497Srusame way as the word `foo' is hyphenated, and this is what @code{hcode} 6959151497Sruis good for. Words which contain other letters won't be hyphenated 6960151497Sruproperly if the corresponding hyphenation patterns actually do contain 6961151497Sruthem. For example, the following @code{hcode} requests are necessary to 6962151497Sruassign hyphenation codes to the letters @samp{�������} (this is needed 6963151497Srufor German): 6964151497Sru 6965151497Sru@Example 6966151497Sru.hcode � � � � 6967151497Sru.hcode � � � � 6968151497Sru.hcode � � � � 6969151497Sru.hcode � � 6970151497Sru@endExample 6971151497Sru 6972151497SruWithout those assignments, groff treats German words like 6973151497Sru@w{`Kinderg�rten'} (the plural form of `kindergarten') as two 6974151497Srusubstrings @w{`kinderg'} and @w{`rten'} because the hyphenation code 6975151497Sruof the umlaut@tie{}a is zero by default. There is a German 6976151497Sruhyphenation pattern which covers @w{`kinder'}, so groff finds the 6977151497Sruhyphenation `kin-der'. The other two hyphenation points 6978151497Sru(`kin-der-g�r-ten') are missed. 6979151497Sru 698075584SruThis request is ignored if it has no parameter. 698175584Sru@endDefreq 698269626Sru 6983104862Sru@DefreqList {hym, [@Var{length}]} 6984104862Sru@DefregListEnd {.hym} 6985104862Sru@cindex hyphenation margin (@code{hym}) 6986104862Sru@cindex margin for hyphenation (@code{hym}) 6987104862Sru@cindex @code{ad} request, and hyphenation margin 698869626SruSet the (right) hyphenation margin to @var{length}. If the current 6989104862Sruadjustment mode is not @samp{b} or @samp{n}, the line is not 699075584Sruhyphenated if it is shorter than @var{length}. Without an argument, 6991114402Sruthe hyphenation margin is reset to its default value, which is@tie{}0. 6992104862SruThe default scaling indicator for this request is @samp{m}. The 699375584Sruhyphenation margin is associated with the current environment 699469626Sru(@pxref{Environments}). 699569626Sru 699675584SruA negative argument resets the hyphenation margin to zero, emitting 699769626Srua warning of type @samp{range}. 699869626Sru 6999104862Sru@cindex hyphenation margin register (@code{.hym}) 700075584SruThe current hyphenation margin is available in the @code{.hym} read-only 700175584Srunumber register. 700275584Sru@endDefreq 700355839Sasmodai 7004104862Sru@DefreqList {hys, [@Var{hyphenation_space}]} 7005104862Sru@DefregListEnd {.hys} 7006104862Sru@cindex hyphenation space (@code{hys}) 7007104862Sru@cindex @code{ad} request, and hyphenation space 700869626SruSet the hyphenation space to @var{hyphenation_space}. If the current 7009104862Sruadjustment mode is @samp{b} or @samp{n}, don't hyphenate the line 701075584Sruif it can be justified by adding no more than @var{hyphenation_space} 701175584Sruextra space to each word space. Without argument, the hyphenation 7012114402Sruspace is set to its default value, which is@tie{}0. The default 7013104862Sruscaling indicator for this request is @samp{m}. The hyphenation 701475584Sruspace is associated with the current environment 701575584Sru(@pxref{Environments}). 701669626Sru 701775584SruA negative argument resets the hyphenation space to zero, emitting a 701869626Sruwarning of type @samp{range}. 701969626Sru 7020104862Sru@cindex hyphenation space register (@code{.hys}) 702175584SruThe current hyphenation space is available in the @code{.hys} read-only 702275584Srunumber register. 702375584Sru@endDefreq 702455839Sasmodai 7025104862Sru@Defreq {shc, [@Var{glyph}]} 7026104862Sru@cindex soft hyphen character, setting (@code{shc}) 7027104862Sru@cindex character, soft hyphen, setting (@code{shc}) 7028104862Sru@cindex glyph, soft hyphen (@code{hy}) 7029104862Sru@cindex soft hyphen glyph (@code{hy}) 7030104862Sru@cindex @code{char} request, and soft hyphen character 7031104862Sru@cindex @code{tr} request, and soft hyphen character 7032104862SruSet the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft 7033104862Sruhyphen character} is a misnomer since it is an output glyph.} If the 7034104862Sruargument is omitted, the soft hyphen character is set to the default 7035104862Sruglyph @code{\(hy} (this is the start-up value of @code{gtroff} also). 7036104862SruThe soft hyphen character is the glyph that is inserted when a word is 703775584Sruhyphenated at a line break. If the soft hyphen character does not 703875584Sruexist in the font of the character immediately preceding a potential 703975584Srubreak point, then the line is not broken at that point. Neither 704055839Sasmodaidefinitions (specified with the @code{char} request) nor translations 704169626Sru(specified with the @code{tr} request) are considered when finding the 704269626Srusoft hyphen character. 704375584Sru@endDefreq 704455839Sasmodai 7045104862Sru@DefreqList {hla, language} 7046104862Sru@DefregListEnd {.hla} 7047104862Sru@cindex @code{hpf} request, and hyphenation language 7048104862Sru@cindex @code{hw} request, and hyphenation language 704955839Sasmodai@pindex troffrc 705069626Sru@pindex troffrc-end 705169626SruSet the current hyphenation language to the string @var{language}. 705269626SruHyphenation exceptions specified with the @code{hw} request and 7053104862Sruhyphenation patterns specified with the @code{hpf} and @code{hpfa} 7054104862Srurequests are both associated with the current hyphenation language. 7055104862SruThe @code{hla} request is usually invoked by the @file{troffrc} or the 705669626Sru@file{troffrc-end} files; @file{troffrc} sets the default language to 705769626Sru@samp{us}. 705855839Sasmodai 7059104862Sru@cindex hyphenation language register (@code{.hla}) 706069626SruThe current hyphenation language is available as a string in the 706169626Sruread-only number register @samp{.hla}. 706255839Sasmodai 706375584Sru@Example 706469626Sru.ds curr_language \n[.hla] 706569626Sru\*[curr_language] 706669626Sru @result{} us 706775584Sru@endExample 706875584Sru@endDefreq 706955839Sasmodai 707069626Sru 707169626Sru@c ===================================================================== 707269626Sru 707375584Sru@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 707455839Sasmodai@section Manipulating Spacing 707555839Sasmodai@cindex manipulating spacing 707655839Sasmodai@cindex spacing, manipulating 707755839Sasmodai 707875584Sru@Defreq {sp, [@Var{distance}]} 7079114402SruSpace downwards @var{distance}. With no argument it advances 7080114402Sru1@tie{}line. A negative argument causes @code{gtroff} to move up the page 708169626Sruthe specified distance. If the argument is preceded by a @samp{|} 708275584Sruthen @code{gtroff} moves that distance from the top of the page. This 7083104862Srurequest causes a line break. The default scaling indicator is @samp{v}. 7084114402Sru 7085114402SruIf a vertical trap is sprung during execution of @code{sp}, the amount of 7086114402Sruvertical space after the trap is discarded. For example, this 7087114402Sru 7088114402Sru@Example 7089114402Sru.de xxx 7090114402Sru.. 7091114402Sru. 7092114402Sru.wh 0 xxx 7093114402Sru. 7094114402Sru.pl 5v 7095114402Srufoo 7096114402Sru.sp 2 7097114402Srubar 7098114402Sru.sp 50 7099114402Srubaz 7100114402Sru@endExample 7101114402Sru 7102114402Sru@noindent 7103114402Sruresults in 7104114402Sru 7105114402Sru@Example 7106114402Srufoo 7107114402Sru 7108114402Sru 7109114402Srubar 7110114402Sru 7111114402Srubaz 7112114402Sru@endExample 7113114402Sru 7114114402Sru@cindex @code{sp} request, and traps 7115114402Sru@cindex discarded space in traps 7116114402Sru@cindex space, discarded, in traps 7117114402Sru@cindex traps, and discarded space 7118114402SruThe amount of discarded space is available in the number register 7119114402Sru@code{.trunc}. 7120114402Sru 7121114402SruTo protect @code{sp} against vertical traps, use the @code{vpt} request: 7122114402Sru 7123114402Sru@Example 7124114402Sru.vpt 0 7125114402Sru.sp -3 7126114402Sru.vpt 1 7127114402Sru@endExample 712875584Sru@endDefreq 712955839Sasmodai 7130104862Sru@DefreqList {ls, [@Var{nnn}]} 7131104862Sru@DefregListEnd {.L} 7132104862Sru@cindex double-spacing (@code{ls}) 713375584SruOutput @w{@var{nnn}@minus{}1} blank lines after each line of text. 713475584SruWith no argument, @code{gtroff} uses the previous value before the 713575584Srulast @code{ls} call. 713655839Sasmodai 713775584Sru@Example 713869626Sru.ls 2 \" This causes double-spaced output 713969626Sru.ls 3 \" This causes triple-spaced output 7140104862Sru.ls \" Again double-spaced 714175584Sru@endExample 714269626Sru 714369626SruThe line spacing is associated with the current environment 714469626Sru(@pxref{Environments}). 714569626Sru 7146104862Sru@cindex line spacing register (@code{.L}) 714775584SruThe read-only number register @code{.L} contains the current line 714875584Sruspacing setting. 714975584Sru@endDefreq 715055839Sasmodai 7151104862Sru@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} 7152104862Sruas alternatives to @code{ls}. 715375584Sru 7154104862Sru@DefescList {\\x, ', spacing, '} 7155104862Sru@DefregListEnd {.a} 715675584SruSometimes, extra vertical spacing is only needed occasionally, e.g.@: 715775584Sruto allow space for a tall construct (like an equation). The @code{\x} 715875584Sruescape does this. The escape is given a numerical argument, usually 715969626Sruenclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 7160104862Sruis @samp{v}. If this number is positive extra vertical space is 716175584Sruinserted below the current line. A negative number adds space above. 716275584SruIf this escape is used multiple times on the same line, the maximum of 716375584Sruthe values is used. 716469626Sru 716569626Sru@xref{Escapes}, for details on parameter delimiting characters. 716669626Sru 7167104862Sru@cindex extra post-vertical line space register (@code{.a}) 716875584SruThe @code{.a} read-only number register contains the most recent 716975584Sru(nonnegative) extra vertical line space. 717055839Sasmodai 7171104862SruUsing @code{\x} can be necessary in combination with the @code{\b} 7172104862Sruescape, as the following example shows. 7173104862Sru 717475584Sru@Example 7175104862SruThis is a test with the \[rs]b escape. 7176104862Sru.br 7177104862SruThis is a test with the \[rs]b escape. 7178104862Sru.br 7179104862SruThis is a test with \b'xyz'\x'-1m'\x'1m'. 7180104862Sru.br 7181104862SruThis is a test with the \[rs]b escape. 7182104862Sru.br 7183104862SruThis is a test with the \[rs]b escape. 718475584Sru@endExample 7185104862Sru 7186104862Sru@noindent 7187104862Sruproduces 7188104862Sru 7189104862Sru@Example 7190104862SruThis is a test with the \b escape. 7191104862SruThis is a test with the \b escape. 7192104862Sru x 7193104862SruThis is a test with y. 7194104862Sru z 7195104862SruThis is a test with the \b escape. 7196104862SruThis is a test with the \b escape. 7197104862Sru@endExample 719875584Sru@endDefesc 719955839Sasmodai 7200104862Sru@DefreqList {ns, } 7201104862Sru@DefreqItem {rs, } 7202104862Sru@DefregListEnd {.ns} 7203104862Sru@cindex @code{sp} request, and no-space mode 7204104862Sru@cindex no-space mode (@code{ns}) 7205104862Sru@cindex mode, no-space (@code{ns}) 720669626Sru@cindex blank lines, disabling 720769626Sru@cindex lines, blank, disabling 720875584SruEnable @dfn{no-space mode}. In this mode, spacing (either via 720975584Sru@code{sp} or via blank lines) is disabled. The @code{bp} request to 721075584Sruadvance to the next page is also disabled, except if it is accompanied 721175584Sruby a page number (see @ref{Page Control}, for more information). This 721275584Srumode ends when actual text is output or the @code{rs} request is 7213104862Sruencountered which ends no-space mode. The read-only number register 7214114402Sru@code{.ns} is set to@tie{}1 as long as no-space mode is active. 721555839Sasmodai 7216104862SruThis request is useful for macros that conditionally 7217104862Sruinsert vertical space before the text starts 7218104862Sru(for example, a paragraph macro could insert some space 7219104862Sruexcept when it is the first paragraph after a section header). 722075584Sru@endDefreq 722169626Sru 722269626Sru 722369626Sru@c ===================================================================== 722469626Sru 722575584Sru@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 722655839Sasmodai@section Tabs and Fields 7227104862Sru@cindex tabs, and fields 7228104862Sru@cindex fields, and tabs 722955839Sasmodai 723069626Sru@cindex @acronym{EBCDIC} encoding of a tab 7231114402SruA tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC} 7232114402Sruchar@tie{}5) causes a horizontal movement to the next tab stop (much 723369626Srulike it did on a typewriter). 723455839Sasmodai 723575584Sru@Defesc {\\t, , , } 7236104862Sru@cindex tab character, non-interpreted (@code{\t}) 7237104862Sru@cindex character, tab, non-interpreted (@code{\t}) 723869626SruThis escape is a non-interpreted tab character. In copy mode 723969626Sru(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 724075584Sru@endDefesc 724155839Sasmodai 7242104862Sru@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 7243104862Sru@DefregListEnd {.tabs} 724469626SruChange tab stop positions. This request takes a series of tab 724569626Sruspecifiers as arguments (optionally divided into two groups with the 724675584Sruletter @samp{T}) which indicate where each tab stop is to be 724775584Sru(overriding any previous settings). 724855839Sasmodai 724969626SruTab stops can be specified absolutely, i.e., as the distance from the 7250114402Sruleft margin. For example, the following sets 6@tie{}tab stops every 725169626Sruone inch. 725269626Sru 725375584Sru@Example 725455839Sasmodai.ta 1i 2i 3i 4i 5i 6i 725575584Sru@endExample 725655839Sasmodai 725775584SruTab stops can also be specified using a leading @samp{+} 725875584Sruwhich means that the specified tab stop is set relative to 725969626Sruthe previous tab stop. For example, the following is equivalent to the 726069626Sruprevious example. 726155839Sasmodai 726275584Sru@Example 726355839Sasmodai.ta 1i +1i +1i +1i +1i +1i 726475584Sru@endExample 726555839Sasmodai 726669626Sru@code{gtroff} supports an extended syntax to specify repeat values after 726769626Sruthe @samp{T} mark (these values are always taken as relative) -- this is 726869626Sruthe usual way to specify tabs set at equal intervals. The following is, 726969626Sruyet again, the same as the previous examples. It does even more since 727069626Sruit defines an infinite number of tab stops separated by one inch. 727155839Sasmodai 727275584Sru@Example 727355839Sasmodai.ta T 1i 727475584Sru@endExample 727555839Sasmodai 727669626SruNow we are ready to interpret the full syntax given at the beginning: 727769626SruSet tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 727869626Srutabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 727969626Sruand then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 728069626Sru@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 728155839Sasmodai 728269626SruExample: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 728369626Sru20c 23c 28c 30c @dots{}}. 728469626Sru 728569626SruThe material in each tab column (i.e., the column between two tab stops) 728669626Srumay be justified to the right or left or centered in the column. This 728769626Sruis specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 728869626Sruspecifier. The default justification is @samp{L}. Example: 728969626Sru 729075584Sru@Example 7291104862Sru.ta 1i 2iC 3iR 729275584Sru@endExample 729355839Sasmodai 729469626SruSome notes: 729569626Sru 729669626Sru@itemize @bullet 729769626Sru@item 729869626SruThe default unit of the @code{ta} request is @samp{m}. 729969626Sru 730069626Sru@item 730169626SruA tab stop is converted into a non-breakable horizontal movement which 730269626Srucan be neither stretched nor squeezed. For example, 730369626Sru 730475584Sru@Example 730569626Sru.ds foo a\tb\tc 730669626Sru.ta T 5i 730769626Sru\*[foo] 730875584Sru@endExample 730969626Sru 731069626Sru@noindent 7311114402Srucreates a single line which is a bit longer than 10@tie{}inches (a string 731269626Sruis used to show exactly where the tab characters are). Now consider the 731369626Srufollowing: 731469626Sru 731575584Sru@Example 731669626Sru.ds bar a\tb b\tc 731769626Sru.ta T 5i 731869626Sru\*[bar] 731975584Sru@endExample 732069626Sru 732169626Sru@noindent 732269626Sru@code{gtroff} first converts the tab stops of the line into unbreakable 732369626Sruhorizontal movements, then splits the line after the second @samp{b} 732469626Sru(assuming a sufficiently short line length). Usually, this isn't what 732569626Sruthe user wants. 732669626Sru 732769626Sru@item 732869626SruSuperfluous tabs (i.e., tab characters which do not correspond to a tab 732969626Srustop) are ignored except the first one which delimits the characters 733075584Srubelonging to the last tab stop for right-justifying or centering. 733169626SruConsider the following example 733269626Sru 733375584Sru@Example 733469626Sru.ds Z foo\tbar\tfoo 733569626Sru.ds ZZ foo\tbar\tfoobar 733669626Sru.ds ZZZ foo\tbar\tfoo\tbar 733769626Sru.ta 2i 4iR 733869626Sru\*[Z] 733969626Sru.br 734069626Sru\*[ZZ] 734169626Sru.br 734269626Sru\*[ZZZ] 734369626Sru.br 734475584Sru@endExample 734569626Sru 734669626Sru@noindent 734769626Sruwhich produces the following output: 734869626Sru 734975584Sru@Example 735069626Srufoo bar foo 735169626Srufoo bar foobar 735269626Srufoo bar foobar 735375584Sru@endExample 735469626Sru 735569626Sru@noindent 735669626SruThe first line right-justifies the second `foo' relative to the tab 735769626Srustop. The second line right-justifies `foobar'. The third line finally 735869626Sruright-justifies only `foo' because of the additional tab character which 735969626Srumarks the end of the string belonging to the last defined tab stop. 736069626Sru 736169626Sru@item 736269626SruTab stops are associated with the current environment 736369626Sru(@pxref{Environments}). 736469626Sru 736569626Sru@item 736675584SruCalling @code{ta} without an argument removes all tab stops. 736769626Sru 736869626Sru@item 7369104862Sru@cindex tab stops, for TTY output devices 7370114402SruThe start-up value of @code{gtroff} is @w{@samp{T 0.8i}}. 737169626Sru@end itemize 737269626Sru 7373104862Sru@cindex tab settings register (@code{.tabs}) 737475584SruThe read-only number register @code{.tabs} contains a string 737575584Srurepresentation of the current tab settings suitable for use as an 737675584Sruargument to the @code{ta} request. 737755839Sasmodai 737875584Sru@Example 737969626Sru.ds tab-string \n[.tabs] 738069626Sru\*[tab-string] 738169626Sru @result{} T120u 738275584Sru@endExample 7383104862Sru 7384114402Sru@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs} 7385114402Sru@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S}) 7386114402SruThe @code{troff} version of the Plan@tie{}9 operating system uses 7387104862Sruregister @code{.S} for the same purpose. 738875584Sru@endDefreq 738955839Sasmodai 7390104862Sru@Defreq {tc, [@Var{fill-glyph}]} 7391104862Sru@cindex tab repetition character (@code{tc}) 7392104862Sru@cindex character, tab repetition (@code{tc}) 7393104862Sru@cindex glyph, tab repetition (@code{tc}) 739475584SruNormally @code{gtroff} fills the space to the next tab stop with 739575584Sruwhitespace. This can be changed with the @code{tc} request. With no 739675584Sruargument @code{gtroff} reverts to using whitespace, which is the 7397104862Srudefault. The value of this @dfn{tab repetition character} is 7398104862Sruassociated with the current environment 7399104862Sru(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a 7400104862Srumisnomer since it is an output glyph.} 740175584Sru@endDefreq 740269626Sru 7403104862Sru@DefreqList {linetabs, n} 7404104862Sru@DefregListEnd {.linetabs} 7405104862Sru@cindex tab, line-tabs mode 7406104862Sru@cindex line-tabs mode 7407104862Sru@cindex mode, line-tabs 7408104862SruIf @var{n} is missing or not zero, enable @dfn{line-tabs} mode, 7409104862Sruor disable it otherwise (the default). 7410104862SruIn line-tabs mode, @code{gtroff} computes tab distances 7411104862Srurelative to the (current) output line instead of the input line. 7412104862Sru 7413104862SruFor example, the following code: 7414104862Sru 7415104862Sru@Example 7416104862Sru.ds x a\t\c 7417104862Sru.ds y b\t\c 7418104862Sru.ds z c 7419104862Sru.ta 1i 3i 7420104862Sru\*x 7421104862Sru\*y 7422104862Sru\*z 7423104862Sru@endExample 7424104862Sru 7425104862Sru@noindent 7426104862Sruin normal mode, results in the output 7427104862Sru 7428104862Sru@Example 7429104862Srua b c 7430104862Sru@endExample 7431104862Sru 7432104862Sru@noindent 7433104862Sruin line-tabs mode, the same code outputs 7434104862Sru 7435104862Sru@Example 7436104862Srua b c 7437104862Sru@endExample 7438104862Sru 7439104862SruLine-tabs mode is associated with the current environment. 7440114402SruThe read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs 7441104862Srumode, and 0 in normal mode. 7442104862Sru@endDefreq 7443104862Sru 744469626Sru@menu 744575584Sru* Leaders:: 744675584Sru* Fields:: 744769626Sru@end menu 744869626Sru 744969626Sru@c --------------------------------------------------------------------- 745069626Sru 745169626Sru@node Leaders, Fields, Tabs and Fields, Tabs and Fields 745255839Sasmodai@subsection Leaders 745355839Sasmodai@cindex leaders 745455839Sasmodai 745569626SruSometimes it may may be desirable to use the @code{tc} request to fill a 7456104862Sruparticular tab stop with a given glyph (for example dots in a table 745769626Sruof contents), but also normal tab stops on the rest of the line. For 745869626Sruthis @code{gtroff} provides an alternate tab mechanism, called 745975584Sru@dfn{leaders} which does just that. 746055839Sasmodai 746169626Sru@cindex leader character 7462114402SruA leader character (character code@tie{}1) behaves similarly to a tab 746369626Srucharacter: It moves to the next tab stop. The only difference is that 7464104862Srufor this movement, the fill glyph defaults to a period character and 746569626Srunot to space. 746655839Sasmodai 746775584Sru@Defesc {\\a, , , } 7468104862Sru@cindex leader character, non-interpreted (@code{\a}) 7469104862Sru@cindex character, leader, non-interpreted (@code{\a}) 747069626SruThis escape is a non-interpreted leader character. In copy mode 747169626Sru(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 747269626Srucharacter. 747375584Sru@endDefesc 747455839Sasmodai 7475104862Sru@Defreq {lc, [@Var{fill-glyph}]} 7476104862Sru@cindex leader repetition character (@code{lc}) 7477104862Sru@cindex character, leader repetition (@code{lc}) 7478104862Sru@cindex glyph, leader repetition (@code{lc}) 7479104862SruDeclare the @dfn{leader repetition character}.@footnote{@dfn{Leader 7480104862Srurepetition character} is a misnomer since it is an output glyph.} 7481104862SruWithout an argument, leaders act the same as tabs (i.e., using 7482104862Sruwhitespace for filling). @code{gtroff}'s start-up value is a dot 7483104862Sru(@samp{.}). The value of the leader repetition character is 7484104862Sruassociated with the current environment (@pxref{Environments}). 748575584Sru@endDefreq 748669626Sru 748755839Sasmodai@cindex table of contents 748855839Sasmodai@cindex contents, table of 748969626SruFor a table of contents, to name an example, tab stops may be defined so 749055839Sasmodaithat the section number is one tab stop, the title is the second with 749169626Sruthe remaining space being filled with a line of dots, and then the page 749269626Srunumber slightly separated from the dots. 749355839Sasmodai 749475584Sru@Example 749569626Sru.ds entry 1.1\tFoo\a\t12 749655839Sasmodai.lc . 749769626Sru.ta 1i 5i +.25i 749869626Sru\*[entry] 749975584Sru@endExample 750055839Sasmodai 750169626Sru@noindent 750269626SruThis produces 750369626Sru 750475584Sru@Example 750569626Sru1.1 Foo.......................................... 12 750675584Sru@endExample 750769626Sru 750869626Sru@c --------------------------------------------------------------------- 750969626Sru 751069626Sru@node Fields, , Leaders, Tabs and Fields 751155839Sasmodai@subsection Fields 751255839Sasmodai@cindex fields 751355839Sasmodai 7514104862Sru@cindex field delimiting character (@code{fc}) 7515104862Sru@cindex delimiting character, for fields (@code{fc}) 7516104862Sru@cindex character, field delimiting (@code{fc}) 7517104862Sru@cindex field padding character (@code{fc}) 7518104862Sru@cindex padding character, for fields (@code{fc}) 7519104862Sru@cindex character, field padding (@code{fc}) 752069626Sru@dfn{Fields} are a more general way of laying out tabular data. A field 752169626Sruis defined as the data between a pair of @dfn{delimiting characters}. 752269626SruIt contains substrings which are separated by @dfn{padding characters}. 752369626SruThe width of a field is the distance on the @emph{input} line from the 752469626Sruposition where the field starts to the next tab stop. A padding 752569626Srucharacter inserts stretchable space similar to @TeX{}'s @code{\hss} 752669626Srucommand (thus it can even be negative) to make the sum of all substring 752769626Srulengths plus the stretchable space equal to the field width. If more 752869626Sruthan one padding character is inserted, the available space is evenly 752969626Srudistributed among them. 753055839Sasmodai 753175584Sru@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 753269626SruDefine a delimiting and a padding character for fields. If the latter 753369626Sruis missing, the padding character defaults to a space character. If 753469626Sruthere is no argument at all, the field mechanism is disabled (which is 753575584Sruthe default). Note that contrary to e.g.@: the tab repetition 7536104862Srucharacter, delimiting and padding characters are @emph{not} associated 7537104862Sruto the current environment (@pxref{Environments}). 753869626Sru 753969626SruExample: 754069626Sru 754175584Sru@Example 754269626Sru.fc # ^ 754369626Sru.ta T 3i 754469626Sru#foo^bar^smurf# 754569626Sru.br 754669626Sru#foo^^bar^smurf# 754775584Sru@endExample 754869626Sru 754969626Sru@noindent 755069626Sruand here the result: 755169626Sru 755275584Sru@Example 755369626Srufoo bar smurf 755469626Srufoo bar smurf 755575584Sru@endExample 755675584Sru@endDefreq 755769626Sru 755869626Sru 755969626Sru@c ===================================================================== 756069626Sru 756175584Sru@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 756255839Sasmodai@section Character Translations 756355839Sasmodai@cindex character translations 756455839Sasmodai@cindex translations of characters 756555839Sasmodai 7566104862Sru@cindex control character, changing (@code{cc}) 7567104862Sru@cindex character, control, changing (@code{cc}) 7568104862Sru@cindex no-break control character, changing (@code{c2}) 7569104862Sru@cindex character, no-break control, changing (@code{c2}) 7570104862Sru@cindex control character, no-break, changing (@code{c2}) 757155839SasmodaiThe control character (@samp{.}) and the no-break control character 757255839Sasmodai(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 757355839Sasmodairespectively. 757455839Sasmodai 757575584Sru@Defreq {cc, [@Var{c}]} 7576114402SruSet the control character to@tie{}@var{c}. With no argument the default 757769626Srucontrol character @samp{.} is restored. The value of the control 757869626Srucharacter is associated with the current environment 757969626Sru(@pxref{Environments}). 758075584Sru@endDefreq 758155839Sasmodai 758275584Sru@Defreq {c2, [@Var{c}]} 7583114402SruSet the no-break control character to@tie{}@var{c}. With no argument the 758469626Srudefault control character @samp{'} is restored. The value of the 758569626Sruno-break control character is associated with the current environment 758669626Sru(@pxref{Environments}). 758775584Sru@endDefreq 758855839Sasmodai 758975584Sru@Defreq {eo, } 7590104862Sru@cindex disabling @code{\} (@code{eo}) 7591104862Sru@cindex @code{\}, disabling (@code{eo}) 759275584SruDisable the escape mechanism completely. After executing this 759375584Srurequest, the backslash character @samp{\} no longer starts an escape 759475584Srusequence. 759569626Sru 759669626SruThis request can be very helpful in writing macros since it is not 759769626Srunecessary then to double the escape character. Here an example: 759869626Sru 759975584Sru@Example 760069626Sru.\" This is a simplified version of the 760169626Sru.\" .BR request from the man macro package 760269626Sru.eo 760369626Sru.de BR 760469626Sru. ds result \& 760569626Sru. while (\n[.$] >= 2) \@{\ 760669626Sru. as result \fB\$1\fR\$2 760769626Sru. shift 2 760869626Sru. \@} 760969626Sru. if \n[.$] .as result \fB\$1 761069626Sru\*[result] 761169626Sru. ft R 761269626Sru.. 761369626Sru.ec 761475584Sru@endExample 761575584Sru@endDefreq 761669626Sru 761775584Sru@Defreq {ec, [@Var{c}]} 7618104862Sru@cindex escape character, changing (@code{ec}) 7619104862Sru@cindex character, escape, changing (@code{ec}) 7620114402SruSet the escape character to@tie{}@var{c}. With no argument the default 762175584Sruescape character @samp{\} is restored. It can be also used to 762275584Srure-enable the escape mechanism after an @code{eo} request. 762369626Sru 762475584SruNote that changing the escape character globally will likely break 7625104862Srumacro packages since @code{gtroff} has no mechanism to `intern' macros, 7626104862Srui.e., to convert a macro definition into an internal form which is 7627104862Sruindependent of its representation (@TeX{} has this mechanism). 7628104862SruIf a macro is called, it is executed literally. 762975584Sru@endDefreq 763069626Sru 7631104862Sru@DefreqList {ecs, } 7632104862Sru@DefreqListEnd {ecr, } 7633104862SruThe @code{ecs} request saves the current escape character 7634104862Sruin an internal register. 7635104862SruUse this request in combination with the @code{ec} request to 7636104862Srutemporarily change the escape character. 7637104862Sru 7638104862SruThe @code{ecr} request restores the escape character 7639104862Srusaved with @code{ecs}. 7640104862SruWithout a previous call to @code{ecs}, this request 7641104862Srusets the escape character to @code{\}. 7642104862Sru@endDefreq 7643104862Sru 7644104862Sru@DefescList {\\\\, , , } 7645104862Sru@DefescItem {\\e, , , } 7646104862Sru@DefescListEnd {\\E, , , } 7647104862SruPrint the current escape character (which is the backslash character 7648104862Sru@samp{\} by default). 7649104862Sru 7650104862Sru@code{\\} is a `delayed' backslash; more precisely, it is the default 7651104862Sruescape character followed by a backslash, which no longer has special 7652104862Srumeaning due to the leading escape character. It is @emph{not} an escape 7653104862Srusequence in the usual sense! In any unknown escape sequence 7654104862Sru@code{\@var{X}} the escape character is ignored and @var{X} is printed. 7655104862SruBut if @var{X} is equal to the current escape character, no warning is 7656104862Sruemitted. 7657104862Sru 7658104862SruAs a consequence, only at top-level or in a diversion a backslash glyph is 7659104862Sruprinted; in copy-in mode, it expands to a single backslash which then 7660104862Srucombines with the following character to an escape sequence. 7661104862Sru 7662104862SruThe @code{\E} escape differs from @code{\e} by printing an escape 7663104862Srucharacter that is not interpreted in copy mode. 7664104862SruUse this to define strings with escapes that work 7665104862Sruwhen used in copy mode (for example, as a macro argument). 7666104862SruThe following example defines strings to begin and end 7667104862Srua superscript: 7668104862Sru 7669104862Sru@Example 7670114402Sru.ds @{ \v'-.3m'\s'\En[.s]*60/100' 7671104862Sru.ds @} \s0\v'.3m' 7672104862Sru@endExample 7673104862Sru 7674104862SruAnother example to demonstrate the differences between the various escape 7675104862Srusequences, using a strange escape character, @samp{-}. 7676104862Sru 7677104862Sru@Example 7678104862Sru.ec - 7679104862Sru.de xxx 7680104862Sru--A'123' 7681104862Sru.. 7682104862Sru.xxx 7683104862Sru @result{} -A'foo' 7684104862Sru@endExample 7685104862Sru 7686104862Sru@noindent 7687104862SruThe result is surprising for most users, expecting @samp{1} since 7688104862Sru@samp{foo} is a valid identifier. What has happened? As mentioned 7689104862Sruabove, the leading escape character makes the following character 7690104862Sruordinary. Written with the default escape character the sequence 7691104862Sru@samp{--} becomes @samp{\-} -- this is the minus sign. 7692104862Sru 7693104862SruIf the escape character followed by itself is a valid escape sequence, 7694104862Sruonly @code{\E} yields the expected result: 7695104862Sru 7696104862Sru@Example 7697104862Sru.ec - 7698104862Sru.de xxx 7699104862Sru-EA'123' 7700104862Sru.. 7701104862Sru.xxx 7702104862Sru @result{} 1 7703104862Sru@endExample 770475584Sru@endDefesc 770569626Sru 7706104862Sru@Defesc {\\., , , } 7707104862SruSimilar to @code{\\}, the sequence @code{\.} isn't a real escape sequence. 7708104862SruAs before, a warning message is suppressed if the escape character is 7709104862Srufollowed by a dot, and the dot itself is printed. 7710104862Sru 7711104862Sru@Example 7712104862Sru.de foo 7713104862Sru. nop foo 7714104862Sru. 7715104862Sru. de bar 7716104862Sru. nop bar 7717104862Sru\\.. 7718104862Sru. 7719104862Sru.. 7720104862Sru.foo 7721104862Sru.bar 7722104862Sru @result{} foo bar 7723104862Sru@endExample 7724104862Sru 7725104862Sru@noindent 7726104862SruThe first backslash is consumed while the macro is read, and the second 7727104862Sruis swallowed while exexuting macro @code{foo}. 7728104862Sru@endDefesc 7729104862Sru 773069626SruA @dfn{translation} is a mapping of an input character to an output 7731104862Sruglyph. The mapping occurs at output time, i.e., the input character 7732104862Srugets assigned the metric information of the mapped output character 7733104862Sruright before input tokens are converted to nodes (@pxref{Gtroff 7734104862SruInternals}, for more on this process). 773569626Sru 7736104862Sru@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7737104862Sru@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7738114402SruTranslate character @var{a} to glyph@tie{}@var{b}, character @var{c} to 7739114402Sruglyph@tie{}@var{d}, etc. If there is an odd number of arguments, the 7740104862Srulast one is translated to an unstretchable space (@w{@samp{\ }}). 774169626Sru 7742104862SruThe @code{trin} request is identical to @code{tr}, 7743104862Srubut when you unformat a diversion with @code{asciify} 7744104862Sruit ignores the translation. 7745104862Sru@xref{Diversions}, for details about the @code{asciify} request. 7746104862Sru 774769626SruSome notes: 774869626Sru 774969626Sru@itemize @bullet 775069626Sru@item 7751104862Sru@cindex @code{\(}, and translations 7752104862Sru@cindex @code{\[}, and translations 7753104862Sru@cindex @code{\'}, and translations 7754104862Sru@cindex @code{\`}, and translations 7755104862Sru@cindex @code{\-}, and translations 7756104862Sru@cindex @code{\_}, and translations 7757104862Sru@cindex @code{\C}, and translations 7758104862Sru@cindex @code{\N}, and translations 7759104862Sru@cindex @code{char} request, and translations 7760104862Sru@cindex special characters 776169626Sru@cindex character, special 7762104862Sru@cindex numbered glyph (@code{\N}) 7763104862Sru@cindex glyph, numbered (@code{\N}) 776469626SruSpecial characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 776569626Sru@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 7766104862Sruglyphs defined with the @code{char} request, and numbered glyphs 776769626Sru(@code{\N'@var{xxx}'}) can be translated also. 776869626Sru 776969626Sru@item 7770104862Sru@cindex @code{\e}, and translations 777169626SruThe @code{\e} escape can be translated also. 777269626Sru 777369626Sru@item 7774104862Sru@cindex @code{\%}, and translations 7775104862Sru@cindex @code{\~}, and translations 777675584SruCharacters can be mapped onto the @code{\%} and @code{\~} escapes (but 7777104862Sru@code{\%} and @code{\~} can't be mapped onto another glyph). 777869626Sru 777969626Sru@item 7780104862Sru@cindex backspace character, and translations 7781104862Sru@cindex character, backspace, and translations 7782104862Sru@cindex leader character, and translations 7783104862Sru@cindex character, leader, and translations 7784104862Sru@cindex newline character, and translations 7785104862Sru@cindex character, newline, and translations 7786104862Sru@cindex tab character, and translations 7787104862Sru@cindex character, tab, and translations 7788104862Sru@cindex @code{\a}, and translations 7789104862Sru@cindex @code{\t}, and translations 779069626SruThe following characters can't be translated: space (with one exception, 779169626Srusee below), backspace, newline, leader (and @code{\a}), tab (and 779269626Sru@code{\t}). 779369626Sru 779469626Sru@item 7795104862Sru@cindex @code{shc} request, and translations 779669626SruTranslations are not considered for finding the soft hyphen character 779769626Sruset with the @code{shc} request. 779869626Sru 779969626Sru@item 7800104862Sru@cindex @code{\&}, and translations 7801114402SruThe pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c} 7802114402Srufollowed by the zero width space character) maps this character to nothing. 780369626Sru 780475584Sru@Example 780569626Sru.tr a\& 780669626Srufoo bar 780769626Sru @result{} foo br 780875584Sru@endExample 780969626Sru 781069626Sru@noindent 781169626SruIt is even possible to map the space character to nothing: 781269626Sru 781375584Sru@Example 781469626Sru.tr aa \& 781569626Srufoo bar 781669626Sru @result{} foobar 781775584Sru@endExample 781869626Sru 781969626Sru@noindent 782069626SruAs shown in the example, the space character can't be the first 7821104862Srucharacter/glyph pair as an argument of @code{tr}. Additionally, it is 7822104862Srunot possible to map the space character to any other glyph; requests 782375584Srulike @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 782469626Sru 782575584SruIf justification is active, lines are justified in spite of the 782669626Sru`empty' space character (but there is no minimal distance, i.e.@: the 782769626Sruspace character, between words). 782869626Sru 782969626Sru@item 7830104862SruAfter an output glyph has been constructed (this happens at the 7831104862Srumoment immediately before the glyph is appended to an output 7832104862Sruglyph list, either by direct output, in a macro, diversion, or 783369626Srustring), it is no longer affected by @code{tr}. 783469626Sru 7835104862Sru@item 7836104862SruTranslating character to glyphs where one of them or both are 7837104862Sruundefined is possible also; @code{tr} does not check whether the 7838104862Sruentities in its argument do exist. 783969626Sru 7840104862Sru@xref{Gtroff Internals}. 7841104862Sru 784269626Sru@item 7843104862Sru@code{troff} no longer has a hard-coded dependency on @w{Latin-1}; 7844104862Sruall @code{char@var{XXX}} entities have been removed from the font 7845104862Srudescription files. This has a notable consequence which shows up in 7846104862Sruwarnings like @code{can't find character with input code @var{XXX}} 7847104862Sruif the @code{tr} request isn't handled properly. 7848104862Sru 7849104862SruConsider the following translation: 7850104862Sru 7851104862Sru@Example 7852151497Sru.tr �� 7853104862Sru@endExample 7854104862Sru 7855104862Sru@noindent 7856151497SruThis maps input character @code{�} onto glyph @code{�}, which is 7857104862Sruidentical to glyph @code{char201}. But this glyph intentionally 7858104862Srudoesn't exist! Instead, @code{\[char201]} is treated as an input 7859104862Srucharacter entity and is by default mapped onto @code{\['E]}, and 7860104862Sru@code{gtroff} doesn't handle translations of translations. 7861104862Sru 7862104862SruThe right way to write the above translation is 7863104862Sru 7864104862Sru@Example 7865151497Sru.tr �\['E] 7866104862Sru@endExample 7867104862Sru 7868104862Sru@noindent 7869104862SruWith other words, the first argument of @code{tr} should be an input 7870104862Srucharacter or entity, and the second one a glyph entity. 7871104862Sru 7872104862Sru@item 787369626SruWithout an argument, the @code{tr} request is ignored. 787469626Sru@end itemize 787575584Sru@endDefreq 787669626Sru 7877104862Sru@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 787875584Sru@cindex @code{\!}, and @code{trnt} 787969626Sru@code{trnt} is the same as the @code{tr} request except that the 788075584Srutranslations do not apply to text that is transparently throughput 788175584Sruinto a diversion with @code{\!}. @xref{Diversions}, for more 788275584Sruinformation. 788369626Sru 788455839SasmodaiFor example, 788555839Sasmodai 788675584Sru@Example 788755839Sasmodai.tr ab 788855839Sasmodai.di x 788955839Sasmodai\!.tm a 789055839Sasmodai.di 789155839Sasmodai.x 789275584Sru@endExample 789355839Sasmodai 789469626Sru@noindent 789575584Sruprints @samp{b} to the standard error stream; if @code{trnt} is used 789675584Sruinstead of @code{tr} it prints @samp{a}. 789775584Sru@endDefreq 789855839Sasmodai 789955839Sasmodai 790069626Sru@c ===================================================================== 790169626Sru 790275584Sru@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 790369626Sru@section Troff and Nroff Mode 790469626Sru@cindex troff mode 790569626Sru@cindex mode, troff 790669626Sru@cindex nroff mode 790769626Sru@cindex mode, nroff 790869626Sru 790969626SruOriginally, @code{nroff} and @code{troff} were two separate programs, 7910104862Sruthe former for TTY output, the latter for everything else. With GNU 791175584Sru@code{troff}, both programs are merged into one executable, sending 7912104862Sruits output to a device driver (@code{grotty} for TTY devices, 791375584Sru@code{grops} for @sc{PostScript}, etc.) which interprets the 791475584Sruintermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 791575584Sruit makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 791675584Srusince the differences are hardcoded. For GNU @code{troff}, this 791775584Srudistinction is not appropriate because @code{gtroff} simply takes the 791875584Sruinformation given in the font files for a particular device without 7919104862Sruhandling requests specially if a TTY output device is used. 792069626Sru 792175584SruUsually, a macro package can be used with all output devices. 792275584SruNevertheless, it is sometimes necessary to make a distinction between 7923104862SruTTY and non-TTY devices: @code{gtroff} provides two built-in 792475584Sruconditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 792575584Sru@code{while} requests to decide whether @code{gtroff} shall behave 792675584Srulike @code{nroff} or like @code{troff}. 792769626Sru 7928104862Sru@Defreq {troff, } 792969626Sru@pindex troffrc 793069626Sru@pindex troffrc-end 793169626SruMake the @samp{t} built-in condition true (and the @samp{n} built-in 793275584Srucondition false) for @code{if}, @code{ie}, and @code{while} 793375584Sruconditional requests. This is the default if @code{gtroff} 793475584Sru(@emph{not} @code{groff}) is started with the @option{-R} switch to 793575584Sruavoid loading of the start-up files @file{troffrc} and 793675584Sru@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 7937104862Srumode if the output device is not a TTY (e.g.@: `ps'). 793875584Sru@endDefreq 793969626Sru 7940104862Sru@Defreq {nroff, } 794175584Sru@pindex tty.tmac 794269626SruMake the @samp{n} built-in condition true (and the @samp{t} built-in 794375584Srucondition false) for @code{if}, @code{ie}, and @code{while} 7944104862Sruconditional requests. This is the default if @code{gtroff} uses a TTY 794575584Sruoutput device; the code for switching to nroff mode is in the file 794675584Sru@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 794775584Sru@endDefreq 794869626Sru 794975584Sru@xref{Conditionals and Loops}, for more details on built-in 795075584Sruconditions. 795169626Sru 795269626Sru 795369626Sru@c ===================================================================== 795469626Sru 7955104862Sru@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference 795655839Sasmodai@section Line Layout 795755839Sasmodai@cindex line layout 795855839Sasmodai@cindex layout, line 795955839Sasmodai 796055839Sasmodai@cindex dimensions, line 796155839Sasmodai@cindex line dimensions 796269626SruThe following drawing shows the dimensions which @code{gtroff} uses for 796355839Sasmodaiplacing a line of output onto the page. They are labeled with the 796469626Srurequest which manipulates each dimension. 796555839Sasmodai 796675584Sru@Example 796769626Sru -->| in |<-- 796869626Sru |<-----------ll------------>| 796955839Sasmodai +----+----+----------------------+----+ 797055839Sasmodai | : : : | 797155839Sasmodai +----+----+----------------------+----+ 797269626Sru -->| po |<-- 797369626Sru |<--------paper width---------------->| 797475584Sru@endExample 797555839Sasmodai 797669626Sru@noindent 797755839SasmodaiThese dimensions are: 797855839Sasmodai 797955839Sasmodai@ftable @code 798055839Sasmodai@item po 7981104862Sru@cindex left margin (@code{po}) 7982104862Sru@cindex margin, left (@code{po}) 7983104862Sru@cindex page offset (@code{po}) 7984104862Sru@cindex offset, page (@code{po}) 798569626Sru@dfn{Page offset} -- this is the leftmost position of text on the final 798669626Sruoutput, defining the @dfn{left margin}. 798769626Sru 798855839Sasmodai@item in 7989104862Sru@cindex indentation (@code{in}) 7990104862Sru@cindex line indentation (@code{in}) 799169626Sru@dfn{Indentation} -- this is the distance from the left margin where 799275584Srutext is printed. 799355839Sasmodai 799455839Sasmodai@item ll 7995104862Sru@cindex line length (@code{ll}) 7996104862Sru@cindex length of line (@code{ll}) 799769626Sru@dfn{Line length} -- this is the distance from the left margin to right 799869626Srumargin. 799955839Sasmodai@end ftable 800055839Sasmodai 8001104862SruA simple demonstration: 800269626Sru 800375584Sru@Example 8004104862Sru.ll 3i 8005104862SruThis is text without indentation. 8006104862SruThe line length has been set to 3\~inch. 800755839Sasmodai.in +.5i 800855839Sasmodai.ll -.5i 8009104862SruNow the left and right margins are both increased. 8010104862Sru.in 8011104862Sru.ll 8012104862SruCalling .in and .ll without parameters restore 8013104862Sruthe previous values. 801475584Sru@endExample 801555839Sasmodai 8016104862SruResult: 8017104862Sru 8018104862Sru@Example 8019104862SruThis is text without indenta- 8020104862Srution. The line length has 8021104862Srubeen set to 3 inch. 8022104862Sru Now the left and 8023104862Sru right margins are 8024104862Sru both increased. 8025104862SruCalling .in and .ll without 8026104862Sruparameters restore the previ- 8027104862Sruous values. 8028104862Sru@endExample 8029104862Sru 8030104862Sru@DefreqList {po, [@Var{offset}]} 8031104862Sru@DefreqItem {po, @t{+}@Var{offset}} 8032104862Sru@DefreqItem {po, @t{-}@Var{offset}} 8033104862Sru@DefregListEnd {.o} 803475584Sru@pindex troffrc 803575584SruSet horizontal page offset to @var{offset} (or increment or decrement 803675584Sruthe current value by @var{offset}). Note that this request does not 803775584Srucause a break, so changing the page offset in the middle of text being 803875584Srufilled may not yield the expected result. The initial value is 8039104862Sru1@dmn{i}. For TTY output devices, it is set to 0 in the startup file 8040104862Sru@file{troffrc}; the default scaling indicator is @samp{m} (and 8041104862Srunot @samp{v} as incorrectly documented in the original 804275584Sru@acronym{UNIX} troff manual). 804355839Sasmodai 804475584SruThe current page offset can be found in the read-only number register 804569626Sru@samp{.o}. 804669626Sru 804769626SruIf @code{po} is called without an argument, the page offset is reset to 804869626Sruthe previous value before the last call to @code{po}. 804969626Sru 805075584Sru@Example 805169626Sru.po 3i 805269626Sru\n[.o] 805369626Sru @result{} 720 805469626Sru.po -1i 805569626Sru\n[.o] 805669626Sru @result{} 480 805769626Sru.po 805869626Sru\n[.o] 805969626Sru @result{} 720 806075584Sru@endExample 806175584Sru@endDefreq 806269626Sru 8063104862Sru@DefreqList {in, [@Var{indent}]} 8064104862Sru@DefreqItem {in, @t{+}@Var{indent}} 8065104862Sru@DefreqItem {in, @t{-}@Var{indent}} 8066104862Sru@DefregListEnd {.i} 806775584SruSet indentation to @var{indent} (or increment or decrement the 806869626Srucurrent value by @var{indent}). This request causes a break. 806969626SruInitially, there is no indentation. 807069626Sru 807169626SruIf @code{in} is called without an argument, the indentation is reset to 807269626Sruthe previous value before the last call to @code{in}. The default 8073104862Sruscaling indicator is @samp{m}. 807469626Sru 8075104862SruThe indentation is associated with the current environment 8076104862Sru(@pxref{Environments}). 807769626Sru 807869626SruIf a negative indentation value is specified (which is not allowed), 807969626Sru@code{gtroff} emits a warning of type @samp{range} and sets the 808069626Sruindentation to zero. 808169626Sru 8082151497SruThe effect of @code{in} is delayed until a partially collected line 8083151497Sru(if it exists) is output. A temporary indentation value is reset to 8084151497Sruzero also. 808569626Sru 808669626SruThe current indentation (as set by @code{in}) can be found in the 808775584Sruread-only number register @samp{.i}. 808875584Sru@endDefreq 808969626Sru 8090104862Sru@DefreqList {ti, offset} 8091104862Sru@DefreqItem {ti, @t{+}@Var{offset}} 8092104862Sru@DefreqItem {ti, @t{-}@Var{offset}} 8093104862Sru@DefregListEnd {.in} 809469626SruTemporarily indent the next output line by @var{offset}. If an 809569626Sruincrement or decrement value is specified, adjust the temporary 809669626Sruindentation relative to the value set by the @code{in} request. 809769626Sru 809869626SruThis request causes a break; its value is associated with the current 8099104862Sruenvironment (@pxref{Environments}). The default scaling indicator 8100104862Sruis @samp{m}. A call of @code{ti} without an argument is ignored. 810169626Sru 810269626SruIf the total indentation value is negative (which is not allowed), 810369626Sru@code{gtroff} emits a warning of type @samp{range} and sets the 810469626Srutemporary indentation to zero. `Total indentation' is either 810569626Sru@var{offset} if specified as an absolute value, or the temporary plus 810669626Srunormal indentation, if @var{offset} is given as a relative value. 810769626Sru 810869626SruThe effect of @code{ti} is delayed until a partially collected line (if 810969626Sruit exists) is output. 811069626Sru 811175584SruThe read-only number register @code{.in} is the indentation that applies 811275584Sruto the current output line. 811369626Sru 811469626SruThe difference between @code{.i} and @code{.in} is that the latter takes 811569626Sruinto account whether a partially collected line still uses the old 811675584Sruindentation value or a temporary indentation value is active. 811775584Sru@endDefreq 811869626Sru 8119104862Sru@DefreqList {ll, [@Var{length}]} 8120104862Sru@DefreqItem {ll, @t{+}@Var{length}} 8121104862Sru@DefreqItem {ll, @t{-}@Var{length}} 8122104862Sru@DefregItem {.l} 8123104862Sru@DefregListEnd {.ll} 812475584SruSet the line length to @var{length} (or increment or decrement the 812569626Srucurrent value by @var{length}). Initially, the line length is set to 812669626Sru6.5@dmn{i}. The effect of @code{ll} is delayed until a partially 812775584Srucollected line (if it exists) is output. The default scaling 8128104862Sruindicator is @samp{m}. 812969626Sru 813069626SruIf @code{ll} is called without an argument, the line length is reset to 813169626Sruthe previous value before the last call to @code{ll}. If a negative 813269626Sruline length is specified (which is not allowed), @code{gtroff} emits a 813369626Sruwarning of type @samp{range} and sets the line length to zero. 813469626Sru 8135104862SruThe line length is associated with the current environment 8136104862Sru(@pxref{Environments}). 813769626Sru 8138104862Sru@cindex line length register (@code{.l}) 813969626SruThe current line length (as set by @code{ll}) can be found in the 814075584Sruread-only number register @samp{.l}. The read-only number register 814175584Sru@code{.ll} is the line length that applies to the current output line. 814269626Sru 814369626SruSimilar to @code{.i} and @code{.in}, the difference between @code{.l} 814469626Sruand @code{.ll} is that the latter takes into account whether a partially 814569626Srucollected line still uses the old line length value. 814675584Sru@endDefreq 814769626Sru 814869626Sru 814969626Sru@c ===================================================================== 815069626Sru 8151104862Sru@node Line Control, Page Layout, Line Layout, gtroff Reference 8152104862Sru@section Line Control 8153104862Sru@cindex line control 8154104862Sru@cindex control, line 8155104862Sru 8156104862SruIt is important to understand how @code{gtroff} handles input and output 8157104862Srulines. 8158104862Sru 8159104862SruMany escapes use positioning relative to the input line. For example, 8160104862Sruthis 8161104862Sru 8162104862Sru@Example 8163104862SruThis is a \h'|1.2i'test. 8164104862Sru 8165104862SruThis is a 8166104862Sru\h'|1.2i'test. 8167104862Sru@endExample 8168104862Sru 8169104862Sru@noindent 8170104862Sruproduces 8171104862Sru 8172104862Sru@Example 8173104862SruThis is a test. 8174104862Sru 8175104862SruThis is a test. 8176104862Sru@endExample 8177104862Sru 8178104862SruThe main usage of this feature is to define macros which act exactly 8179104862Sruat the place where called. 8180104862Sru 8181104862Sru@Example 8182104862Sru.\" A simple macro to underline a word 8183104862Sru.de underline 8184104862Sru. nop \\$1\l'|0\[ul]' 8185104862Sru.. 8186104862Sru@endExample 8187104862Sru 8188104862Sru@noindent 8189104862SruIn the above example, @samp{|0} specifies a negative distance from the 8190104862Srucurrent position (at the end of the just emitted argument @code{\$1}) back 8191104862Sruto the beginning of the input line. Thus, the @samp{\l} escape draws a 8192104862Sruline from right to left. 8193104862Sru 8194104862Sru@cindex input line continuation (@code{\}) 8195104862Sru@cindex line, input, continuation (@code{\}) 8196104862Sru@cindex continuation, input line (@code{\}) 8197104862Sru@cindex output line, continuation (@code{\c}) 8198104862Sru@cindex line, output, continuation (@code{\c}) 8199104862Sru@cindex continuation, output line (@code{\c}) 8200104862Sru@cindex interrupted line 8201104862Sru@cindex line, interrupted 8202104862Sru@code{gtroff} makes a difference between input and output line 8203104862Srucontinuation; the latter is also called @dfn{interrupting} a line. 8204104862Sru 8205104862Sru@DefescList {\\@key{RET}, , ,} 8206104862Sru@DefescItem {\\c, , ,} 8207104862Sru@DefregListEnd{.int} 8208104862SruContinue a line. @code{\@key{RET}} (this is a backslash at the end 8209104862Sruof a line immediately followed by a newline) works on the input level, 8210104862Srusuppressing the effects of the following newline in the input. 8211104862Sru 8212104862Sru@Example 8213104862SruThis is a \ 8214104862Sru.test 8215104862Sru @result{} This is a .test 8216104862Sru@endExample 8217104862Sru 8218104862SruThe @samp{|} operator is also affected. 8219104862Sru 8220104862Sru@cindex @code{\R}, after @code{\c} 8221104862Sru@code{\c} works on the output level. Anything after this escape on the 8222104862Srusame line is ignored, except @code{\R} which works as usual. Anything 8223104862Srubefore @code{\c} on the same line will be appended to the current partial 8224104862Sruoutput line. The next non-command line after an interrupted line counts 8225104862Sruas a new input line. 8226104862Sru 8227104862SruThe visual results depend on whether no-fill mode is active. 8228104862Sru 8229104862Sru@itemize @bullet 8230104862Sru@item 8231104862Sru@cindex @code{\c}, and no-fill mode 8232104862Sru@cindex no-fill mode, and @code{\c} 8233104862Sru@cindex mode, no-fill, and @code{\c} 8234104862SruIf no-fill mode is active (using the @code{nf} request), the next input 8235104862Srutext line after @code{\c} will be handled as a continuation of the same 8236104862Sruinput text line. 8237104862Sru 8238104862Sru@Example 8239104862Sru.nf 8240104862SruThis is a \c 8241104862Srutest. 8242104862Sru @result{} This is a test. 8243104862Sru@endExample 8244104862Sru 8245104862Sru@item 8246104862Sru@cindex @code{\c}, and fill mode 8247104862Sru@cindex fill mode, and @code{\c} 8248104862Sru@cindex mode, fill, and @code{\c} 8249104862SruIf fill mode is active (using the @code{fi} request), a word interrupted 8250104862Sruwith @code{\c} will be continued with the text on the next input text line, 8251104862Sruwithout an intervening space. 8252104862Sru 8253104862Sru@Example 8254104862SruThis is a te\c 8255104862Srust. 8256104862Sru @result{} This is a test. 8257104862Sru@endExample 8258104862Sru@end itemize 8259104862Sru 8260104862SruNote that an intervening control line which causes a break is stronger 8261104862Sruthan @code{\c}, flushing out the current partial line in the usual way. 8262104862Sru 8263104862Sru@cindex interrupted line register (@code{.int}) 8264104862SruThe @code{.int} register contains a positive value 8265104862Sruif the last output line was interrupted with @code{\c}; this is 8266104862Sruassociated with the current environment (@pxref{Environments}). 8267104862Sru@endDefesc 8268104862Sru 8269104862Sru@c ===================================================================== 8270104862Sru 8271104862Sru@node Page Layout, Page Control, Line Control, gtroff Reference 827255839Sasmodai@section Page Layout 827355839Sasmodai@cindex page layout 827455839Sasmodai@cindex layout, page 827555839Sasmodai 827669626Sru@code{gtroff} provides some very primitive operations for controlling 827769626Srupage layout. 827855839Sasmodai 8279104862Sru@DefreqList {pl, [@Var{length}]} 8280104862Sru@DefreqItem {pl, @t{+}@Var{length}} 8281104862Sru@DefreqItem {pl, @t{-}@Var{length}} 8282104862Sru@DefregListEnd {.p} 8283104862Sru@cindex page length (@code{pl}) 8284104862Sru@cindex length of page (@code{pl}) 828575584SruSet the @dfn{page length} to @var{length} (or increment or decrement 828675584Sruthe current value by @var{length}). This is the length of the 8287104862Sruphysical output page. The default scaling indicator is @samp{v}. 828855839Sasmodai 8289104862Sru@cindex page length register (@code{.p}) 829075584SruThe current setting can be found in the read-only number register 829169626Sru@samp{.p}. 829255839Sasmodai 829369626Sru@cindex top margin 829469626Sru@cindex margin, top 829569626Sru@cindex bottom margin 829669626Sru@cindex margin, bottom 829769626SruNote that this only specifies the size of the page, not the top and 829875584Srubottom margins. Those are not set by @code{gtroff} directly. 829975584Sru@xref{Traps}, for further information on how to do this. 830069626Sru 830169626SruNegative @code{pl} values are possible also, but not very useful: No 830269626Srutrap is sprung, and each line is output on a single page (thus 830369626Srusuppressing all vertical spacing). 830469626Sru 830575584SruIf no argument or an invalid argument is given, @code{pl} sets the page 830675584Srulength to 11@dmn{i}. 830775584Sru@endDefreq 830875584Sru 830955839Sasmodai@cindex headers 831055839Sasmodai@cindex footers 831155839Sasmodai@cindex titles 831269626Sru@code{gtroff} provides several operations which help in setting up top 831369626Sruand bottom titles (or headers and footers). 831455839Sasmodai 831575584Sru@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 8316104862Sru@cindex title line (@code{tl}) 8317104862Sru@cindex three-part title (@code{tl}) 8318104862Sru@cindex page number character (@code{%}) 831975584SruPrint a @dfn{title line}. It consists of three parts: a left 832075584Srujustified portion, a centered portion, and a right justified portion. 832175584SruThe argument separator @samp{'} can be replaced with any character not 832275584Sruoccurring in the title line. The @samp{%} character is replaced with 832375584Sruthe current page number. This character can be changed with the 832475584Sru@code{pc} request (see below). 832555839Sasmodai 832675584SruWithout argument, @code{tl} is ignored. 832775584Sru 832875584SruSome notes: 832975584Sru 833075584Sru@itemize @bullet 833175584Sru@item 833275584SruA title line is not restricted to the top or bottom of a page. 833375584Sru 833475584Sru@item 833575584Sru@code{tl} prints the title line immediately, ignoring a partially filled 833675584Sruline (which stays untouched). 833775584Sru 833875584Sru@item 833975584SruIt is not an error to omit closing delimiters. For example, 834075584Sru@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 834175584Srutitle line with the left justified word @samp{foo}; the centered and 834275584Sruright justfied parts are empty. 834375584Sru 834475584Sru@item 834575584Sru@code{tl} accepts the same parameter delimiting characters as the 834675584Sru@code{\A} escape; see @ref{Escapes}. 834775584Sru@end itemize 834875584Sru@endDefreq 834975584Sru 8350104862Sru@DefreqList {lt, [@Var{length}]} 8351104862Sru@DefreqItem {lt, @t{+}@Var{length}} 8352104862Sru@DefreqItem {lt, @t{-}@Var{length}} 8353104862Sru@DefregListEnd {.lt} 8354104862Sru@cindex length of title line (@code{lt}) 8355104862Sru@cindex title line, length (@code{lt}) 8356104862Sru@cindex title line length register (@code{.lt}) 835775584SruThe title line is printed using its own line length, which is 835875584Sruspecified (or incremented or decremented) with the @code{lt} request. 835975584SruInitially, the title line length is set to 6.5@dmn{i}. If a negative 836075584Sruline length is specified (which is not allowed), @code{gtroff} emits a 836175584Sruwarning of type @samp{range} and sets the title line length to zero. 8362104862SruThe default scaling indicator is @samp{m}. If @code{lt} is called 836375584Sruwithout an argument, the title length is reset to the previous value 836475584Srubefore the last call to @code{lt}. 836555839Sasmodai 836675584SruThe current setting of this is available in the @code{.lt} read-only 836775584Srunumber register; it is associated with the current environment 836875584Sru(@pxref{Environments}). 836975584Sru@endDefreq 837075584Sru 8371104862Sru@DefreqList {pn, page} 8372104862Sru@DefreqItem {pn, @t{+}@Var{page}} 8373104862Sru@DefreqItem {pn, @t{-}@Var{page}} 8374104862Sru@DefregListEnd {.pn} 8375104862Sru@cindex page number (@code{pn}) 8376104862Sru@cindex number, page (@code{pn}) 837775584SruChange (increase or decrease) the page number of the @emph{next} page. 837875584SruThe only argument is the page number; the request is ignored without a 837975584Sruparameter. 838055839Sasmodai 838175584SruThe read-only number register @code{.pn} contains the number of the next 838275584Srupage: either the value set by a @code{pn} request, or the number of the 8383114402Srucurrent page plus@tie{}1. 838475584Sru@endDefreq 838575584Sru 8386104862Sru@Defreq {pc, [@Var{char}]} 8387104862Sru@cindex changing the page number character (@code{pc}) 8388104862Sru@cindex page number character, changing (@code{pc}) 838975584Sru@vindex % 839075584SruChange the page number character (used by the @code{tl} request) to a 839175584Srudifferent character. With no argument, this mechanism is disabled. 8392114402SruNote that this doesn't affect the number register@tie{}@code{%}. 839375584Sru@endDefreq 839455839Sasmodai 839569626Sru@xref{Traps}. 839655839Sasmodai 839755839Sasmodai 839869626Sru@c ===================================================================== 839969626Sru 8400114402Sru@node Page Control, Fonts and Symbols, Page Layout, gtroff Reference 840155839Sasmodai@section Page Control 840255839Sasmodai@cindex page control 840355839Sasmodai@cindex control, page 840455839Sasmodai 8405104862Sru@DefreqList {bp, [@Var{page}]} 8406104862Sru@DefreqItem {bp, @t{+}@Var{page}} 8407151497Sru@DefreqItem {bp, @t{-}@Var{page}} 8408151497Sru@DefregListEnd {%} 8409104862Sru@cindex new page (@code{bp}) 8410104862Sru@cindex page, new (@code{bp}) 841175584SruStop processing the current page and move to the next page. This 841275584Srurequest causes a break. It can also take an argument to set 8413151497Sru(increase, decrease) the page number of the next page (which actually 8414151497Srubecomes the current page after @code{bp} has finished). The 841575584Srudifference between @code{bp} and @code{pn} is that @code{pn} does not 8416151497Srucause a break or actually eject a page. @xref{Page Layout}. 841755839Sasmodai 841875584Sru@Example 841975584Sru.de newpage \" define macro 842075584Sru'bp \" begin page 842175584Sru'sp .5i \" vertical space 842275584Sru.tl 'left top'center top'right top' \" title 842375584Sru'sp .3i \" vertical space 842475584Sru.. \" end macro 842575584Sru@endExample 842655839Sasmodai 8427104862Sru@cindex @code{bp} request, and top-level diversion 8428104862Sru@cindex top-level diversion, and @code{bp} 8429104862Sru@cindex diversion, top-level, and @code{bp} 843075584Sru@code{bp} has no effect if not called within the top-level diversion 843175584Sru(@pxref{Diversions}). 8432114402Sru 8433151497Sru@cindex page number register (@code{%}) 8434151497Sru@cindex current page number (@code{%}) 8435151497SruThe read-write register@tie{}@code{%} holds the current page number. 8436151497Sru 8437114402SruThe number register @code{.pe} is set to@tie{}1 while @code{bp} is 8438114402Sruactive. @xref{Page Location Traps}. 843975584Sru@endDefreq 844075584Sru 844175584Sru@Defreq {ne, [@Var{space}]} 8442104862Sru@cindex orphan lines, preventing with @code{ne} 8443104862Sru@cindex conditional page break (@code{ne}) 8444104862Sru@cindex page break, conditional (@code{ne}) 844569626SruIt is often necessary to force a certain amount of space before a new 844669626Srupage occurs. This is most useful to make sure that there is not a 844769626Srusingle @dfn{orphan} line left at the bottom of a page. The @code{ne} 844875584Srurequest ensures that there is a certain distance, specified by the 844975584Srufirst argument, before the next page is triggered (see @ref{Traps}, 8450104862Srufor further information). The default scaling indicator for @code{ne} 8451114402Sruis @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no 8452104862Sruargument is given. 845355839Sasmodai 8454114402SruFor example, to make sure that no fewer than 2@tie{}lines get orphaned, 845569626Srudo the following before each paragraph: 845655839Sasmodai 845775584Sru@Example 845855839Sasmodai.ne 2 845975584Srutext text text 846075584Sru@endExample 8461104862Sru 8462104862Sru@code{ne} will then automatically cause a page break if there is space 8463104862Srufor one line only. 846475584Sru@endDefreq 846555839Sasmodai 8466104862Sru@DefreqList {sv, [@Var{space}]} 8467104862Sru@DefreqListEnd {os, } 8468104862Sru@cindex @code{ne} request, comparison with @code{sv} 846975584Sru@code{sv} is similar to the @code{ne} request; it reserves the 847075584Sruspecified amount of vertical space. If the desired amount of space 8471104862Sruexists before the next trap (or the bottom page boundary if no trap is 8472104862Sruset), the space is output immediately (ignoring a partially filled line 8473104862Sruwhich stays untouched). If there is not enough space, it is stored for 8474114402Srulater output via the @code{os} request. The default value is@tie{}1@dmn{v} 8475104862Sruif no argument is given; the default scaling indicator is @samp{v}. 8476104862Sru 8477104862Sru@cindex @code{sv} request, and no-space mode 8478104862Sru@cindex @code{os} request, and no-space mode 8479104862SruBoth @code{sv} and @code{os} ignore no-space mode. While the @code{sv} 8480104862Srurequest allows negative values for @var{space}, @code{os} will ignore 8481104862Sruthem. 848275584Sru@endDefreq 848355839Sasmodai 8484104862Sru@Defreg {nl} 8485151497Sru@cindex current vertical position (@code{nl}) 8486151497Sru@cindex vertical position, current (@code{nl}) 8487151497Sru@cindex position, vertical, current (@code{nl}) 8488104862SruThis register contains the current vertical position. If the vertical 8489104862Sruposition is zero and the top of page transition hasn't happened yet, 8490104862Sru@code{nl} is set to negative value. @code{gtroff} itself does this at 8491104862Sruthe very beginning of a document before anything has been printed, but 8492104862Sruthe main usage is to plant a header trap on a page if this page has 8493104862Srualready started. 849455839Sasmodai 8495104862SruConsider the following: 8496104862Sru 8497104862Sru@Example 8498104862Sru.de xxx 8499104862Sru. sp 8500104862Sru. tl ''Header'' 8501104862Sru. sp 8502104862Sru.. 8503104862Sru. 8504104862SruFirst page. 8505104862Sru.bp 8506104862Sru.wh 0 xxx 8507104862Sru.nr nl (-1) 8508104862SruSecond page. 8509104862Sru@endExample 8510104862Sru 8511104862Sru@noindent 8512104862SruResult: 8513104862Sru 8514104862Sru@Example 8515104862SruFirst page. 8516104862Sru 8517104862Sru... 8518104862Sru 8519104862Sru Header 8520104862Sru 8521104862SruSecond page. 8522104862Sru 8523104862Sru... 8524104862Sru@endExample 8525104862Sru 8526104862Sru@noindent 8527104862SruWithout resetting @code{nl} to a negative value, the just planted trap 8528104862Sruwould be active beginning with the @emph{next} page, not the current 8529104862Sruone. 8530104862Sru 8531104862Sru@xref{Diversions}, for a comparison with the @code{.h} and @code{.d} 8532104862Sruregisters. 8533104862Sru@endDefreg 8534104862Sru 853569626Sru@c ===================================================================== 853669626Sru 8537114402Sru@node Fonts and Symbols, Sizes, Page Control, gtroff Reference 8538114402Sru@section Fonts and Symbols 853955839Sasmodai@cindex fonts 854055839Sasmodai 854175584Sru@code{gtroff} can switch fonts at any point in the text. 854255839Sasmodai 854375584SruThe basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 8544104862SruThese are Times Roman, Italic, Bold, and Bold Italic. For non-TTY 854575584Srudevices, there is also at least one symbol font which contains various 854675584Sruspecial symbols (Greek, mathematics). 854755839Sasmodai 854855839Sasmodai@menu 854975584Sru* Changing Fonts:: 855075584Sru* Font Families:: 855175584Sru* Font Positions:: 855275584Sru* Using Symbols:: 855375584Sru* Special Fonts:: 855475584Sru* Artificial Fonts:: 855575584Sru* Ligatures and Kerning:: 855655839Sasmodai@end menu 855755839Sasmodai 855869626Sru@c --------------------------------------------------------------------- 855969626Sru 8560114402Sru@node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols 856155839Sasmodai@subsection Changing Fonts 8562104862Sru@cindex fonts 856355839Sasmodai 8564104862Sru@DefreqList {ft, [@Var{font}]} 8565104862Sru@DefescItem {\\f, , f, } 8566151497Sru@DefescItem {\\f, @Lparen{}, fn, } 8567151497Sru@DefescItem {\\f, @Lbrack{}, font, @Rbrack{}} 8568151497Sru@DefregListEnd {.sty} 8569104862Sru@cindex changing fonts (@code{ft}, @code{\f}) 8570104862Sru@cindex fonts, changing (@code{ft}, @code{\f}) 8571104862Sru@cindex @code{sty} request, and changing fonts 8572104862Sru@cindex @code{fam} request, and changing fonts 8573104862Sru@cindex @code{\F}, and changing fonts 857475584Sru@kindex styles 857575584Sru@kindex family 857675584Sru@pindex DESC 857775584SruThe @code{ft} request and the @code{\f} escape change the current font 8578114402Sruto @var{font} (one-character name@tie{}@var{f}, two-character name 857975584Sru@var{fn}). 858075584Sru 858175584SruIf @var{font} is a style name (as set with the @code{sty} request or 858275584Sruwith the @code{styles} command in the @file{DESC} file), use it within 8583104862Sruthe current font family (as set with the @code{fam} request, @code{\F} 8584104862Sruescape, or with the @code{family} command in the @file{DESC} file). 858575584Sru 8586104862Sru@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP}) 8587104862Sru@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP}) 858875584SruWith no argument or using @samp{P} as an argument, @code{.ft} switches 8589104862Sruto the previous font. Use @code{\f[]} to do this with the escape. The 8590104862Sruold syntax forms @code{\fP} or @code{\f[P]} are also supported. 859155839Sasmodai 859275584SruFonts are generally specified as upper-case strings, which are usually 8593114402Sru1@tie{}to 4 characters representing an abbreviation or acronym of the 859475584Srufont name. This is no limitation, just a convention. 859575584Sru 859675584SruThe example below produces two identical lines. 859775584Sru 859875584Sru@Example 859955839Sasmodaieggs, bacon, 860055839Sasmodai.ft B 860155839Sasmodaispam 860255839Sasmodai.ft 860355839Sasmodaiand sausage. 860455839Sasmodai 860555839Sasmodaieggs, bacon, \fBspam\fP and sausage. 860675584Sru@endExample 860755839Sasmodai 8608104862SruNote that @code{\f} doesn't produce an input token in @code{gtroff}. 8609104862SruAs a consequence, it can be used in requests like @code{mc} (which 8610104862Sruexpects a single character as an argument) to change the font on 8611104862Sruthe fly: 8612104862Sru 8613104862Sru@Example 8614104862Sru.mc \f[I]x\f[] 8615104862Sru@endExample 8616104862Sru 8617151497SruThe current style name is available in the read-only number register 8618151497Sru@samp{.sty} (this is a string-valued register); if the current font 8619151497Sruisn't a style, the empty string is returned. It is associated with 8620151497Sruthe current environment. 8621151497Sru 862275584Sru@xref{Font Positions}, for an alternative syntax. 862375584Sru@endDefreq 862455839Sasmodai 862575584Sru@Defreq {ftr, f [@Var{g}]} 8626104862Sru@cindex @code{ft} request, and font translations 8627104862Sru@cindex @code{ul} request, and font translations 8628104862Sru@cindex @code{bd} request, and font translations 8629104862Sru@cindex @code{\f}, and font translations 8630104862Sru@cindex @code{cs} request, and font translations 8631104862Sru@cindex @code{tkf} request, and font translations 8632104862Sru@cindex @code{special} request, and font translations 8633104862Sru@cindex @code{fspecial} request, and font translations 8634104862Sru@cindex @code{fp} request, and font translations 8635104862Sru@cindex @code{sty} request, and font translations 8636151497Sru@cindex @code{if} request, and font translations 8637151497Sru@cindex @code{ie} request, and font translations 8638151497Sru@cindex @code{while} request, and font translations 8639114402SruTranslate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font 8640151497Srunamed@tie{}@var{f} is referred to in a @code{\f} escape sequence, 8641151497Sruin the @code{F} and @code{S} conditional operators, or in the 864275584Sru@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 8643104862Sru@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, 8644114402Srufont@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f} 864575584Sruthe translation is undone. 864675584Sru@endDefreq 864755839Sasmodai 864869626Sru@c --------------------------------------------------------------------- 864969626Sru 8650114402Sru@node Font Families, Font Positions, Changing Fonts, Fonts and Symbols 865155839Sasmodai@subsection Font Families 865255839Sasmodai@cindex font families 865355839Sasmodai@cindex families, font 865475584Sru@cindex font styles 865575584Sru@cindex styles, font 865655839Sasmodai 865769626SruDue to the variety of fonts available, @code{gtroff} has added the 865875584Sruconcept of @dfn{font families} and @dfn{font styles}. The fonts are 865975584Sruspecified as the concatenation of the font family and style. Specifying 866075584Srua font without the family part causes @code{gtroff} to use that style of 866175584Sruthe current family. 866255839Sasmodai 8663104862Sru@cindex PostScript fonts 8664104862Sru@cindex fonts, PostScript 8665151497SruCurrently, fonts for the devices @option{-Tps}, @option{-Tdvi}, 8666151497Sru@option{-Tlj4}, @option{-Tlbp}, and the X11 fonts are set up to this 8667151497Srumechanism. By default, @code{gtroff} uses the Times family with the four 8668151497Srustyles @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 866955839Sasmodai 867069626SruThis way, it is possible to use the basic four fonts and to select a 867175584Srudifferent font family on the command line (@pxref{Groff Options}). 867255839Sasmodai 8673104862Sru@DefreqList {fam, [@Var{family}]} 8674104862Sru@DefregItem {.fam} 8675104862Sru@DefescItem {\\F, , f, } 8676151497Sru@DefescItem {\\F, @Lparen{}, fm, } 8677151497Sru@DefescItem {\\F, @Lbrack{}, family, @Rbrack{}} 8678104862Sru@DefregListEnd {.fn} 8679104862Sru@cindex changing font family (@code{fam}, @code{\F}) 8680104862Sru@cindex font family, changing (@code{fam}, @code{\F}) 8681114402SruSwitch font family to @var{family} (one-character name@tie{}@var{f}, 8682104862Srutwo-character name @var{fm}). If no argument is given, switch 8683104862Sruback to the previous font family. Use @code{\F[]} to do this with the 8684104862Sruescape. Note that @code{\FP} doesn't work; it selects font family 8685104862Sru@samp{P} instead. 868655839Sasmodai 8687104862SruThe value at start-up is @samp{T}. 8688104862SruThe current font family is available in the read-only number register 8689104862Sru@samp{.fam} (this is a string-valued register); it is associated with 8690104862Sruthe current environment. 8691104862Sru 869275584Sru@Example 869355839Sasmodaispam, 869475584Sru.fam H \" helvetica family 869575584Sruspam, \" used font is family H + style R = HR 869675584Sru.ft B \" family H + style B = font HB 869755839Sasmodaispam, 869875584Sru.fam T \" times family 869975584Sruspam, \" used font is family T + style B = TB 870075584Sru.ft AR \" font AR (not a style) 870155839Sasmodaibaked beans, 870275584Sru.ft R \" family T + style R = font TR 870355839Sasmodaiand spam. 870475584Sru@endExample 8705104862Sru 8706104862SruNote that @code{\F} doesn't produce an input token in @code{gtroff}. 8707104862SruAs a consequence, it can be used in requests like @code{mc} (which 8708104862Sruexpects a single character as an argument) to change the font family on 8709104862Sruthe fly: 8710104862Sru 8711104862Sru@Example 8712104862Sru.mc \F[P]x\F[] 8713104862Sru@endExample 8714104862Sru 8715104862SruThe @samp{.fn} register contains the current @dfn{real font name} 8716104862Sruof the current font. 8717104862SruThis is a string-valued register. 8718104862SruIf the current font is a style, the value of @code{\n[.fn]} 8719104862Sruis the proper concatenation of family and style name. 872075584Sru@endDefreq 872155839Sasmodai 872275584Sru@Defreq {sty, n style} 8723104862Sru@cindex changing font style (@code{sty}) 8724104862Sru@cindex font style, changing (@code{sty}) 8725104862Sru@cindex @code{cs} request, and font styles 8726104862Sru@cindex @code{bd} request, and font styles 8727104862Sru@cindex @code{tkf} request, and font styles 8728104862Sru@cindex @code{uf} request, and font styles 8729104862Sru@cindex @code{fspecial} request, and font styles 8730114402SruAssociate @var{style} with font position@tie{}@var{n}. A font position 873175584Srucan be associated either with a font or with a style. The current 873275584Srufont is the index of a font position and so is also either a font or a 8733104862Srustyle. If it is a style, the font that is actually used is the font 8734104862Sruwhich name is the concatenation of the name of the current 873575584Srufamily and the name of the current style. For example, if the current 8736114402Srufont is@tie{}1 and font position@tie{}1 is associated with style 8737104862Sru@samp{R} and the current font family is @samp{T}, then font 873875584Sru@samp{TR} will be used. If the current font is not a style, then the 8739104862Srucurrent family is ignored. If the requests @code{cs}, @code{bd}, 8740104862Sru@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, 874175584Sruthey will instead be applied to the member of the current family 874275584Srucorresponding to that style. 874375584Sru 8744114402Sru@var{n}@tie{}must be a non-negative integer value. 874575584Sru 874675584Sru@pindex DESC 874775584Sru@kindex styles 874875584SruThe default family can be set with the @option{-f} option 874975584Sru(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 875075584Srufile controls which font positions (if any) are initially associated 875175584Sruwith styles rather than fonts. For example, the default setting for 875275584Sru@sc{PostScript} fonts 875375584Sru 875475584Sru@Example 875575584Srustyles R I B BI 875675584Sru@endExample 875775584Sru 875875584Sru@noindent 875975584Sruis equivalent to 876075584Sru 876175584Sru@Example 876275584Sru.sty 1 R 876375584Sru.sty 2 I 876475584Sru.sty 3 B 876575584Sru.sty 4 BI 876675584Sru@endExample 876775584Sru 8768104862Sru@code{fam} and @code{\F} always check whether the current font position 8769104862Sruis valid; this can give surprising results if the current font position is 877075584Sruassociated with a style. 877175584Sru 877275584SruIn the following example, we want to access the @sc{PostScript} font 877375584Sru@code{FooBar} from the font family @code{Foo}: 877475584Sru 877575584Sru@Example 877675584Sru.sty \n[.fp] Bar 877775584Sru.fam Foo 877875584Sru @result{} warning: can't find font `FooR' 877975584Sru@endExample 878075584Sru 878175584Sru@noindent 8782114402SruThe default font position at start-up is@tie{}1; for the 878375584Sru@sc{PostScript} device, this is associated with style @samp{R}, so 878475584Sru@code{gtroff} tries to open @code{FooR}. 878575584Sru 878675584SruA solution to this problem is to use a dummy font like the following: 878775584Sru 878875584Sru@Example 878975584Sru.fp 0 dummy TR \" set up dummy font at position 0 879075584Sru.sty \n[.fp] Bar \" register style `Bar' 879175584Sru.ft 0 \" switch to font at position 0 879275584Sru.fam Foo \" activate family `Foo' 879375584Sru.ft Bar \" switch to font `FooBar' 879475584Sru@endExample 879575584Sru 879675584Sru@xref{Font Positions}. 879775584Sru@endDefreq 879875584Sru 879969626Sru@c --------------------------------------------------------------------- 880055839Sasmodai 8801114402Sru@node Font Positions, Using Symbols, Font Families, Fonts and Symbols 880255839Sasmodai@subsection Font Positions 880355839Sasmodai@cindex font positions 880455839Sasmodai@cindex positions, font 880555839Sasmodai 880675584SruFor the sake of old phototypesetters and compatibility with old versions 880769626Sruof @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 880875584Sruon which various fonts are mounted. 880955839Sasmodai 8810104862Sru@DefreqList {fp, pos font [@Var{external-name}]} 8811104862Sru@DefregItem {.f} 8812104862Sru@DefregListEnd {.fp} 8813104862Sru@cindex mounting font (@code{fp}) 8814104862Sru@cindex font, mounting (@code{fp}) 881575584SruMount font @var{font} at position @var{pos} (which must be a 881675584Srunon-negative integer). This numeric position can then be referred to 881775584Sruwith font changing commands. When @code{gtroff} starts it is using 8818114402Srufont position@tie{}1 (which must exist; position@tie{}0 is unused 881975584Sruusually at start-up). 882055839Sasmodai 8821104862Sru@cindex font position register (@code{.f}) 882275584SruThe current font in use, as a font position, is available in the 882375584Sruread-only number register @samp{.f}. This can be useful to remember the 882475584Srucurrent font for later recall. It is associated with the current 882575584Sruenvironment (@pxref{Environments}). 882655839Sasmodai 882775584Sru@Example 882875584Sru.nr save-font \n[.f] 882975584Sru.ft B 883075584Sru... text text text ... 883155839Sasmodai.ft \n[save-font] 883275584Sru@endExample 883355839Sasmodai 8834104862Sru@cindex next free font position register (@code{.fp}) 883575584SruThe number of the next free font position is available in the read-only 883675584Srunumber register @samp{.fp}. This is useful when mounting a new font, 883775584Srulike so: 883855839Sasmodai 883975584Sru@Example 884055839Sasmodai.fp \n[.fp] NEATOFONT 884175584Sru@endExample 884255839Sasmodai 884369626Sru@pindex DESC@r{, and font mounting} 884455839SasmodaiFonts not listed in the @file{DESC} file are automatically mounted on 884575584Sruthe next available font position when they are referenced. If a font 884675584Sruis to be mounted explicitly with the @code{fp} request on an unused 884775584Srufont position, it should be mounted on the first unused font position, 884875584Sruwhich can be found in the @code{.fp} register. Although @code{gtroff} 884975584Srudoes not enforce this strictly, it is not allowed to mount a font at a 885075584Sruposition whose number is much greater (approx.@: 1000 positions) than 885175584Sruthat of any currently used position. 885255839Sasmodai 885369626SruThe @code{fp} request has an optional third argument. This argument 885469626Srugives the external name of the font, which is used for finding the font 885555839Sasmodaidescription file. The second argument gives the internal name of the 885669626Srufont which is used to refer to the font in @code{gtroff} after it has 885775584Srubeen mounted. If there is no third argument then the internal name is 885875584Sruused as the external name. This feature makes it possible to use 885969626Srufonts with long names in compatibility mode. 886075584Sru@endDefreq 886155839Sasmodai 886275584SruBoth the @code{ft} request and the @code{\f} escape have alternative 886375584Srusyntax forms to access font positions. 886475584Sru 8865104862Sru@DefreqList {ft, nnn} 8866104862Sru@DefescItem {\\f, , n, } 8867151497Sru@DefescItem {\\f, @Lparen{}, nn, } 8868151497Sru@DefescListEnd {\\f, @Lbrack{}, nnn, @Rbrack{}} 8869104862Sru@cindex changing font position (@code{\f}) 8870104862Sru@cindex font position, changing (@code{\f}) 8871104862Sru@cindex @code{sty} request, and font positions 8872104862Sru@cindex @code{fam} request, and font positions 8873104862Sru@cindex @code{\F}, and font positions 887475584Sru@kindex styles 887575584Sru@kindex family 887675584Sru@pindex DESC 8877114402SruChange the current font position to @var{nnn} (one-digit 8878114402Sruposition@tie{}@var{n}, two-digit position @var{nn}), which must be a 8879114402Srunon-negative integer. 888075584Sru 888175584SruIf @var{nnn} is associated with a style (as set with the @code{sty} 888275584Srurequest or with the @code{styles} command in the @file{DESC} file), use 8883104862Sruit within the current font family (as set with the @code{fam} request, 8884104862Sruthe @code{\F} escape, or with the @code{family} command in the @file{DESC} 8885104862Srufile). 888675584Sru 888775584Sru@Example 888875584Sruthis is font 1 888975584Sru.ft 2 889075584Sruthis is font 2 889175584Sru.ft \" switch back to font 1 889275584Sru.ft 3 889375584Sruthis is font 3 889475584Sru.ft 889575584Sruthis is font 1 again 889675584Sru@endExample 889775584Sru 889875584Sru@xref{Changing Fonts}, for the standard syntax form. 889975584Sru@endDefreq 890075584Sru 890169626Sru@c --------------------------------------------------------------------- 890255839Sasmodai 8903114402Sru@node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols 890455839Sasmodai@subsection Using Symbols 890555839Sasmodai@cindex using symbols 890655839Sasmodai@cindex symbols, using 890755839Sasmodai 890875584Sru@cindex glyph 890975584Sru@cindex character 891075584Sru@cindex ligature 891175584SruA @dfn{glyph} is a graphical representation of a @dfn{character}. 891275584SruWhile a character is an abstract entity containing semantic 891375584Sruinformation, a glyph is something which can be actually seen on screen 891475584Sruor paper. It is possible that a character has multiple glyph 891575584Srurepresentation forms (for example, the character `A' can be either 891675584Sruwritten in a roman or an italic font, yielding two different glyphs); 891775584Srusometimes more than one character maps to a single glyph (this is a 891875584Sru@dfn{ligature} -- the most common is `fi'). 891955839Sasmodai 892075584Sru@cindex symbol 892175584Sru@cindex special fonts 892275584Sru@kindex fonts 892375584Sru@pindex DESC 8924114402Sru@cindex @code{special} request, and glyph search order 8925114402Sru@cindex @code{fspecial} request, and glyph search order 892675584SruA @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 892775584Sruglyph names of a particular font are defined in its font file. If the 892875584Sruuser requests a glyph not available in this font, @code{gtroff} looks 892975584Sruup an ordered list of @dfn{special fonts}. By default, the 893075584Sru@sc{PostScript} output device supports the two special fonts @samp{SS} 893175584Sru(slanted symbols) and @samp{S} (symbols) (the former is looked up 893275584Srubefore the latter). Other output devices use different names for 893375584Sruspecial fonts. Fonts mounted with the @code{fonts} keyword in the 893475584Sru@file{DESC} file are globally available. To install additional 893575584Sruspecial fonts locally (i.e.@: for a particular font), use the 893675584Sru@code{fspecial} request. 893755839Sasmodai 8938114402SruHere the exact rules how @code{gtroff} searches a given symbol: 8939104862Sru 8940104862Sru@itemize @bullet 8941104862Sru@item 8942104862SruIf the symbol has been defined with the @code{char} request, use it. 8943104862SruThis hides a symbol with the same name in the current font. 8944104862Sru 8945104862Sru@item 8946104862SruCheck the current font. 8947104862Sru 8948104862Sru@item 8949104862SruIf the symbol has been defined with the @code{fchar} request, use it. 8950104862Sru 8951104862Sru@item 8952114402SruCheck whether the current font has a font-specific list of special fonts; 8953114402Srutest all fonts in the order of appearance in the last @code{fspecial} 8954114402Srucall if appropriate. 8955104862Sru 8956104862Sru@item 8957114402SruIf the symbol has been defined with the @code{fschar} request for the 8958114402Srucurrent font, use it. 8959104862Sru 8960104862Sru@item 8961114402SruCheck all fonts in the order of appearance in the last @code{special} 8962114402Srucall. 8963114402Sru 8964114402Sru@item 8965114402SruIf the symbol has been defined with the @code{schar} request, use it. 8966114402Sru 8967114402Sru@item 8968114402SruAs a last resort, consult all fonts loaded up to now for special fonts 8969114402Sruand check them, starting with the lowest font number. Note that this can 8970114402Srusometimes lead to surprising results since the @code{fonts} line in the 8971114402Sru@file{DESC} file often contains empty positions which are filled later 8972114402Sruon. For example, consider the following: 8973114402Sru 8974114402Sru@Example 8975114402Srufonts 3 0 0 FOO 8976114402Sru@endExample 8977114402Sru 8978114402Sru@noindent 8979114402SruThis mounts font @code{foo} at font position@tie{}3. We assume that 8980114402Sru@code{FOO} is a special font, containing glyph @code{foo}, 8981114402Sruand that no font has been loaded yet. The line 8982114402Sru 8983114402Sru@Example 8984114402Sru.fspecial BAR BAZ 8985114402Sru@endExample 8986114402Sru 8987114402Sru@noindent 8988114402Srumakes font @code{BAZ} special only if font @code{BAR} is active. We 8989114402Srufurther assume that @code{BAZ} is really a special font, i.e., the font 8990114402Srudescription file contains the @code{special} keyword, and that it 8991114402Srualso contains glyph @code{foo} with a special shape fitting to font 8992114402Sru@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at 8993114402Srufont position@tie{}1, and @code{BAZ} at position@tie{}2. 8994114402Sru 8995114402SruWe now switch to a new font @code{XXX}, trying to access glyph @code{foo} 8996114402Sruwhich is assumed to be missing. There are neither font-specific special 8997114402Srufonts for @code{XXX} nor any other fonts made special with the 8998114402Sru@code{special} request, so @code{gtroff} starts the search for special 8999114402Srufonts in the list of already mounted fonts, with increasing font 9000114402Srupositions. Consequently, it finds @code{BAZ} before @code{FOO} even for 9001114402Sru@code{XXX} which is not the intended behaviour. 9002104862Sru@end itemize 9003104862Sru 900475584Sru@xref{Font Files}, and @ref{Special Fonts}, for more details. 900555839Sasmodai 9006104862Sru@cindex list of available glyphs (@cite{groff_char(7)} man page) 9007104862Sru@cindex available glyphs, list (@cite{groff_char(7)} man page) 9008104862Sru@cindex glyphs, available, list (@cite{groff_char(7)} man page) 9009104862SruThe list of available symbols is device dependent; see the 9010114402Sru@cite{groff_char(7)} man page for a complete list of all glyphs. For 9011114402Sruexample, say 901275584Sru 9013104862Sru@Example 9014104862Sruman -Tdvi groff_char > groff_char.dvi 9015104862Sru@endExample 9016104862Sru 9017104862Sru@noindent 9018104862Srufor a list using the default DVI fonts (not all versions of the 9019104862Sru@code{man} program support the @option{-T} option). If you want to 9020104862Sruuse an additional macro package to change the used fonts, @code{groff} 9021104862Srumust be called directly: 9022104862Sru 9023104862Sru@Example 9024104862Srugroff -Tdvi -mec -man groff_char.7 > groff_char.dvi 9025104862Sru@endExample 9026104862Sru 9027114402Sru@cindex composite glyph names 9028114402Sru@cindex glyph names, composite 9029114402Sru@cindex groff glyph list (GGL) 9030114402Sru@cindex GGL (groff glyph list) 9031114402Sru@cindex adobe glyph list (AGL) 9032114402Sru@cindex AGL (adobe glyph list) 9033114402SruGlyph names not listed in groff_char(7) are derived algorithmically, 9034114402Sruusing a simplified version of the Adobe Glyph List (AGL) algorithm 9035151497Sruwhich is described in 9036151497Sru@uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}. 9037114402SruThe (frozen) set of glyph names which can't be derived algorithmically 9038114402Sruis called @dfn{groff glyph list (GGL)}. 9039114402Sru 9040114402Sru@itemize @bullet 9041114402Sru@item 9042114402SruA glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is 9043114402Srunot a composite character will be named 9044114402Sru@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an 9045114402Sruuppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E}, 9046114402Sru@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at 9047114402Sruleast four @code{X} digits; if necessary, add leading zeroes (after the 9048114402Sru@samp{u}). No zero padding is allowed for character codes greater than 9049114402Sru0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF 9050114402Srurepresented with character codes from the surrogate area U+D800-U+DFFF) 9051114402Sruare not allowed too. 9052114402Sru 9053114402Sru@item 9054114402SruA glyph representing more than a single input character will be named 9055114402Sru 9056114402Sru@display 9057114402Sru@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{} 9058114402Sru@end display 9059114402Sru 9060114402Sru@noindent 9061114402SruExample: @code{u0045_0302_0301}. 9062114402Sru 9063114402SruFor simplicity, all Unicode characters which are composites must be 9064114402Srudecomposed maximally (this is normalization form@tie{}D in the Unicode 9065114402Srustandard); for example, @code{u00CA_0301} is not a valid glyph name 9066114402Srusince U+00CA (@sc{latin capital letter e with circumflex}) can be 9067114402Srufurther decomposed into U+0045 (@sc{latin capital letter e}) and U+0302 9068114402Sru(@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the 9069114402Sruglyph name for U+1EBE, @sc{latin capital letter e with circumflex and 9070114402Sruacute}. 9071114402Sru 9072114402Sru@item 9073114402Srugroff maintains a table to decompose all algorithmically derived glyph 9074114402Srunames which are composites itself. For example, @code{u0100} (@sc{latin 9075114402Sruletter a with macron}) will be automatically decomposed into 9076114402Sru@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred 9077114402Sruto an algorithmically derived glyph name; groff also automatically does 9078114402Sruthe mapping. Example: The glyph @code{u0045_0302} will be mapped to 9079114402Sru@code{^E}. 9080114402Sru 9081114402Sru@item 9082114402Sruglyph names of the GGL can't be used in composite glyph names; for 9083114402Sruexample, @code{^E_u0301} is invalid. 9084114402Sru@end itemize 9085114402Sru 9086151497Sru@DefescList {\\, @Lparen{}, nm, } 9087151497Sru@DefescItem {\\, @Lbrack{}, name, @Rbrack{}} 9088151497Sru@DefescListEnd {\\, @Lbrack{}, component1 component2 @dots{}, @Rbrack{}} 9089114402SruInsert a symbol @var{name} (two-character name @var{nm}) or a composite 9090114402Sruglyph with component glyphs @var{component1}, @var{component2}, 9091114402Sru@enddots{} There is no special syntax for one-character names -- the 9092114402Srunatural form @samp{\@var{n}} would collide with escapes.@footnote{Note 9093114402Sruthat a one-character symbol is not the same as an input character, i.e., 9094114402Sruthe character @code{a} is not the same as @code{\[a]}. By default, 9095114402Sru@code{groff} defines only a single one-character symbol, @code{\[-]}; it 9096114402Sruis usually accessed as @code{\-}. On the other hand, @code{gtroff} has 9097114402Sruthe special feature that @code{\[char@var{XXX}]} is the same as the 9098114402Sruinput character with character code @var{XXX}. For example, 9099114402Sru@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} 9100114402Sruencoding is active.} 9101114402Sru 9102114402SruIf @var{name} is undefined, a warning of type @samp{char} is generated, 9103114402Sruand the escape is ignored. @xref{Debugging}, for information about 9104114402Sruwarnings. 9105114402Sru 9106114402Srugroff resolves @code{\[...]} with more than a single component as 9107114402Srufollows: 9108114402Sru 9109114402Sru@itemize @bullet 9110114402Sru@item 9111114402SruAny component which is found in the GGL will be converted to the 9112114402Sru@code{u@var{XXXX}} form. 9113114402Sru 9114114402Sru@item 9115114402SruAny component @code{u@var{XXXX}} which is found in the list of 9116114402Srudecomposable glyphs will be decomposed. 9117114402Sru 9118114402Sru@item 9119114402SruThe resulting elements are then concatenated with @samp{_} inbetween, 9120114402Srudropping the leading @samp{u} in all elements but the first. 9121114402Sru@end itemize 9122114402Sru 9123114402SruNo check for the existence of any component (similar to @code{tr} 9124114402Srurequest) will be done. 9125114402Sru 9126114402SruExamples: 9127114402Sru 9128114402Sru@table @code 9129114402Sru@item \[A ho] 9130114402Sru@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the 9131114402Srufinal glyph name would be @code{u0041_02DB}. Note this is not the 9132114402Sruexpected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for 9133114402Srua proper composite a non-spacing ogonek (U+0328) is necessary. Looking 9134114402Sruinto the file @file{composite.tmac} one can find @w{@samp{.composite ho 9135114402Sruu0328}} which changes the mapping of @samp{ho} while a composite glyph 9136114402Sruname is constructed, causing the final glyph name to be 9137114402Sru@code{u0041_0328}. 9138114402Sru 9139114402Sru@item \[^E u0301] 9140114402Sru@itemx \[^E aa] 9141114402Sru@itemx \[E a^ aa] 9142114402Sru@itemx \[E ^ '] 9143114402Sru@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is 9144114402Sru@code{u0045_0302_0301} in all forms (assuming proper calls of the 9145114402Sru@code{composite} request). 9146114402Sru@end table 9147114402Sru 9148114402SruIt is not possible to define glyphs with names like @w{@samp{A ho}} 9149114402Sruwithin a groff font file. This is not really a limitation; instead, you 9150114402Sruhave to define @code{u0041_0328}. 915175584Sru@endDefesc 915275584Sru 915375584Sru@Defesc {\\C, ', xxx, '} 9154104862Sru@cindex named character (@code{\C}) 9155104862Sru@cindex character, named (@code{\C}) 9156104862SruTypeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a 9157104862Srumisnomer since it accesses an output glyph.} Normally it is more 9158104862Sruconvenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage 9159104862Sruthat it is compatible with newer versions of @acronym{AT&T} 9160104862Sru@code{troff} and is available in compatibility mode. 916175584Sru@endDefesc 916275584Sru 9163114402Sru@Defreq {composite, from to} 9164114402Sru@pindex composite.tmac 9165114402SruMap glyph name @var{from} to glyph name @var{to} if it is used in 9166114402Sru@code{\[...]} with more than one component. See above for examples. 9167114402Sru 9168114402SruThis mapping is based on glyph names only; no check for the existence of 9169114402Srueither glyph is done. 9170114402Sru 9171114402SruA set of default mappings for many accents can be found in the file 9172114402Sru@file{composite.tmac} which is loaded at start-up. 9173114402Sru@endDefreq 9174114402Sru 917575584Sru@Defesc {\\N, ', n, '} 9176104862Sru@cindex numbered glyph (@code{\N}) 9177104862Sru@cindex glyph, numbered (@code{\N}) 9178104862Sru@cindex @code{char} request, used with @code{\N} 9179104862Sru@cindex Unicode 9180114402SruTypeset the glyph with code@tie{}@var{n} in the current font 9181114402Sru(@code{n}@tie{}is @strong{not} the input character code). The 9182114402Srunumber @var{n}@tie{}can be any non-negative decimal integer. Most devices 9183114402Sruonly have glyphs with codes between 0 and@tie{}255; the Unicode 9184104862Sruoutput device uses codes in the range 0--65535. If the current 9185104862Srufont does not contain a glyph with that code, special fonts are 9186104862Sru@emph{not} searched. The @code{\N} escape sequence can be 9187104862Sruconveniently used in conjunction with the @code{char} request: 918875584Sru 918975584Sru@Example 919075584Sru.char \[phone] \f[ZD]\N'37' 919175584Sru@endExample 919275584Sru 919369626Sru@noindent 919469626Sru@pindex DESC 9195104862Sru@cindex unnamed glyphs 9196104862Sru@cindex glyphs, unnamed 9197104862SruThe code of each glyph is given in the fourth column in the font 919875584Srudescription file after the @code{charset} command. It is possible to 9199104862Sruinclude unnamed glyphs in the font description file by using a 920075584Sruname of @samp{---}; the @code{\N} escape sequence is the only way to 920175584Sruuse these. 9202114402Sru 9203114402SruNo kerning is applied to glyphs accessed with @code{\N}. 920475584Sru@endDefesc 920555839Sasmodai 9206104862SruSome escape sequences directly map onto special glyphs. 920769626Sru 9208104862Sru@Defesc {\\', , , } 9209104862SruThis is a backslash followed by the apostrophe character, @acronym{ASCII} 9210104862Srucharacter @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same 9211104862Sruas @code{\[aa]}, the acute accent. 9212104862Sru@endDefesc 9213104862Sru 9214104862Sru@Defesc {\\`, , , } 9215104862SruThis is a backslash followed by @acronym{ASCII} character @code{0x60} 9216104862Sru(@acronym{EBCDIC} character @code{0x79} usually). The same as 9217104862Sru@code{\[ga]}, the grave accent. 9218104862Sru@endDefesc 9219104862Sru 9220104862Sru@Defesc {\\-, , , } 9221104862SruThis is the same as @code{\[-]}, the minus sign in the current font. 9222104862Sru@endDefesc 9223104862Sru 922475584Sru@Defreq {cflags, n c1 c2 @dots{}} 9225104862Sru@cindex glyph properties (@code{cflags}) 9226104862Sru@cindex character properties (@code{cflags}) 9227104862Sru@cindex properties of glyphs (@code{cflags}) 9228104862Sru@cindex properties of characters (@code{cflags}) 9229104862SruInput characters and symbols have certain properties associated 9230104862Sruwith it.@footnote{Note that the output glyphs themselves don't have 9231104862Srusuch properties. For @code{gtroff}, a glyph is a numbered box with 9232104862Srua given width, depth, and height, nothing else. All manipulations 9233104862Sruwith the @code{cflags} request work on the input level.} These 9234104862Sruproperties can be modified with the @code{cflags} request. The 9235104862Srufirst argument is the sum of the desired flags and the remaining 9236104862Sruarguments are the characters or symbols to have those properties. 9237104862SruIt is possible to omit the spaces between the characters or symbols. 923869626Sru 923955839Sasmodai@table @code 924055839Sasmodai@item 1 9241104862Sru@cindex end-of-sentence characters 9242104862Sru@cindex characters, end-of-sentence 9243104862SruThe character ends sentences (initially characters @samp{.?!} have this 9244104862Sruproperty). 924569626Sru 924655839Sasmodai@item 2 924769626Sru@cindex hyphenating characters 924869626Sru@cindex characters, hyphenation 9249104862SruLines can be broken before the character (initially no characters have 9250104862Sruthis property). 925169626Sru 925255839Sasmodai@item 4 9253104862Sru@cindex @code{hy} glyph, and @code{cflags} 9254104862Sru@cindex @code{em} glyph, and @code{cflags} 9255104862SruLines can be broken after the character (initially the character 9256114402Sru@samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property). 925769626Sru 925855839Sasmodai@item 8 925969626Sru@cindex overlapping characters 926069626Sru@cindex characters, overlapping 9261104862Sru@cindex @code{ul} glyph, and @code{cflags} 9262104862Sru@cindex @code{rn} glyph, and @code{cflags} 9263104862Sru@cindex @code{ru} glyph, and @code{cflags} 9264114402Sru@cindex @code{radicalex} glyph, and @code{cflags} 9265114402Sru@cindex @code{sqrtex} glyph, and @code{cflags} 9266151497SruThe character overlaps horizontally if used as a horizontal line building 9267151497Sruelement. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]}, 9268151497Sru@samp{\[radicalex]}, and @samp{\[sqrtex]} have this property. 926969626Sru 927055839Sasmodai@item 16 9271104862Sru@cindex @code{br} glyph, and @code{cflags} 9272151497SruThe character overlaps vertically if used as vertical line building element. 9273151497SruInitially symbol @samp{\[br]} has this property. 927469626Sru 927555839Sasmodai@item 32 927669626Sru@cindex transparent characters 927769626Sru@cindex character, transparent 9278104862Sru@cindex @code{"}, at end of sentence 9279104862Sru@cindex @code{'}, at end of sentence 9280104862Sru@cindex @code{)}, at end of sentence 9281104862Sru@cindex @code{]}, at end of sentence 9282104862Sru@cindex @code{*}, at end of sentence 9283104862Sru@cindex @code{dg} glyph, at end of sentence 9284104862Sru@cindex @code{rq} glyph, at end of sentence 9285104862SruAn end-of-sentence character followed by any number of characters with 928675584Sruthis property is treated as the end of a sentence if followed by a 928775584Srunewline or two spaces; in other words the character is 9288104862Sru@dfn{transparent} for the purposes of end-of-sentence recognition -- 928975584Sruthis is the same as having a zero space factor in @TeX{} (initially 9290114402Srucharacters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have 9291114402Sruthis property). 929255839Sasmodai@end table 929375584Sru@endDefreq 929455839Sasmodai 9295104862Sru@DefreqList {char, g [@Var{string}]} 9296114402Sru@DefreqItem {fchar, g [@Var{string}]} 9297114402Sru@DefreqItem {fschar, f g [@Var{string}]} 9298114402Sru@DefreqListEnd {schar, g [@Var{string}]} 9299104862Sru@cindex defining character (@code{char}) 9300114402Sru@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar}) 9301104862Sru@cindex character, defining (@code{char}) 9302114402Sru@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar}) 9303114402Sru@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar}) 9304104862Sru@cindex creating new characters (@code{char}) 9305104862Sru@cindex defining symbol (@code{char}) 9306104862Sru@cindex symbol, defining (@code{char}) 9307104862Sru@cindex defining glyph (@code{char}) 9308104862Sru@cindex glyph, defining (@code{char}) 9309104862Sru@cindex escape character, while defining glyph 9310104862Sru@cindex character, escape, while defining glyph 9311104862Sru@cindex @code{tr} request, and glyph definitions 9312104862Sru@cindex @code{cp} request, and glyph definitions 9313104862Sru@cindex @code{rc} request, and glyph definitions 9314104862Sru@cindex @code{lc} request, and glyph definitions 9315104862Sru@cindex @code{\l}, and glyph definitions 9316104862Sru@cindex @code{\L}, and glyph definitions 9317104862Sru@cindex @code{\&}, and glyph definitions 9318104862Sru@cindex @code{\e}, and glyph definitions 9319104862Sru@cindex @code{hcode} request, and glyph definitions 9320114402SruDefine a new glyph@tie{}@var{g} to be @var{string} (which can be 9321104862Sruempty).@footnote{@code{char} is a misnomer since an output glyph is 9322114402Srudefined.} Every time glyph@tie{}@var{g} needs to be printed, 932375584Sru@var{string} is processed in a temporary environment and the result is 932475584Sruwrapped up into a single object. Compatibility mode is turned off and 932575584Sruthe escape character is set to @samp{\} while @var{string} is being 932675584Sruprocessed. Any emboldening, constant spacing or track kerning is 932769626Sruapplied to this object rather than to individual characters in 9328104862Sru@var{string}. 9329104862Sru 9330114402SruA glyph defined by these requests can be used just 9331104862Srulike a normal glyph provided by the output device. In particular, 9332104862Sruother characters can be translated to it with the @code{tr} or 9333104862Sru@code{trin} requests; it can be made the leader character by the 9334104862Sru@code{lc} request; repeated patterns can be drawn with the glyph 9335104862Sruusing the @code{\l} and @code{\L} escape sequences; words containing 9336104862Sruthe glyph can be hyphenated correctly if the @code{hcode} request 9337104862Sruis used to give the glyph's symbol a hyphenation code. 9338104862Sru 9339104862SruThere is a special anti-recursion feature: Use of @code{g} within 9340104862Sruthe glyph's definition is handled like normal characters and symbols 9341104862Srunot defined with @code{char}. 9342104862Sru 9343104862SruNote that the @code{tr} and @code{trin} requests take precedence if 9344104862Sru@code{char} accesses the same symbol. 9345104862Sru 9346104862Sru@Example 9347104862Sru.tr XY 9348104862SruX 9349104862Sru @result{} Y 9350104862Sru.char X Z 9351104862SruX 9352104862Sru @result{} Y 9353104862Sru.tr XX 9354104862SruX 9355104862Sru @result{} Z 9356104862Sru@endExample 9357104862Sru 9358104862SruThe @code{fchar} request defines a fallback glyph: 9359104862Sru@code{gtroff} only checks for glyphs defined with @code{fchar} 9360104862Sruif it cannot find the glyph in the current font. 9361104862Sru@code{gtroff} carries out this test before checking special fonts. 9362114402Sru 9363114402Sru@code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff} 9364114402Sruchecks for glyphs defined with @code{fschar} after the list of fonts 9365114402Srudeclared as font-specific special fonts with the @code{fspecial} request, 9366114402Srubut before the list of fonts declared as global special fonts with the 9367114402Sru@code{special} request. 9368114402Sru 9369114402SruFinally, the @code{schar} request defines a global fallback glyph: 9370114402Sru@code{gtroff} checks for glyphs defined with @code{schar} after the list 9371114402Sruof fonts declared as global special fonts with the @code{special} request, 9372114402Srubut before the already mounted special fonts. 9373114402Sru 9374114402Sru@xref{Using Symbols}, for a detailed description of the glyph 9375114402Srusearching mechanism in @code{gtroff}. 937675584Sru@endDefreq 937769626Sru 9378114402Sru@DefreqList {rchar, c1 c2 @dots{}} 9379114402Sru@DefreqListEnd {rfschar, f c1 c2 @dots{}} 9380114402Sru@cindex removing glyph definition (@code{rchar}, @code{rfschar}) 9381114402Sru@cindex glyph, removing definition (@code{rchar}, @code{rfschar}) 9382114402Sru@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar}) 9383114402SruRemove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{} 9384114402SruThis undoes the effect of a @code{char}, @code{fchar}, or 9385114402Sru@code{schar} request. 938655839Sasmodai 938775584SruIt is possible to omit the whitespace between arguments. 9388114402Sru 9389114402SruThe request @code{rfschar} removes glyph definitions defined with 9390114402Sru@code{fschar} for glyph@tie{}f. 939175584Sru@endDefreq 939275584Sru 939369626Sru@xref{Special Characters}. 939455839Sasmodai 939569626Sru@c --------------------------------------------------------------------- 939669626Sru 9397114402Sru@node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols 939875584Sru@subsection Special Fonts 939975584Sru@cindex special fonts 940075584Sru@cindex fonts, special 940175584Sru 9402104862SruSpecial fonts are those that @code{gtroff} searches 9403104862Sruwhen it cannot find the requested glyph in the current font. 9404104862SruThe Symbol font is usually a special font. 940575584Sru 9406104862Sru@code{gtroff} provides the following two requests to add more special 9407104862Srufonts. @xref{Using Symbols}, for a detailed description of the glyph 9408104862Srusearching mechanism in @code{gtroff}. 940975584Sru 9410104862SruUsually, only non-TTY devices have special fonts. 9411104862Sru 9412114402Sru@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]} 9413114402Sru@DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]} 9414104862Sru@kindex fonts 9415104862Sru@pindex DESC 9416114402SruUse the @code{special} request to define special fonts. Initially, this 9417114402Srulist is empty. 9418104862Sru 9419114402SruUse the @code{fspecial} request to designate special fonts only when 9420114402Srufont@tie{}@var{f} is active. Initially, this list is empty. 9421114402Sru 9422114402SruPrevious calls to @code{special} or @code{fspecial} are overwritten; 9423114402Sruwithout arguments, the particular list of special fonts is set to empty. 9424114402SruSpecial fonts are searched in the order they appear as arguments. 9425114402Sru 9426114402SruAll fonts which appear in a call to @code{special} or @code{fspecial} are 9427114402Sruloaded. 9428114402Sru 9429114402Sru@xref{Using Symbols}, for the exact search order of glyphs. 9430104862Sru@endDefreq 9431104862Sru 943275584Sru@c --------------------------------------------------------------------- 943375584Sru 9434114402Sru@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols 943555839Sasmodai@subsection Artificial Fonts 943655839Sasmodai@cindex artificial fonts 943755839Sasmodai@cindex fonts, artificial 943855839Sasmodai 9439104862SruThere are a number of requests and escapes for artificially creating 9440104862Srufonts. These are largely vestiges of the days when output devices 9441104862Srudid not have a wide variety of fonts, and when @code{nroff} and 9442104862Sru@code{troff} were separate programs. Most of them are no longer 9443104862Srunecessary in GNU @code{troff}. Nevertheless, they are supported. 944455839Sasmodai 9445104862Sru@DefescList {\\H, ', height, '} 9446114402Sru@DefescItem {\\H, ', @t{+}height, '} 9447114402Sru@DefescItem {\\H, ', @t{-}height, '} 9448114402Sru@DefregListEnd {.height} 9449104862Sru@cindex changing the font height (@code{\H}) 9450104862Sru@cindex font height, changing (@code{\H}) 9451104862Sru@cindex height, font, changing (@code{\H}) 9452104862SruChange (increment, decrement) the height of the current font, but not 9453104862Sruthe width. If @var{height} is zero, restore the original height. 9454104862SruDefault scaling indicator is @samp{z}. 9455104862Sru 9456114402SruThe read-only number register @code{.height} contains the font height as 9457114402Sruset by @code{\H}. 9458114402Sru 9459104862SruCurrently, only the @option{-Tps} device supports this feature. 9460104862Sru 9461104862SruNote that @code{\H} doesn't produce an input token in @code{gtroff}. 9462104862SruAs a consequence, it can be used in requests like @code{mc} (which 9463104862Sruexpects a single character as an argument) to change the font on 9464104862Sruthe fly: 9465104862Sru 9466104862Sru@Example 9467104862Sru.mc \H'+5z'x\H'0' 9468104862Sru@endExample 9469104862Sru 9470104862SruIn compatibility mode, @code{gtroff} behaves differently: If an 9471104862Sruincrement or decrement is used, it is always taken relative to the 9472104862Srucurrent point size and not relative to the previously selected font 9473104862Sruheight. Thus, 9474104862Sru 9475104862Sru@Example 9476104862Sru.cp 1 9477104862Sru\H'+5'test \H'+5'test 9478104862Sru@endExample 9479104862Sru 9480104862Sru@noindent 9481104862Sruprints the word @samp{test} twice with the same font height (five 9482104862Srupoints larger than the current font size). 9483104862Sru@endDefesc 9484104862Sru 9485104862Sru@DefescList {\\S, ', slant, '} 9486114402Sru@DefregListEnd {.slant} 9487104862Sru@cindex changing the font slant (@code{\S}) 9488104862Sru@cindex font slant, changing (@code{\S}) 9489104862Sru@cindex slant, font, changing (@code{\S}) 9490104862SruSlant the current font by @var{slant} degrees. Positive values slant 9491114402Sruto the right. Only integer values are possible. 9492104862Sru 9493114402SruThe read-only number register @code{.slant} contains the font slant as 9494114402Sruset by @code{\S}. 9495114402Sru 9496104862SruCurrently, only the @option{-Tps} device supports this feature. 9497104862Sru 9498104862SruNote that @code{\S} doesn't produce an input token in @code{gtroff}. 9499104862SruAs a consequence, it can be used in requests like @code{mc} (which 9500104862Sruexpects a single character as an argument) to change the font on 9501104862Sruthe fly: 9502104862Sru 9503104862Sru@Example 9504104862Sru.mc \S'20'x\S'0' 9505104862Sru@endExample 9506104862Sru 9507104862SruThis request is incorrectly documented in the original @acronym{UNIX} 9508104862Srutroff manual; the slant is always set to an absolute value. 9509104862Sru@endDefesc 9510104862Sru 951175584Sru@Defreq {ul, [@Var{lines}]} 9512104862Sru@cindex underlining (@code{ul}) 9513104862SruThe @code{ul} request normally underlines subsequent lines if a TTY 951475584Sruoutput device is used. Otherwise, the lines are printed in italics 951575584Sru(only the term `underlined' is used in the following). The single 951675584Sruargument is the number of input lines to be underlined; with no 951775584Sruargument, the next line is underlined. If @var{lines} is zero or 951875584Srunegative, stop the effects of @code{ul} (if it was active). Requests 951975584Sruand empty lines do not count for computing the number of underlined 952075584Sruinput lines, even if they produce some output like @code{tl}. Lines 952175584Sruinserted by macros (e.g.@: invoked by a trap) do count. 952255839Sasmodai 952375584SruAt the beginning of @code{ul}, the current font is stored and the 952475584Sruunderline font is activated. Within the span of a @code{ul} request, 952575584Sruit is possible to change fonts, but after the last line affected by 952675584Sru@code{ul} the saved font is restored. 952775584Sru 9528104862SruThis number of lines still to be underlined is associated with the 9529104862Srucurrent environment (@pxref{Environments}). The underline font can be 9530104862Sruchanged with the @code{uf} request. 953175584Sru 953275584Sru@c XXX @xref should be changed to grotty 953375584Sru 9534104862Sru@c @xref{Troff and Nroff Mode}, for a discussion how underlining is 9535104862Sru@c implemented in for TTY output devices, and which problems can arise. 953675584Sru 953775584SruThe @code{ul} request does not underline spaces. 953875584Sru@endDefreq 953975584Sru 954075584Sru@Defreq {cu, [@Var{lines}]} 9541104862Sru@cindex continuous underlining (@code{cu}) 9542104862Sru@cindex underlining, continuous (@code{cu}) 954375584SruThe @code{cu} request is similar to @code{ul} but underlines spaces as 9544104862Sruwell (if a TTY output device is used). 954575584Sru@endDefreq 954655839Sasmodai 954775584Sru@Defreq {uf, font} 9548104862Sru@cindex underline font (@code{uf}) 9549104862Sru@cindex font for underlining (@code{uf}) 955075584SruSet the underline font (globally) used by @code{ul} and @code{cu}. By 9551114402Srudefault, this is the font at position@tie{}2. @var{font} can be either 955275584Srua non-negative font position or the name of a font. 955375584Sru@endDefreq 955455839Sasmodai 9555104862Sru@DefreqList {bd, font [@Var{offset}]} 9556104862Sru@DefreqItem {bd, font1 font2 [@Var{offset}]} 9557104862Sru@DefregListEnd {.b} 9558104862Sru@cindex imitating bold face (@code{bd}) 9559104862Sru@cindex bold face, imitating (@code{bd}) 9560104862SruArtificially create a bold font by printing each glyph twice, 956175584Sruslightly offset. 956255839Sasmodai 956375584SruTwo syntax forms are available. 956475584Sru 956575584Sru@itemize @bullet 956675584Sru@item 956775584SruImitate a bold font unconditionally. The first argument specifies the 956875584Srufont to embolden, and the second is the number of basic units, minus 9569104862Sruone, by which the two glyphs are offset. If the second argument is 957075584Srumissing, emboldening is turned off. 957175584Sru 957275584Sru@var{font} can be either a non-negative font position or the name of a 957375584Srufont. 957475584Sru 957575584Sru@var{offset} is available in the @code{.b} read-only register if a 957675584Sruspecial font is active; in the @code{bd} request, its default unit is 957775584Sru@samp{u}. 957875584Sru 9579104862Sru@cindex @code{fspecial} request, and imitating bold 958075584Sru@kindex special 958175584Sru@cindex embolding of special fonts 958275584Sru@cindex special fonts, emboldening 958375584Sru@item 958475584SruImitate a bold form conditionally. Embolden @var{font1} by 958575584Sru@var{offset} only if font @var{font2} is the current font. This 958675584Srucommand can be issued repeatedly to set up different emboldening 958775584Sruvalues for different current fonts. If the second argument is 958875584Srumissing, emboldening is turned off for this particular current font. 958975584Sru 959075584SruThis affects special fonts only (either set up with the @code{special} 959175584Srucommand in font files or with the @code{fspecial} request). 959275584Sru@end itemize 959375584Sru@endDefreq 959475584Sru 959575584Sru@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 9596104862Sru@cindex constant glyph space mode (@code{cs}) 9597104862Sru@cindex mode for constant glyph space (@code{cs}) 9598104862Sru@cindex glyph, constant space 9599104862Sru@cindex @code{ps} request, and constant glyph space mode 9600104862SruSwitch to and from @dfn{constant glyph space mode}. If activated, the 9601104862Sruwidth of every glyph is @math{@var{width}/36} ems. The em size is 960275584Srugiven absolutely by @var{em-size}; if this argument is missing, the em 960375584Sruvalue is taken from the current font size (as set with the @code{ps} 960475584Srurequest) when the font is effectively in use. Without second and 9605104862Sruthird argument, constant glyph space mode is deactivated. 960675584Sru 9607104862SruDefault scaling indicator for @var{em-size} is @samp{z}; @var{width} is 9608104862Sruan integer. 960975584Sru@endDefreq 961075584Sru 961169626Sru@c --------------------------------------------------------------------- 961255839Sasmodai 9613114402Sru@node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols 961455839Sasmodai@subsection Ligatures and Kerning 961555839Sasmodai@cindex ligatures and kerning 961655839Sasmodai@cindex kerning and ligatures 961755839Sasmodai 9618104862SruLigatures are groups of characters that are run together, i.e, producing 9619104862Srua single glyph. For example, the letters `f' and `i' can form a 9620104862Sruligature `fi' as in the word `file'. This produces a cleaner look 9621104862Sru(albeit subtle) to the printed output. Usually, ligatures are not 9622104862Sruavailable in fonts for TTY output devices. 962355839Sasmodai 962475584SruMost @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 9625104862Srutypesetter that was the target of @acronym{AT&T} @code{troff} also 9626104862Srusupported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or 9627104862Sru`expert' fonts may include ligatures for `ft' and `ct', although GNU 962875584Sru@code{troff} does not support these (yet). 962969626Sru 9630114402SruOnly the current font is checked for ligatures and kerns; neither special 9631114402Srufonts nor entities defined with the @code{char} request (and its siblings) 9632114402Sruare taken into account. 9633114402Sru 9634104862Sru@DefreqList {lg, [@Var{flag}]} 9635104862Sru@DefregListEnd {.lg} 9636104862Sru@cindex activating ligatures (@code{lg}) 9637104862Sru@cindex ligatures, activating (@code{lg}) 9638104862Sru@cindex ligatures enabled register (@code{.lg}) 9639104862SruSwitch the ligature mechanism on or off; if the parameter is non-zero 9640104862Sruor missing, ligatures are enabled, otherwise disabled. Default is on. 9641104862SruThe current ligature mode can be found in the read-only number register 9642114402Sru@code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise). 964355839Sasmodai 9644114402SruSetting the ligature mode to@tie{}2 enables the two-character ligatures 964575584Sru(fi, fl, and ff) and disables the three-character ligatures (ffi and 964675584Sruffl). 964775584Sru@endDefreq 964855839Sasmodai 964975584Sru@dfn{Pairwise kerning} is another subtle typesetting mechanism that 9650104862Srumodifies the distance between a glyph pair to improve readability. 965175584SruIn most cases (but not always) the distance is decreased. 9652151497Sru@iftex 965375584SruFor example, compare the combination of the letters `V' and `A'. With 965475584Srukerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 9655151497Sru@end iftex 9656104862SruTypewriter-like fonts and fonts for terminals where all glyphs 965775584Sruhave the same width don't use kerning. 965869626Sru 9659104862Sru@DefreqList {kern, [@Var{flag}]} 9660104862Sru@DefregListEnd {.kern} 9661104862Sru@cindex activating kerning (@code{kern}) 9662104862Sru@cindex kerning, activating (@code{kern}) 9663104862Sru@cindex kerning enabled register (@code{.kern}) 9664104862SruSwitch kerning on or off. If the parameter is non-zero or missing, 9665104862Sruenable pairwise kerning, otherwise disable it. The read-only number 9666114402Sruregister @code{.kern} is set to@tie{}1 if pairwise kerning is enabled, 9667114402Sru0@tie{}otherwise. 966875584Sru 9669104862Sru@cindex zero width space character (@code{\&}) 9670104862Sru@cindex character, zero width space (@code{\&}) 9671104862Sru@cindex space character, zero width (@code{\&}) 967255839SasmodaiIf the font description file contains pairwise kerning information, 9673104862Sruglyphs from that font are kerned. Kerning between two glyphs 967475584Srucan be inhibited by placing @code{\&} between them: @samp{V\&A}. 967555839Sasmodai 967675584Sru@xref{Font File Format}. 967775584Sru@endDefreq 967855839Sasmodai 967969626Sru@cindex track kerning 968069626Sru@cindex kerning, track 9681104862Sru@dfn{Track kerning} expands or reduces the space between glyphs. 968275584SruThis can be handy, for example, if you need to squeeze a long word 968375584Sruonto a single line or spread some text to fill a narrow column. It 968475584Srumust be used with great care since it is usually considered bad 968575584Srutypography if the reader notices the effect. 968669626Sru 968775584Sru@Defreq {tkf, f s1 n1 s2 n2} 9688104862Sru@cindex activating track kerning (@code{tkf}) 9689104862Sru@cindex track kerning, activating (@code{tkf}) 9690114402SruEnable track kerning for font@tie{}@var{f}. If the current font 9691114402Sruis@tie{}@var{f} the width of every glyph is increased by an amount 969275584Srubetween @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 969375584Sruthe current point size is less than or equal to @var{s1} the width is 969475584Sruincreased by @var{n1}; if it is greater than or equal to @var{s2} the 969575584Sruwidth is increased by @var{n2}; if the point size is greater than or 969675584Sruequal to @var{s1} and less than or equal to @var{s2} the increase in 969775584Sruwidth is a linear function of the point size. 969869626Sru 9699104862SruThe default scaling indicator is @samp{z} for @var{s1} and @var{s2}, 9700104862Sru@samp{p} for @var{n1} and @var{n2}. 9701104862Sru 9702104862SruNote that the track kerning amount is added even to the rightmost glyph 9703104862Sruin a line; for large values it is thus recommended to increase the line 9704104862Srulength by the same amount to compensate it. 970575584Sru@endDefreq 970669626Sru 970775584SruSometimes, when typesetting letters of different fonts, more or less 970875584Sruspace at such boundaries are needed. There are two escapes to help 970975584Sruwith this. 971069626Sru 971175584Sru@Defesc {\\/, , , } 9712104862Sru@cindex italic correction (@code{\/}) 9713104862Sru@cindex correction, italic (@code{\/}) 9714104862Sru@cindex correction between italic and roman glyph (@code{\/}, @code{\,}) 9715104862Sru@cindex roman glyph, correction after italic glyph (@code{\/}) 9716104862Sru@cindex italic glyph, correction before roman glyph (@code{\/}) 9717104862Sru@cindex glyph, italic correction (@code{\/}) 9718104862SruIncrease the width of the preceding glyph so that the spacing 9719104862Srubetween that glyph and the following glyph is correct if the 9720104862Srufollowing glyph is a roman glyph. For example, if an 9721114402Sruitalic@tie{}@code{f} is immediately followed by a roman right 9722114402Sruparenthesis, then in many fonts the top right portion of the@tie{}@code{f} 972375584Sruoverlaps the top left of the right parenthesis. Use this escape 9724104862Srusequence whenever an italic glyph is immediately followed by a 9725104862Sruroman glyph without any intervening space. This small amount of 972675584Sruspace is also called @dfn{italic correction}. 972775584Sru 972875584Sru@iftex 9729151497Sru@c can't use @Example...@endExample here 973069626Sru@example 973175584Sru@group 973275584Sru\f[I]f\f[R]) 973375584Sru @result{} {@it f}@r{)} 973475584Sru\f[I]f\/\f[R]) 973575584Sru @result{} @i{f}@r{)} 973675584Sru@end group 973769626Sru@end example 973875584Sru@end iftex 973975584Sru@endDefesc 974069626Sru 974175584Sru@Defesc {\\\,, , , } 9742104862Sru@cindex left italic correction (@code{\,}) 9743104862Sru@cindex correction, left italic (@code{\,}) 9744104862Sru@cindex glyph, left italic correction (@code{\,}) 9745104862Sru@cindex roman glyph, correction before italic glyph (@code{\,}) 9746104862Sru@cindex italic glyph, correction after roman glyph (@code{\,}) 9747104862SruModify the spacing of the following glyph so that the spacing 9748104862Srubetween that glyph and the preceding glyph is correct if the 9749104862Srupreceding glyph is a roman glyph. Use this escape sequence 9750104862Sruwhenever a roman glyph is immediately followed by an italic 9751104862Sruglyph without any intervening space. In analogy to above, this 975275584Sruspace could be called @dfn{left italic correction}, but this term 975375584Sruisn't used widely. 975455839Sasmodai 975575584Sru@iftex 9756151497Sru@c can't use @Example...@endExample here 975775584Sru@example 975875584Sru@group 975975584Sruq\f[I]f 976075584Sru @result{} @r{q}@i{f} 976175584Sruq\,\f[I]f 976275584Sru @result{} @r{q}@math{@ptexcomma}@i{f} 976375584Sru@end group 976475584Sru@end example 976575584Sru@end iftex 976675584Sru@endDefesc 976755839Sasmodai 976875584Sru@Defesc {\\&, , , } 976975584SruInsert a zero-width character, which is invisible. Its intended use 977075584Sruis to stop interaction of a character with its surrounding. 977175584Sru 977275584Sru@itemize @bullet 977375584Sru@item 9774104862SruIt prevents the insertion of extra space after an end-of-sentence 977575584Srucharacter. 977675584Sru 977775584Sru@Example 977875584SruTest. 977975584SruTest. 978075584Sru @result{} Test. Test. 978175584SruTest.\& 978275584SruTest. 978375584Sru @result{} Test. Test. 978475584Sru@endExample 978575584Sru 978675584Sru@item 978775584SruIt prevents interpretation of a control character at the beginning of 978875584Sruan input line. 978975584Sru 979075584Sru@Example 979175584Sru.Test 979275584Sru @result{} warning: `Test' not defined 979375584Sru\&.Test 979475584Sru @result{} .Test 979575584Sru@endExample 979675584Sru 979775584Sru@item 9798104862SruIt prevents kerning between two glyphs. 979975584Sru 9800151497Sru@iftex 9801151497Sru@c can't use @Example...@endExample here 980275584Sru@example 980375584Sru@group 980475584SruVA 980575584Sru @result{} @r{VA} 980675584SruV\&A 980775584Sru @result{} @r{V@w{}A} 980875584Sru@end group 980975584Sru@end example 9810151497Sru@end iftex 981175584Sru 981275584Sru@item 981375584SruIt is needed to map an arbitrary character to nothing in the @code{tr} 981475584Srurequest (@pxref{Character Translations}). 981575584Sru@end itemize 981675584Sru@endDefesc 981775584Sru 9818104862Sru@Defesc {\\), , , } 9819104862SruThis escape is similar to @code{\&} except that it behaves like a 9820104862Srucharacter declared with the @code{cflags} request to be transparent 9821104862Srufor the purposes of an end-of-sentence character. 982275584Sru 9823104862SruIts main usage is in macro definitions to protect against arguments 9824104862Srustarting with a control character. 9825104862Sru 9826104862Sru@Example 9827104862Sru.de xxx 9828104862Sru\)\\$1 9829104862Sru.. 9830104862Sru.de yyy 9831104862Sru\&\\$1 9832104862Sru.. 9833104862SruThis is a test.\c 9834104862Sru.xxx ' 9835104862SruThis is a test. 9836104862Sru @result{}This is a test.' This is a test. 9837104862SruThis is a test.\c 9838104862Sru.yyy ' 9839104862SruThis is a test. 9840104862Sru @result{}This is a test.' This is a test. 9841104862Sru@endExample 9842104862Sru@endDefesc 9843104862Sru 9844104862Sru 984569626Sru@c ===================================================================== 984669626Sru 9847114402Sru@node Sizes, Strings, Fonts and Symbols, gtroff Reference 984855839Sasmodai@section Sizes 984955839Sasmodai@cindex sizes 985055839Sasmodai 985155839Sasmodai@cindex baseline 985269626Sru@cindex type size 985369626Sru@cindex size of type 985469626Sru@cindex vertical spacing 985569626Sru@cindex spacing, vertical 985675584Sru@code{gtroff} uses two dimensions with each line of text, type size 985775584Sruand vertical spacing. The @dfn{type size} is approximately the height 9858104862Sruof the tallest glyph.@footnote{This is usually the parenthesis. 985975584SruNote that in most cases the real dimensions of the glyphs in a font 986075584Sruare @emph{not} related to its type size! For example, the standard 986175584Sru@sc{PostScript} font families `Times Roman', `Helvetica', and 986275584Sru`Courier' can't be used together at 10@dmn{pt}; to get acceptable 986375584Sruoutput, the size of `Helvetica' has to be reduced by one point, and 986475584Sruthe size of `Courier' must be increased by one point.} @dfn{Vertical 986575584Sruspacing} is the amount of space @code{gtroff} allows for a line of 9866114402Srutext; normally, this is about 20%@tie{}larger than the current type 986775584Srusize. Ratios smaller than this can result in hard-to-read text; 986875584Srularger than this, it spreads the text out more vertically (useful for 9869114402Sruterm papers). By default, @code{gtroff} uses 10@tie{}point type on 9870114402Sru12@tie{}point spacing. 987155839Sasmodai 987255839Sasmodai@cindex leading 987355839SasmodaiThe difference between type size and vertical spacing is known, by 9874104862Srutypesetters, as @dfn{leading} (this is pronounced `ledding'). 987555839Sasmodai 987655839Sasmodai@menu 987775584Sru* Changing Type Sizes:: 987875584Sru* Fractional Type Sizes:: 987955839Sasmodai@end menu 988055839Sasmodai 988169626Sru@c --------------------------------------------------------------------- 988269626Sru 988355839Sasmodai@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 988455839Sasmodai@subsection Changing Type Sizes 988555839Sasmodai 9886104862Sru@DefreqList {ps, [@Var{size}]} 9887104862Sru@DefreqItem {ps, @t{+}@Var{size}} 9888104862Sru@DefreqItem {ps, @t{-}@Var{size}} 9889104862Sru@DefescItem {\\s, , size, } 9890104862Sru@DefregListEnd {.s} 9891104862Sru@cindex changing type sizes (@code{ps}, @code{\s}) 9892104862Sru@cindex type sizes, changing (@code{ps}, @code{\s}) 9893104862Sru@cindex point sizes, changing (@code{ps}, @code{\s}) 989475584SruUse the @code{ps} request or the @code{\s} escape to change (increase, 989575584Srudecrease) the type size (in points). Specify @var{size} as either an 989675584Sruabsolute point size, or as a relative change from the current size. 9897114402SruThe size@tie{}0, or no argument, goes back to the previous size. 989855839Sasmodai 9899104862SruDefault scaling indicator of @code{size} is @samp{z}. If @code{size} 9900104862Sruis zero or negative, it is set to 1@dmn{u}. 990155839Sasmodai 9902104862Sru@cindex type size registers (@code{.s}, @code{.ps}) 9903104862Sru@cindex point size registers (@code{.s}, @code{.ps}) 990475584SruThe read-only number register @code{.s} returns the point size in 990575584Srupoints as a decimal fraction. This is a string. To get the point 990675584Srusize in scaled points, use the @code{.ps} register instead. 990775584Sru 990875584Sru@code{.s} is associated with the current environment 990975584Sru(@pxref{Environments}). 991075584Sru 991175584Sru@Example 991255839Sasmodaisnap, snap, 991355839Sasmodai.ps +2 991455839Sasmodaigrin, grin, 991555839Sasmodai.ps +2 991655839Sasmodaiwink, wink, \s+2nudge, nudge,\s+8 say no more! 991755839Sasmodai.ps 10 991875584Sru@endExample 991955839Sasmodai 992069626SruThe @code{\s} escape may be called in a variety of ways. Much like 992169626Sruother escapes there must be a way to determine where the argument ends 992269626Sruand the text begins. Any of the following forms are valid: 992355839Sasmodai 992469626Sru@table @code 992569626Sru@item \s@var{n} 9926114402SruSet the point size to @var{n}@tie{}points. @var{n}@tie{}must be either 9927114402Sru0 or in the range 4 to@tie{}39. 992869626Sru 992969626Sru@item \s+@var{n} 993069626Sru@itemx \s-@var{n} 9931114402SruIncrease or decrease the point size by @var{n}@tie{}points. 9932114402Sru@var{n}@tie{}must be exactly one digit. 993369626Sru 993469626Sru@item \s(@var{nn} 9935114402SruSet the point size to @var{nn}@tie{}points. @var{nn} must be exactly 993675584Srutwo digits. 993769626Sru 993869626Sru@item \s+(@var{nn} 993969626Sru@itemx \s-(@var{nn} 994069626Sru@itemx \s(+@var{nn} 994169626Sru@itemx \s(-@var{nn} 9942114402SruIncrease or decrease the point size by @var{nn}@tie{}points. @var{nn} 994375584Srumust be exactly two digits. 994469626Sru@end table 994569626Sru 9946104862SruNote that @code{\s} doesn't produce an input token in @code{gtroff}. 9947104862SruAs a consequence, it can be used in requests like @code{mc} (which 9948104862Sruexpects a single character as an argument) to change the font on 9949104862Sruthe fly: 9950104862Sru 9951104862Sru@Example 9952104862Sru.mc \s[20]x\s[0] 9953104862Sru@endExample 9954104862Sru 995575584Sru@xref{Fractional Type Sizes}, for yet another syntactical form of 995675584Sruusing the @code{\s} escape. 9957104862Sru@endDefreq 995869626Sru 9959104862Sru@Defreq {sizes, s1 s2 @dots{} sn [0]} 996055839SasmodaiSome devices may only have certain permissible sizes, in which case 996175584Sru@code{gtroff} rounds to the nearest permissible size. 9962104862SruThe @file{DESC} file specifies which sizes are permissible for the device. 9963104862Sru 9964104862SruUse the @code{sizes} request to change the permissible sizes 9965104862Srufor the current output device. 9966104862SruArguments are in scaled points; 9967104862Sruthe @code{sizescale} line in the 9968104862Sru@file{DESC} file for the output device 9969104862Sruprovides the scaling factor. 9970104862SruFor example, if the scaling factor is 1000, 9971114402Sruthen the value 12000 is 12@tie{}points. 9972104862Sru 9973104862SruEach argument can be a single point size (such as @samp{12000}), 9974104862Sruor a range of sizes (such as @samp{4000-72000}). 9975104862SruYou can optionally end the list with a zero. 997675584Sru@endDefreq 997755839Sasmodai 9978104862Sru@DefreqList {vs, [@Var{space}]} 9979104862Sru@DefreqItem {vs, @t{+}@Var{space}} 9980104862Sru@DefreqItem {vs, @t{-}@Var{space}} 9981104862Sru@DefregListEnd {.v} 9982104862Sru@cindex changing vertical line spacing (@code{vs}) 9983104862Sru@cindex vertical line spacing, changing (@code{vs}) 9984104862Sru@cindex vertical line spacing register (@code{.v}) 998575584SruChange (increase, decrease) the vertical spacing by @var{space}. The 9986104862Srudefault scaling indicator is @samp{p}. 998775584Sru 998875584SruIf @code{vs} is called without an argument, the vertical spacing is 998975584Srureset to the previous value before the last call to @code{vs}. 999075584Sru 9991104862Sru@cindex @code{.V} register, and @code{vs} 999275584Sru@code{gtroff} creates a warning of type @samp{range} if @var{space} is 9993151497Srunegative; the vertical spacing is then set to smallest positive value, 9994151497Sruthe vertical resolution (as given in the @code{.V} register). 999575584Sru 9996151497SruNote that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't 9997151497Sruresult in a vertical motion. You explicitly have to repeat this command 9998151497Srubefore inserting the diversion. 9999151497Sru 1000075584SruThe read-only number register @code{.v} contains the current vertical 1000175584Sruspacing; it is associated with the current environment 1000275584Sru(@pxref{Environments}). 1000375584Sru@endDefreq 1000475584Sru 10005104862Sru@cindex vertical line spacing, effective value 10006151497SruThe effective vertical line spacing consists of four components. Breaking 10007151497Srua line causes the following actions (in the given order). 1000869626Sru 10009104862Sru@itemize @bullet 10010104862Sru@item 10011151497Sru@cindex extra pre-vertical line space (@code{\x}) 10012151497Sru@cindex line space, extra pre-vertical (@code{\x}) 10013151497SruMove the current point vertically by the @dfn{extra pre-vertical line 10014151497Sruspace}. This is the minimum value of all @code{\x} escapes with a 10015151497Srunegative argument in the current output line. 1001655839Sasmodai 10017104862Sru@item 10018151497SruMove the current point vertically by the vertical line spacing as set with 10019151497Sruthe @code{vs} request. 10020104862Sru 10021104862Sru@item 10022151497SruOutput the current line. 10023104862Sru 10024151497Sru@item 10025104862Sru@cindex extra post-vertical line space (@code{\x}) 10026104862Sru@cindex line space, extra post-vertical (@code{\x}) 10027151497SruMove the current point vertically by the @dfn{extra post-vertical line 10028151497Sruspace}. This is the maximum value of all @code{\x} escapes with a 10029151497Srupositive argument in the line which has just been output. 10030151497Sru 10031104862Sru@item 10032151497Sru@cindex post-vertical line spacing 10033151497Sru@cindex line spacing, post-vertical (@code{pvs}) 10034151497SruMove the current point vertically by the @dfn{post-vertical line spacing} 10035151497Sruas set with the @code{pvs} request. 10036104862Sru@end itemize 10037104862Sru 10038104862Sru@cindex double-spacing (@code{vs}, @code{pvs}) 10039104862SruIt is usually better to use @code{vs} or @code{pvs} instead of @code{ls} 10040104862Sruto produce double-spaced documents: @code{vs} and @code{pvs} have a finer 10041104862Srugranularity for the inserted vertical space compared to @code{ls}; 10042104862Srufurthermore, certain preprocessors assume single-spacing. 10043104862Sru 10044104862Sru@xref{Manipulating Spacing}, for more details on the @code{\x} escape 10045104862Sruand the @code{ls} request. 10046104862Sru 10047104862Sru@DefreqList {pvs, [@Var{space}]} 10048104862Sru@DefreqItem {pvs, @t{+}@Var{space}} 10049104862Sru@DefreqItem {pvs, @t{-}@Var{space}} 10050104862Sru@DefregListEnd {.pvs} 10051104862Sru@cindex @code{ls} request, alternative to (@code{pvs}) 10052104862Sru@cindex post-vertical line spacing, changing (@code{pvs}) 10053104862Sru@cindex post-vertical line spacing register (@code{.pvs}) 10054104862SruChange (increase, decrease) the post-vertical spacing by 10055104862Sru@var{space}. The default scaling indicator is @samp{p}. 10056104862Sru 10057104862SruIf @code{pvs} is called without an argument, the post-vertical spacing is 10058104862Srureset to the previous value before the last call to @code{pvs}. 10059104862Sru 10060104862Sru@code{gtroff} creates a warning of type @samp{range} if @var{space} is 10061104862Sruzero or negative; the vertical spacing is then set to zero. 10062104862Sru 10063104862SruThe read-only number register @code{.pvs} contains the current 10064104862Srupost-vertical spacing; it is associated with the current environment 10065104862Sru(@pxref{Environments}). 10066104862Sru@endDefreq 10067104862Sru 1006869626Sru@c --------------------------------------------------------------------- 1006969626Sru 1007055839Sasmodai@node Fractional Type Sizes, , Changing Type Sizes, Sizes 1007155839Sasmodai@subsection Fractional Type Sizes 1007255839Sasmodai@cindex fractional type sizes 10073104862Sru@cindex fractional point sizes 1007455839Sasmodai@cindex type sizes, fractional 10075104862Sru@cindex point sizes, fractional 10076104862Sru@cindex sizes, fractional 1007755839Sasmodai 1007869626Sru@cindex @code{s} unit 1007969626Sru@cindex unit, @code{s} 1008069626Sru@cindex @code{z} unit 1008169626Sru@cindex unit, @code{z} 10082104862Sru@cindex @code{ps} request, with fractional type sizes 10083104862Sru@cindex @code{cs} request, with fractional type sizes 10084104862Sru@cindex @code{tkf} request, with fractional type sizes 10085104862Sru@cindex @code{\H}, with fractional type sizes 10086104862Sru@cindex @code{\s}, with fractional type sizes 1008775584SruA @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 10088114402Sruwhere @var{sizescale} is specified in the @file{DESC} file (1@tie{}by 1008975584Srudefault). There is a new scale indicator @samp{z} which has the 1009075584Srueffect of multiplying by @var{sizescale}. Requests and escape 1009175584Srusequences in @code{gtroff} interpret arguments that represent a point 1009275584Srusize as being in units of scaled points, but they evaluate each such 1009375584Sruargument using a default scale indicator of @samp{z}. Arguments 1009475584Srutreated in this way are the argument to the @code{ps} request, the 1009575584Sruthird argument to the @code{cs} request, the second and fourth 1009675584Sruarguments to the @code{tkf} request, the argument to the @code{\H} 1009775584Sruescape sequence, and those variants of the @code{\s} escape sequence 1009875584Sruthat take a numeric expression as their argument (see below). 1009955839Sasmodai 10100114402SruFor example, suppose @var{sizescale} is@tie{}1000; then a scaled point 1010175584Sruis equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 1010269626Sruequivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 10103114402Sru10250@tie{}scaled points, which is equal to 10.25@tie{}points. 1010455839Sasmodai 1010575584Sru@code{gtroff} disallows the use of the @samp{z} scale indicator in 1010675584Sruinstances where it would make no sense, such as a numeric 1010769626Sruexpression whose default scale indicator was neither @samp{u} nor 1010875584Sru@samp{z}. Similarly it would make 1010955839Sasmodaino sense to use a scaling indicator other than @samp{z} or @samp{u} in a 1011055839Sasmodainumeric expression whose default scale indicator was @samp{z}, and so 1011169626Sru@code{gtroff} disallows this as well. 1011255839Sasmodai 1011355839SasmodaiThere is also new scale indicator @samp{s} which multiplies by the 1011469626Srunumber of units in a scaled point. So, for example, @samp{\n[.ps]s} is 1011569626Sruequal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 1011655839Sasmodaiscale indicators. 1011755839Sasmodai 1011875584Sru@Defreg {.ps} 1011975584SruA read-only number register returning the point size in scaled points. 1012069626Sru 1012175584Sru@code{.ps} is associated with the current environment 1012275584Sru(@pxref{Environments}). 1012375584Sru@endDefreg 1012475584Sru 10125104862Sru@DefregList {.psr} 10126104862Sru@DefregListEnd {.sr} 10127104862Sru@cindex last-requested point size registers (@code{.psr}, @code{.sr}) 10128104862Sru@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) 10129104862Sru@cindex @code{.ps} register, in comparison with @code{.psr} 10130104862Sru@cindex @code{.s} register, in comparison with @code{.sr} 1013169626SruThe last-requested point size in scaled points is contained in the 1013275584Sru@code{.psr} read-only number register. The last requested point size 1013375584Sruin points as a decimal fraction can be found in @code{.sr}. This is a 1013475584Srustring-valued read-only number register. 1013569626Sru 1013675584SruNote that the requested point sizes are device-independent, whereas 1013775584Sruthe values returned by the @code{.ps} and @code{.s} registers are not. 10138104862SruFor example, if a point size of 11@dmn{pt} is requested, and a 10139104862Sru@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file) 10140104862Sruspecifies 10.95@dmn{pt} instead, this value is actually used. 1014175584Sru 1014275584SruBoth registers are associated with the current environment 1014375584Sru(@pxref{Environments}). 1014475584Sru@endDefreg 1014575584Sru 1014675584SruThe @code{\s} escape has the following syntax for working with 1014775584Srufractional type sizes: 1014875584Sru 1014969626Sru@table @code 1015069626Sru@item \s[@var{n}] 1015169626Sru@itemx \s'@var{n}' 10152114402SruSet the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric 1015355839Sasmodaiexpression with a default scale indicator of @samp{z}. 1015455839Sasmodai 1015569626Sru@item \s[+@var{n}] 1015669626Sru@itemx \s[-@var{n}] 1015769626Sru@itemx \s+[@var{n}] 1015869626Sru@itemx \s-[@var{n}] 1015969626Sru@itemx \s'+@var{n}' 1016069626Sru@itemx \s'-@var{n}' 1016169626Sru@itemx \s+'@var{n}' 1016269626Sru@itemx \s-'@var{n}' 10163114402SruIncrease or or decrease the point size by @var{n}@tie{}scaled points; 10164114402Sru@var{n}@tie{}is a numeric expression with a default scale indicator of 1016569626Sru@samp{z}. 1016669626Sru@end table 1016755839Sasmodai 1016869626Sru@xref{Font Files}. 1016955839Sasmodai 1017055839Sasmodai 1017169626Sru@c ===================================================================== 1017255839Sasmodai 1017375584Sru@node Strings, Conditionals and Loops, Sizes, gtroff Reference 1017455839Sasmodai@section Strings 1017555839Sasmodai@cindex strings 1017655839Sasmodai 1017769626Sru@code{gtroff} has string variables, which are entirely for user 1017875584Sruconvenience (i.e.@: there are no built-in strings exept @code{.T}, but 1017975584Srueven this is a read-write string variable). 1018055839Sasmodai 10181104862Sru@DefreqList {ds, name [@Var{string}]} 10182104862Sru@DefreqItem {ds1, name [@Var{string}]} 10183104862Sru@DefescItem {\\*, , n, } 10184151497Sru@DefescItem {\\*, @Lparen{}, nm, } 10185151497Sru@DefescListEnd {\\*, @Lbrack{}, name arg1 arg2 @dots{}, @Rbrack{}} 10186104862Sru@cindex string interpolation (@code{\*}) 10187104862Sru@cindex string expansion (@code{\*}) 10188104862Sru@cindex interpolation of strings (@code{\*}) 10189104862Sru@cindex expansion of strings (@code{\*}) 10190104862Sru@cindex string arguments 10191104862Sru@cindex arguments, of strings 10192114402SruDefine and access a string variable @var{name} (one-character 10193114402Sruname@tie{}@var{n}, two-character name @var{nm}). If @var{name} already 10194114402Sruexists, @code{ds} overwrites the previous definition. Only the syntax form 10195104862Sruusing brackets can take arguments which are handled identically to 10196104862Srumacro arguments; the single exception is that a closing bracket as an 10197114402Sruargument must be enclosed in double quotes. @xref{Request and Macro 10198114402SruArguments}, and @ref{Parameters}. 1019955839Sasmodai 1020075584SruExample: 1020175584Sru 1020275584Sru@Example 10203104862Sru.ds foo a \\$1 test 1020475584Sru. 10205104862SruThis is \*[foo nice]. 10206104862Sru @result{} This is a nice test. 1020775584Sru@endExample 1020855839Sasmodai 1020975584SruThe @code{\*} escape @dfn{interpolates} (expands in-place) a 1021075584Srupreviously-defined string variable. To be more precise, the stored 1021175584Srustring is pushed onto the input stack which is then parsed by 1021275584Sru@code{gtroff}. Similar to number registers, it is possible to nest 10213104862Srustrings, i.e. string variables can be called within string variables. 1021455839Sasmodai 10215104862SruIf the string named by the @code{\*} escape does not exist, it is 10216104862Srudefined as empty, and a warning of type @samp{mac} is emitted (see 1021775584Sru@ref{Debugging}, for more details). 1021875584Sru 1021955839Sasmodai@cindex comments, with @code{ds} 10220104862Sru@cindex @code{ds} request, and comments 1022169626Sru@strong{Caution:} Unlike other requests, the second argument to the 1022269626Sru@code{ds} request takes up the entire line including trailing spaces. 1022369626SruThis means that comments on a line with such a request can introduce 1022469626Sruunwanted space into a string. 1022555839Sasmodai 1022675584Sru@Example 1022769626Sru.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 1022875584Sru@endExample 1022955839Sasmodai 1023069626Sru@noindent 1023169626SruInstead the comment should be put on another line or have the comment 1023269626Sruescape adjacent with the end of the string. 1023355839Sasmodai 1023475584Sru@Example 1023569626Sru.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 1023675584Sru@endExample 1023755839Sasmodai 1023869626Sru@cindex trailing quotes 1023969626Sru@cindex quotes, trailing 1024069626Sru@cindex leading spaces with @code{ds} 1024169626Sru@cindex spaces with @code{ds} 10242104862Sru@cindex @code{ds} request, and leading spaces 1024375584SruTo produce leading space the string can be started with a double 1024475584Sruquote. No trailing quote is needed; in fact, any trailing quote is 1024575584Sruincluded in your string. 1024655839Sasmodai 1024775584Sru@Example 1024855839Sasmodai.ds sign " Yours in a white wine sauce, 1024975584Sru@endExample 1025055839Sasmodai 1025169626Sru@cindex multi-line strings 1025269626Sru@cindex strings, multi-line 10253104862Sru@cindex newline character, in strings, escaping 10254104862Sru@cindex escaping newline characters, in strings 1025569626SruStrings are not limited to a single line of text. A string can span 1025675584Sruseveral lines by escaping the newlines with a backslash. The 1025775584Sruresulting string is stored @emph{without} the newlines. 1025855839Sasmodai 1025975584Sru@Example 1026055839Sasmodai.ds foo lots and lots \ 1026155839Sasmodaiof text are on these \ 1026255839Sasmodainext several lines 1026375584Sru@endExample 1026455839Sasmodai 10265104862SruIt is not possible to have real newlines in a string. To put a single 10266104862Srudouble quote character into a string, use two consecutive double quote 10267104862Srucharacters. 1026869626Sru 10269104862SruThe @code{ds1} request turns off compatibility mode 10270104862Sruwhile interpreting a string. To be more precise, a @dfn{compatibility 10271104862Srusave} input token is inserted at the beginning of the string, and a 10272104862Sru@dfn{compatibility restore} input token at the end. 10273104862Sru 10274104862Sru@Example 10275104862Sru.nr xxx 12345 10276104862Sru.ds aa The value of xxx is \\n[xxx]. 10277104862Sru.ds1 bb The value of xxx ix \\n[xxx]. 10278104862Sru. 10279104862Sru.cp 1 10280104862Sru. 10281104862Sru\*(aa 10282104862Sru @result{} warning: number register `[' not defined 10283104862Sru @result{} The value of xxx is 0xxx]. 10284104862Sru\*(bb 10285104862Sru @result{} The value of xxx ix 12345. 10286104862Sru@endExample 10287104862Sru 10288104862Sru@cindex name space, common, of macros, diversions, and strings 10289104862Sru@cindex common name space of macros, diversions, and strings 10290104862Sru@cindex macros, shared name space with strings and diversions 10291104862Sru@cindex strings, shared name space with macros and diversions 10292104862Sru@cindex diversions, shared name space with macros and strings 1029375584SruStrings, macros, and diversions (and boxes) share the same name space. 1029475584SruInternally, even the same mechanism is used to store them. This has 1029575584Srusome interesting consequences. For example, it is possible to call a 1029675584Srumacro with string syntax and vice versa. 1029769626Sru 1029875584Sru@Example 1029975584Sru.de xxx 1030075584Srua funny test. 1030175584Sru.. 1030275584SruThis is \*[xxx] 1030375584Sru @result{} This is a funny test. 1030469626Sru 1030575584Sru.ds yyy a funny test 1030675584SruThis is 1030775584Sru.yyy 1030875584Sru @result{} This is a funny test. 1030975584Sru@endExample 1031069626Sru 10311104862SruDiversions and boxes can be also called with string syntax. 1031269626Sru 1031375584SruAnother consequence is that you can copy one-line diversions or boxes 1031475584Sruto a string. 1031575584Sru 1031675584Sru@Example 1031775584Sru.di xxx 1031875584Srua \fItest\fR 1031975584Sru.br 1032075584Sru.di 1032175584Sru.ds yyy This is \*[xxx]\c 1032275584Sru\*[yyy]. 1032375584Sru @result{} @r{This is a }@i{test}. 1032475584Sru@endExample 1032575584Sru 1032669626Sru@noindent 1032775584SruAs the previous example shows, it is possible to store formatted 1032875584Sruoutput in strings. The @code{\c} escape prevents the insertion of an 1032975584Sruadditional blank line in the output. 1033069626Sru 1033175584SruCopying diversions longer than a single output line produces 1033275584Sruunexpected results. 1033355839Sasmodai 1033475584Sru@Example 1033575584Sru.di xxx 1033675584Srua funny 1033775584Sru.br 1033875584Srutest 1033975584Sru.br 1034075584Sru.di 1034175584Sru.ds yyy This is \*[xxx]\c 1034275584Sru\*[yyy]. 1034375584Sru @result{} test This is a funny. 1034475584Sru@endExample 1034569626Sru 1034675584SruUsually, it is not predictable whether a diversion contains one or 1034775584Srumore output lines, so this mechanism should be avoided. With 1034875584Sru@acronym{UNIX} @code{troff}, this was the only solution to strip off a 1034975584Srufinal newline from a diversion. Another disadvantage is that the 1035075584Sruspaces in the copied string are already formatted, making them 1035175584Sruunstretchable. This can cause ugly results. 1035255839Sasmodai 10353104862Sru@cindex stripping final newline in diversions 10354104862Sru@cindex diversion, stripping final newline 10355104862Sru@cindex final newline, stripping in diversions 10356104862Sru@cindex newline, final, stripping in diversions 10357104862Sru@cindex horizontal space, unformatting 10358104862Sru@cindex space, horizontal, unformatting 10359104862Sru@cindex unformatting horizontal space 1036075584SruA clean solution to this problem is available in GNU @code{troff}, 1036175584Sruusing the requests @code{chop} to remove the final newline of a 1036275584Srudiversion, and @code{unformat} to make the horizontal spaces 1036375584Srustretchable again. 1036469626Sru 1036575584Sru@Example 1036675584Sru.box xxx 1036775584Srua funny 1036875584Sru.br 1036975584Srutest 1037075584Sru.br 1037175584Sru.box 1037275584Sru.chop xxx 1037375584Sru.unformat xxx 1037475584SruThis is \*[xxx]. 1037575584Sru @result{} This is a funny test. 1037675584Sru@endExample 1037755839Sasmodai 1037875584Sru@xref{Gtroff Internals}, for more information. 1037975584Sru@endDefreq 1038069626Sru 10381104862Sru@DefreqList {as, name [@Var{string}]} 10382104862Sru@DefreqListEnd {as1, name [@Var{string}]} 10383104862Sru@cindex appending to a string (@code{as}) 10384104862Sru@cindex string, appending (@code{as}) 1038575584SruThe @code{as} request is similar to @code{ds} but appends @var{string} 1038675584Sruto the string stored as @var{name} instead of redefining it. If 1038775584Sru@var{name} doesn't exist yet, it is created. 1038855839Sasmodai 1038975584Sru@Example 1039075584Sru.as sign " with shallots, onions and garlic, 1039175584Sru@endExample 10392104862Sru 10393104862SruThe @code{as1} request is similar to @code{as}, but compatibility mode 10394104862Sruis switched off while the appended string is interpreted. To be more 10395104862Sruprecise, a @dfn{compatibility save} input token is inserted at the 10396104862Srubeginning of the appended string, and a @dfn{compatibility restore} 10397104862Sruinput token at the end. 1039875584Sru@endDefreq 1039955839Sasmodai 1040075584SruRudimentary string manipulation routines are given with the next two 1040175584Srurequests. 1040269626Sru 1040375584Sru@Defreq {substring, str n1 [@Var{n2}]} 10404104862Sru@cindex substring (@code{substring}) 10405104862SruReplace the string named @var{str} with the substring 10406114402Srudefined by the indices @var{n1} and@tie{}@var{n2}. The first character 10407114402Sruin the string has index@tie{}0. If @var{n2} is omitted, it is taken to 1040875584Srube equal to the string's length. If the index value @var{n1} or 10409104862Sru@var{n2} is negative, it is counted from the end of the 10410114402Srustring, going backwards: The last character has index@tie{}@minus{}1, the 10411114402Srucharacter before the last character has index@tie{}@minus{}2, etc. 1041275584Sru 1041375584Sru@Example 1041475584Sru.ds xxx abcdefgh 10415104862Sru.substring xxx 1 -4 1041675584Sru\*[xxx] 1041775584Sru @result{} bcde 1041875584Sru@endExample 1041975584Sru@endDefreq 1042075584Sru 1042175584Sru@Defreq {length, reg str} 10422104862Sru@cindex length of a string (@code{length}) 10423104862Sru@cindex string, length of (@code{length}) 10424104862SruCompute the number of characters of @var{str} and return it in the 10425104862Srunumber register @var{reg}. If @var{reg} doesn't exist, it is created. 10426104862Sru@code{str} is read in copy mode. 1042775584Sru 1042875584Sru@Example 10429104862Sru.ds xxx abcd\h'3i'efgh 10430114402Sru.length yyy \*[xxx] 1043175584Sru\n[yyy] 10432104862Sru @result{} 14 1043375584Sru@endExample 1043475584Sru@endDefreq 1043575584Sru 1043675584Sru@Defreq {rn, xx yy} 10437104862Sru@cindex renaming request (@code{rn}) 10438104862Sru@cindex request, renaming (@code{rn}) 10439104862Sru@cindex renaming macro (@code{rn}) 10440104862Sru@cindex macro, renaming (@code{rn}) 10441104862Sru@cindex renaming string (@code{rn}) 10442104862Sru@cindex string, renaming (@code{rn}) 10443104862Sru@cindex renaming diversion (@code{rn}) 10444104862Sru@cindex diversion, renaming (@code{rn}) 10445104862SruRename the request, macro, diversion, or string @var{xx} to @var{yy}. 1044675584Sru@endDefreq 1044775584Sru 1044875584Sru@Defreq {rm, xx} 10449104862Sru@cindex removing request (@code{rm}) 10450104862Sru@cindex request, removing (@code{rm}) 10451104862Sru@cindex removing macro (@code{rm}) 10452104862Sru@cindex macro, removing (@code{rm}) 10453104862Sru@cindex removing string (@code{rm}) 10454104862Sru@cindex string, removing (@code{rm}) 10455104862Sru@cindex removing diversion (@code{rm}) 10456104862Sru@cindex diversion, removing (@code{rm}) 10457104862SruRemove the request, macro, diversion, or string @var{xx}. @code{gtroff} 10458104862Srutreats subsequent invocations as if the object had never been defined. 1045975584Sru@endDefreq 1046075584Sru 1046175584Sru@Defreq {als, new old} 10462104862Sru@cindex alias, string, creating (@code{als}) 10463104862Sru@cindex alias, macro, creating (@code{als}) 10464104862Sru@cindex alias, diversion, creating (@code{als}) 10465104862Sru@cindex creating alias, for string (@code{als}) 10466104862Sru@cindex creating alias, for macro (@code{als}) 10467104862Sru@cindex creating alias, for diversion (@code{als}) 10468104862Sru@cindex string, creating alias (@code{als}) 10469104862Sru@cindex macro, creating alias (@code{als}) 10470104862Sru@cindex diversion, creating alias (@code{als}) 1047175584SruCreate an alias named @var{new} for the request, string, macro, or 1047275584Srudiversion object named @var{old}. The new name and the old name are 1047375584Sruexactly equivalent (it is similar to a hard rather than a soft 1047475584Srulink). If @var{old} is undefined, @code{gtroff} generates a warning of 1047575584Srutype @samp{mac} and ignores the request. 1047675584Sru@endDefreq 1047775584Sru 1047875584Sru@Defreq {chop, xx} 1047975584SruRemove (chop) the last character from the macro, string, or diversion 10480104862Srunamed @var{xx}. This is useful for removing the newline from the end 1048175584Sruof diversions that are to be interpolated as strings. This command 1048275584Srucan be used repeatedly; see @ref{Gtroff Internals}, for details on 10483104862Srunodes inserted additionally by @code{gtroff}. 1048475584Sru@endDefreq 1048575584Sru 1048669626Sru@xref{Identifiers}, and @ref{Comments}. 1048769626Sru 1048869626Sru 1048969626Sru@c ===================================================================== 1049069626Sru 1049175584Sru@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 1049255839Sasmodai@section Conditionals and Loops 1049355839Sasmodai@cindex conditionals and loops 1049455839Sasmodai@cindex loops and conditionals 1049555839Sasmodai 1049675584Sru@menu 1049775584Sru* Operators in Conditionals:: 1049875584Sru* if-else:: 1049975584Sru* while:: 1050075584Sru@end menu 1050155839Sasmodai 1050275584Sru@c --------------------------------------------------------------------- 1050375584Sru 1050475584Sru@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 1050575584Sru@subsection Operators in Conditionals 1050675584Sru 10507104862Sru@cindex @code{if} request, operators to use with 10508104862Sru@cindex @code{while} request, operators to use with 1050975584SruIn @code{if} and @code{while} requests, there are several more 1051075584Sruoperators available: 1051175584Sru 1051255839Sasmodai@table @code 1051355839Sasmodai@item e 1051455839Sasmodai@itemx o 1051569626SruTrue if the current page is even or odd numbered (respectively). 1051669626Sru 1051755839Sasmodai@item n 1051875584SruTrue if the document is being processed in nroff mode (i.e., the 1051975584Sru@code{.nroff} command has been issued). 1052069626Sru 1052169626Sru@item t 1052275584SruTrue if the document is being processed in troff mode (i.e., the 1052375584Sru@code{.troff} command has been issued). 1052469626Sru 1052575584Sru@item v 10526104862SruAlways false. This condition is for compatibility with other 10527151497Sru@code{troff} versions only (identifying a @code{-Tversatec} device). 1052875584Sru 1052955839Sasmodai@item '@var{xxx}'@var{yyy}' 1053069626SruTrue if the string @var{xxx} is equal to the string @var{yyy}. Other 1053175584Srucharacters can be used in place of the single quotes; the same set of 1053275584Srudelimiters as for the @code{\D} escape is used (@pxref{Escapes}). 1053375584Sru@code{gtroff} formats the strings before being compared: 1053469626Sru 1053575584Sru@Example 1053675584Sru.ie "|"\fR|\fP" \ 1053775584Srutrue 1053875584Sru.el \ 1053975584Srufalse 1054075584Sru @result{} true 1054175584Sru@endExample 1054275584Sru 1054375584Sru@noindent 10544104862SruThe resulting motions, glyph sizes, and fonts have to 1054575584Srumatch,@footnote{The created output nodes must be identical. 1054675584Sru@xref{Gtroff Internals}.} and not the individual motion, size, and 1054775584Srufont requests. In the previous example, @samp{|} and @samp{\fR|\fP} 10548104862Sruboth result in a roman @samp{|} glyph with the same point size and 1054975584Sruat the same location on the page, so the strings are equal. If 10550114402Sru@samp{.ft@tie{}I} had been added before the @samp{.ie}, the result 1055175584Sruwould be ``false'' because (the first) @samp{|} produces an italic 1055275584Sru@samp{|} rather than a roman one. 1055375584Sru 1055475584Sru@item r @var{xxx} 1055555839SasmodaiTrue if there is a number register named @var{xxx}. 1055669626Sru 1055775584Sru@item d @var{xxx} 1055855839SasmodaiTrue if there is a string, macro, diversion, or request named @var{xxx}. 1055969626Sru 10560104862Sru@item m @var{xxx} 10561104862SruTrue if there is a color named @var{xxx}. 10562104862Sru 10563104862Sru@item c @var{g} 10564104862SruTrue if there is a glyph @var{g} available@footnote{The name of this 10565104862Sruconditional operator is a misnomer since it tests names of output 10566104862Sruglyphs.}; @var{g} is either an @acronym{ASCII} character or a special 10567104862Srucharacter (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition 10568104862Sruis also true if @var{g} has been defined by the @code{char} request. 10569151497Sru 10570151497Sru@item F @var{font} 10571151497SruTrue if a font named @var{font} exists. @var{font} is handled as if it was 10572151497Sruopened with the @code{ft} request (this is, font translation and styles are 10573151497Sruapplied), without actually mounting it. 10574151497Sru 10575151497SruThis test doesn't load the complete font but only its header to verify 10576151497Sruits validity. 10577151497Sru 10578151497Sru@item S @var{style} 10579151497SruTrue if style @var{style} has been registered. Font translation is applied. 1058055839Sasmodai@end table 1058155839Sasmodai 1058275584SruNote that these operators can't be combined with other operators like 1058375584Sru@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 1058475584Srubetween the exclamation mark and the operator) can be used to negate 1058575584Sruthe result. 1058655839Sasmodai 1058775584Sru@Example 1058875584Sru.nr xxx 1 1058975584Sru.ie !r xxx \ 1059075584Srutrue 1059175584Sru.el \ 1059275584Srufalse 1059375584Sru @result{} false 1059475584Sru@endExample 1059575584Sru 1059675584SruA whitespace after @samp{!} always evaluates to zero (this bizarre 1059775584Srubehaviour is due to compatibility with @acronym{UNIX} @code{troff}). 1059875584Sru 1059975584Sru@Example 1060075584Sru.nr xxx 1 1060175584Sru.ie ! r xxx \ 1060275584Srutrue 1060375584Sru.el \ 1060475584Srufalse 1060575584Sru @result{} r xxx true 1060675584Sru@endExample 1060775584Sru 1060875584SruIt is possible to omit the whitespace before the argument to the 1060975584Sru@samp{r}, @samp{d}, and @samp{c} operators. 1061075584Sru 1061175584Sru@xref{Expressions}. 1061275584Sru 1061369626Sru@c --------------------------------------------------------------------- 1061469626Sru 1061575584Sru@node if-else, while, Operators in Conditionals, Conditionals and Loops 1061655839Sasmodai@subsection if-else 1061755839Sasmodai@cindex if-else 1061855839Sasmodai 1061969626Sru@code{gtroff} has if-then-else constructs like other languages, although 1062055839Sasmodaithe formatting can be painful. 1062155839Sasmodai 1062275584Sru@Defreq {if, expr anything} 10623151497Sru 1062475584SruEvaluate the expression @var{expr}, and executes @var{anything} (the 10625151497Sruremainder of the line) if @var{expr} evaluates to a value greater than 10626151497Sruzero (true). @var{anything} is interpreted as though it was on a line 10627151497Sruby itself (except that leading spaces are swallowed). 10628151497Sru@xref{Expressions}, for more info. 1062955839Sasmodai 1063075584Sru@Example 1063175584Sru.nr xxx 1 1063275584Sru.nr yyy 2 1063375584Sru.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 1063475584Sru @result{} true 1063575584Sru@endExample 1063675584Sru@endDefreq 1063769626Sru 10638104862Sru@Defreq{nop, anything} 10639104862SruExecutes @var{anything}. 10640114402SruThis is similar to @code{.if@tie{}1}. 10641104862Sru@endDefreq 1064269626Sru 10643104862Sru@DefreqList {ie, expr anything} 10644104862Sru@DefreqListEnd {el, anything} 1064575584SruUse the @code{ie} and @code{el} requests to write an if-then-else. 1064669626SruThe first request is the `if' part and the latter is the `else' part. 1064755839Sasmodai 1064875584Sru@Example 10649104862Sru.ie n .ls 2 \" double-spacing in nroff 10650104862Sru.el .ls 1 \" single-spacing in troff 1065175584Sru@endExample 1065275584Sru@endDefreq 1065369626Sru 10654104862Sru@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument 10655104862Sru@c to @deffn 10656104862Sru@c 10657104862Sru@c and in 4.2 you still can't use @{ in macros. 1065855839Sasmodai 10659104862Sru@c @DefescList {\@{, , , } 10660104862Sru@c @DefescListEnd {\@}, , , } 10661104862Sru@deffn Escape @t{\@{} 10662104862Sru@deffnx Escape @t{\@}} 1066375584Sru@esindex \@{ 1066475584Sru@esindex \@} 10665104862Sru@cindex begin of conditional block (@code{\@{}) 10666104862Sru@cindex end of conditional block (@code{\@}}) 10667104862Sru@cindex conditional block, begin (@code{\@{}) 10668104862Sru@cindex conditional block, end (@code{\@}}) 10669104862Sru@cindex block, conditional, begin (@code{\@{}) 10670104862Sru@cindex block, condititional, end (@code{\@}}) 1067175584SruIn many cases, an if (or if-else) construct needs to execute more than 1067275584Sruone request. This can be done using the @code{\@{} and @code{\@}} 1067369626Sruescapes. The following example shows the possible ways to use these 1067469626Sruescapes (note the position of the opening and closing braces). 1067555839Sasmodai 1067675584Sru@Example 1067755839Sasmodai.ie t \@{\ 1067855839Sasmodai. ds lq `` 1067955839Sasmodai. ds rq '' 1068055839Sasmodai.\@} 1068155839Sasmodai.el \ 1068255839Sasmodai.\@{\ 1068355839Sasmodai. ds lq " 1068455839Sasmodai. ds rq "\@} 1068575584Sru@endExample 1068675584Sru@c @endDefesc 10687104862Sru@end deffn 1068855839Sasmodai 1068969626Sru@xref{Expressions}. 1069055839Sasmodai 1069169626Sru@c --------------------------------------------------------------------- 1069255839Sasmodai 1069355839Sasmodai@node while, , if-else, Conditionals and Loops 1069455839Sasmodai@subsection while 1069555839Sasmodai@cindex while 1069655839Sasmodai 1069769626Sru@code{gtroff} provides a looping construct using the @code{while} 1069869626Srurequest, which is used much like the @code{if} (and related) requests. 1069955839Sasmodai 1070075584Sru@Defreq {while, expr anything} 1070175584SruEvaluate the expression @var{expr}, and repeatedly execute 1070275584Sru@var{anything} (the remainder of the line) until @var{expr} evaluates 10703114402Sruto@tie{}0. 1070475584Sru 1070575584Sru@Example 1070655839Sasmodai.nr a 0 1 1070775584Sru.while (\na < 9) \@{\ 1070875584Sru\n+a, 1070975584Sru.\@} 1071075584Sru\n+a 1071175584Sru @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 1071275584Sru@endExample 1071355839Sasmodai 1071475584SruSome remarks. 1071575584Sru 10716104862Sru@cindex @code{de} request, and @code{while} 1071775584Sru@itemize @bullet 1071875584Sru@item 1071975584SruThe body of a @code{while} request is treated like the body of a 1072075584Sru@code{de} request: @code{gtroff} temporarily stores it in a macro 1072175584Sruwhich is deleted after the loop has been exited. It can considerably 1072275584Sruslow down a macro if the body of the @code{while} request (within the 1072375584Srumacro) is large. Each time the macro is executed, the @code{while} 1072475584Srubody is parsed and stored again as a temporary macro. 1072575584Sru 1072675584Sru@Example 1072775584Sru.de xxx 1072875584Sru. nr num 10 1072975584Sru. while (\\n[num] > 0) \@{\ 1073075584Sru. \" many lines of code 1073175584Sru. nr num -1 1073275584Sru. \@} 1073375584Sru.. 1073475584Sru@endExample 1073575584Sru 1073675584Sru@cindex recursive macros 1073775584Sru@cindex macros, recursive 1073869626Sru@noindent 1073975584SruThe traditional and ofter better solution (@acronym{UNIX} @code{troff} 1074075584Srudoesn't have the @code{while} request) is to use a recursive macro 1074175584Sruinstead which is parsed only once during its definition. 1074255839Sasmodai 1074375584Sru@Example 1074475584Sru.de yyy 1074575584Sru. if (\\n[num] > 0) \@{\ 1074675584Sru. \" many lines of code 1074775584Sru. nr num -1 1074875584Sru. yyy 1074975584Sru. \@} 1075075584Sru.. 1075175584Sru. 1075275584Sru.de xxx 1075375584Sru. nr num 10 1075475584Sru. yyy 1075575584Sru.. 1075675584Sru@endExample 1075755839Sasmodai 1075869626Sru@noindent 10759114402SruNote that the number of available recursion levels is set to@tie{}1000 1076075584Sru(this is a compile-time constant value of @code{gtroff}). 1076155839Sasmodai 1076275584Sru@item 1076375584SruThe closing brace of a @code{while} body must end a line. 1076455839Sasmodai 1076575584Sru@Example 1076675584Sru.if 1 \@{\ 1076775584Sru. nr a 0 1 1076875584Sru. while (\n[a] < 10) \@{\ 1076975584Sru. nop \n+[a] 1077075584Sru.\@}\@} 1077175584Sru @result{} unbalanced \@{ \@} 1077275584Sru@endExample 1077375584Sru@end itemize 1077475584Sru@endDefreq 1077575584Sru 1077675584Sru@Defreq {break, } 10777104862Sru@cindex @code{while} request, confusing with @code{br} 10778104862Sru@cindex @code{break} request, in a @code{while} loop 10779104862Sru@cindex @code{continue} request, in a @code{while} loop 1078075584SruBreak out of a @code{while} loop. Be sure not to confuse this with 1078175584Sruthe @code{br} request (causing a line break). 1078275584Sru@endDefreq 1078375584Sru 1078475584Sru@Defreq {continue, } 10785104862SruFinish the current iteration of a @code{while} loop, immediately 1078675584Srurestarting the next iteration. 1078775584Sru@endDefreq 1078875584Sru 1078969626Sru@xref{Expressions}. 1079069626Sru 1079169626Sru 1079269626Sru@c ===================================================================== 1079369626Sru 1079475584Sru@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 1079555839Sasmodai@section Writing Macros 1079655839Sasmodai@cindex writing macros 1079755839Sasmodai@cindex macros, writing 1079855839Sasmodai 1079975584SruA @dfn{macro} is a collection of text and embedded commands which can 1080075584Srube invoked multiple times. Use macros to define common operations. 1080155839Sasmodai 10802104862Sru@DefreqList {de, name [@Var{end}]} 10803104862Sru@DefreqItem {de1, name [@Var{end}]} 10804151497Sru@DefreqItem {dei, name [@Var{end}]} 10805151497Sru@DefreqListEnd {dei1, name [@Var{end}]} 1080675584SruDefine a new macro named @var{name}. @code{gtroff} copies subsequent 1080775584Srulines (starting with the next one) into an internal buffer until it 1080875584Sruencounters the line @samp{..} (two dots). The optional second 1080975584Sruargument to @code{de} changes this to a macro to @samp{.@var{end}}. 1081055839Sasmodai 10811104862SruThere can be whitespace after the first dot in the line containing the 10812104862Sruending token (either @samp{.} or macro @samp{@var{end}}). 1081375584Sru 1081475584SruHere a small example macro called @samp{P} which causes a break and 1081575584Sruinserts some vertical space. It could be used to separate paragraphs. 1081675584Sru 1081775584Sru@Example 1081855839Sasmodai.de P 1081975584Sru. br 1082075584Sru. sp .8v 1082155839Sasmodai.. 1082275584Sru@endExample 1082355839Sasmodai 10824104862SruThe following example defines a macro within another. Remember that 10825104862Sruexpansion must be protected twice; once for reading the macro and 10826104862Sruonce for executing. 1082775584Sru 10828104862Sru@Example 10829104862Sru\# a dummy macro to avoid a warning 10830104862Sru.de end 10831104862Sru.. 10832104862Sru. 10833104862Sru.de foo 10834104862Sru. de bar end 10835104862Sru. nop \f[B]Hallo \\\\$1!\f[] 10836104862Sru. end 10837104862Sru.. 10838104862Sru. 10839104862Sru.foo 10840104862Sru.bar Joe 10841104862Sru @result{} @b{Hallo Joe!} 10842104862Sru@endExample 1084375584Sru 10844104862Sru@noindent 10845104862SruSince @code{\f} has no expansion, it isn't necessary to protect its 10846104862Srubackslash. Had we defined another macro within @code{bar} which takes 10847104862Srua parameter, eight backslashes would be necessary before @samp{$1}. 1084875584Sru 10849104862SruThe @code{de1} request turns off compatibility mode 10850104862Sruwhile executing the macro. On entry, the current compatibility mode 10851104862Sruis saved and restored at exit. 10852104862Sru 10853104862Sru@Example 10854104862Sru.nr xxx 12345 10855104862Sru. 10856104862Sru.de aa 10857104862SruThe value of xxx is \\n[xxx]. 10858104862Sru.. 10859104862Sru.de1 bb 10860104862SruThe value of xxx ix \\n[xxx]. 10861104862Sru.. 10862104862Sru. 10863104862Sru.cp 1 10864104862Sru. 10865104862Sru.aa 10866151497Sru @result{} warning: number register `[' not defined 10867104862Sru @result{} The value of xxx is 0xxx]. 10868104862Sru.bb 10869104862Sru @result{} The value of xxx ix 12345. 10870104862Sru@endExample 10871104862Sru 10872104862SruThe @code{dei} request defines a macro indirectly. 10873104862SruThat is, it expands strings whose names 10874104862Sruare @var{name} or @var{end} before performing the append. 10875104862Sru 10876104862SruThis: 10877104862Sru 10878104862Sru@Example 10879104862Sru.ds xx aa 10880104862Sru.ds yy bb 10881104862Sru.dei xx yy 10882104862Sru@endExample 10883104862Sru 10884104862Sru@noindent 10885104862Sruis equivalent to: 10886104862Sru 10887104862Sru@Example 10888104862Sru.de aa bb 10889104862Sru@endExample 10890104862Sru 10891151497SruThe @code{dei1} request is similar to @code{dei} but with compatibility 10892151497Srumode switched off during execution of the defined macro. 10893151497Sru 10894151497SruIf compatibility mode is on, @code{de} (and @code{dei}) behave similar to 10895151497Sru@code{de1} (and @code{dei1}): A `compatibility save' token is inserted at 10896151497Sruthe beginning, and a `compatibility restore' token at the end, with 10897151497Srucompatibility mode switched on during execution. @xref{Gtroff Internals}, 10898151497Srufor more information on switching compatibility mode on and off in a 10899151497Srusingle document. 10900151497Sru 10901104862Sru@pindex trace.tmac 10902104862SruUsing @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}. 10903104862Sru 10904104862SruNote that macro identifiers are shared with identifiers for strings and 10905104862Srudiversions. 1090675584Sru@endDefreq 1090775584Sru 10908114402Sru@DefreqList {am, name [@Var{end}]} 10909114402Sru@DefreqItem {am1, name [@Var{end}]} 10910151497Sru@DefreqItem {ami, name [@Var{end}]} 10911151497Sru@DefreqListEnd {ami1, name [@Var{end}]} 10912104862Sru@cindex appending to a macro (@code{am}) 10913104862Sru@cindex macro, appending (@code{am}) 1091475584SruWorks similarly to @code{de} except it appends onto the macro named 10915114402Sru@var{name}. So, to make the previously defined @samp{P} macro actually 1091675584Srudo indented instead of block paragraphs, add the necessary code to the 1091775584Sruexisting macro like this: 1091855839Sasmodai 1091975584Sru@Example 1092055839Sasmodai.am P 1092155839Sasmodai.ti +5n 1092255839Sasmodai.. 1092375584Sru@endExample 10924104862Sru 10925104862SruThe @code{am1} request turns off compatibility mode 10926104862Sruwhile executing the appended macro piece. To be more precise, a 10927104862Sru@dfn{compatibility save} input token is inserted at the beginning of 10928104862Sruthe appended code, and a @dfn{compatibility restore} input token at 10929104862Sruthe end. 10930104862Sru 10931104862SruThe @code{ami} request appends indirectly, 10932104862Srumeaning that @code{gtroff} expands strings whose names 10933114402Sruare @var{name} or @var{end} before performing the append. 10934104862Sru 10935151497SruThe @code{ami1} request is similar to @code{ami} but compatibility mode 10936151497Sruis switched off during execution of the defined macro. 10937151497Sru 10938104862Sru@pindex trace.tmac 10939104862SruUsing @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. 1094075584Sru@endDefreq 1094155839Sasmodai 10942104862Sru@xref{Strings}, for the @code{als} request to rename a macro. 1094355839Sasmodai 10944104862SruThe @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and 10945104862Sru@code{as} requests (together with its variants) only create a new object 10946104862Sruif the name of the macro, diversion or string diversion is currently 10947104862Sruundefined or if it is defined to be a request; normally they modify the 10948104862Sruvalue of an existing object. 10949104862Sru 10950151497Sru@Defreq {return, [@Var{anything}]} 10951104862SruExit a macro, immediately returning to the caller. 10952151497Sru 10953151497SruIf called with an argument, exit twice, namely the current macro and the 10954151497Srumacro one level higher. This is used to define a wrapper macro for 10955151497Sru@code{return} in @file{trace.tmac}. 1095675584Sru@endDefreq 1095755839Sasmodai 1095855839Sasmodai@menu 1095975584Sru* Copy-in Mode:: 1096075584Sru* Parameters:: 1096155839Sasmodai@end menu 1096255839Sasmodai 1096369626Sru@c --------------------------------------------------------------------- 1096469626Sru 1096555839Sasmodai@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 1096655839Sasmodai@subsection Copy-in Mode 1096755839Sasmodai@cindex copy-in mode 1096855839Sasmodai@cindex mode, copy-in 1096955839Sasmodai 1097075584Sru@cindex @code{\n}, when reading text for a macro 1097175584Sru@cindex @code{\$}, when reading text for a macro 1097275584Sru@cindex @code{\*}, when reading text for a macro 1097375584Sru@cindex @code{\\}, when reading text for a macro 1097475584Sru@cindex \@key{RET}, when reading text for a macro 10975104862SruWhen @code{gtroff} reads in the text for a macro, string, or diversion, 10976104862Sruit copies the text (including request lines, but excluding escapes) into 10977104862Sruan internal buffer. Escapes are converted into an internal form, 1097869626Sruexcept for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 1097969626Sru@code{\@key{RET}} which are evaluated and inserted into the text where 1098069626Sruthe escape was located. This is known as @dfn{copy-in} mode or 1098169626Sru@dfn{copy} mode. 1098255839Sasmodai 1098355839SasmodaiWhat this means is that you can specify when these escapes are to be 1098469626Sruevaluated (either at copy-in time or at the time of use) by insulating 1098569626Sruthe escapes with an extra backslash. Compare this to the @code{\def} 1098669626Sruand @code{\edef} commands in @TeX{}. 1098755839Sasmodai 10988114402SruThe following example prints the numbers 20 and@tie{}10: 1098955839Sasmodai 1099075584Sru@Example 1099155839Sasmodai.nr x 20 1099255839Sasmodai.de y 1099355839Sasmodai.nr x 10 1099455839Sasmodai\&\nx 1099555839Sasmodai\&\\nx 1099655839Sasmodai.. 1099755839Sasmodai.y 1099875584Sru@endExample 1099955839Sasmodai 1100069626Sru@c --------------------------------------------------------------------- 1100155839Sasmodai 1100255839Sasmodai@node Parameters, , Copy-in Mode, Writing Macros 1100355839Sasmodai@subsection Parameters 1100455839Sasmodai@cindex parameters 1100555839Sasmodai 11006104862SruThe arguments to a macro or string can be examined using a variety of 11007104862Sruescapes. 11008104862Sru 11009104862Sru@Defreg {.$} 11010104862Sru@cindex number of arguments register (@code{.$}) 11011104862SruThe number of arguments passed to a macro or string. This is a read-only 11012104862Srunumber register. 11013151497Sru 11014151497SruNote that the @code{shift} request can change its value. 11015104862Sru@endDefreg 11016104862Sru 1101755839SasmodaiAny individual argument can be retrieved with one of the following 1101855839Sasmodaiescapes: 1101955839Sasmodai 11020104862Sru@DefescList {\\$, , n, } 11021151497Sru@DefescItem {\\$, @Lparen{}, nn, } 11022151497Sru@DefescListEnd {\\$, @Lbrack{}, nnn, @Rbrack{}} 1102369626Sru@cindex copy-in mode, and macro arguments 11024104862Sru@cindex macro, arguments (@code{\$}) 11025104862Sru@cindex arguments, macro (@code{\$}) 11026104862SruRetrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} 11027104862Sruargument. As usual, the first form only accepts a single number 11028104862Sru(larger than zero), the second a two-digit number (larger or equal 11029114402Sruto@tie{}10), and the third any positive integer value (larger 11030104862Sruthan zero). Macros and strings can have an unlimited number of arguments. 11031104862SruNote that due to copy-in mode, use two backslashes on these in actual use 11032104862Sruto prevent interpolation until the macro is actually invoked. 1103375584Sru@endDefesc 1103455839Sasmodai 1103575584Sru@Defreq {shift, [@Var{n}]} 11036114402SruShift the arguments 1@tie{}position, or as 1103769626Srumany positions as specified by its argument. After executing this 11038114402Srurequest, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}}; 11039114402Sruarguments 1 to@tie{}@var{n} are no longer available. Shifting by 1104069626Srunegative amounts is currently undefined. 11041151497Sru 11042151497SruThe register @code{.$} is adjusted accordingly. 1104375584Sru@endDefreq 1104455839Sasmodai 11045104862Sru@DefescList {\\$*, , , } 11046104862Sru@DefescListEnd {\\$@@, , , } 1104769626SruIn some cases it is convenient to use all of the arguments at once (for 1104869626Sruexample, to pass the arguments along to another macro). The @code{\$*} 1104975584Sruescape concatenates all the arguments separated by spaces. A 1105075584Srusimilar escape is @code{\$@@}, which concatenates all the 1105169626Sruarguments with each surrounded by double quotes, and separated by 11052104862Sruspaces. If not in compatibility mode, the input level of double quotes 11053114402Sruis preserved (see @ref{Request and Macro Arguments}). 1105475584Sru@endDefesc 1105555839Sasmodai 1105675584Sru@Defesc {\\$0, , , } 11057104862Sru@cindex macro name register (@code{\$0}) 11058104862Sru@cindex @code{als} request, and @code{\$0} 1105975584SruThe name used to invoke the current macro. 1106075584SruThe @code{als} request can make a macro have more than one name. 1106155839Sasmodai 1106275584Sru@Example 11063104862Sru.de generic-macro 11064104862Sru. ... 11065104862Sru. if \\n[error] \@{\ 11066104862Sru. tm \\$0: Houston, we have a problem. 11067104862Sru. return 11068104862Sru. \@} 1106955839Sasmodai.. 11070104862Sru. 11071104862Sru.als foo generic-macro 11072104862Sru.als bar generic-macro 1107375584Sru@endExample 1107475584Sru@endDefesc 1107555839Sasmodai 11076114402Sru@xref{Request and Macro Arguments}. 1107755839Sasmodai 1107855839Sasmodai 1107969626Sru@c ===================================================================== 1108069626Sru 1108175584Sru@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 1108255839Sasmodai@section Page Motions 1108355839Sasmodai@cindex page motions 1108455839Sasmodai@cindex motions, page 1108555839Sasmodai 11086104862Sru@xref{Manipulating Spacing}, for a discussion of the main request for 11087104862Sruvertical motion, @code{sp}. 1108855839Sasmodai 11089104862Sru@DefreqList {mk, [@Var{reg}]} 11090104862Sru@DefreqListEnd {rt, [@Var{dist}]} 11091104862Sru@cindex marking vertical page location (@code{mk}) 11092104862Sru@cindex page location, vertical, marking (@code{mk}) 11093104862Sru@cindex location, vertical, page, marking (@code{mk}) 11094104862Sru@cindex vertical page location, marking (@code{mk}) 11095104862Sru@cindex returning to marked vertical page location (@code{rt}) 11096104862Sru@cindex page location, vertical, returning to marked (@code{rt}) 11097104862Sru@cindex location, vertical, page, returning to marked (@code{rt}) 11098104862Sru@cindex vertical page location, returning to marked (@code{rt}) 1109955839SasmodaiThe request @code{mk} can be used to mark a location on a page, for 11100104862Srumovement to later. This request takes a register name as an argument 11101104862Sruin which to store the current page location. With no argument it 11102104862Srustores the location in an internal register. The results of this can 11103104862Srube used later by the @code{rt} or the @code{sp} request (or the 11104104862Sru@code{\v} escape). 1110555839Sasmodai 11106104862SruThe @code{rt} request returns @emph{upwards} to the location marked 11107104862Sruwith the last @code{mk} request. If used with an argument, return to 11108104862Srua position which distance from the top of the page is @var{dist} (no 11109104862Sruprevious call to @code{mk} is necessary in this case). Default scaling 11110104862Sruindicator is @samp{v}. 11111104862Sru 11112104862SruHere a primitive solution for a two-column macro. 11113104862Sru 1111475584Sru@Example 11115104862Sru.nr column-length 1.5i 11116104862Sru.nr column-gap 4m 11117104862Sru.nr bottom-margin 1m 11118104862Sru. 1111975584Sru@endExample 11120104862Sru@Example 11121104862Sru.de 2c 11122104862Sru. br 11123104862Sru. mk 11124104862Sru. ll \\n[column-length]u 11125104862Sru. wh -\\n[bottom-margin]u 2c-trap 11126104862Sru. nr right-side 0 11127104862Sru.. 11128104862Sru. 11129104862Sru@endExample 11130104862Sru@Example 11131104862Sru.de 2c-trap 11132104862Sru. ie \\n[right-side] \@{\ 11133104862Sru. nr right-side 0 11134104862Sru. po -(\\n[column-length]u + \\n[column-gap]u) 11135104862Sru. \" remove trap 11136104862Sru. wh -\\n[bottom-margin]u 11137104862Sru. \@} 11138104862Sru. el \@{\ 11139104862Sru. \" switch to right side 11140104862Sru. nr right-side 1 11141104862Sru. po +(\\n[column-length]u + \\n[column-gap]u) 11142104862Sru. rt 11143104862Sru. \@} 11144104862Sru.. 11145104862Sru. 11146104862Sru@endExample 11147104862Sru@Example 11148104862Sru.pl 1.5i 11149104862Sru.ll 4i 11150104862SruThis is a small test which shows how the 11151104862Srurt request works in combination with mk. 11152104862Sru 11153104862Sru.2c 11154104862SruStarting here, text is typeset in two columns. 11155104862SruNote that this implementation isn't robust 11156104862Sruand thus not suited for a real two-column 11157104862Srumacro. 11158104862Sru@endExample 11159104862Sru 11160104862SruResult: 11161104862Sru 11162104862Sru@Example 11163104862SruThis is a small test which shows how the 11164104862Srurt request works in combination with mk. 11165104862Sru 11166104862SruStarting here, isn't robust 11167104862Srutext is typeset and thus not 11168104862Sruin two columns. suited for a 11169104862SruNote that this real two-column 11170104862Sruimplementation macro. 11171104862Sru@endExample 1117275584Sru@endDefreq 1117355839Sasmodai 1117469626SruThe following escapes give fine control of movements about the page. 1117555839Sasmodai 1117675584Sru@Defesc {\\v, ', e, '} 11177104862Sru@cindex vertical motion (@code{\v}) 11178104862Sru@cindex motion, vertical (@code{\v}) 11179104862SruMove vertically, usually from the current location on the page (if no 11180104862Sruabsolute position operator @samp{|} is used). The 11181114402Sruargument@tie{}@var{e} specifies the distance to move; positive is 11182104862Srudownwards and negative upwards. The default scaling indicator for this 11183104862Sruescape is @samp{v}. Beware, however, that @code{gtroff} continues text 11184104862Sruprocessing at the point where the motion ends, so you should always 11185104862Srubalance motions to avoid interference with text processing. 11186104862Sru 11187104862Sru@code{\v} doesn't trigger a trap. This can be quite useful; for example, 11188104862Sruconsider a page bottom trap macro which prints a marker in the margin to 11189104862Sruindicate continuation of a footnote or something similar. 1119075584Sru@endDefesc 1119155839Sasmodai 11192104862SruThere are some special-case escapes for vertical motion. 1119355839Sasmodai 11194104862Sru@Defesc {\\r, , , } 11195114402SruMove upwards@tie{}1@dmn{v}. 11196104862Sru@endDefesc 1119769626Sru 11198104862Sru@Defesc {\\u, , , } 11199114402SruMove upwards@tie{}.5@dmn{v}. 11200104862Sru@endDefesc 1120169626Sru 11202104862Sru@Defesc {\\d, , , } 11203114402SruMove down@tie{}.5@dmn{v}. 11204104862Sru@endDefesc 1120555839Sasmodai 1120675584Sru@Defesc {\\h, ', e, '} 11207104862Sru@cindex inserting horizontal space (@code{\h}) 11208104862Sru@cindex horizontal space (@code{\h}) 11209104862Sru@cindex space, horizontal (@code{\h}) 11210104862Sru@cindex horizontal motion (@code{\h}) 11211104862Sru@cindex motion, horizontal (@code{\h}) 11212104862SruMove horizontally, usually from the current location (if no absolute 11213114402Sruposition operator @samp{|} is used). The expression@tie{}@var{e} 11214104862Sruindicates how far to move: positive is rightwards and negative 11215104862Sruleftwards. The default scaling indicator for this escape is @samp{m}. 11216114402Sru 11217114402SruThis horizontal space is not discarded at the end of a line. To insert 11218114402Srudiscardable space of a certain length use the @code{ss} request. 1121975584Sru@endDefesc 1122055839Sasmodai 11221104862SruThere are a number of special-case escapes for horizontal motion. 1122255839Sasmodai 11223104862Sru@Defesc {\\@key{SP}, , , } 11224104862Sru@cindex space, unbreakable 11225104862Sru@cindex unbreakable space 1122675584SruAn unbreakable and unpaddable (i.e.@: not expanded during filling) 1122769626Sruspace. (Note: This is a backslash followed by a space.) 11228104862Sru@endDefesc 1122969626Sru 11230104862Sru@Defesc {\\~, , , } 1123175584SruAn unbreakable space that stretches like a normal inter-word space 1123275584Sruwhen a line is adjusted. 11233104862Sru@endDefesc 1123469626Sru 11235104862Sru@Defesc {\\|, , , } 11236104862SruA 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to 1123775584Sruzero). 11238104862Sru@endDefesc 1123969626Sru 11240104862Sru@Defesc {\\^, , , } 11241104862SruA 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to 1124275584Sruzero). 11243104862Sru@endDefesc 1124469626Sru 11245104862Sru@Defesc {\\0, , , } 11246104862Sru@cindex space, width of a digit (@code{\0}) 11247104862Sru@cindex digit width space (@code{\0}) 1124875584SruA space the size of a digit. 11249104862Sru@endDefesc 1125069626Sru 1125175584SruThe following string sets the @TeX{} logo: 1125269626Sru 1125375584Sru@Example 1125475584Sru.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 1125575584Sru@endExample 1125655839Sasmodai 11257104862Sru@DefescList {\\w, ', text, '} 11258104862Sru@DefregItem {st} 11259104862Sru@DefregItem {sb} 11260104862Sru@DefregItem {rst} 11261104862Sru@DefregItem {rsb} 11262104862Sru@DefregItem {ct} 11263104862Sru@DefregItem {ssc} 11264104862Sru@DefregListEnd {skw} 11265104862Sru@cindex width escape (@code{\w}) 11266104862SruReturn the width of the specified @var{text} in basic units. 1126775584SruThis allows horizontal movement based on the width of some 1126875584Sruarbitrary text (e.g.@: given as an argument to a macro). 1126955839Sasmodai 1127075584Sru@Example 11271104862SruThe length of the string `abc' is \w'abc'u. 11272104862Sru @result{} The length of the string `abc' is 72u. 1127375584Sru@endExample 1127455839Sasmodai 1127569626SruFont changes may occur in @var{text} which don't affect current 1127669626Srusettings. 1127755839Sasmodai 1127869626SruAfter use, @code{\w} sets several registers: 1127955839Sasmodai 1128055839Sasmodai@table @code 1128155839Sasmodai@item st 1128269626Sru@itemx sb 11283104862SruThe highest and lowest point of the baseline, respectively, in @var{text}. 1128469626Sru 1128555839Sasmodai@item rst 1128669626Sru@itemx rsb 1128755839SasmodaiLike the @code{st} and @code{sb} registers, but takes account of the 11288104862Sruheights and depths of glyphs. With other words, this gives the 11289114402Sruhighest and lowest point of @var{text}. Values below the baseline are 11290114402Srunegative. 1129169626Sru 1129255839Sasmodai@item ct 11293104862SruDefines the kinds of glyphs occurring in @var{text}: 1129469626Sru 1129555839Sasmodai@table @asis 1129655839Sasmodai@item 0 11297104862Sruonly short glyphs, no descenders or tall glyphs. 1129869626Sru 1129955839Sasmodai@item 1 1130075584Sruat least one descender. 1130169626Sru 1130255839Sasmodai@item 2 11303104862Sruat least one tall glyph. 1130469626Sru 1130555839Sasmodai@item 3 11306104862Sruat least one each of a descender and a tall glyph. 1130755839Sasmodai@end table 1130869626Sru 1130955839Sasmodai@item ssc 1131069626SruThe amount of horizontal space (possibly negative) that should be added 11311104862Sruto the last glyph before a subscript. 1131269626Sru 1131355839Sasmodai@item skw 11314104862SruHow far to right of the center of the last glyph in the @code{\w} 1131575584Sruargument, the center of an accent from a roman font should be placed 11316104862Sruover that glyph. 1131755839Sasmodai@end table 1131875584Sru@endDefesc 1131955839Sasmodai 11320104862Sru@DefescList {\\k, , p, } 11321151497Sru@DefescItem {\\k, @Lparen{}, ps, } 11322151497Sru@DefescListEnd {\\k, @Lbrack{}, position, @Rbrack{}} 11323104862Sru@cindex saving horizontal input line position (@code{\k}) 11324104862Sru@cindex horizontal input line position, saving (@code{\k}) 11325104862Sru@cindex input line position, horizontal, saving (@code{\k}) 11326104862Sru@cindex position, horizontal input line, saving (@code{\k}) 11327104862Sru@cindex line, input, horizontal position, saving (@code{\k}) 11328104862SruStore the current horizontal position in the @emph{input} line in 11329114402Srunumber register with name @var{position} (one-character name@tie{}@var{p}, 11330104862Srutwo-character name @var{ps}). Use this, for example, to return to the 11331104862Srubeginning of a string for highlighting or other decoration. 1133275584Sru@endDefesc 1133369626Sru 11334104862Sru@Defreg {hp} 11335104862Sru@cindex horizontal input line position register (@code{hp}) 11336104862Sru@cindex input line, horizontal position, register (@code{hp}) 11337104862Sru@cindex position, horizontal, in input line, register (@code{hp}) 11338104862Sru@cindex line, input, horizontal position, register (@code{hp}) 11339104862SruThe current horizontal position at the input line. 11340104862Sru@endDefreg 11341104862Sru 1134275584Sru@Defreg {.k} 11343104862Sru@cindex horizontal output line position register (@code{.k}) 11344104862Sru@cindex output line, horizontal position, register (@code{.k}) 11345104862Sru@cindex position, horizontal, in output line, register (@code{.k}) 11346104862Sru@cindex line, output, horizontal position, register (@code{.k}) 1134775584SruA read-only number register containing the current horizontal output 11348151497Sruposition (relative to the current indentation). 1134975584Sru@endDefreg 1135055839Sasmodai 11351114402Sru@Defesc {\\o, ', abc, '} 11352104862Sru@cindex overstriking glyphs (@code{\o}) 11353104862Sru@cindex glyphs, overstriking (@code{\o}) 11354104862SruOverstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs 11355104862Sruare centered, and the resulting spacing is the largest width of the 11356104862Sruaffected glyphs. 11357104862Sru@endDefesc 1135855839Sasmodai 11359104862Sru@Defesc {\\z, , g, , } 11360104862Sru@cindex zero-width printing (@code{\z}, @code{\Z}) 11361104862Sru@cindex printing, zero-width (@code{\z}, @code{\Z}) 11362104862SruPrint glyph @var{g} with zero width, i.e., without spacing. Use 11363104862Sruthis to overstrike glyphs left-aligned. 11364104862Sru@endDefesc 1136555839Sasmodai 11366104862Sru@Defesc {\\Z, ', anything, '} 11367104862Sru@cindex zero-width printing (@code{\z}, @code{\Z}) 11368104862Sru@cindex printing, zero-width (@code{\z}, @code{\Z}) 11369104862SruPrint @var{anything}, then restore the horizontal and vertical position. 11370104862SruThe argument may not contain tabs or leaders. 11371104862Sru 11372104862SruThe following is an example of a strike-through macro: 11373104862Sru 11374104862Sru@Example 11375104862Sru.de ST 11376104862Sru.nr ww \w'\\$1' 11377104862Sru\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1 11378104862Sru.. 11379104862Sru. 11380104862SruThis is 11381104862Sru.ST "a test" 11382104862Sruan actual emergency! 11383104862Sru@endExample 11384104862Sru@endDefesc 11385104862Sru 11386104862Sru 1138769626Sru@c ===================================================================== 1138855839Sasmodai 1138975584Sru@node Drawing Requests, Traps, Page Motions, gtroff Reference 1139069626Sru@section Drawing Requests 1139169626Sru@cindex drawing requests 1139269626Sru@cindex requests for drawing 1139369626Sru 1139469626Sru@code{gtroff} provides a number of ways to draw lines and other figures 1139569626Sruon the page. Used in combination with the page motion commands (see 1139669626Sru@ref{Page Motions}, for more info), a wide variety of figures can be 1139769626Srudrawn. However, for complex drawings these operations can be quite 1139869626Srucumbersome, and it may be wise to use graphic preprocessors like 1139969626Sru@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 1140069626Sruinformation. 1140169626Sru 1140255839SasmodaiAll drawing is done via escapes. 1140355839Sasmodai 11404114402Sru@DefescList {\\l, ', l, '} 11405114402Sru@DefescListEnd {\\l, ', lg, '} 11406104862Sru@cindex drawing horizontal lines (@code{\l}) 11407104862Sru@cindex horizontal line, drawing (@code{\l}) 11408104862Sru@cindex line, horizontal, drawing (@code{\l}) 11409104862SruDraw a line horizontally. @var{l} is the length of the line to be 11410104862Srudrawn. If it is positive, start the line at the current location and 11411104862Srudraw to the right; its end point is the new current location. Negative 11412104862Sruvalues are handled differently: The line starts at the current location 11413104862Sruand draws to the left, but the current location doesn't move. 1141455839Sasmodai 11415104862Sru@var{l} can also be specified absolutely (i.e.@: with a leading 11416104862Sru@samp{|}) which draws back to the beginning of the input line. 11417104862SruDefault scaling indicator is @samp{m}. 1141869626Sru 11419104862Sru@cindex underscore glyph (@code{\[ru]}) 11420104862Sru@cindex glyph, underscore (@code{\[ru]}) 11421104862Sru@cindex line drawing glyph 11422104862Sru@cindex glyph, for line drawing 11423114402SruThe optional second parameter@tie{}@var{g} is a glyph to draw the line 1142475584Sruwith. If this second argument is not specified, @code{gtroff} uses 11425104862Sruthe underscore glyph, @code{\[ru]}. 1142655839Sasmodai 11427104862Sru@cindex zero width space character (@code{\&}) 11428104862Sru@cindex character, zero width space (@code{\&}) 11429104862Sru@cindex space character, zero width (@code{\&}) 1143069626SruTo separate the two arguments (to prevent @code{gtroff} from 11431104862Sruinterpreting a drawing glyph as a scaling indicator if the glyph is 11432104862Srurepresented by a single character) use @code{\&}. 1143355839Sasmodai 1143469626SruHere a small useful example: 1143555839Sasmodai 1143675584Sru@Example 1143755839Sasmodai.de box 11438104862Sru\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 1143955839Sasmodai.. 1144075584Sru@endExample 1144155839Sasmodai 1144269626Sru@noindent 1144369626SruNote that this works by outputting a box rule (a vertical line), then 11444104862Sruthe text given as an argument and then another box rule. Finally, the 11445104862Sruline drawing escapes both draw from the current location to the 11446104862Srubeginning of the @emph{input} line -- this works because the line 11447104862Srulength is negative, not moving the current point. 1144875584Sru@endDefesc 1144955839Sasmodai 11450114402Sru@DefescList {\\L, ', l, '} 11451114402Sru@DefescListEnd {\\L, ', lg, '} 11452104862Sru@cindex drawing vertical lines (@code{\L}) 11453104862Sru@cindex vertical line drawing (@code{\L}) 11454104862Sru@cindex line, vertical, drawing (@code{\L}) 11455104862Sru@cindex line drawing glyph 11456104862Sru@cindex glyph for line drawing 11457104862Sru@cindex box rule glyph (@code{\[br]}) 11458104862Sru@cindex glyph, box rule (@code{\[br]}) 11459104862SruDraw vertical lines. Its parameters are 11460104862Srusimilar to the @code{\l} escape, except that the default scaling 11461104862Sruindicator is @samp{v}. The movement is downwards for positive values, 11462104862Sruand upwards for negative values. The default glyph is the box rule 11463104862Sruglyph, @code{\[br]}. As with the vertical motion escapes, text 11464104862Sruprocessing blindly continues where the line ends. 1146555839Sasmodai 11466104862Sru@Example 11467104862SruThis is a \L'3v'test. 11468104862Sru@endExample 1146969626Sru 11470104862Sru@noindent 11471104862SruHere the result, produced with @code{grotty}. 11472104862Sru 1147375584Sru@Example 11474104862SruThis is a 11475104862Sru | 11476104862Sru | 11477104862Sru |test. 1147875584Sru@endExample 1147975584Sru@endDefesc 1148055839Sasmodai 1148175584Sru@Defesc {\\D, ', command arg @dots{}, '} 1148275584SruThe @code{\D} escape provides a variety of drawing functions. 11483104862SruNote that on character devices, only vertical and horizontal lines are 11484104862Srusupported within @code{grotty}; other devices may only support a subset 11485104862Sruof the available drawing functions. 1148655839Sasmodai 11487104862SruThe default scaling indicator for all subcommands of @code{\D} is 11488104862Sru@samp{m} for horizontal distances and @samp{v} for vertical ones. 11489104862SruExceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} 11490114402Sruwhich use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}} 11491114402Sruwhich arguments are treated similar to the @code{defcolor} request. 11492104862Sru 1149355839Sasmodai@table @code 1149469626Sru@item \D'l @var{dx} @var{dy}' 11495104862Sru@cindex line, drawing (@w{@code{\D'l @dots{}'}}) 11496104862Sru@cindex drawing a line (@w{@code{\D'l @dots{}'}}) 1149769626SruDraw a line from the current location to the relative point specified by 11498151497Sru(@var{dx},@var{dy}), where positive values mean down and right, 11499151497Srurespectively. The end point of the line is the new current location. 1150055839Sasmodai 11501104862SruThe following example is a macro for creating a box around a text string; 11502104862Srufor simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}. 1150369626Sru 1150475584Sru@Example 11505104862Sru.de BOX 11506104862Sru. nr @@wd \w'\\$1' 11507104862Sru\h'.2m'\ 11508104862Sru\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11509104862Sru\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 11510104862Sru\D'l (\\n[@@wd]u + .4m) 0'\ 11511104862Sru\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 11512104862Sru\D'l -(\\n[@@wd]u + .4m) 0'\ 11513104862Sru\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11514104862Sru\\$1\ 11515104862Sru\h'.2m' 11516104862Sru.. 1151775584Sru@endExample 1151855839Sasmodai 11519104862Sru@noindent 11520104862SruFirst, the width of the string is stored in register @code{@@wd}. Then, 11521104862Srufour lines are drawn to form a box, properly offset by the box margin. 11522104862SruThe registers @code{rst} and @code{rsb} are set by the @code{\w} escape, 11523104862Srucontaining the largest height and depth of the whole string. 11524104862Sru 1152555839Sasmodai@item \D'c @var{d}' 11526104862Sru@cindex circle, drawing (@w{@code{\D'c @dots{}'}}) 11527104862Sru@cindex drawing a circle (@w{@code{\D'c @dots{}'}}) 11528114402SruDraw a circle with a diameter of@tie{}@var{d} with the leftmost point at the 11529114402Srucurrent position. After drawing, the current location is positioned at the 11530114402Srurightmost point of the circle. 1153169626Sru 1153255839Sasmodai@item \D'C @var{d}' 11533104862Sru@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) 11534104862Sru@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) 11535104862Sru@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) 11536114402SruDraw a solid circle with the same parameters and behaviour as an outlined 11537114402Srucircle. No outline is drawn. 1153869626Sru 11539104862Sru@item \D'e @var{x} @var{y}' 11540104862Sru@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) 11541104862Sru@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) 11542104862SruDraw an ellipse with a horizontal diameter of @var{x} and a vertical 11543104862Srudiameter of @var{y} with the leftmost point at the current position. 11544114402SruAfter drawing, the current location is positioned at the rightmost point of 11545114402Sruthe ellipse. 1154669626Sru 11547104862Sru@item \D'E @var{x} @var{y}' 11548104862Sru@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) 11549104862Sru@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) 11550104862Sru@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) 11551114402SruDraw a solid ellipse with the same parameters and behaviour as an 11552114402Sruoutlined ellipse. No outline is drawn. 1155369626Sru 1155455839Sasmodai@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 11555104862Sru@cindex arc, drawing (@w{@code{\D'a @dots{}'}}) 11556104862Sru@cindex drawing an arc (@w{@code{\D'a @dots{}'}}) 1155755839SasmodaiDraw an arc clockwise from the current location through the two 11558104862Sruspecified relative locations (@var{dx1},@var{dy1}) and 11559104862Sru(@var{dx2},@var{dy2}). The coordinates of the first point are relative 11560104862Sruto the current position, and the coordinates of the second point are 11561114402Srurelative to the first point. After drawing, the current position is moved 11562114402Sruto the final point of the arc. 1156369626Sru 11564104862Sru@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11565104862Sru@cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) 11566104862Sru@cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) 11567104862SruDraw a spline from the current location to the relative point 11568104862Sru(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. 11569114402SruThe current position is moved to the terminal point of the drawn curve. 1157069626Sru 1157155839Sasmodai@item \D'f @var{n}' 11572104862Sru@cindex gray shading (@w{@code{\D'f @dots{}'}}) 11573104862Sru@cindex shading filled objects (@w{@code{\D'f @dots{}'}}) 11574114402SruSet the shade of gray to be used for filling solid objects to@tie{}@var{n}; 11575114402Sru@var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0 1157669626Srucorresponds solid white and 1000 to solid black, and values in between 1157769626Srucorrespond to intermediate shades of gray. This applies only to solid 11578104862Srucircles, solid ellipses, and solid polygons. By default, a level of 11579104862Sru1000 is used. 1158055839Sasmodai 11581114402SruDespite of being silly, the current point is moved horizontally to the 11582114402Sruright by@tie{}@var{n}. 11583114402Sru 11584114402Sru@cindex @w{@code{\D'f @dots{}'}} and horizontal resolution 11585114402SruDon't use this command! It has the serious drawback that it will be 11586114402Srualways rounded to the next integer multiple of the horizontal resolution 11587114402Sru(the value of the @code{hor} keyword in the @file{DESC} file). Use 11588114402Sru@code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead. 11589114402Sru 11590104862Sru@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11591104862Sru@cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) 11592104862Sru@cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) 11593104862SruDraw a polygon from the current location to the relative position 11594104862Sru(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. 11595104862SruWhen the specified data points are exhausted, a line is drawn back 11596114402Sruto the starting point. The current position is changed by adding the 11597114402Srusum of all arguments with odd index to the actual horizontal position and 11598114402Sruthe even ones to the vertical position. 1159969626Sru 11600104862Sru@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11601104862Sru@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) 11602104862Sru@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) 11603104862Sru@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) 11604114402SruDraw a solid polygon with the same parameters and behaviour as an 11605114402Sruoutlined polygon. No outline is drawn. 1160655839Sasmodai 11607104862SruHere a better variant of the box macro to fill the box with some color. 11608104862SruNote that the box must be drawn before the text since colors in 11609104862Sru@code{gtroff} are not transparent; the filled polygon would hide the 11610104862Srutext completely. 1161169626Sru 1161275584Sru@Example 11613104862Sru.de BOX 11614104862Sru. nr @@wd \w'\\$1' 11615104862Sru\h'.2m'\ 11616104862Sru\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11617104862Sru\M[lightcyan]\ 11618104862Sru\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 11619104862Sru (\\n[@@wd]u + .4m) 0 \ 11620104862Sru 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 11621104862Sru -(\\n[@@wd]u + .4m) 0'\ 11622104862Sru\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11623104862Sru\M[]\ 11624104862Sru\\$1\ 11625104862Sru\h'.2m' 11626104862Sru.. 1162775584Sru@endExample 1162855839Sasmodai 1162955839Sasmodai@item \D't @var{n}' 11630104862Sru@cindex line thickness (@w{@code{\D't @dots{}'}}) 11631104862Sru@cindex thickness of lines (@w{@code{\D't @dots{}'}}) 11632114402SruSet the current line thickness to @var{n}@tie{}machine units. A value of 1163369626Sruzero selects the smallest available line thickness. A negative value 1163469626Srumakes the line thickness proportional to the current point size (this is 11635104862Sruthe default behaviour of @acronym{AT&T} @code{troff}). 11636114402Sru 11637114402SruDespite of being silly, the current point is moved horizontally to the 11638114402Sruright by@tie{}@var{n}. 11639114402Sru 11640114402Sru@item \D'F@var{scheme} @var{color_components}' 11641114402Sru@cindex unnamed fill colors (@code{\D'F@dots{}'}) 11642114402Sru@cindex fill colors, unnamed (@code{\D'F@dots{}'}) 11643114402Sru@cindex colors, fill, unnamed (@code{\D'F@dots{}'}) 11644114402SruChange current fill color. @var{scheme} is a single letter denoting the 11645114402Srucolor scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g} 11646114402Sru(gray), or @samp{d} (default color). The color components use exactly 11647114402Sruthe same syntax as in the @code{defcolor} request (@pxref{Colors}); the 11648114402Srucommand @code{\D'Fd'} doesn't take an argument. 11649114402Sru 11650114402Sru@emph{No} position changing! 11651114402Sru 11652114402SruExamples: 11653114402Sru 11654114402Sru@Example 11655114402Sru@endExample 11656114402Sru\D'Fg .3' \" same gray as \D'f 700' 11657114402Sru\D'Fr #0000ff' \" blue 1165855839Sasmodai@end table 1165975584Sru@endDefesc 1166055839Sasmodai 11661104862Sru@xref{Graphics Commands}. 11662104862Sru 1166375584Sru@Defesc {\\b, ', string, '} 11664104862Sru@cindex pile, glyph (@code{\b}) 11665104862Sru@cindex glyph pile (@code{\b}) 11666104862Sru@cindex stacking glyphs (@code{\b}) 11667104862Sru@dfn{Pile} a sequence of glyphs vertically, and center it vertically 11668104862Sruon the current line. Use it to build large brackets and braces. 1166955839Sasmodai 11670104862SruHere an example how to create a large opening brace: 11671104862Sru 1167275584Sru@Example 11673104862Sru\b'\[lt]\[bv]\[lk]\[bv]\[lb]' 1167475584Sru@endExample 11675104862Sru 11676104862Sru@cindex @code{\b}, limitations 11677104862Sru@cindex limitations of @code{\b} escape 11678104862SruThe first glyph is on the top, the last glyph in @var{string} is 11679104862Sruat the bottom. Note that @code{gtroff} separates the glyphs 11680104862Sruvertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m} 11681104862Sruabove the current baseline; the largest glyph width is used as the 11682104862Sruwidth for the whole object. This rather unflexible positioning 11683104862Srualgorithm doesn't work with @option{-Tdvi} since the bracket pieces vary 11684104862Sruin height for this device. Instead, use the @code{eqn} preprocessor. 11685104862Sru 11686104862Sru@xref{Manipulating Spacing}, how to adjust the vertical spacing with 11687104862Sruthe @code{\x} escape. 1168875584Sru@endDefesc 1168955839Sasmodai 1169055839Sasmodai 1169169626Sru@c ===================================================================== 1169255839Sasmodai 1169375584Sru@node Traps, Diversions, Drawing Requests, gtroff Reference 1169455839Sasmodai@section Traps 1169555839Sasmodai@cindex traps 1169655839Sasmodai 1169775584Sru@dfn{Traps} are locations, which, when reached, call a specified 1169869626Srumacro. These traps can occur at a given location on the page, at a 11699104862Srugiven location in the current diversion, at a blank line, 11700104862Sruafter a certain number of input lines, or at the end of input. 1170155839Sasmodai 11702104862Sru@cindex planting a trap 11703104862Sru@cindex trap, planting 11704104862SruSetting a trap is also called @dfn{planting}. 11705104862Sru@cindex trap, springing 11706104862Sru@cindex springing a trap 11707104862SruIt is also said that a trap is @dfn{sprung} if the associated macro 11708104862Sruis executed. 11709104862Sru 1171055839Sasmodai@menu 1171175584Sru* Page Location Traps:: 1171275584Sru* Diversion Traps:: 1171375584Sru* Input Line Traps:: 11714104862Sru* Blank Line Traps:: 1171575584Sru* End-of-input Traps:: 1171655839Sasmodai@end menu 1171755839Sasmodai 1171869626Sru@c --------------------------------------------------------------------- 1171969626Sru 1172055839Sasmodai@node Page Location Traps, Diversion Traps, Traps, Traps 1172155839Sasmodai@subsection Page Location Traps 1172255839Sasmodai@cindex page location traps 1172355839Sasmodai@cindex traps, page location 1172455839Sasmodai 1172575584Sru@dfn{Page location traps} perform an action when @code{gtroff} 11726104862Srureaches or passes a certain vertical location on the page. Page 11727104862Srulocation traps have a variety of purposes, including: 1172855839Sasmodai 1172975584Sru@itemize 1173075584Sru@item 1173175584Srusetting headers and footers 1173275584Sru 1173375584Sru@item 1173475584Srusetting body text in multiple columns 1173575584Sru 1173675584Sru@item 1173775584Srusetting footnotes 1173875584Sru@end itemize 1173975584Sru 11740104862Sru@DefreqList {vpt, flag} 11741104862Sru@DefregListEnd {.vpt} 11742104862Sru@cindex enabling vertical position traps (@code{vpt}) 11743104862Sru@cindex vertical position traps, enabling (@code{vpt}) 11744104862Sru@cindex vertical position trap enable register (@code{.vpt}) 11745104862SruEnable vertical position traps if @var{flag} is non-zero, or disables 1174675584Sruthem otherwise. Vertical position traps are traps set by the @code{wh} 1174775584Sruor @code{dt} requests. Traps set by the @code{it} request are not 1174875584Sruvertical position traps. The parameter that controls whether vertical 1174975584Sruposition traps are enabled is global. Initially vertical position traps 1175075584Sruare enabled. The current setting of this is available in the 1175175584Sru@code{.vpt} read-only number register. 11752114402Sru 11753114402SruNote that a page can't be ejected if @code{vpt} is set to zero. 1175475584Sru@endDefreq 1175575584Sru 11756104862Sru@Defreq {wh, dist [@Var{macro}]} 11757114402SruSet a page location trap. Non-negative values for @var{dist} set 1175875584Sruthe trap relative to the top of the page; negative values set 11759104862Sruthe trap relative to the bottom of the page. Default scaling 11760104862Sruindicator is @samp{v}. 1176175584Sru 1176275584Sru@var{macro} is the name of the macro to execute when the 11763104862Srutrap is sprung. If @var{macro} is missing, remove the first trap 11764104862Sru(if any) at @var{dist}. 1176575584Sru 1176669626Sru@cindex page headers 1176769626Sru@cindex page footers 1176869626Sru@cindex headers 1176969626Sru@cindex footers 1177075584SruThe following is a simple example of how many macro packages 1177175584Sruset headers and footers. 1177255839Sasmodai 1177375584Sru@Example 1177469626Sru.de hd \" Page header 11775104862Sru' sp .5i 11776104862Sru. tl 'Title''date' 11777104862Sru' sp .3i 1177855839Sasmodai.. 11779104862Sru. 1178069626Sru.de fo \" Page footer 11781104862Sru' sp 1v 11782104862Sru. tl ''%'' 11783104862Sru' bp 1178455839Sasmodai.. 11785104862Sru. 1178669626Sru.wh 0 hd \" trap at top of the page 1178769626Sru.wh -1i fo \" trap one inch from bottom 1178875584Sru@endExample 11789104862Sru 11790104862SruA trap at or below the bottom of the page is ignored; it can be made 11791104862Sruactive by either moving it up or increasing the page length so that the 11792104862Srutrap is on the page. 11793104862Sru 11794104862SruIt is possible to have more than one trap at the same location; to do so, 11795104862Sruthe traps must be defined at different locations, then moved together with 11796104862Sruthe @code{ch} request; otherwise the second trap would replace the first 11797104862Sruone. Earlier defined traps hide later defined traps if moved to the same 11798114402Sruposition (the many empty lines caused by the @code{bp} request are omitted 11799114402Sruin the following example): 11800104862Sru 11801104862Sru@Example 11802104862Sru.de a 11803104862Sru. nop a 11804104862Sru.. 11805104862Sru.de b 11806104862Sru. nop b 11807104862Sru.. 11808104862Sru.de c 11809104862Sru. nop c 11810104862Sru.. 11811104862Sru. 11812104862Sru.wh 1i a 11813104862Sru.wh 2i b 11814104862Sru.wh 3i c 11815104862Sru.bp 11816104862Sru @result{} a b c 11817104862Sru@endExample 11818104862Sru@Example 11819104862Sru.ch b 1i 11820104862Sru.ch c 1i 11821104862Sru.bp 11822104862Sru @result{} a 11823104862Sru@endExample 11824104862Sru@Example 11825104862Sru.ch a 0.5i 11826104862Sru.bp 11827104862Sru @result{} a b 11828104862Sru@endExample 1182975584Sru@endDefreq 1183055839Sasmodai 1183175584Sru@Defreg {.t} 11832104862Sru@cindex distance to next trap register (@code{.t}) 11833104862Sru@cindex trap, distance, register (@code{.t}) 1183475584SruA read-only number register holding the distance to the next trap. 11835104862Sru 11836104862SruIf there are no traps between the current position and the bottom of the 11837104862Srupage, it contains the distance to the page bottom. In a diversion, the 11838104862Srudistance to the page bottom is infinite (the returned value is the biggest 11839104862Sruinteger which can be represented in @code{groff}) if there are no diversion 11840104862Srutraps. 1184175584Sru@endDefreg 1184255839Sasmodai 11843114402Sru@Defreq {ch, macro [@Var{dist}]} 11844104862Sru@cindex changing trap location (@code{ch}) 11845104862Sru@cindex trap, changing location (@code{ch}) 11846104862SruChange the location of a trap. 1184775584SruThe first argument is the name of the macro to be invoked at 1184875584Sruthe trap, and the second argument is the new location for the trap 11849114402Sru(note that the parameters are specified in opposite order as in the 11850114402Sru@code{wh} request). This is useful for building up footnotes in a 11851114402Srudiversion to allow more space at the bottom of the page for them. 1185255839Sasmodai 11853104862SruDefault scaling indicator for @var{dist} is @samp{v}. If @var{dist} 11854104862Sruis missing, the trap is removed. 11855104862Sru 1185669626Sru@c XXX 1185769626Sru 1185869626Sru@ignore 1185975584Sru@Example 1186055839Sasmodai... (simplified) footnote example ... 1186175584Sru@endExample 1186269626Sru@end ignore 1186375584Sru@endDefreq 1186455839Sasmodai 1186575584Sru@Defreg {.ne} 1186675584SruThe read-only number register @code{.ne} contains the amount of space 1186775584Sruthat was needed in the last @code{ne} request that caused a trap to be 1186875584Srusprung. Useful in conjunction with the @code{.trunc} register. 1186975584Sru@xref{Page Control}, for more information. 11870114402Sru 11871114402SruSince the @code{.ne} register is only set by traps it doesn't make 11872114402Srumuch sense to use it outside of trap macros. 1187375584Sru@endDefreg 1187455839Sasmodai 1187575584Sru@Defreg {.trunc} 11876104862Sru@cindex @code{ne} request, and the @code{.trunc} register 11877104862Sru@cindex truncated vertical space register (@code{.trunc}) 1187875584SruA read-only register containing the amount of vertical space truncated 1187975584Sruby the most recently sprung vertical position trap, or, if the trap was 1188075584Srusprung by an @code{ne} request, minus the amount of vertical motion 1188175584Sruproduced by the @code{ne} request. In other words, at the point a trap 1188275584Sruis sprung, it represents the difference of what the vertical position 1188375584Sruwould have been but for the trap, and what the vertical position 1188475584Sruactually is. 11885114402Sru 11886151497SruSince the @code{.trunc} register is only set by traps it doesn't make 11887114402Srumuch sense to use it outside of trap macros. 1188875584Sru@endDefreg 1188955839Sasmodai 11890114402Sru@Defreg {.pe} 11891114402Sru@cindex @code{bp} request, and traps (@code{.pe}) 11892114402Sru@cindex traps, sprung by @code{bp} request (@code{.pe}) 11893114402Sru@cindex page ejecting register (@code{.pe}) 11894114402SruA read-only register which is set to@tie{}1 while a page is ejected with 11895114402Sruthe @code{bp} request (or by the end of input). 11896114402Sru 11897114402SruOutside of traps this register is always zero. In the following example, 11898114402Sruonly the second call to@tie{}@code{x} is caused by @code{bp}. 11899114402Sru 11900114402Sru@Example 11901114402Sru.de x 11902114402Sru\&.pe=\\n[.pe] 11903114402Sru.br 11904114402Sru.. 11905114402Sru.wh 1v x 11906114402Sru.wh 4v x 11907114402SruA line. 11908114402Sru.br 11909114402SruAnother line. 11910114402Sru.br 11911114402Sru @result{} A line. 11912151497Sru .pe=0 11913151497Sru Another line. 11914114402Sru 11915151497Sru .pe=1 11916114402Sru@endExample 11917114402Sru@endDefreg 11918114402Sru 11919114402Sru@cindex diversions, and traps 11920114402Sru@cindex traps, and diversions 11921114402SruAn important fact to consider while designing macros is that diversions and 11922114402Srutraps do not interact normally. For example, if a trap invokes a header 11923114402Srumacro (while outputting a diversion) which tries to change the font on the 11924114402Srucurrent page, the effect will not be visible before the diversion has 11925114402Srucompletely been printed (except for input protected with @code{\!} or 11926114402Sru@code{\?}) since the data in the diversion is already formatted. In most 11927114402Srucases, this is not the expected behaviour. 11928114402Sru 1192969626Sru@c --------------------------------------------------------------------- 1193055839Sasmodai 1193155839Sasmodai@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 1193255839Sasmodai@subsection Diversion Traps 1193355839Sasmodai@cindex diversion traps 1193455839Sasmodai@cindex traps, diversion 1193555839Sasmodai 11936151497Sru@Defreq {dt, [@Var{dist} @Var{macro}]} 11937104862Sru@cindex @code{.t} register, and diversions 11938104862Sru@cindex setting diversion trap (@code{dt}) 11939104862Sru@cindex diversion trap, setting (@code{dt}) 11940104862Sru@cindex trap, diversion, setting (@code{dt}) 11941104862SruSet a trap @emph{within} a diversion. 11942104862Sru@var{dist} is the location of the trap 11943114402Sru(identical to the @code{wh} request; default scaling indicator is 11944151497Sru@samp{v}) and @var{macro} is the name of the macro to be invoked. 11945151497SruIf called without arguments, the diversion trap is removed. 11946151497Sru 11947151497SruNote that there exists only a single diversion trap. 11948151497Sru 11949151497SruThe number register @code{.t} still works within diversions. 1195055839Sasmodai@xref{Diversions}, for more information. 1195175584Sru@endDefreq 1195255839Sasmodai 1195369626Sru@c --------------------------------------------------------------------- 1195469626Sru 11955104862Sru@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps 1195655839Sasmodai@subsection Input Line Traps 1195755839Sasmodai@cindex input line traps 1195855839Sasmodai@cindex traps, input line 1195955839Sasmodai 11960104862Sru@DefreqList {it, n macro} 11961104862Sru@DefreqItem {itc, n macro} 11962104862Sru@cindex setting input line trap (@code{it}) 11963104862Sru@cindex input line trap, setting (@code{it}) 11964104862Sru@cindex trap, input line, setting (@code{it}) 11965104862SruSet an input line trap. 11966114402Sru@var{n}@tie{}is the number of lines of input which may be read before 11967104862Sruspringing the trap, @var{macro} is the macro to be invoked. 1196869626SruRequest lines are not counted as input lines. 1196969626Sru 1197075584SruFor example, one possible use is to have a macro which prints the 11971114402Srunext @var{n}@tie{}lines in a bold font. 1197255839Sasmodai 1197375584Sru@Example 1197455839Sasmodai.de B 11975104862Sru. it \\$1 B-end 11976104862Sru. ft B 1197755839Sasmodai.. 11978104862Sru. 1197955839Sasmodai.de B-end 11980104862Sru. ft R 1198155839Sasmodai.. 1198275584Sru@endExample 11983104862Sru 11984104862Sru@cindex input line traps and interrupted lines (@code{itc}) 11985104862Sru@cindex interrupted lines and input line traps (@code{itc}) 11986104862Sru@cindex traps, input line, and interrupted lines (@code{itc}) 11987104862Sru@cindex lines, interrupted, and input line traps (@code{itc}) 11988114402SruThe @code{itc} request is identical 11989114402Sruexcept that an interrupted text line (ending with @code{\c}) 11990114402Sruis not counted as a separate line. 11991104862Sru 11992104862SruBoth requests are associated with the current environment 11993104862Sru(@pxref{Environments}); switching to another environment disables the 11994104862Srucurrent input trap, and going back reactivates it, restoring the number 11995104862Sruof already processed lines. 1199675584Sru@endDefreq 1199755839Sasmodai 1199869626Sru@c --------------------------------------------------------------------- 1199969626Sru 12000104862Sru@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps 12001104862Sru@subsection Blank Line Traps 12002104862Sru@cindex blank line traps 12003104862Sru@cindex traps, blank line 12004104862Sru 12005104862Sru@Defreq {blm, macro} 12006104862Sru@cindex blank line macro (@code{blm}) 12007104862SruSet a blank line trap. 12008104862Sru@code{gtroff} executes @var{macro} when it encounters a blank line in 12009104862Sruthe input file. 12010104862Sru@endDefreq 12011104862Sru 12012104862Sru@c --------------------------------------------------------------------- 12013104862Sru 12014104862Sru@node End-of-input Traps, , Blank Line Traps, Traps 1201555839Sasmodai@subsection End-of-input Traps 1201655839Sasmodai@cindex end-of-input traps 1201755839Sasmodai@cindex traps, end-of-input 1201855839Sasmodai 1201975584Sru@Defreq {em, macro} 12020104862Sru@cindex setting end-of-input trap (@code{em}) 12021104862Sru@cindex end-of-input trap, setting (@code{em}) 12022104862Sru@cindex trap, end-of-input, setting (@code{em}) 12023104862Sru@cindex end-of-input macro (@code{em}) 12024104862Sru@cindex macro, end-of-input (@code{em}) 12025104862SruSet a trap at the end of input. @var{macro} is executed after the 12026104862Srulast line of the input file has been processed. 1202755839Sasmodai 1202869626SruFor example, if the document had to have a section at the bottom of the 1202969626Srulast page for someone to approve it, the @code{em} request could be 1203069626Sruused. 1203155839Sasmodai 1203275584Sru@Example 1203355839Sasmodai.de approval 12034104862Sru. ne 5v 12035104862Sru. sp |(\\n[.t] - 6v) 12036104862Sru. in +4i 12037104862Sru. lc _ 12038104862Sru. br 1203955839SasmodaiApproved:\t\a 12040104862Sru. sp 1204155839SasmodaiDate:\t\t\a 1204255839Sasmodai.. 12043104862Sru. 1204455839Sasmodai.em approval 1204575584Sru@endExample 1204675584Sru@endDefreq 1204755839Sasmodai 1204855839Sasmodai 1204969626Sru@c ===================================================================== 1205069626Sru 1205175584Sru@node Diversions, Environments, Traps, gtroff Reference 1205255839Sasmodai@section Diversions 1205355839Sasmodai@cindex diversions 1205455839Sasmodai 1205569626SruIn @code{gtroff} it is possible to @dfn{divert} text into a named 1205669626Srustorage area. Due to the similarity to defining macros it is sometimes 1205769626Srusaid to be stored in a macro. This is used for saving text for output 1205869626Sruat a later time, which is useful for keeping blocks of text on the same 12059104862Srupage, footnotes, tables of contents, and indices. 1206055839Sasmodai 12061104862Sru@cindex top-level diversion 12062104862Sru@cindex diversion, top-level 12063104862SruFor orthogonality it is said that @code{gtroff} is in the @dfn{top-level 12064104862Srudiversion} if no diversion is active (i.e., the data is diverted to the 12065104862Sruoutput device). 1206675584Sru 12067104862Sru@DefreqList {di, macro} 12068104862Sru@DefreqListEnd {da, macro} 12069104862Sru@cindex beginning diversion (@code{di}) 12070104862Sru@cindex diversion, beginning (@code{di}) 12071104862Sru@cindex ending diversion (@code{di}) 12072104862Sru@cindex diversion, ending (@code{di}) 12073104862Sru@cindex appending to a diversion (@code{da}) 12074104862Sru@cindex diversion, appending (@code{da}) 12075104862SruBegin a diversion. Like the @code{de} 1207669626Srurequest, it takes an argument of a macro name to divert subsequent text 1207775584Sruinto. The @code{da} macro appends to an existing diversion. 1207855839Sasmodai 1207975584Sru@code{di} or @code{da} without an argument ends the diversion. 12080104862Sru@endDefreq 1208169626Sru 12082104862Sru@DefreqList {box, macro} 12083104862Sru@DefreqListEnd {boxa, macro} 12084104862SruBegin (or appends to) a diversion like the 12085104862Sru@code{di} and @code{da} requests. 12086104862SruThe difference is that @code{box} and @code{boxa} 12087104862Srudo not include a partially-filled line in the diversion. 1208869626Sru 12089104862SruCompare this: 12090104862Sru 1209175584Sru@Example 12092104862SruBefore the box. 12093104862Sru.box xxx 12094104862SruIn the box. 12095104862Sru.br 12096104862Sru.box 12097104862SruAfter the box. 12098104862Sru.br 12099104862Sru @result{} Before the box. After the box. 12100104862Sru.xxx 12101104862Sru @result{} In the box. 1210275584Sru@endExample 12103104862Sru 12104104862Sru@noindent 12105104862Sruwith this: 12106104862Sru 12107104862Sru@Example 12108104862SruBefore the diversion. 12109104862Sru.di yyy 12110104862SruIn the diversion. 12111104862Sru.br 12112104862Sru.di 12113104862SruAfter the diversion. 12114104862Sru.br 12115104862Sru @result{} After the diversion. 12116104862Sru.yyy 12117104862Sru @result{} Before the diversion. In the diversion. 12118104862Sru@endExample 12119104862Sru 12120104862Sru@code{box} or @code{boxa} without an argument ends the diversion. 1212175584Sru@endDefreq 1212255839Sasmodai 12123104862Sru@DefregList {.z} 12124104862Sru@DefregListEnd {.d} 12125104862Sru@cindex @code{nl} register, and @code{.d} 1212669626Sru@cindex nested diversions 1212769626Sru@cindex diversion, nested 12128104862Sru@cindex diversion name register (@code{.z}) 12129104862Sru@cindex vertical position in diversion register (@code{.d}) 12130104862Sru@cindex position, vertical, in diversion, register (@code{.d}) 12131104862Sru@cindex diversion, vertical position in, register (@code{.d}) 1213275584SruDiversions may be nested. The read-only number register @code{.z} 1213375584Srucontains the name of the current diversion (this is a string-valued 1213475584Sruregister). The read-only number register @code{.d} contains the current 1213575584Sruvertical place in the diversion. If not in a diversion it is the same 12136114402Sruas register @code{nl}. 1213775584Sru@endDefreg 1213869626Sru 1213975584Sru@Defreg {.h} 12140104862Sru@cindex high-water mark register (@code{.h}) 12141104862Sru@cindex mark, high-water, register (@code{.h}) 12142104862Sru@cindex position of lowest text line (@code{.h}) 12143104862Sru@cindex text line, position of lowest (@code{.h}) 1214475584SruThe @dfn{high-water mark} on the current page. It corresponds to the 1214575584Srutext baseline of the lowest line on the page. This is a read-only 1214675584Sruregister. 12147104862Sru 12148104862Sru@Example 12149104862Sru.tm .h==\n[.h], nl==\n[nl] 12150104862Sru @result{} .h==0, nl==-1 12151104862SruThis is a test. 12152104862Sru.br 12153104862Sru.sp 2 12154104862Sru.tm .h==\n[.h], nl==\n[nl] 12155104862Sru @result{} .h==40, nl==120 12156104862Sru@endExample 12157104862Sru 12158104862Sru@cindex @code{.h} register, difference to @code{nl} 12159104862Sru@cindex @code{nl} register, difference to @code{.h} 12160104862Sru@noindent 12161104862SruAs can be seen in the previous example, empty lines are not considered 12162104862Sruin the return value of the @code{.h} register. 1216375584Sru@endDefreg 1216455839Sasmodai 12165104862Sru@DefregList {dn} 12166104862Sru@DefregListEnd {dl} 12167114402Sru@cindex @code{dn} register, and @code{da} (@code{boxa}) 12168114402Sru@cindex @code{dl} register, and @code{da} (@code{boxa}) 12169114402Sru@cindex @code{da} request, and @code{dn} (@code{dl}) 12170114402Sru@cindex @code{boxa} request, and @code{dn} (@code{dl}) 1217175584SruAfter completing a diversion, the read-write number registers @code{dn} 1217255839Sasmodaiand @code{dl} contain the vertical and horizontal size of the diversion. 12173114402SruNote that only the just processed lines are counted: For the computation 12174114402Sruof @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are 12175114402Sruhandled as if @code{di} and @code{box} had been used -- lines which have 12176114402Srubeen already stored in a macro are not taken into account. 1217755839Sasmodai 12178104862Sru@Example 1217955839Sasmodai.\" Center text both horizontally & vertically 12180104862Sru. 12181104862Sru.\" Enclose macro definitions in .eo and .ec 12182104862Sru.\" to avoid the doubling of the backslash 12183104862Sru.eo 12184104862Sru.\" macro .(c starts centering mode 1218555839Sasmodai.de (c 12186104862Sru. br 12187104862Sru. ev (c 12188104862Sru. evc 0 12189104862Sru. in 0 12190104862Sru. nf 12191104862Sru. di @@c 1219255839Sasmodai.. 12193104862Sru@endExample 12194104862Sru@Example 12195104862Sru.\" macro .)c terminates centering mode 1219655839Sasmodai.de )c 12197104862Sru. br 12198104862Sru. ev 12199104862Sru. di 12200104862Sru. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 12201104862Sru. sp \n[@@s]u 12202104862Sru. ce 1000 12203104862Sru. @@c 12204104862Sru. ce 0 12205104862Sru. sp \n[@@s]u 12206104862Sru. br 12207104862Sru. fi 12208104862Sru. rr @@s 12209104862Sru. rm @@s 12210104862Sru. rm @@c 1221155839Sasmodai.. 12212104862Sru.\" End of macro definitions, restore escape mechanism 12213104862Sru.ec 12214104862Sru@endExample 1221575584Sru@endDefreg 1221655839Sasmodai 12217104862Sru@DefescList {\\!, , , } 12218114402Sru@DefescListEnd {\\?, , anything, \\?} 12219104862Sru@cindex transparent output (@code{\!}, @code{\?}) 12220104862Sru@cindex output, transparent (@code{\!}, @code{\?}) 12221104862SruPrevent requests, macros, and escapes from being 12222114402Sruinterpreted when read into a diversion. Both escapes take the given text 12223114402Sruand @dfn{transparently} embed it into the diversion. This is useful for 1222469626Srumacros which shouldn't be invoked until the diverted text is actually 1222569626Sruoutput. 1222655839Sasmodai 1222775584SruThe @code{\!} escape transparently embeds text up to 1222875584Sruand including the end of the line. 1222975584SruThe @code{\?} escape transparently embeds text until the next 12230114402Sruoccurrence of the @code{\?} escape. Example: 1223155839Sasmodai 1223275584Sru@Example 1223369626Sru\?@var{anything}\? 1223475584Sru@endExample 1223569626Sru 1223669626Sru@noindent 1223769626Sru@var{anything} may not contain newlines; use @code{\!} to embed 1223869626Srunewlines in a diversion. The escape sequence @code{\?} is also 1223969626Srurecognized in copy mode and turned into a single internal code; it is 12240104862Sruthis code that terminates @var{anything}. Thus the following example 12241114402Sruprints@tie{}4. 1224269626Sru 1224375584Sru@Example 1224455839Sasmodai.nr x 1 1224555839Sasmodai.nf 1224655839Sasmodai.di d 1224755839Sasmodai\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 1224855839Sasmodai.di 1224955839Sasmodai.nr x 2 1225055839Sasmodai.di e 1225155839Sasmodai.d 1225255839Sasmodai.di 1225355839Sasmodai.nr x 3 1225455839Sasmodai.di f 1225555839Sasmodai.e 1225655839Sasmodai.di 1225755839Sasmodai.nr x 4 1225855839Sasmodai.f 1225975584Sru@endExample 12260104862Sru 12261104862SruBoth escapes read the data in copy mode. 12262104862Sru 12263104862Sru@cindex @code{\!}, in top-level diversion 12264104862Sru@cindex top-level diversion, and @code{\!} 12265104862Sru@cindex diversion, top-level, and @code{\!} 12266104862SruIf @code{\!} is used in the top-level diversion, its argument is 12267104862Srudirectly embedded into the @code{gtroff} intermediate output. This can 12268104862Srube used for example to control a postprocessor which processes the data 12269104862Srubefore it is sent to the device driver. 12270104862Sru 12271104862Sru@cindex @code{\?}, in top-level diversion 12272104862Sru@cindex top-level diversion, and @code{\?} 12273104862Sru@cindex diversion, top-level, and @code{\?} 12274104862SruThe @code{\?} escape used in the top-level diversion produces no output 12275104862Sruat all; its argument is simply ignored. 1227675584Sru@endDefesc 1227755839Sasmodai 12278104862Sru@cindex @code{\!}, and @code{output} 12279104862Sru@cindex @code{output} request, and @code{\!} 12280104862Sru@Defreq {output, string} 12281104862SruEmit @var{string} directly to the @code{gtroff} intermediate output 12282114402Sru(subject to copy-mode interpretation); this is similar to @code{\!} used 12283104862Sruat the top level. An initial double quote in @var{string} is stripped off 12284104862Sruto allow initial blanks. 12285104862Sru 12286104862SruThis request can't be used before the first page has started -- if you get 12287104862Sruan error, simply insert @code{.br} before the @code{output} request. 12288104862Sru 12289104862SruWithout argument, @code{output} is ignored. 12290104862Sru 12291104862SruUse with caution! It is normally only needed for mark-up used by a 12292104862Srupostprocessor which does something with the output before sending it to 12293114402Sruthe output device, filtering out @var{string} again. 12294104862Sru@endDefreq 12295104862Sru 1229675584Sru@Defreq {asciify, div} 12297104862Sru@cindex unformatting diversions (@code{asciify}) 12298104862Sru@cindex diversion, unformatting (@code{asciify}) 12299104862Sru@cindex @code{trin} request, and @code{asciify} 12300104862Sru@dfn{Unformat} the diversion specified by @var{div} 12301104862Sruin such a way that @acronym{ASCII} characters, characters translated with 12302104862Sruthe @code{trin} request, space characters, and some escape sequences that 1230375584Sruwere formatted and diverted are treated like ordinary input 1230475584Srucharacters when the diversion is reread. It can be also used for gross 12305114402Sruhacks; for example, the following sets register@tie{}@code{n} to@tie{}1. 1230655839Sasmodai 1230775584Sru@Example 1230869626Sru.tr @@. 1230969626Sru.di x 1231075584Sru@@nr n 1 1231155839Sasmodai.br 1231255839Sasmodai.di 1231369626Sru.tr @@@@ 1231469626Sru.asciify x 1231555839Sasmodai.x 1231675584Sru@endExample 1231755839Sasmodai 1231869626Sru@xref{Copy-in Mode}. 1231975584Sru@endDefreq 1232055839Sasmodai 12321104862Sru@Defreq {unformat, div} 12322104862SruLike @code{asciify}, unformat the specified diversion. 12323104862SruHowever, @code{unformat} only unformats spaces and tabs 12324104862Srubetween words. 12325104862SruUnformatted tabs are treated as input tokens, 12326104862Sruand spaces are stretchable again. 1232755839Sasmodai 12328104862SruThe vertical size of lines is not preserved; glyph information (font, 12329104862Srufont size, space width, etc.)@: is retained. 12330104862Sru@endDefreq 12331104862Sru 12332104862Sru 1233369626Sru@c ===================================================================== 1233469626Sru 1233575584Sru@node Environments, Suppressing output, Diversions, gtroff Reference 1233655839Sasmodai@section Environments 1233755839Sasmodai@cindex environments 1233855839Sasmodai 1233969626SruIt happens frequently that some text should be printed in a certain 1234069626Sruformat regardless of what may be in effect at the time, for example, in 1234169626Srua trap invoked macro to print headers and footers. To solve this 1234275584Sru@code{gtroff} processes text in @dfn{environments}. An 1234369626Sruenvironment contains most of the parameters that control text 1234469626Sruprocessing. It is possible to switch amongst these environments; by 12345114402Srudefault @code{gtroff} processes text in environment@tie{}0. The 1234669626Srufollowing is the information kept in an environment. 1234755839Sasmodai 1234869626Sru@itemize @bullet 1234969626Sru@item 12350104862Srufont parameters (size, family, style, glyph height and slant, space 1235169626Sruand sentence space size) 1235255839Sasmodai 1235355839Sasmodai@item 1235469626Srupage parameters (line length, title length, vertical spacing, 12355104862Sruline spacing, indentation, line numbering, centering, right-justifying, 12356104862Sruunderlining, hyphenation data) 1235769626Sru 1235855839Sasmodai@item 1235969626Srufill and adjust mode 1236069626Sru 1236155839Sasmodai@item 12362104862Srutab stops, tab and leader characters, escape character, 12363104862Sruno-break and hyphen indicators, margin character data 1236469626Sru 1236555839Sasmodai@item 1236669626Srupartially collected lines 12367104862Sru 12368104862Sru@item 12369104862Sruinput traps 12370104862Sru 12371104862Sru@item 12372104862Srudrawing and fill colours 1237355839Sasmodai@end itemize 1237455839Sasmodai 1237569626SruThese environments may be given arbitrary names (see @ref{Identifiers}, 1237669626Srufor more info). Old versions of @code{troff} only had environments 12377104862Srunamed @samp{0}, @samp{1}, and @samp{2}. 1237855839Sasmodai 12379104862Sru@DefreqList {ev, [@Var{env}]} 12380104862Sru@DefregListEnd {.ev} 12381104862Sru@cindex switching environments (@code{ev}) 12382104862Sru@cindex environment, switching (@code{ev}) 12383104862Sru@cindex environment number/name register (@code{.ev}) 12384104862SruSwitch to another environment. The argument @var{env} is the name of 1238575584Sruthe environment to switch to. With no argument, @code{gtroff} switches 1238675584Sruback to the previous environment. There is no limit on the number of 1238775584Srunamed environments; they are created the first time that they are 1238875584Srureferenced. The @code{.ev} read-only register contains the name or 1238975584Srunumber of the current environment. This is a string-valued register. 1239055839Sasmodai 1239175584SruNote that a call to @code{ev} (with argument) pushes the previously 1239269626Sruactive environment onto a stack. If, say, environments @samp{foo}, 1239369626Sru@samp{bar}, and @samp{zap} are called (in that order), the first 1239475584Sru@code{ev} request without parameter switches back to environment 1239575584Sru@samp{bar} (which is popped off the stack), and a second call 1239675584Sruswitches back to environment @samp{foo}. 1239769626Sru 1239875584SruHere is an example: 1239969626Sru 1240075584Sru@Example 1240155839Sasmodai.ev footnote-env 1240255839Sasmodai.fam N 1240355839Sasmodai.ps 6 1240455839Sasmodai.vs 8 1240555839Sasmodai.ll -.5i 1240655839Sasmodai.ev 1240775584Sru 1240855839Sasmodai... 1240975584Sru 1241055839Sasmodai.ev footnote-env 1241155839Sasmodai\(dg Note the large, friendly letters. 1241255839Sasmodai.ev 1241375584Sru@endExample 1241475584Sru@endDefreq 1241555839Sasmodai 1241675584Sru@Defreq {evc, env} 12417104862Sru@cindex copying environment (@code{evc}) 12418104862Sru@cindex environment, copying (@code{evc}) 12419104862SruCopy the environment @var{env} into the current environment. 12420104862Sru 12421104862SruThe following environment data is not copied: 12422104862Sru 12423104862Sru@itemize @bullet 12424104862Sru@item 12425104862SruPartially filled lines. 12426104862Sru 12427104862Sru@item 12428104862SruThe status whether the previous line was interrupted. 12429104862Sru 12430104862Sru@item 12431104862SruThe number of lines still to center, or to right-justify, or to underline 12432104862Sru(with or without underlined spaces); they are set to zero. 12433104862Sru 12434104862Sru@item 12435151497SruThe status whether a temporary indentation is active. 12436104862Sru 12437104862Sru@item 12438104862SruInput traps and its associated data. 12439104862Sru 12440104862Sru@item 12441104862SruLine numbering mode is disabled; it can be reactivated with 12442104862Sru@w{@samp{.nm +0}}. 12443104862Sru 12444104862Sru@item 12445104862SruThe number of consecutive hyphenated lines (set to zero). 12446104862Sru@end itemize 1244775584Sru@endDefreq 1244855839Sasmodai 12449114402Sru@DefregList {.w} 12450114402Sru@DefregItem {.cht} 12451104862Sru@DefregItem {.cdp} 12452104862Sru@DefregListEnd {.csk} 12453114402Sru@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 12454114402Sru@cindex width, of last glyph (@code{.w}) 12455114402Sru@cindex height, of last glyph (@code{.cht}) 12456114402Sru@cindex depth, of last glyph (@code{.cdp}) 12457114402Sru@cindex skew, of last glyph (@code{.csk}) 12458114402Sru@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 12459114402Sru@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 12460114402SruThe @code{\n[.w]} register contains the 12461114402Sruwidth of the last glyph added to the current environment. 12462114402Sru 12463104862SruThe @code{\n[.cht]} register contains the 12464114402Sruheight of the last glyph added to the current environment. 1246555839Sasmodai 12466104862SruThe @code{\n[.cdp]} register contains the 12467114402Srudepth of the last glyph added to the current environment. 12468114402SruIt is positive for glyphs extending below the baseline. 12469104862Sru 12470104862SruThe @code{\n[.csk]} register contains the 12471104862Sru@dfn{skew} (how far to the right of the glyph's center 12472114402Sruthat @code{gtroff} should place an accent) 12473104862Sruof the last glyph added to the current environment. 12474104862Sru@endDefreg 12475104862Sru 12476114402Sru@Defreg {.n} 12477114402Sru@cindex environment, previous line length (@code{.n}) 12478114402Sru@cindex line length, previous (@code{.n}) 12479114402Sru@cindex length of previous line (@code{.n}) 12480114402Sru@cindex previous line length (@code{.n}) 12481114402SruThe @code{\n[.n]} register contains the 12482114402Srulength of the previous output line in the current environment. 12483114402Sru@endDefreg 12484104862Sru 12485114402Sru 1248669626Sru@c ===================================================================== 1248755839Sasmodai 12488104862Sru@node Suppressing output, Colors, Environments, gtroff Reference 1248975584Sru@section Suppressing output 1249075584Sru 1249175584Sru@Defesc {\\O, , num, } 12492104862Sru@cindex suppressing output (@code{\O}) 12493104862Sru@cindex output, suppressing (@code{\O}) 12494104862SruDisable or enable output depending on the value of @var{num}: 1249575584Sru 1249675584Sru@table @samp 1249775584Sru@item \O0 12498104862SruDisable any glyphs from being emitted to the device driver, provided that 12499104862Sruthe escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}). 12500104862SruMotion is not suppressed so effectively @code{\O[0]} means @emph{pen up}. 1250175584Sru 1250275584Sru@item \O1 12503104862SruEnable output of glyphs, provided that the escape occurs at the outer 12504104862Srulevel. 1250575584Sru@end table 1250675584Sru 1250775584Sru@vindex opminx 1250875584Sru@vindex opminy 1250975584Sru@vindex opmaxx 1251075584Sru@vindex opmaxy 1251175584Sru@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 1251275584Sru@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 1251375584Sru@xref{Register Index}. These four registers mark the top left and 1251475584Srubottom right hand corners of a box which encompasses all written glyphs. 1251575584Sru 12516104862SruFor example the input text: 1251775584Sru 12518104862Sru@Example 12519104862SruHello \O[0]world \O[1]this is a test. 12520104862Sru@endExample 12521104862Sru 12522104862Sru@noindent 12523104862Sruproduces the following output: 12524104862Sru 12525104862Sru@Example 12526104862SruHello this is a test. 12527104862Sru@endExample 12528104862Sru 1252975584Sru@table @samp 1253075584Sru@item \O2 12531104862SruProvided that the escape occurs at the outer level, enable output of 12532104862Sruglyphs and also write out to @code{stderr} the page number and four 12533104862Sruregisters encompassing the glyphs previously written since the last call 12534104862Sruto @code{\O}. 1253575584Sru 1253675584Sru@item \O3 12537104862SruBegin a nesting level. At start-up, @code{gtroff} is at outer level. 12538104862Sru 12539104862Sru@item \O4 12540104862SruEnd a nesting level. 12541104862Sru 12542104862Sru@item \O[5@var{P}@var{filename}] 12543104862SruThis escape is @code{grohtml} specific. Provided that this escape 12544104862Sruoccurs at the outer nesting level write the @code{filename} to 12545104862Sru@code{stderr}. The position of the image, @var{P}, must be specified 12546114402Sruand must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left, 12547104862Sruright, centered, inline). @var{filename} will be associated with the 12548104862Sruproduction of the next inline image. 1254975584Sru@end table 1255075584Sru@endDefesc 1255175584Sru 12552104862Sru@c ===================================================================== 1255375584Sru 12554104862Sru@node Colors, I/O, Suppressing output, gtroff Reference 12555104862Sru@section Colors 12556104862Sru@cindex colors 12557104862Sru 12558104862Sru@DefreqList {color, [@Var{n}]} 12559104862Sru@DefregListEnd {.color} 12560104862SruIf @var{n} is missing or non-zero, activate colors (this is the default); 12561104862Sruotherwise, turn it off. 12562104862Sru 12563114402SruThe read-only number register @code{.color} is@tie{}1 if colors are active, 12564114402Sru0@tie{}otherwise. 12565104862Sru 12566104862SruInternally, @code{color} sets a global flag; it does not produce a token. 12567104862SruSimilar to the @code{cp} request, you should use it at the beginning of 12568104862Sruyour document to control color output. 12569104862Sru 12570104862SruColors can be also turned off with the @option{-c} command line option. 12571104862Sru@endDefreq 12572104862Sru 12573104862Sru@Defreq {defcolor, ident scheme color_components} 12574104862SruDefine color with name @var{ident}. @var{scheme} can be one of the 12575114402Srufollowing values: @code{rgb} (three components), @code{cmy} (three 12576104862Srucomponents), @code{cmyk} (four components), and @code{gray} or 12577104862Sru@code{grey} (one component). 12578104862Sru 12579104862Sru@cindex default color 12580104862Sru@cindex color, default 12581104862SruColor components can be given either as a hexadecimal string or as 12582104862Srupositive decimal integers in the range 0--65535. A hexadecimal string 12583104862Srucontains all color components concatenated. It must start with either 12584104862Sru@code{#} or @code{##}; the former specifies hex values in the range 12585114402Sru0--255 (which are internally multiplied by@tie{}257), the latter in the 12586104862Srurange 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} 12587104862Sru(magenta). The default color name @c{default} can't be redefined; its 12588104862Sruvalue is device-specific (usually black). It is possible that the 12589104862Srudefault color for @code{\m} and @code{\M} is not identical. 12590104862Sru 12591104862Sru@cindex @code{f} unit, and colors 12592104862Sru@cindex unit, @code{f}, and colors 12593114402SruA new scaling indicator@tie{}@code{f} has been introduced which multiplies 12594104862Sruits value by 65536; this makes it convenient to specify color components 12595114402Sruas fractions in the range 0 to@tie{}1 (1f equals 65536u). Example: 12596104862Sru 12597104862Sru@Example 12598104862Sru.defcolor darkgreen rgb 0.1f 0.5f 0.2f 12599104862Sru@endExample 12600104862Sru 12601104862SruNote that @code{f} is the default scaling indicator for the 12602104862Sru@code{defcolor} request, thus the above statement is equivalent to 12603104862Sru 12604104862Sru@Example 12605104862Sru.defcolor darkgreen rgb 0.1 0.5 0.2 12606104862Sru@endExample 12607104862Sru@endDefreq 12608104862Sru 12609151497Sru@DefreqList {gcolor, [@Var{color}]} 12610151497Sru@DefescItem {\\m, , c, } 12611151497Sru@DefescItem {\\m, @Lparen{}, co, } 12612151497Sru@DefescItem {\\m, @Lbrack{}, color, @Rbrack{}} 12613151497Sru@DefregListEnd {.m} 12614151497SruSet (glyph) drawing color. The following examples show how to turn the 12615151497Srunext four words red. 12616104862Sru 12617104862Sru@Example 12618151497Sru.gcolor red 12619151497Sruthese are in red 12620151497Sru.gcolor 12621151497Sruand these words are in black. 12622151497Sru@endExample 12623151497Sru 12624151497Sru@Example 12625104862Sru\m[red]these are in red\m[] and these words are in black. 12626104862Sru@endExample 12627104862Sru 12628151497SruThe escape @code{\m[]} returns to the previous color, as does a call to 12629151497Sru@code{gcolor} without an argument. 12630104862Sru 12631151497Sru@cindex drawing color name register (@code{.m}) 12632151497Sru@cindex name, drawing color, register (@code{.m}) 12633151497Sru@cindex color name, drawing, register (@code{.m}) 12634151497SruThe name of the current drawing color is available in the read-only, 12635151497Srustring-valued number register @samp{.m}. 12636151497Sru 12637104862SruThe drawing color is associated with the current environment 12638104862Sru(@pxref{Environments}). 12639104862Sru 12640104862SruNote that @code{\m} doesn't produce an input token in @code{gtroff}. 12641104862SruAs a consequence, it can be used in requests like @code{mc} (which 12642104862Sruexpects a single character as an argument) to change the color on 12643104862Sruthe fly: 12644104862Sru 12645104862Sru@Example 12646104862Sru.mc \m[red]x\m[] 12647104862Sru@endExample 12648104862Sru@endDefesc 12649104862Sru 12650151497Sru@DefreqList {fcolor, [@Var{color}]} 12651151497Sru@DefescItem {\\M, , c, } 12652151497Sru@DefescItem {\\M, @Lparen{}, co, } 12653151497Sru@DefescItem {\\M, @Lbrack{}, color, @Rbrack{}} 12654151497Sru@DefregListEnd {.M} 12655151497SruSet fill (background) color for filled objects drawn with the 12656104862Sru@code{\D'@dots{}'} commands. 12657104862Sru 12658104862SruA red ellipse can be created with the following code: 12659104862Sru 12660104862Sru@Example 12661104862Sru\M[red]\h'0.5i'\D'E 2i 1i'\M[] 12662104862Sru@endExample 12663104862Sru 12664151497SruThe escape @code{\M[]} returns to the previous fill color, as does a call to 12665151497Sru@code{fcolor} without an argument. 12666104862Sru 12667151497Sru@cindex background color name register (@code{.M}) 12668151497Sru@cindex name, background color, register (@code{.M}) 12669151497Sru@cindex color name, background, register (@code{.M}) 12670151497Sru@cindex fill color name register (@code{.M}) 12671151497Sru@cindex name, fill color, register (@code{.M}) 12672151497Sru@cindex color name, fill, register (@code{.M}) 12673151497SruThe name of the current fill (background) color is available in the 12674151497Sruread-only, string-valued number register @samp{.M}. 12675151497Sru 12676104862SruThe fill color is associated with the current environment 12677104862Sru(@pxref{Environments}). 12678104862Sru 12679104862SruNote that @code{\M} doesn't produce an input token in @code{gtroff}. 12680104862Sru@endDefesc 12681104862Sru 12682104862Sru 1268375584Sru@c ===================================================================== 1268475584Sru 12685104862Sru@node I/O, Postprocessor Access, Colors, gtroff Reference 1268655839Sasmodai@section I/O 1268755839Sasmodai@cindex i/o 1268869626Sru@cindex input and output requests 1268969626Sru@cindex requests for input and output 1269069626Sru@cindex output and input requests 1269155839Sasmodai 1269275584Sru@code{gtroff} has several requests for including files: 1269375584Sru 1269475584Sru@Defreq {so, file} 12695104862Sru@cindex including a file (@code{so}) 12696104862Sru@cindex file, inclusion (@code{so}) 12697104862SruRead in the specified @var{file} and 1269875584Sruincludes it in place of the @code{so} request. This is quite useful for 1269975584Srularge documents, e.g.@: keeping each chapter in a separate file. 1270055839Sasmodai@xref{gsoelim}, for more information. 12701104862Sru 12702104862SruSince @code{gtroff} replaces the @code{so} request with the contents 12703104862Sruof @code{file}, it makes a difference whether the data is terminated with 12704104862Srua newline or not: Assuming that file @file{xxx} contains the word 12705104862Sru@samp{foo} without a final newline, this 12706104862Sru 12707104862Sru@Example 12708104862SruThis is 12709104862Sru.so xxx 12710104862Srubar 12711104862Sru@endExample 12712104862Sru 12713104862Sru@noindent 12714104862Sruyields @samp{This is foobar}. 12715151497Sru 12716151497SruThe search path for @var{file} can be controlled with the @option{-I} command 12717151497Sruline option. 1271875584Sru@endDefreq 1271955839Sasmodai 12720104862Sru@Defreq {pso, command} 12721104862SruRead the standard output from the specified @var{command} 12722104862Sruand includes it in place of the @code{pso} request. 12723104862Sru 12724104862Sru@cindex safer mode 12725104862Sru@cindex mode, safer 12726104862Sru@cindex unsafe mode 12727104862Sru@cindex mode, unsafe 12728104862SruThis request causes an error if used in safer mode (which is the default). 12729104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12730104862Srumode. 12731104862Sru 12732104862SruThe comment regarding a final newline for the @code{so} request is valid 12733104862Srufor @code{pso} also. 12734104862Sru@endDefreq 12735104862Sru 1273675584Sru@Defreq {mso, file} 12737104862SruIdentical to the @code{so} request except that @code{gtroff} searches for 12738104862Sruthe specified @var{file} in the same directories as macro files for the 1273975584Sruthe @option{-m} command line option. If the file name to be included 1274075584Sruhas the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 1274175584Sruto include @file{tmac.@var{name}} and vice versa. 1274275584Sru@endDefreq 1274355839Sasmodai 12744104862Sru@DefreqList {trf, file} 12745104862Sru@DefreqListEnd {cf, file} 12746104862Sru@cindex transparent output (@code{cf}, @code{trf}) 12747104862Sru@cindex output, transparent (@code{cf}, @code{trf}) 12748104862SruTransparently output the contents of @var{file}. Each line is output 12749104862Sruas if it were preceded by @code{\!}; however, the lines are not subject 12750104862Sruto copy mode interpretation. If the file does not end with a newline, 12751104862Sruthen a newline is added (@code{trf} only). For example, to define a 12752114402Srumacro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use 1275355839Sasmodai 1275475584Sru@Example 1275555839Sasmodai.di x 1275655839Sasmodai.trf f 1275755839Sasmodai.di 1275875584Sru@endExample 1275955839Sasmodai 12760104862SruBoth @code{trf} and @code{cf}, when used in a diversion, 1276175584Sruembeds an object in the diversion which, when reread, causes the 12762104862Srucontents of @var{file} to be transparently copied through to the 12763104862Sruoutput. In @acronym{UNIX} @code{troff}, the contents of @var{file} 1276469626Sruis immediately copied through to the output regardless of whether there 1276569626Sruis a current diversion; this behaviour is so anomalous that it must be 12766104862Sruconsidered a bug. 1276755839Sasmodai 12768104862Sru@cindex @code{trf} request, and invalid characters 12769104862Sru@cindex characters, invalid for @code{trf} request 12770104862Sru@cindex invalid characters for @code{trf} request 12771104862SruWhile @code{cf} copies the contents of @var{file} completely unprocessed, 12772104862Sru@code{trf} disallows characters such as NUL that are not valid 12773104862Sru@code{gtroff} input characters (@pxref{Identifiers}). 12774104862Sru 12775104862SruBoth requests cause a line break. 1277675584Sru@endDefreq 1277755839Sasmodai 12778104862Sru@Defreq {nx, [@Var{file}]} 12779104862Sru@cindex processing next file (@code{nx}) 12780104862Sru@cindex file, processing next (@code{nx}) 12781104862Sru@cindex next file, processing (@code{nx}) 12782104862SruForce @code{gtroff} to continue processing of 12783104862Sruthe file specified as an argument. If no argument is given, immediately 12784104862Srujump to the end of file. 1278575584Sru@endDefreq 1278655839Sasmodai 12787104862Sru@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]} 12788104862Sru@cindex reading from standard input (@code{rd}) 12789104862Sru@cindex standard input, reading from (@code{rd}) 12790104862Sru@cindex input, standard, reading from (@code{rd}) 12791104862SruRead from standard input, and include what is read as though it 12792104862Sruwere part of the input file. Text is read until a blank line 12793104862Sruis encountered. 12794104862Sru 12795104862SruIf standard input is a TTY input device (keyboard), write @var{prompt} 12796104862Sruto standard error, followed by a colon (or send BEL for a beep if no 12797104862Sruargument is given). 12798104862Sru 12799104862SruArguments after @var{prompt} are available for the input. For example, 12800104862Sruthe line 12801104862Sru 12802104862Sru@Example 12803104862Sru.rd data foo bar 12804104862Sru@endExample 12805104862Sru 12806104862Sruwith the input @w{@samp{This is \$2.}} prints 12807104862Sru 12808104862Sru@Example 12809104862SruThis is bar. 12810104862Sru@endExample 1281175584Sru@endDefreq 1281255839Sasmodai 1281355839Sasmodai@cindex form letters 1281455839Sasmodai@cindex letters, form 1281575584SruUsing the @code{nx} and @code{rd} requests, 1281675584Sruit is easy to set up form letters. The form 12817104862Sruletter template is constructed like this, putting the following lines 12818104862Sruinto a file called @file{repeat.let}: 1281955839Sasmodai 1282075584Sru@Example 1282155839Sasmodai.ce 1282255839Sasmodai\*(td 1282355839Sasmodai.sp 2 1282455839Sasmodai.nf 1282555839Sasmodai.rd 1282655839Sasmodai.sp 1282755839Sasmodai.rd 1282855839Sasmodai.fi 1282955839SasmodaiBody of letter. 1283055839Sasmodai.bp 1283155839Sasmodai.nx repeat.let 1283275584Sru@endExample 1283355839Sasmodai 12834104862Sru@cindex @code{ex} request, used with @code{nx} and @code{rd} 1283569626Sru@noindent 12836104862SruWhen this is run, a file containing the following lines should be 12837104862Sruredirected in. Note that requests included in this file are executed 12838104862Sruas though they were part of the form letter. The last block of input 12839104862Sruis the @code{ex} request which tells @code{groff} to stop processing. If 12840104862Sruthis was not there, @code{groff} would not know when to stop. 1284155839Sasmodai 1284275584Sru@Example 1284355839SasmodaiTrent A. Fisher 1284455839Sasmodai708 NW 19th Av., #202 1284555839SasmodaiPortland, OR 97209 1284655839Sasmodai 1284755839SasmodaiDear Trent, 1284855839Sasmodai 1284955839SasmodaiLen Adollar 1285055839Sasmodai4315 Sierra Vista 1285155839SasmodaiSan Diego, CA 92103 1285255839Sasmodai 1285355839SasmodaiDear Mr. Adollar, 1285455839Sasmodai 1285555839Sasmodai.ex 1285675584Sru@endExample 1285755839Sasmodai 1285875584Sru@Defreq {pi, pipe} 12859104862SruPipe the output of @code{gtroff} to the shell command(s) 1286075584Sruspecified by @var{pipe}. This request must occur before 1286175584Sru@code{gtroff} has a chance to print anything. 12862104862Sru 12863104862Sru@cindex safer mode 12864104862Sru@cindex mode, safer 12865104862Sru@cindex unsafe mode 12866104862Sru@cindex mode, unsafe 12867104862Sru@code{pi} causes an error if used in safer mode (which is the default). 12868104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12869104862Srumode. 12870104862Sru 12871104862SruMultiple calls to @code{pi} are allowed, acting as a chain. For example, 12872104862Sru 12873104862Sru@Example 12874104862Sru.pi foo 12875104862Sru.pi bar 12876104862Sru... 12877104862Sru@endExample 12878104862Sru 12879104862Sruis the same as @w{@samp{.pi foo | bar}}. 12880104862Sru 12881104862Sru@cindex @code{groff}, and @code{pi} request 12882104862Sru@cindex @code{pi} request, and @code{groff} 12883104862SruNote that the intermediate output format of @code{gtroff} is piped to 12884104862Sruthe specified commands. Consequently, calling @code{groff} without the 12885104862Sru@option{-Z} option normally causes a fatal error. 1288675584Sru@endDefreq 1288755839Sasmodai 12888104862Sru@DefreqList {sy, cmds} 12889104862Sru@DefregListEnd {systat} 12890104862SruExecute the shell command(s) specified by @var{cmds}. The output is not 12891104862Srusaved anyplace, so it is up to the user to do so. 1289269626Sru 12893104862Sru@cindex safer mode 12894104862Sru@cindex mode, safer 12895104862Sru@cindex unsafe mode 12896104862Sru@cindex mode, unsafe 12897104862SruThis request causes an error if used in safer mode (which is the default). 12898104862SruUse @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12899104862Srumode. 1290069626Sru 12901104862SruFor example, the following code fragment introduces the current time into a 12902104862Srudocument: 1290355839Sasmodai 1290469626Sru@cindex time, current 1290569626Sru@cindex current time 1290655839Sasmodai@pindex perl 1290775584Sru@Example 1290855839Sasmodai.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 12909114402Sru (localtime(time))[2,1,0]' > /tmp/x\n[$$] 1291055839Sasmodai.so /tmp/x\n[$$] 1291155839Sasmodai.sy rm /tmp/x\n[$$] 1291255839Sasmodai\nH:\nM:\nS 1291375584Sru@endExample 1291455839Sasmodai 1291569626Sru@noindent 1291669626SruNote that this works by having the @code{perl} script (run by @code{sy}) 1291775584Sruprint out the @code{nr} requests which set the number registers 12918104862Sru@code{H}, @code{M}, and @code{S}, and then reads those commands in with 1291969626Sruthe @code{so} request. 1292055839Sasmodai 12921104862SruFor most practical purposes, the number registers @code{seconds}, 12922104862Sru@code{minutes}, and @code{hours} which are initialized at start-up of 12923104862Sru@code{gtroff} should be sufficient. Use the @code{af} request to get a 12924104862Sruformatted output: 12925104862Sru 12926104862Sru@Example 12927104862Sru.af hours 00 12928104862Sru.af minutes 00 12929104862Sru.af seconds 00 12930104862Sru\n[hours]:\n[minutes]:\n[seconds] 12931104862Sru@endExample 12932104862Sru 12933104862Sru@cindex @code{system()} return value register (@code{systat}) 1293475584SruThe @code{systat} read-write number register contains the return value 1293575584Sruof the @code{system()} function executed by the last @code{sy} request. 1293675584Sru@endDefreq 1293755839Sasmodai 12938104862Sru@DefreqList {open, stream file} 12939104862Sru@DefreqListEnd {opena, stream file} 12940104862Sru@cindex opening file (@code{open}) 12941104862Sru@cindex file, opening (@code{open}) 12942104862Sru@cindex appending to a file (@code{opena}) 12943104862Sru@cindex file, appending to (@code{opena}) 12944104862SruOpen the specified @var{file} for writing and 1294575584Sruassociates the specified @var{stream} with it. 1294655839Sasmodai 12947104862SruThe @code{opena} request is like @code{open}, but if the file exists, 12948104862Sruappend to it instead of truncating it. 12949104862Sru 12950104862Sru@cindex safer mode 12951104862Sru@cindex mode, safer 12952104862Sru@cindex unsafe mode 12953104862Sru@cindex mode, unsafe 12954104862SruBoth @code{open} and @code{opena} cause an error if used in safer mode 12955104862Sru(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U} 12956104862Sruoption to activate unsafe mode. 1295775584Sru@endDefreq 1295855839Sasmodai 12959104862Sru@DefreqList {write, stream data} 12960104862Sru@DefreqListEnd {writec, stream data} 1296169626Sru@cindex copy-in mode, and @code{write} requests 1296269626Sru@cindex mode, copy-in, and @code{write} requests 12963104862Sru@cindex writing to file (@code{write}) 12964104862Sru@cindex file, writing to (@code{write}) 12965104862SruWrite to the file associated with the specified @var{stream}. 1296675584SruThe stream must previously have 1296769626Srubeen the subject of an open request. The remainder of the line is 1296869626Sruinterpreted as the @code{ds} request reads its second argument: A 1296975584Sruleading @samp{"} is stripped, and it is read in copy-in mode. 12970104862Sru 12971104862SruThe @code{writec} request is like @code{write}, but only 12972104862Sru@code{write} appends a newline to the data. 1297375584Sru@endDefreq 1297455839Sasmodai 12975104862Sru@Defreq {writem, stream xx} 12976104862Sru@cindex @code{asciify} request, and @code{writem} 12977104862SruWrite the contents of the macro or string @var{xx} 12978104862Sruto the file associated with the specified @var{stream}. 12979104862Sru 12980104862Sru@var{xx} is read in copy mode, i.e., already formatted elements are 12981104862Sruignored. Consequently, diversions must be unformatted with the 12982104862Sru@code{asciify} request before calling @code{writem}. Usually, this 12983104862Srumeans a loss of information. 12984104862Sru@endDefreq 12985104862Sru 1298675584Sru@Defreq {close, stream} 12987104862Sru@cindex closing file (@code{close}) 12988104862Sru@cindex file, closing (@code{close}) 12989104862SruClose the specified @var{stream}; 1299075584Sruthe stream is no longer an acceptable argument to the 1299169626Sru@code{write} request. 1299255839Sasmodai 12993104862SruHere a simple macro to write an index entry. 1299469626Sru 1299575584Sru@Example 12996104862Sru.open idx test.idx 12997104862Sru. 12998104862Sru.de IX 12999104862Sru. write idx \\n[%] \\$* 13000104862Sru.. 13001104862Sru. 13002104862Sru.IX test entry 13003104862Sru. 13004104862Sru.close idx 1300575584Sru@endExample 1300675584Sru@endDefreq 1300755839Sasmodai 13008104862Sru@DefescList {\\V, , e, } 13009151497Sru@DefescItem {\\V, @Lparen{}, ev, } 13010151497Sru@DefescListEnd {\\V, @Lbrack{}, env, @Rbrack{}} 13011104862SruInterpolate the contents of the specified environment variable 13012114402Sru@var{env} (one-character name@tie{}@var{e}, two-character name @var{ev}) 13013104862Sruas returned by the function @code{getenv}. @code{\V} is interpreted 13014104862Sruin copy-in mode. 1301575584Sru@endDefesc 1301655839Sasmodai 1301755839Sasmodai 1301869626Sru@c ===================================================================== 1301969626Sru 1302075584Sru@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 1302155839Sasmodai@section Postprocessor Access 1302255839Sasmodai@cindex postprocessor access 1302355839Sasmodai@cindex access of postprocessor 1302455839Sasmodai 1302575584SruThere are two escapes which give information directly to the 1302675584Srupostprocessor. This is particularly useful for embedding 1302769626Sru@sc{PostScript} into the final document. 1302855839Sasmodai 1302975584Sru@Defesc {\\X, ', xxx, '} 1303075584SruEmbeds its argument into the @code{gtroff} 1303169626Sruoutput preceded with @w{@samp{x X}}. 13032104862Sru 13033104862Sru@cindex @code{\&}, in @code{\X} 13034104862Sru@cindex @code{\)}, in @code{\X} 13035104862Sru@cindex @code{\%}, in @code{\X} 13036104862Sru@ifnotinfo 13037104862Sru@cindex @code{\:}, in @code{\X} 13038104862Sru@end ifnotinfo 13039104862Sru@ifinfo 13040104862Sru@cindex @code{\@r{<colon>}}, in @code{\X} 13041104862Sru@end ifinfo 13042104862SruThe escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored 13043104862Sruwithin @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single 13044104862Sruspace characters. All other escapes (except @code{\\} which produces a 13045104862Srubackslash) cause an error. 13046104862Sru 13047104862Sru@kindex use_charnames_in_special 13048104862Sru@pindex DESC@r{, and @code{use_charnames_in_special}} 13049104862Sru@cindex @code{\X}, and special characters 13050104862SruIf the @samp{use_charnames_in_special} keyword is set in the @file{DESC} 13051104862Srufile, special characters no longer cause an error; the name @var{xx} is 13052104862Srurepresented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command. 13053104862SruAdditionally, the backslash is represented as @code{\\}. 13054104862Sru 13055104862Sru@samp{use_charnames_in_special} is currently used by @code{grohtml} only. 1305675584Sru@endDefesc 1305755839Sasmodai 13058104862Sru@DefescList {\\Y, , n, } 13059151497Sru@DefescItem {\\Y, @Lparen{}, nm, } 13060151497Sru@DefescListEnd {\\Y, @Lbrack{}, name, @Rbrack{}} 13061104862SruThis is approximately equivalent to @samp{\X'\*[@var{name}]'} 13062114402Sru(one-character name@tie{}@var{n}, two-character name @var{nm}). 13063104862SruHowever, the contents of the string or macro @var{name} are not 13064104862Sruinterpreted; also it is permitted for @var{name} to have been defined 13065104862Sruas a macro and thus contain newlines (it is not permitted for the 13066104862Sruargument to @code{\X} to contain newlines). The inclusion of 13067104862Srunewlines requires an extension to the @acronym{UNIX} @code{troff} 13068104862Sruoutput format, and confuses drivers that do not know about this 13069104862Sruextension (@pxref{Device Control Commands}). 1307075584Sru@endDefesc 1307155839Sasmodai 1307269626Sru@xref{Output Devices}. 1307355839Sasmodai 1307455839Sasmodai 1307569626Sru@c ===================================================================== 1307655839Sasmodai 1307775584Sru@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 1307869626Sru@section Miscellaneous 1307955839Sasmodai 1308069626SruThis section documents parts of @code{gtroff} which cannot (yet) be 1308155839Sasmodaicategorized elsewhere in this manual. 1308255839Sasmodai 13083104862Sru@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]} 13084104862Sru@cindex printing line numbers (@code{nm}) 13085104862Sru@cindex line numbers, printing (@code{nm}) 13086104862Sru@cindex numbers, line, printing (@code{nm}) 13087104862SruPrint line numbers. 1308875584Sru@var{start} is the line number of the @emph{next} 13089104862Sruoutput line. @var{inc} indicates which line numbers are printed. 13090114402SruFor example, the value@tie{}5 means to emit only line numbers which 13091114402Sruare multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the 13092104862Sruspace to be left between the number and the text; this defaults to 13093104862Sruone digit space. The fourth argument is the indentation of the line 13094104862Srunumbers, defaulting to zero. Both @var{space} and @var{indent} are 13095104862Srugiven as multiples of digit spaces; they can be negative also. 13096104862SruWithout any arguments, line numbers are turned off. 1309755839Sasmodai 13098104862Sru@code{gtroff} reserves three digit spaces for the line number (which is 13099104862Sruprinted right-justified) plus the amount given by @var{indent}; the 13100104862Sruoutput lines are concatenated to the line numbers, separated by 13101104862Sru@var{space}, and @emph{without} reducing the line length. Depending 13102104862Sruon the value of the horizontal page offset (as set with the 13103104862Sru@code{po} request), line numbers which are longer than the reserved 13104104862Sruspace stick out to the left, or the whole line is moved to the right. 1310569626Sru 13106104862SruParameters corresponding to missing arguments are not changed; any 13107104862Srunon-digit argument (to be more precise, any argument starting with a 13108104862Srucharacter valid as a delimiter for identifiers) is also treated as 13109104862Srumissing. 1311055839Sasmodai 13111104862SruIf line numbering has been disabled with a call to @code{nm} without 13112104862Sruan argument, it can be reactivated with @samp{.nm +0}, using the 13113104862Srupreviously active line numbering parameters. 1311469626Sru 13115104862SruThe parameters of @code{nm} are associated with the current environment 13116104862Sru(@pxref{Environments}). The current output line number is available 13117104862Sruin the number register @code{ln}. 1311869626Sru 1311975584Sru@Example 13120104862Sru.po 1m 13121104862Sru.ll 2i 13122104862SruThis test shows how line numbering works with groff. 13123104862Sru.nm 999 13124104862SruThis test shows how line numbering works with groff. 13125104862Sru.br 13126104862Sru.nm xxx 3 2 13127104862Sru.ll -\w'0'u 13128104862SruThis test shows how line numbering works with groff. 13129104862Sru.nn 2 13130104862SruThis test shows how line numbering works with groff. 1313175584Sru@endExample 13132104862Sru 13133104862Sru@noindent 13134104862SruAnd here the result: 13135104862Sru 13136104862Sru@Example 13137104862Sru This test shows how 13138104862Sru line numbering works 13139104862Sru 999 with groff. This 13140104862Sru1000 test shows how line 13141104862Sru1001 numbering works with 13142104862Sru1002 groff. 13143104862Sru This test shows how 13144104862Sru line numbering 13145104862Sru works with groff. 13146104862Sru This test shows how 13147104862Sru1005 line numbering 13148104862Sru works with groff. 13149104862Sru@endExample 1315075584Sru@endDefreq 1315155839Sasmodai 13152104862Sru@Defreq {nn, [@Var{skip}]} 13153104862SruTemporarily turn off line numbering. The argument is the number 13154114402Sruof lines not to be numbered; this defaults to@tie{}1. 13155104862Sru@endDefreq 1315655839Sasmodai 13157104862Sru@Defreq {mc, glyph [@Var{dist}]} 13158104862Sru@cindex margin glyph (@code{mc}) 13159104862Sru@cindex glyph, for margins (@code{mc}) 13160104862SruPrint a @dfn{margin character} to the right of the 13161104862Srutext.@footnote{@dfn{Margin character} is a misnomer since it is an 13162104862Sruoutput glyph.} The first argument is the glyph to be 13163104862Sruprinted. The second argument is the distance away from the right 13164104862Srumargin. If missing, the previously set value is used; default is 13165104862Sru10@dmn{pt}). For text lines that are too long (that is, longer than 13166104862Sruthe text length plus @var{dist}), the margin character is directly 13167104862Sruappended to the lines. 13168104862Sru 13169104862SruWith no arguments the margin character is turned off. 13170104862SruIf this occurs before a break, no margin character is printed. 13171104862Sru 13172151497SruFor compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc} 13173151497Sruto set the margin character can't be undone immediately; at least one 13174151497Sruline gets a margin character. Thus 13175151497Sru 13176151497Sru@Example 13177151497Sru.ll 1i 13178151497Sru.mc \[br] 13179151497Sru.mc 13180151497Sruxxx 13181151497Sru.br 13182151497Sruxxx 13183151497Sru@endExample 13184151497Sru 13185151497Sru@noindent 13186151497Sruproduces 13187151497Sru 13188151497Sru@Example 13189151497Sruxxx | 13190151497Sruxxx 13191151497Sru@endExample 13192151497Sru 13193104862Sru@cindex @code{tl} request, and @code{mc} 13194104862SruFor empty lines and lines produced by the @code{tl} request no margin 13195104862Srucharacter is emitted. 13196104862Sru 13197104862SruThe margin character is associated with the current environment 13198104862Sru(@pxref{Environments}). 13199104862Sru 1320069626Sru@pindex nrchbar 1320169626Sru@pindex changebar 1320269626SruThis is quite useful for indicating text that has changed, and, in fact, 1320369626Sruthere are programs available for doing this (they are called 1320455839Sasmodai@code{nrchbar} and @code{changebar} and can be found in any 13205151497Sru@samp{comp.sources.unix} archive). 1320655839Sasmodai 1320775584Sru@Example 13208104862Sru.ll 3i 13209104862Sru.mc | 13210104862SruThis paragraph is highlighted with a margin 13211104862Srucharacter. 13212104862Sru.sp 13213104862SruNote that vertical space isn't marked. 13214104862Sru.br 13215104862Sru\& 13216104862Sru.br 13217104862SruBut we can fake it with `\&'. 1321875584Sru@endExample 1321955839Sasmodai 13220104862SruResult: 1322155839Sasmodai 13222104862Sru@Example 13223104862SruThis paragraph is highlighted | 13224104862Sruwith a margin character. | 1322569626Sru 13226104862SruNote that vertical space isn't | 13227104862Srumarked. | 13228104862Sru | 13229104862SruBut we can fake it with `\&'. | 1323075584Sru@endExample 1323175584Sru@endDefreq 1323255839Sasmodai 13233104862Sru@DefreqList {psbb, filename} 13234104862Sru@DefregItem {llx} 13235104862Sru@DefregItem {lly} 13236104862Sru@DefregItem {urx} 13237104862Sru@DefregListEnd {ury} 13238104862Sru@cindex PostScript, bounding box 13239104862Sru@cindex bounding box 13240104862SruRetrieve the bounding box of the PostScript image 13241104862Srufound in @var{filename}. 13242104862SruThe file must conform to 13243104862SruAdobe's @dfn{Document Structuring Conventions} (DSC); 13244104862Sruthe command searches for a @code{%%BoundingBox} comment 13245104862Sruand extracts the bounding box values into the number registers 13246104862Sru@code{llx}, @code{lly}, @code{urx}, and @code{ury}. 13247104862SruIf an error occurs (for example, @code{psbb} cannot find 13248104862Sruthe @code{%%BoundingBox} comment), 13249104862Sruit sets the four number registers to zero. 13250151497Sru 13251151497SruThe search path for @var{filename} can be controlled with the @option{-I} 13252151497Srucommand line option. 13253104862Sru@endDefreq 1325469626Sru 13255104862Sru 1325669626Sru@c ===================================================================== 1325769626Sru 1325875584Sru@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 1325975584Sru@section @code{gtroff} Internals 1326075584Sru 1326175584Sru@cindex input token 1326275584Sru@cindex token, input 1326375584Sru@cindex output node 1326475584Sru@cindex node, output 1326575584Sru@code{gtroff} processes input in three steps. One or more input 13266104862Srucharacters are converted to an @dfn{input token}.@footnote{Except the 13267104862Sruescapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R}, 13268104862Sru@code{\s}, and @code{\S} which are processed immediately if not in 13269104862Srucopy-in mode.} Then, one or more input tokens are converted to an 13270104862Sru@dfn{output node}. Finally, output nodes are converted to the 13271104862Sruintermediate output language understood by all output devices. 1327275584Sru 13273104862SruActually, before step one happens, @code{gtroff} converts certain 13274104862Sruescape sequences into reserved input characters (not accessible by 13275104862Sruthe user); such reserved characters are used for other internal 13276104862Sruprocessing also -- this is the very reason why not all characters 13277104862Sruare valid input. @xref{Identifiers}, for more on this topic. 13278104862Sru 13279104862SruFor example, the input string @samp{fi\[:u]} is converted into a 1328075584Srucharacter token @samp{f}, a character token @samp{i}, and a special 13281114402Srutoken @samp{:u} (representing u@tie{}umlaut). Later on, the character 1328275584Srutokens @samp{f} and @samp{i} are merged to a single output node 13283104862Srurepresenting the ligature glyph @samp{fi} (provided the current font 13284104862Sruhas a glyph for this ligature); the same happens with @samp{:u}. All 13285104862Sruoutput glyph nodes are `processed' which means that they are invariably 13286104862Sruassociated with a given font, font size, advance width, etc. During 13287104862Sruthe formatting process, @code{gtroff} itself adds various nodes to 13288104862Srucontrol the data flow. 1328975584Sru 1329075584SruMacros, diversions, and strings collect elements in two chained lists: 1329175584Srua list of input tokens which have been passed unprocessed, and a list 1329275584Sruof output nodes. Consider the following the diversion. 1329375584Sru 1329475584Sru@Example 1329575584Sru.di xxx 1329675584Srua 1329775584Sru\!b 1329875584Sruc 1329975584Sru.br 1330075584Sru.di 1330175584Sru@endExample 1330275584Sru 1330375584Sru@noindent 1330475584SruIt contains these elements. 1330575584Sru 1330675584Sru@multitable {@i{vertical size node}} {token list} {element number} 1330775584Sru@item node list @tab token list @tab element number 1330875584Sru 1330975584Sru@item @i{line start node} @tab --- @tab 1 1331075584Sru@item @i{glyph node @code{a}} @tab --- @tab 2 1331175584Sru@item @i{word space node} @tab --- @tab 3 1331275584Sru@item --- @tab @code{b} @tab 4 1331375584Sru@item --- @tab @code{\n} @tab 5 1331475584Sru@item @i{glyph node @code{c}} @tab --- @tab 6 1331575584Sru@item @i{vertical size node} @tab --- @tab 7 1331675584Sru@item @i{vertical size node} @tab --- @tab 8 1331775584Sru@item --- @tab @code{\n} @tab 9 1331875584Sru@end multitable 1331975584Sru 13320104862Sru@cindex @code{\v}, internal representation 1332175584Sru@noindent 13322114402SruElements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two 1332375584Sru(which are always present) specify the vertical extent of the last 13324104862Sruline, possibly modified by @code{\x}. The @code{br} request finishes 1332575584Sruthe current partial line, inserting a newline input token which is 1332675584Srusubsequently converted to a space when the diversion is reread. Note 1332775584Sruthat the word space node has a fixed width which isn't stretchable 1332875584Sruanymore. To convert horizontal space nodes back to input tokens, use 1332975584Sruthe @code{unformat} request. 1333075584Sru 1333175584SruMacros only contain elements in the token list (and the node list is 1333275584Sruempty); diversions and strings can contain elements in both lists. 1333375584Sru 13334104862SruNote that the @code{chop} request simply reduces the number of elements in a 13335104862Srumacro, string, or diversion by one. Exceptions are @dfn{compatibility save} 13336104862Sruand @dfn{compatibility ignore} input tokens which are ignored. The 13337104862Sru@code{substring} request also ignores those input tokens. 1333875584Sru 13339104862SruSome requests like @code{tr} or @code{cflags} work on glyph 13340104862Sruidentifiers only; this means that the associated glyph can be changed 13341104862Sruwithout destroying this association. This can be very helpful for 13342104862Srusubstituting glyphs. In the following example, we assume that 13343104862Sruglyph @samp{foo} isn't available by default, so we provide a 13344104862Srusubstitution using the @code{fchar} request and map it to input 13345104862Srucharacter @samp{x}. 13346104862Sru 13347104862Sru@Example 13348104862Sru.fchar \[foo] foo 13349104862Sru.tr x \[foo] 13350104862Sru@endExample 13351104862Sru 13352104862Sru@noindent 13353104862SruNow let us assume that we install an additional special font 13354104862Sru@samp{bar} which has glyph @samp{foo}. 13355104862Sru 13356104862Sru@Example 13357104862Sru.special bar 13358104862Sru.rchar \[foo] 13359104862Sru@endExample 13360104862Sru 13361104862Sru@noindent 13362104862SruSince glyphs defined with @code{fchar} are searched before glyphs 13363104862Sruin special fonts, we must call @code{rchar} to remove the definition 13364104862Sruof the fallback glyph. Anyway, the translation is still active; 13365104862Sru@samp{x} now maps to the real glyph @samp{foo}. 13366104862Sru 13367151497Sru@cindex compatibility mode, and parameters 13368151497Sru@cindex mode, compatibility, and parameters 13369151497Sru@cindex arguments, and compatibility mode 13370151497Sru@cindex parameters, and compatibility mode 13371151497Sru@cindex macro arguments, and compatibility mode 13372151497Sru@cindex request arguments, and compatibility mode 13373151497SruMacro and request arguments preserve the compatibility mode: 13374104862Sru 13375151497Sru@Example 13376151497Sru.cp 1 \" switch to compatibility mode 13377151497Sru.de xx 13378151497Sru\\$1 13379151497Sru.. 13380151497Sru.cp 0 \" switch compatibility mode off 13381151497Sru.xx caf\['e] 13382151497Sru @result{} caf� 13383151497Sru@endExample 13384151497Sru 13385151497Sru@noindent 13386151497SruSince compatibility mode is on while @code{de} is called, the macro 13387151497Sru@code{xx} activates compatibility mode while executing. Argument 13388151497Sru@code{$1} can still be handled properly because it inherits the 13389151497Srucompatibility mode status which was active at the point where @code{xx} 13390151497Sruis called. 13391151497Sru 13392151497SruAfter expansion of the parameters, the compatibility save and restore 13393151497Srutokens are removed. 13394151497Sru 13395151497Sru 1339675584Sru@c ===================================================================== 1339775584Sru 1339875584Sru@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 1339955839Sasmodai@section Debugging 1340055839Sasmodai@cindex debugging 1340155839Sasmodai 1340269626Sru@code{gtroff} is not easy to debug, but there are some useful features 1340369626Sruand strategies for debugging. 1340455839Sasmodai 13405114402Sru@Defreq {lf, line [@Var{filename}]} 13406104862Sru@pindex soelim 13407104862Sru@cindex multi-file documents 13408104862Sru@cindex documents, multi-file 13409104862Sru@cindex setting input line number (@code{lf}) 13410104862Sru@cindex input line number, setting (@code{lf}) 13411104862Sru@cindex number, input line, setting (@code{lf}) 13412114402SruChange the line number and optionally the file name @code{gtroff} shall 13413114402Sruuse for error and warning messages. @var{line} is the input line number 13414114402Sruof the @emph{next} line. 13415104862Sru 13416104862SruWithout argument, the request is ignored. 13417104862Sru 13418104862SruThis is a debugging aid for documents which are split into many files, 13419104862Sruthen put together with @code{soelim} and other preprocessors. Usually, 13420104862Sruit isn't invoked manually. 13421114402Sru 13422114402SruNote that other @code{troff} implementations (including the original 13423114402Sru@acronym{AT&T} version) handle @code{lf} differently. For them, 13424114402Sru@var{line} changes the line number of the @emph{current} line. 1342575584Sru@endDefreq 1342669626Sru 13427104862Sru@DefreqList {tm, string} 13428104862Sru@DefreqItem {tm1, string} 13429104862Sru@DefreqListEnd {tmc, string} 13430104862Sru@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc}) 13431104862Sru@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc}) 13432104862SruSend @var{string} to the standard error output; 13433104862Sruthis is very useful for printing debugging messages among other things. 13434104862Sru 13435104862Sru@var{string} is read in copy mode. 13436104862Sru 13437104862SruThe @code{tm} request ignores leading spaces of @var{string}; @code{tm1} 13438104862Sruhandles its argument similar to the @code{ds} request: a leading double 13439104862Sruquote in @var{string} is stripped to allow initial blanks. 13440104862Sru 13441104862SruThe @code{tmc} request is similar to @code{tm1} but does 13442104862Srunot append a newline (as is done in @code{tm} and @code{tm1}). 13443104862Sru@endDefreq 13444104862Sru 1344575584Sru@Defreq {ab, [@Var{string}]} 13446104862Sru@cindex aborting (@code{ab}) 1344775584SruSimilar to the @code{tm} request, except that 1344875584Sruit causes @code{gtroff} to stop processing. With no argument it 13449104862Sruprints @samp{User Abort.} to standard error. 1345075584Sru@endDefreq 1345175584Sru 1345275584Sru@Defreq {ex, } 13453104862Sru@cindex @code{ex} request, use in debugging 13454104862Sru@cindex exiting (@code{ex}) 13455104862SruThe @code{ex} request also causes @code{gtroff} to stop processing; 13456104862Srusee also @ref{I/O}. 1345775584Sru@endDefreq 1345875584Sru 1345955839SasmodaiWhen doing something involved it is useful to leave the debugging 1346069626Srustatements in the code and have them turned on by a command line flag. 1346155839Sasmodai 1346275584Sru@Example 1346355839Sasmodai.if \n(DB .tm debugging output 1346475584Sru@endExample 1346555839Sasmodai 1346669626Sru@noindent 1346769626SruTo activate these statements say 1346855839Sasmodai 1346975584Sru@Example 1347055839Sasmodaigroff -rDB=1 file 1347175584Sru@endExample 1347255839Sasmodai 1347369626SruIf it is known in advance that there will be many errors and no useful 1347469626Sruoutput, @code{gtroff} can be forced to suppress formatted output with 1347569626Sruthe @option{-z} flag. 1347669626Sru 1347775584Sru@Defreq {pm, } 13478104862Sru@cindex dumping symbol table (@code{pm}) 13479104862Sru@cindex symbol table, dumping (@code{pm}) 13480104862SruPrint the entire symbol table on @code{stderr}. Names of all defined 13481104862Srumacros, strings, and diversions are print together with their size in 13482104862Srubytes. Since @code{gtroff} sometimes adds nodes by itself, the 13483104862Srureturned size can be larger than expected. 13484104862Sru 13485104862SruThis request differs from @acronym{UNIX} @code{troff}: @code{gtroff} 13486104862Srureports the sizes of diversions, ignores an additional argument to 13487104862Sruprint only the total of the sizes, and the size isn't returned in 13488104862Srublocks of 128 characters. 1348975584Sru@endDefreq 1349069626Sru 1349175584Sru@Defreq {pnr, } 13492104862Sru@cindex dumping number registers (@code{pnr}) 13493104862Sru@cindex number registers, dumping (@code{pnr}) 13494104862SruPrint the names and contents of all 1349575584Srucurrently defined number registers on @code{stderr}. 1349675584Sru@endDefreq 1349769626Sru 1349875584Sru@Defreq {ptr, } 13499104862Sru@cindex dumping traps (@code{ptr}) 13500104862Sru@cindex traps, dumping (@code{ptr}) 13501104862SruPrint the names and positions of all traps 1350275584Sru(not including input line traps and diversion traps) on @code{stderr}. 1350375584SruEmpty slots in the page trap list are printed as well, because they can 1350475584Sruaffect the priority of subsequently planted traps. 1350575584Sru@endDefreq 1350669626Sru 13507104862Sru@Defreq {fl, } 13508104862Sru@cindex flush output (@code{fl}) 13509104862Sru@cindex output, flush (@code{fl}) 1351069626Sru@cindex interactive use of @code{gtroff} 1351169626Sru@cindex @code{gtroff}, interactive use 13512104862SruInstruct @code{gtroff} to flush its output immediately. The intent 13513104862Sruis for interactive use, but this behaviour is currently not 13514104862Sruimplemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff}, 13515104862SruTTY output is sent to a device driver also (@code{grotty}), making it 13516104862Srunon-trivial to communicate interactively. 13517104862Sru 13518104862SruThis request causes a line break. 1351975584Sru@endDefreq 1352069626Sru 1352175584Sru@Defreq {backtrace, } 13522104862Sru@cindex backtrace of input stack (@code{backtrace}) 13523104862Sru@cindex input stack, backtrace (@code{backtrace}) 13524104862SruPrint a backtrace of the input stack to the standard error stream. 13525104862Sru 13526104862SruConsider the following in file @file{test}: 13527104862Sru 13528104862Sru@Example 13529104862Sru.de xxx 13530104862Sru. backtrace 13531104862Sru.. 13532104862Sru.de yyy 13533104862Sru. xxx 13534104862Sru.. 13535104862Sru. 13536104862Sru.yyy 13537104862Sru@endExample 13538104862Sru 13539104862Sru@noindent 13540104862SruOn execution, @code{gtroff} prints the following: 13541104862Sru 13542104862Sru@Example 13543104862Srutest:2: backtrace: macro `xxx' 13544104862Srutest:5: backtrace: macro `yyy' 13545104862Srutest:8: backtrace: file `test' 13546104862Sru@endExample 13547104862Sru 13548104862SruThe option @option{-b} of @code{gtroff} internally calls a variant of 13549104862Sruthis request on each error and warning. 1355075584Sru@endDefreq 1355169626Sru 13552104862Sru@Defreg {slimit} 13553104862Sru@cindex input stack, setting limit 13554104862SruUse the @code{slimit} number register 13555104862Sruto set the maximum number of objects on the input stack. 13556114402SruIf @code{slimit} is less than or equal to@tie{}0, 13557104862Sruthere is no limit set. 13558104862SruWith no limit, a buggy recursive macro can exhaust virtual memory. 13559104862Sru 13560104862SruThe default value is 1000; this is a compile-time constant. 13561104862Sru@endDefreg 13562104862Sru 13563104862Sru@Defreq {warnscale, si} 13564104862SruSet the scaling indicator used in warnings to @var{si}. Valid values for 13565104862Sru@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At 13566104862Srustartup, it is set to @samp{i}. 13567104862Sru@endDefreq 13568104862Sru 13569104862Sru@Defreq {spreadwarn, [@Var{limit}]} 13570104862SruMake @code{gtroff} emit a warning if the additional space inserted for 13571104862Srueach space between words in an output line is larger or equal to 13572104862Sru@var{limit}. A negative value is changed to zero; no argument toggles the 13573104862Sruwarning on and off without changing @var{limit}. The default scaling 13574104862Sruindicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and 13575104862Sru@var{limit} is set to 3@dmn{m}. 13576104862Sru 13577104862SruFor example, 13578104862Sru 13579104862Sru@Example 13580104862Sru.spreadwarn 0.2m 13581104862Sru@endExample 13582104862Sru 13583104862Sru@noindent 13584104862Sruwill cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each 13585104862Sruinterword space in a line. 13586104862Sru 13587104862SruThis request is active only if text is justified to both margins (using 13588104862Sru@w{@samp{.ad b}}). 13589104862Sru@endDefreq 13590104862Sru 1359169626Sru@cindex warnings 1359269626Sru@code{gtroff} has command line options for printing out more warnings 1359369626Sru(@option{-w}) and for printing backtraces (@option{-b}) when a warning 1359469626Sruor an error occurs. The most verbose level of warnings is @option{-ww}. 1359569626Sru 13596104862Sru@DefreqList {warn, [@Var{flags}]} 13597104862Sru@DefregListEnd {.warn} 13598104862Sru@cindex level of warnings (@code{warn}) 13599104862Sru@cindex warnings, level (@code{warn}) 13600104862SruControl the level of warnings checked for. The @var{flags} are the sum 1360175584Sruof the numbers associated with each warning that is to be enabled; all 1360275584Sruother warnings are disabled. The number associated with each warning is 1360375584Srulisted below. For example, @w{@code{.warn 0}} disables all warnings, 1360475584Sruand @w{@code{.warn 1}} disables all warnings except that about missing 13605104862Sruglyphs. If no argument is given, all warnings are enabled. 1360655839Sasmodai 1360775584SruThe read-only number register @code{.warn} contains the current warning 1360875584Srulevel. 1360975584Sru@endDefreq 1361069626Sru 1361169626Sru@menu 1361275584Sru* Warnings:: 1361369626Sru@end menu 1361469626Sru 1361575584Sru@c --------------------------------------------------------------------- 1361675584Sru 1361769626Sru@node Warnings, , Debugging, Debugging 1361855839Sasmodai@subsection Warnings 1361955839Sasmodai@cindex warnings 1362055839Sasmodai 1362169626SruThe warnings that can be given to @code{gtroff} are divided into the 1362269626Srufollowing categories. The name associated with each warning is used by 1362369626Sruthe @option{-w} and @option{-W} options; the number is used by the 1362469626Sru@code{warn} request and by the @code{.warn} register. 1362555839Sasmodai 1362655839Sasmodai@table @samp 1362769626Sru@item char 1362855839Sasmodai@itemx 1 13629104862SruNon-existent glyphs.@footnote{@code{char} is a misnomer since it reports 13630104862Srumissing glyphs -- there aren't missing input characters, only invalid 13631104862Sruones.} This is enabled by default. 1363269626Sru 1363369626Sru@item number 1363455839Sasmodai@itemx 2 1363555839SasmodaiInvalid numeric expressions. This is enabled by default. 1363669626Sru@xref{Expressions}. 1363769626Sru 1363869626Sru@item break 1363955839Sasmodai@itemx 4 1364069626Sru@cindex fill mode 1364169626Sru@cindex mode, fill 1364269626SruIn fill mode, lines which could not be broken so that their length was 1364369626Sruless than the line length. This is enabled by default. 1364469626Sru 1364569626Sru@item delim 1364655839Sasmodai@itemx 8 1364755839SasmodaiMissing or mismatched closing delimiters. 1364869626Sru 1364969626Sru@item el 1365055839Sasmodai@itemx 16 13651104862Sru@cindex @code{ie} request, and warnings 13652104862Sru@cindex @code{el} request, and warnings 1365355839SasmodaiUse of the @code{el} request with no matching @code{ie} request. 1365469626Sru@xref{if-else}. 1365569626Sru 1365669626Sru@item scale 1365755839Sasmodai@itemx 32 1365855839SasmodaiMeaningless scaling indicators. 1365969626Sru 1366069626Sru@item range 1366155839Sasmodai@itemx 64 1366255839SasmodaiOut of range arguments. 1366369626Sru 1366469626Sru@item syntax 1366555839Sasmodai@itemx 128 1366655839SasmodaiDubious syntax in numeric expressions. 1366769626Sru 1366869626Sru@item di 1366955839Sasmodai@itemx 256 13670104862Sru@cindex @code{di} request, and warnings 13671104862Sru@cindex @code{da} request, and warnings 1367255839SasmodaiUse of @code{di} or @code{da} without an argument when there is no 1367355839Sasmodaicurrent diversion. 1367469626Sru 1367569626Sru@item mac 1367655839Sasmodai@itemx 512 13677104862Sru@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings 13678104862Sru@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings 13679104862Sru@cindex @code{ds}, @code{ds1} requests, and warnings 13680104862Sru@cindex @code{as}, @code{as1} requests, and warnings 13681104862Sru@cindex @code{di} request, and warnings 13682104862Sru@cindex @code{da} request, and warnings 13683104862Sru@cindex @code{box}, @code{boxa} requests, and warnings 13684104862Sru@cindex @code{\*}, and warnings 1368569626SruUse of undefined strings, macros and diversions. When an undefined 13686104862Srustring, macro, or diversion is used, that string is automatically 13687104862Srudefined as empty. So, in most cases, at most one warning is given 13688104862Srufor each name. 1368969626Sru 13690104862Sru@item reg 1369155839Sasmodai@itemx 1024 13692104862Sru@cindex @code{nr} request, and warnings 13693104862Sru@cindex @code{\R}, and warnings 13694104862Sru@cindex @code{\n}, and warnings 1369569626SruUse of undefined number registers. When an undefined number register is 13696114402Sruused, that register is automatically defined to have a value of@tie{}0. 13697104862SruSo, in most cases, at most one warning is given for use of a particular 13698104862Sruname. 1369969626Sru 13700104862Sru@item tab 1370155839Sasmodai@itemx 2048 13702104862Sru@cindex @code{\t}, and warnings 1370355839SasmodaiUse of a tab character where a number was expected. 1370469626Sru 13705104862Sru@item right-brace 1370655839Sasmodai@itemx 4096 13707104862Sru@cindex @code{\@}}, and warnings 1370855839SasmodaiUse of @code{\@}} where a number was expected. 1370969626Sru 13710104862Sru@item missing 1371155839Sasmodai@itemx 8192 1371255839SasmodaiRequests that are missing non-optional arguments. 1371369626Sru 13714104862Sru@item input 1371555839Sasmodai@itemx 16384 13716104862SruInvalid input characters. 1371769626Sru 13718104862Sru@item escape 1371955839Sasmodai@itemx 32768 13720104862SruUnrecognized escape sequences. When an unrecognized escape sequence 13721104862Sru@code{\@var{X}} is encountered, the escape character is ignored, and 13722104862Sru@var{X} is printed. 1372369626Sru 13724104862Sru@item space 1372555839Sasmodai@itemx 65536 1372669626Sru@cindex compatibility mode 1372769626SruMissing space between a request or macro and its argument. This warning 1372875584Sruis given when an undefined name longer than two characters is 1372969626Sruencountered, and the first two characters of the name make a defined 1373075584Sruname. The request or macro is not invoked. When this warning is 1373169626Srugiven, no macro is automatically defined. This is enabled by default. 1373275584SruThis warning never occurs in compatibility mode. 1373369626Sru 13734104862Sru@item font 1373555839Sasmodai@itemx 131072 1373669626SruNon-existent fonts. This is enabled by default. 1373769626Sru 13738104862Sru@item ig 13739104862Sru@itemx 262144 13740104862SruInvalid escapes in text ignored with the @code{ig} request. These are 13741104862Sruconditions that are errors when they do not occur in ignored text. 13742104862Sru 13743104862Sru@item color 13744104862Sru@itemx 524288 13745104862SruColor related warnings. 13746104862Sru 1374755839Sasmodai@item all 1374869626SruAll warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 1374969626Sruintended that this covers all warnings that are useful with traditional 1375069626Srumacro packages. 1375169626Sru 1375255839Sasmodai@item w 1375355839SasmodaiAll warnings. 1375455839Sasmodai@end table 1375555839Sasmodai 1375655839Sasmodai 1375769626Sru@c ===================================================================== 1375869626Sru 13759104862Sru@node Implementation Differences, , Debugging, gtroff Reference 1376055839Sasmodai@section Implementation Differences 1376155839Sasmodai@cindex implementation differences 1376255839Sasmodai@cindex differences in implementation 13763104862Sru@cindex incompatibilities with @acronym{AT&T} @code{troff} 1376469626Sru@cindex compatibility mode 1376569626Sru@cindex mode, compatibility 1376655839Sasmodai 1376769626SruGNU @code{troff} has a number of features which cause incompatibilities 1376869626Sruwith documents written with old versions of @code{troff}. 1376955839Sasmodai 1377069626Sru@cindex long names 1377169626Sru@cindex names, long 1377269626SruLong names cause some incompatibilities. @acronym{UNIX} @code{troff} 1377375584Sruinterprets 1377455839Sasmodai 1377575584Sru@Example 1377655839Sasmodai.dsabcd 1377775584Sru@endExample 1377855839Sasmodai 13779104862Sru@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff} 13780104862Sru@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff} 1378169626Sru@noindent 1378269626Sruas defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 1378375584Sru@code{troff} interprets this as a call of a macro named 1378475584Sru@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 1378569626Sru@code{\*[} or @code{\n[} as references to a string or number register 1378675584Srucalled @samp{[}. In GNU @code{troff}, however, this is normally 1378769626Sruinterpreted as the start of a long name. In compatibility mode GNU 1378875584Sru@code{troff} interprets long names in the traditional way 1378975584Sru(which means that they are not recognized as names). 1379055839Sasmodai 13791104862Sru@DefreqList {cp, [@Var{n}]} 13792104862Sru@DefreqItem {do, cmd} 13793104862Sru@DefregListEnd {.C} 13794104862SruIf @var{n} is missing or non-zero, turn on compatibility mode; 13795104862Sruotherwise, turn it off. 13796104862Sru 13797114402SruThe read-only number register @code{.C} is@tie{}1 if compatibility mode is 13798114402Sruon, 0@tie{}otherwise. 13799104862Sru 13800104862SruCompatibility mode can be also turned on with the @option{-C} command line 13801104862Sruoption. 13802104862Sru 13803104862SruThe @code{do} request turns off compatibility mode 13804104862Sruwhile executing its arguments as a @code{gtroff} command. 13805104862Sru 13806104862Sru@Example 13807104862Sru.do fam T 13808104862Sru@endExample 13809104862Sru 13810104862Sru@noindent 13811104862Sruexecutes the @code{fam} request when compatibility mode 13812104862Sruis enabled. 13813104862Sru 13814104862Sru@code{gtroff} restores the previous compatibility setting 13815104862Srubefore interpreting any files sourced by the @var{cmd}. 13816104862Sru@endDefreq 13817104862Sru 13818104862Sru@cindex input level in delimited arguments 13819104862Sru@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff} 13820104862SruTwo other features are controlled by @option{-C}. If not in 13821104862Srucompatibility mode, GNU @code{troff} preserves the input level in 13822104862Srudelimited arguments: 13823104862Sru 13824104862Sru@Example 13825104862Sru.ds xx ' 13826104862Sru\w'abc\*(xxdef' 13827104862Sru@endExample 13828104862Sru 13829104862Sru@noindent 13830104862SruIn compatibility mode, the string @samp{72def'} is returned; without 13831104862Sru@option{-C} the resulting string is @samp{168} (assuming a TTY output 13832104862Srudevice). 13833104862Sru 13834104862Sru@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff} 13835104862Sru@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff} 13836104862Sru@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff} 13837104862Sru@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff} 13838104862SruFinally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M}, 13839104862Sru@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the 13840104862Srubeginning of a line only in compatibility mode (this is a rather obscure 13841104862Srufeature). For example, the code 13842104862Sru 13843104862Sru@Example 13844104862Sru.de xx 13845104862SruHallo! 13846104862Sru.. 13847104862Sru\fB.xx\fP 13848104862Sru@endExample 13849104862Sru 13850114402Sru@noindent 13851104862Sruprints @samp{Hallo!} in bold face if in compatibility mode, and 13852104862Sru@samp{.xx} in bold face otherwise. 13853104862Sru 13854104862Sru@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff} 13855104862Sru@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff} 13856104862Sru@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff} 13857104862Sru@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff} 13858104862Sru@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff} 13859104862Sru@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff} 13860104862Sru@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff} 13861104862Sru@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff} 13862104862Sru@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff} 13863104862Sru@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff} 13864104862Sru@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff} 13865104862Sru@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13866104862Sru@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff} 13867104862Sru@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff} 1386869626SruGNU @code{troff} does not allow the use of the escape sequences 1386975584Sru@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 1387069626Sru@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 1387169626Sru@code{\%}, and @code{\c} in names of strings, macros, diversions, number 1387269626Sruregisters, fonts or environments; @acronym{UNIX} @code{troff} does. The 1387369626Sru@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 1387469626Sruavoiding use of these escape sequences in names. 1387555839Sasmodai 1387655839Sasmodai@cindex fractional point sizes 13877104862Sru@cindex fractional type sizes 1387855839Sasmodai@cindex point sizes, fractional 13879104862Sru@cindex type sizes, fractional 13880104862Sru@cindex sizes, fractional 13881104862Sru@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff} 1388269626SruFractional point sizes cause one noteworthy incompatibility. In 1388369626Sru@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 1388469626Sruindicators and thus 1388555839Sasmodai 1388675584Sru@Example 1388755839Sasmodai.ps 10u 1388875584Sru@endExample 1388955839Sasmodai 1389069626Sru@noindent 13891114402Srusets the point size to 10@tie{}points, whereas in GNU @code{troff} it 13892114402Srusets the point size to 10@tie{}scaled points. @xref{Fractional Type 1389369626SruSizes}, for more information. 1389455839Sasmodai 13895104862Sru@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} 13896104862Sru@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff} 13897104862Sru@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff} 13898104862Sru@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff} 13899104862Sru@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13900104862Sru@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff} 13901104862Sru@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13902104862Sru@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff} 1390369626SruIn GNU @code{troff} there is a fundamental difference between 13904104862Sru(unformatted) input characters and (formatted) output glyphs. 13905104862SruEverything that affects how a glyph is output is stored 13906104862Sruwith the glyph node; once a glyph node has been constructed it is 1390755839Sasmodaiunaffected by any subsequent requests that are executed, including 1390869626Sru@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 13909104862SruNormally glyphs are constructed from input characters at the 13910104862Srumoment immediately before the glyph is added to the current output 1391169626Sruline. Macros, diversions and strings are all, in fact, the same type of 13912104862Sruobject; they contain lists of input characters and glyph nodes in 13913104862Sruany combination. A glyph node does not behave like an input 1391469626Srucharacter for the purposes of macro processing; it does not inherit any 1391569626Sruof the special properties that the input character from which it was 1391669626Sruconstructed might have had. For example, 1391755839Sasmodai 1391875584Sru@Example 1391955839Sasmodai.di x 1392055839Sasmodai\\\\ 1392155839Sasmodai.br 1392255839Sasmodai.di 1392355839Sasmodai.x 1392475584Sru@endExample 1392555839Sasmodai 13926104862Sru@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13927104862Sru@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13928104862Sru@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff} 13929104862Sru@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13930104862Sru@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff} 13931104862Sru@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff} 13932104862Sru@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff} 1393369626Sru@noindent 1393475584Sruprints @samp{\\} in GNU @code{troff}; each pair of input backslashes 1393569626Sruis turned into one output backslash and the resulting output backslashes 1393669626Sruare not interpreted as escape characters when they are reread. 1393769626Sru@acronym{UNIX} @code{troff} would interpret them as escape characters 1393869626Sruwhen they were reread and would end up printing one @samp{\}. The 1393969626Srucorrect way to obtain a printable backslash is to use the @code{\e} 1394075584Sruescape sequence: This always prints a single instance of the current 1394169626Sruescape character, regardless of whether or not it is used in a 1394275584Srudiversion; it also works in both GNU @code{troff} and @acronym{UNIX} 13943104862Sru@code{troff}.@footnote{To be completely independent of the current 13944104862Sruescape character, use @code{\(rs} which represents a reverse solidus 13945104862Sru(backslash) glyph.} To store, for some reason, an escape sequence in a 1394669626Srudiversion that will be interpreted when the diversion is reread, either 1394769626Sruuse the traditional @code{\!} transparent output facility, or, if this 1394869626Sruis unsuitable, the new @code{\?} escape sequence. 1394955839Sasmodai 13950104862Sru@xref{Diversions}, and @ref{Gtroff Internals}, for more information. 1395175584Sru 1395255839Sasmodai 1395369626Sru 1395469626Sru@c ===================================================================== 1395569626Sru@c ===================================================================== 1395669626Sru 1395775584Sru@node Preprocessors, Output Devices, gtroff Reference, Top 1395869626Sru@chapter Preprocessors 1395969626Sru@cindex preprocessors 1396069626Sru 1396169626SruThis chapter describes all preprocessors that come with @code{groff} or 1396269626Sruwhich are freely available. 1396369626Sru 1396469626Sru@menu 1396575584Sru* geqn:: 1396675584Sru* gtbl:: 1396775584Sru* gpic:: 1396875584Sru* ggrn:: 1396975584Sru* grap:: 1397075584Sru* grefer:: 1397175584Sru* gsoelim:: 1397269626Sru@end menu 1397369626Sru 1397469626Sru 1397569626Sru@c ===================================================================== 1397669626Sru 1397769626Sru@node geqn, gtbl, Preprocessors, Preprocessors 1397869626Sru@section @code{geqn} 13979104862Sru@cindex @code{eqn}, the program 13980104862Sru@cindex @code{geqn}, the program 1398155839Sasmodai 1398269626Sru@c XXX 1398355839Sasmodai 1398455839Sasmodai@menu 1398575584Sru* Invoking geqn:: 1398655839Sasmodai@end menu 1398755839Sasmodai 1398869626Sru@c --------------------------------------------------------------------- 1398969626Sru 1399055839Sasmodai@node Invoking geqn, , geqn, geqn 1399169626Sru@subsection Invoking @code{geqn} 1399255839Sasmodai@cindex invoking @code{geqn} 1399355839Sasmodai@cindex @code{geqn}, invoking 1399455839Sasmodai 1399569626Sru@c XXX 1399655839Sasmodai 1399755839Sasmodai 1399869626Sru@c ===================================================================== 1399969626Sru 1400069626Sru@node gtbl, gpic, geqn, Preprocessors 1400169626Sru@section @code{gtbl} 14002104862Sru@cindex @code{tbl}, the program 14003104862Sru@cindex @code{gtbl}, the program 1400455839Sasmodai 1400569626Sru@c XXX 1400655839Sasmodai 1400755839Sasmodai@menu 1400875584Sru* Invoking gtbl:: 1400955839Sasmodai@end menu 1401055839Sasmodai 1401169626Sru@c --------------------------------------------------------------------- 1401269626Sru 1401355839Sasmodai@node Invoking gtbl, , gtbl, gtbl 1401469626Sru@subsection Invoking @code{gtbl} 1401555839Sasmodai@cindex invoking @code{gtbl} 1401655839Sasmodai@cindex @code{gtbl}, invoking 1401755839Sasmodai 1401869626Sru@c XXX 1401955839Sasmodai 1402069626Sru 1402169626Sru@c ===================================================================== 1402269626Sru 1402369626Sru@node gpic, ggrn, gtbl, Preprocessors 1402469626Sru@section @code{gpic} 14025104862Sru@cindex @code{pic}, the program 14026104862Sru@cindex @code{gpic}, the program 1402755839Sasmodai 1402869626Sru@c XXX 1402955839Sasmodai 1403055839Sasmodai@menu 1403175584Sru* Invoking gpic:: 1403255839Sasmodai@end menu 1403355839Sasmodai 1403469626Sru@c --------------------------------------------------------------------- 1403569626Sru 1403655839Sasmodai@node Invoking gpic, , gpic, gpic 1403769626Sru@subsection Invoking @code{gpic} 1403855839Sasmodai@cindex invoking @code{gpic} 1403955839Sasmodai@cindex @code{gpic}, invoking 1404055839Sasmodai 1404169626Sru@c XXX 1404255839Sasmodai 1404355839Sasmodai 1404469626Sru@c ===================================================================== 1404569626Sru 1404669626Sru@node ggrn, grap, gpic, Preprocessors 1404769626Sru@section @code{ggrn} 14048104862Sru@cindex @code{grn}, the program 14049104862Sru@cindex @code{ggrn}, the program 1405069626Sru 1405169626Sru@c XXX 1405269626Sru 1405369626Sru@menu 1405475584Sru* Invoking ggrn:: 1405569626Sru@end menu 1405669626Sru 1405769626Sru@c --------------------------------------------------------------------- 1405869626Sru 1405969626Sru@node Invoking ggrn, , ggrn, ggrn 1406069626Sru@subsection Invoking @code{ggrn} 1406169626Sru@cindex invoking @code{ggrn} 1406269626Sru@cindex @code{ggrn}, invoking 1406369626Sru 1406469626Sru@c XXX 1406569626Sru 1406669626Sru 1406769626Sru@c ===================================================================== 1406869626Sru 1406969626Sru@node grap, grefer, ggrn, Preprocessors 1407069626Sru@section @code{grap} 14071104862Sru@cindex @code{grap}, the program 1407255839Sasmodai 1407369626SruA free implementation of @code{grap}, written by Ted Faber, 1407469626Sruis available as an extra package from the following address: 1407555839Sasmodai 1407669626Sru@display 14077114402Sru@uref{http://www.lunabase.org/~faber/Vault/software/grap/} 1407869626Sru@end display 1407955839Sasmodai 1408069626Sru 1408169626Sru@c ===================================================================== 1408269626Sru 1408369626Sru@node grefer, gsoelim, grap, Preprocessors 1408469626Sru@section @code{grefer} 14085104862Sru@cindex @code{refer}, the program 14086104862Sru@cindex @code{grefer}, the program 1408755839Sasmodai 1408869626Sru@c XXX 1408955839Sasmodai 1409055839Sasmodai@menu 1409175584Sru* Invoking grefer:: 1409255839Sasmodai@end menu 1409355839Sasmodai 1409469626Sru@c --------------------------------------------------------------------- 1409569626Sru 1409655839Sasmodai@node Invoking grefer, , grefer, grefer 1409769626Sru@subsection Invoking @code{grefer} 1409855839Sasmodai@cindex invoking @code{grefer} 1409955839Sasmodai@cindex @code{grefer}, invoking 1410055839Sasmodai 1410169626Sru@c XXX 1410255839Sasmodai 1410355839Sasmodai 1410469626Sru@c ===================================================================== 1410569626Sru 1410669626Sru@node gsoelim, , grefer, Preprocessors 1410769626Sru@section @code{gsoelim} 14108104862Sru@cindex @code{soelim}, the program 14109104862Sru@cindex @code{gsoelim}, the program 1411055839Sasmodai 1411169626Sru@c XXX 1411255839Sasmodai 1411355839Sasmodai@menu 1411475584Sru* Invoking gsoelim:: 1411555839Sasmodai@end menu 1411655839Sasmodai 1411769626Sru@c --------------------------------------------------------------------- 1411869626Sru 1411955839Sasmodai@node Invoking gsoelim, , gsoelim, gsoelim 1412069626Sru@subsection Invoking @code{gsoelim} 1412155839Sasmodai@cindex invoking @code{gsoelim} 1412255839Sasmodai@cindex @code{gsoelim}, invoking 1412355839Sasmodai 1412469626Sru@c XXX 1412555839Sasmodai 1412655839Sasmodai 1412755839Sasmodai 1412869626Sru@c ===================================================================== 1412969626Sru@c ===================================================================== 1413055839Sasmodai 1413169626Sru@node Output Devices, File formats, Preprocessors, Top 1413269626Sru@chapter Output Devices 1413369626Sru@cindex output devices 1413469626Sru@cindex devices for output 1413555839Sasmodai 1413669626Sru@c XXX 1413769626Sru 1413855839Sasmodai@menu 1413975584Sru* Special Characters:: 1414075584Sru* grotty:: 1414175584Sru* grops:: 1414275584Sru* grodvi:: 1414375584Sru* grolj4:: 1414475584Sru* grolbp:: 1414575584Sru* grohtml:: 1414675584Sru* gxditview:: 1414755839Sasmodai@end menu 1414855839Sasmodai 1414969626Sru 1415069626Sru@c ===================================================================== 1415169626Sru 1415269626Sru@node Special Characters, grotty, Output Devices, Output Devices 1415355839Sasmodai@section Special Characters 1415455839Sasmodai@cindex special characters 1415555839Sasmodai@cindex characters, special 1415655839Sasmodai 1415769626Sru@c XXX 1415855839Sasmodai 1415969626Sru@xref{Font Files}. 1416055839Sasmodai 1416169626Sru 1416269626Sru@c ===================================================================== 1416369626Sru 1416469626Sru@node grotty, grops, Special Characters, Output Devices 1416555839Sasmodai@section @code{grotty} 14166104862Sru@cindex @code{grotty}, the program 1416755839Sasmodai 1416869626Sru@c XXX 1416955839Sasmodai 1417055839Sasmodai@menu 1417175584Sru* Invoking grotty:: 1417255839Sasmodai@end menu 1417355839Sasmodai 1417469626Sru@c --------------------------------------------------------------------- 1417569626Sru 1417655839Sasmodai@node Invoking grotty, , grotty, grotty 1417755839Sasmodai@subsection Invoking @code{grotty} 1417855839Sasmodai@cindex invoking @code{grotty} 1417955839Sasmodai@cindex @code{grotty}, invoking 1418055839Sasmodai 1418169626Sru@c XXX 1418255839Sasmodai 14183104862Sru@c The following is no longer true; fix and extend it. 1418455839Sasmodai 14185104862Sru@c @pindex less 14186104862Sru@c @cindex Teletype 14187104862Sru@c @cindex ISO 6249 SGR 14188104862Sru@c @cindex terminal control sequences 14189104862Sru@c @cindex control sequences, for terminals 14190104862Sru@c For TTY output devices, underlining is done by emitting sequences of 14191104862Sru@c @samp{_} and @samp{\b} (the backspace character) before the actual 14192104862Sru@c character. Literally, this is printing an underline character, then 14193104862Sru@c moving back one character position, and printing the actual character 14194104862Sru@c at the same position as the underline character (similar to a 14195104862Sru@c typewriter). Usually, a modern terminal can't interpret this (and the 14196104862Sru@c original Teletype machines for which this sequence was appropriate are 14197104862Sru@c no longer in use). You need a pager program like @code{less} which 14198104862Sru@c translates this into ISO 6429 SGR sequences to control terminals. 14199104862Sru 14200104862Sru 1420169626Sru@c ===================================================================== 1420269626Sru 1420369626Sru@node grops, grodvi, grotty, Output Devices 1420455839Sasmodai@section @code{grops} 14205104862Sru@cindex @code{grops}, the program 1420655839Sasmodai 1420769626Sru@c XXX 1420855839Sasmodai 1420955839Sasmodai@menu 1421075584Sru* Invoking grops:: 1421175584Sru* Embedding PostScript:: 1421255839Sasmodai@end menu 1421355839Sasmodai 1421469626Sru@c --------------------------------------------------------------------- 1421569626Sru 1421655839Sasmodai@node Invoking grops, Embedding PostScript, grops, grops 1421755839Sasmodai@subsection Invoking @code{grops} 1421855839Sasmodai@cindex invoking @code{grops} 1421955839Sasmodai@cindex @code{grops}, invoking 1422055839Sasmodai 1422169626Sru@c XXX 1422255839Sasmodai 1422369626Sru@c --------------------------------------------------------------------- 1422455839Sasmodai 1422555839Sasmodai@node Embedding PostScript, , Invoking grops, grops 1422669626Sru@subsection Embedding @sc{PostScript} 14227104862Sru@cindex embedding PostScript 14228104862Sru@cindex PostScript, embedding 1422955839Sasmodai 1423069626Sru@c XXX 1423155839Sasmodai 1423255839Sasmodai 1423369626Sru@c ===================================================================== 1423469626Sru 1423569626Sru@node grodvi, grolj4, grops, Output Devices 1423655839Sasmodai@section @code{grodvi} 14237104862Sru@cindex @code{grodvi}, the program 1423855839Sasmodai 1423969626Sru@c XXX 1424055839Sasmodai 1424155839Sasmodai@menu 1424275584Sru* Invoking grodvi:: 1424355839Sasmodai@end menu 1424455839Sasmodai 1424569626Sru@c --------------------------------------------------------------------- 1424669626Sru 1424755839Sasmodai@node Invoking grodvi, , grodvi, grodvi 1424855839Sasmodai@subsection Invoking @code{grodvi} 1424955839Sasmodai@cindex invoking @code{grodvi} 1425055839Sasmodai@cindex @code{grodvi}, invoking 1425155839Sasmodai 1425269626Sru@c XXX 1425355839Sasmodai 1425455839Sasmodai 1425569626Sru@c ===================================================================== 1425669626Sru 1425769626Sru@node grolj4, grolbp, grodvi, Output Devices 1425855839Sasmodai@section @code{grolj4} 14259104862Sru@cindex @code{grolj4}, the program 1426055839Sasmodai 1426169626Sru@c XXX 1426255839Sasmodai 1426355839Sasmodai@menu 1426475584Sru* Invoking grolj4:: 1426555839Sasmodai@end menu 1426655839Sasmodai 1426769626Sru@c --------------------------------------------------------------------- 1426869626Sru 1426955839Sasmodai@node Invoking grolj4, , grolj4, grolj4 1427055839Sasmodai@subsection Invoking @code{grolj4} 1427155839Sasmodai@cindex invoking @code{grolj4} 1427255839Sasmodai@cindex @code{grolj4}, invoking 1427355839Sasmodai 1427469626Sru@c XXX 1427555839Sasmodai 1427655839Sasmodai 1427769626Sru@c ===================================================================== 1427869626Sru 1427969626Sru@node grolbp, grohtml, grolj4, Output Devices 1428069626Sru@section @code{grolbp} 14281104862Sru@cindex @code{grolbp}, the program 1428269626Sru 1428369626Sru@c XXX 1428469626Sru 1428569626Sru@menu 1428675584Sru* Invoking grolbp:: 1428769626Sru@end menu 1428869626Sru 1428969626Sru@c --------------------------------------------------------------------- 1429069626Sru 1429169626Sru@node Invoking grolbp, , grolbp, grolbp 1429269626Sru@subsection Invoking @code{grolbp} 1429369626Sru@cindex invoking @code{grolbp} 1429469626Sru@cindex @code{grolbp}, invoking 1429569626Sru 1429669626Sru@c XXX 1429769626Sru 1429869626Sru 1429969626Sru@c ===================================================================== 1430069626Sru 1430169626Sru@node grohtml, gxditview, grolbp, Output Devices 1430255839Sasmodai@section @code{grohtml} 14303104862Sru@cindex @code{grohtml}, the program 1430455839Sasmodai 1430569626Sru@c XXX 1430655839Sasmodai 1430755839Sasmodai@menu 1430875584Sru* Invoking grohtml:: 14309104862Sru* grohtml specific registers and strings:: 1431055839Sasmodai@end menu 1431155839Sasmodai 1431269626Sru@c --------------------------------------------------------------------- 1431369626Sru 14314104862Sru@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml 1431555839Sasmodai@subsection Invoking @code{grohtml} 1431655839Sasmodai@cindex invoking @code{grohtml} 1431755839Sasmodai@cindex @code{grohtml}, invoking 1431855839Sasmodai 1431969626Sru@c XXX 1432055839Sasmodai 14321104862Sru@c --------------------------------------------------------------------- 1432255839Sasmodai 14323104862Sru@node grohtml specific registers and strings, , Invoking grohtml, grohtml 14324104862Sru@subsection @code{grohtml} specific registers and strings 14325104862Sru@cindex registers specific to @code{grohtml} 14326104862Sru@cindex strings specific to @code{grohtml} 14327104862Sru@cindex @code{grohtml}, registers and strings 14328104862Sru 14329104862Sru@DefmpregList {ps4html, grohtml} 14330104862Sru@DefstrListEnd {www-image-template, grohtml} 14331104862SruThe registers @code{ps4html} and @code{www-image-template} are defined 14332104862Sruby the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in 14333104862Sruthe @code{troff} input, marks up the inline equations and passes the 14334104862Sruresult firstly to 14335104862Sru 14336104862Sru@Example 14337104862Srutroff -Tps -rps4html=1 -dwww-image-template=@var{template} 14338104862Sru@endExample 14339104862Sru 14340104862Sru@noindent 14341104862Sruand secondly to 14342104862Sru 14343104862Sru@Example 14344104862Srutroff -Thtml 14345104862Sru@endExample 14346104862Sru 14347104862SruThe PostScript device is used to create all the image files, and the 14348104862Sruregister @code{ps4html} enables the macro sets to ignore floating 14349104862Srukeeps, footers, and headings. 14350104862Sru 14351104862SruThe register @code{www-image-template} is set to the user specified 14352104862Srutemplate name or the default name. 14353104862Sru@endDefmpreg 14354104862Sru 14355104862Sru 1435669626Sru@c ===================================================================== 1435769626Sru 1435869626Sru@node gxditview, , grohtml, Output Devices 1435955839Sasmodai@section @code{gxditview} 14360104862Sru@cindex @code{gxditview}, the program 1436155839Sasmodai 1436269626Sru@c XXX 1436355839Sasmodai 1436455839Sasmodai@menu 1436575584Sru* Invoking gxditview:: 1436655839Sasmodai@end menu 1436755839Sasmodai 1436869626Sru@c --------------------------------------------------------------------- 1436969626Sru 1437055839Sasmodai@node Invoking gxditview, , gxditview, gxditview 1437155839Sasmodai@subsection Invoking @code{gxditview} 1437255839Sasmodai@cindex invoking @code{gxditview} 1437355839Sasmodai@cindex @code{gxditview}, invoking 1437455839Sasmodai 1437569626Sru@c XXX 1437669626Sru@c X11's xditview 1437755839Sasmodai 1437855839Sasmodai 1437969626Sru 1438069626Sru@c ===================================================================== 1438169626Sru@c ===================================================================== 1438269626Sru 1438369626Sru@node File formats, Installation, Output Devices, Top 1438455839Sasmodai@chapter File formats 1438555839Sasmodai@cindex file formats 1438655839Sasmodai@cindex formats, file 1438755839Sasmodai 14388104862SruAll files read and written by @code{gtroff} are text files. The 14389104862Srufollowing two sections describe their format. 1439055839Sasmodai 1439155839Sasmodai@menu 1439275584Sru* gtroff Output:: 1439375584Sru* Font Files:: 1439455839Sasmodai@end menu 1439555839Sasmodai 1439669626Sru 1439769626Sru@c ===================================================================== 1439869626Sru 1439955839Sasmodai@node gtroff Output, Font Files, File formats, File formats 1440055839Sasmodai@section @code{gtroff} Output 14401104862Sru@cindex @code{gtroff}, output 1440255839Sasmodai@cindex output, @code{gtroff} 1440355839Sasmodai 14404104862SruThis section describes the intermediate output format of GNU 14405104862Sru@code{troff}. This output is produced by a run of @code{gtroff} 14406104862Srubefore it is fed into a device postprocessor program. 1440755839Sasmodai 14408104862SruAs @code{groff} is a wrapper program around @code{gtroff} that 14409104862Sruautomatically calls a postprocessor, this output does not show up 14410104862Srunormally. This is why it is called @dfn{intermediate}. 14411104862Sru@code{groff} provides the option @option{-Z} to inhibit postprocessing, 14412104862Srusuch that the produced intermediate output is sent to standard output 14413104862Srujust like calling @code{gtroff} manually. 14414104862Sru 14415104862Sru@cindex troff output 14416104862Sru@cindex output, troff 14417104862Sru@cindex intermediate output 14418104862Sru@cindex output, intermediate 14419104862SruHere, the term @dfn{troff output} describes what is output by 14420104862Sru@code{gtroff}, while @dfn{intermediate output} refers to the language 14421104862Sruthat is accepted by the parser that prepares this output for the 14422104862Srupostprocessors. This parser is smarter on whitespace and implements 14423104862Sruobsolete elements for compatibility, otherwise both formats are the 14424104862Srusame.@footnote{The parser and postprocessor for intermediate output 14425104862Srucan be found in the file@* 14426114402Sru@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.} 14427104862Sru 14428104862SruThe main purpose of the intermediate output concept is to facilitate 14429104862Sruthe development of postprocessors by providing a common programming 14430104862Sruinterface for all devices. It has a language of its own that is 14431104862Srucompletely different from the @code{gtroff} language. While the 14432104862Sru@code{gtroff} language is a high-level programming language for text 14433104862Sruprocessing, the intermediate output language is a kind of low-level 14434104862Sruassembler language by specifying all positions on the page for writing 14435104862Sruand drawing. 14436104862Sru 14437104862SruThe intermediate output produced by @code{gtroff} is fairly readable, 14438104862Sruwhile output from @acronym{AT&T} @code{troff} is rather hard to 14439104862Sruunderstand because of strange habits that are still supported, but not 14440104862Sruused any longer by @code{gtroff}. 14441104862Sru 1444269626Sru@menu 14443104862Sru* Language Concepts:: 14444104862Sru* Command Reference:: 14445104862Sru* Intermediate Output Examples:: 14446104862Sru* Output Language Compatibility:: 1444769626Sru@end menu 1444855839Sasmodai 1444969626Sru@c --------------------------------------------------------------------- 1445055839Sasmodai 14451104862Sru@node Language Concepts, Command Reference, gtroff Output, gtroff Output 14452104862Sru@subsection Language Concepts 1445369626Sru 14454104862SruDuring the run of @code{gtroff}, the input data is cracked down to the 14455104862Sruinformation on what has to be printed at what position on the intended 14456104862Srudevice. So the language of the intermediate output format can be quite 14457104862Srusmall. Its only elements are commands with and without arguments. 14458104862SruIn this section, the term @dfn{command} always refers to the intermediate 14459104862Sruoutput language, and never to the @code{gtroff} language used for document 14460104862Sruformatting. There are commands for positioning and text writing, for drawing, and 14461104862Srufor device controlling. 1446269626Sru 14463104862Sru@menu 14464104862Sru* Separation:: 14465104862Sru* Argument Units:: 14466104862Sru* Document Parts:: 14467104862Sru@end menu 1446855839Sasmodai 14469104862Sru@node Separation, Argument Units, Language Concepts, Language Concepts 14470104862Sru@subsubsection Separation 1447155839Sasmodai 14472104862Sru@acronym{AT&T} @code{troff} output has strange requirements on whitespace. 14473104862SruThe @code{gtroff} output parser, however, is smart about whitespace by 14474104862Srumaking it maximally optional. The whitespace characters, i.e., the 14475104862Srutab, space, and newline characters, always have a syntactical meaning. 14476104862SruThey are never printable because spacing within the output is always 14477104862Srudone by positioning commands. 1447855839Sasmodai 14479104862SruAny sequence of space or tab characters is treated as a single 14480104862Sru@dfn{syntactical space}. It separates commands and arguments, but is 14481104862Sruonly required when there would occur a clashing between the command code 14482104862Sruand the arguments without the space. Most often, this happens when 14483104862Sruvariable-length command names, arguments, argument lists, or command 14484104862Sruclusters meet. Commands and arguments with a known, fixed length need 14485104862Srunot be separated by syntactical space. 14486104862Sru 14487104862SruA line break is a syntactical element, too. Every command argument can be 14488104862Srufollowed by whitespace, a comment, or a newline character. Thus a 14489104862Sru@dfn{syntactical line break} is defined to consist of optional 14490104862Srusyntactical space that is optionally followed by a comment, and a 14491104862Srunewline character. 14492104862Sru 14493104862SruThe normal commands, those for positioning and text, consist of a 14494104862Srusingle letter taking a fixed number of arguments. For historical reasons, 14495104862Sruthe parser allows to stack such commands on the same line, but 14496104862Srufortunately, in @code{gtroff}'s intermediate output, every command with 14497104862Sruat least one argument is followed by a line break, thus providing 14498104862Sruexcellent readability. 14499104862Sru 14500104862SruThe other commands -- those for drawing and device controlling -- 14501104862Sruhave a more complicated structure; some recognize long command names, 14502104862Sruand some take a variable number of arguments. So all @samp{D} and 14503104862Sru@samp{x} commands were designed to request a syntactical line break 14504104862Sruafter their last argument. Only one command, @w{@samp{x X}}, 14505104862Sruhas an argument that can stretch over several lines; all other 14506104862Srucommands must have all of their arguments on the same line as the 14507104862Srucommand, i.e., the arguments may not be splitted by a line break. 14508104862Sru 14509104862SruEmpty lines (these are lines containing only space and/or a comment), can 14510104862Sruoccur everywhere. They are just ignored. 14511104862Sru 14512104862Sru@node Argument Units, Document Parts, Separation, Language Concepts 14513104862Sru@subsubsection Argument Units 14514104862Sru 14515104862SruSome commands take integer arguments that are assumed to represent 14516104862Sruvalues in a measurement unit, but the letter for the corresponding 14517104862Sruscale indicator is not written with the output command arguments. 14518104862SruMost commands assume the scale indicator @samp{u}, the basic unit of 14519104862Sruthe device, some use @samp{z}, the scaled point unit of the device, 14520104862Sruwhile others, such as the color commands, expect plain integers. 14521104862Sru 14522104862SruNote that single characters can have the eighth bit set, as can the 14523104862Srunames of fonts and special characters. The names of characters and 14524104862Srufonts can be of arbitrary length. A character that is to be printed 14525104862Sruwill always be in the current font. 14526104862Sru 14527104862SruA string argument is always terminated by the next whitespace 14528104862Srucharacter (space, tab, or newline); an embedded @samp{#} character is 14529104862Sruregarded as part of the argument, not as the beginning of a comment 14530104862Srucommand. An integer argument is already terminated by the next 14531104862Srunon-digit character, which then is regarded as the first character of 14532104862Sruthe next argument or command. 14533104862Sru 14534104862Sru@node Document Parts, , Argument Units, Language Concepts 14535104862Sru@subsubsection Document Parts 14536104862Sru 14537104862SruA correct intermediate output document consists of two parts, the 14538104862Sru@dfn{prologue} and the @dfn{body}. 14539104862Sru 14540104862SruThe task of the prologue is to set the general device parameters 14541104862Sruusing three exactly specified commands. @code{gtroff}'s prologue 14542104862Sruis guaranteed to consist of the following three lines (in that order): 14543104862Sru 14544104862Sru@Example 14545104862Srux T @var{device} 14546104862Srux res @var{n} @var{h} @var{v} 14547104862Srux init 14548104862Sru@endExample 14549104862Sru 14550104862Sru@noindent 14551104862Sruwith the arguments set as outlined in @ref{Device Control Commands}. 14552104862SruNote that the parser for the intermediate output format is able to 14553104862Sruswallow additional whitespace and comments as well even in the 14554104862Sruprologue. 14555104862Sru 14556104862SruThe body is the main section for processing the document data. 14557104862SruSyntactically, it is a sequence of any commands different from the 14558104862Sruones used in the prologue. Processing is terminated as soon as the 14559104862Srufirst @w{@samp{x stop}} command is encountered; the last line of any 14560104862Sru@code{gtroff} intermediate output always contains such a command. 14561104862Sru 14562104862SruSemantically, the body is page oriented. A new page is started by a 14563104862Sru@samp{p} command. Positioning, writing, and drawing commands are 14564104862Srualways done within the current page, so they cannot occur before the 14565104862Srufirst @samp{p} command. Absolute positioning (by the @samp{H} and 14566104862Sru@samp{V} commands) is done relative to the current page; all other 14567104862Srupositioning is done relative to the current location within this page. 14568104862Sru 14569104862Sru@c --------------------------------------------------------------------- 14570104862Sru 14571104862Sru@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output 14572104862Sru@subsection Command Reference 14573104862Sru 14574104862SruThis section describes all intermediate output commands, both from 14575104862Sru@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions. 14576104862Sru 14577104862Sru@menu 14578104862Sru* Comment Command:: 14579104862Sru* Simple Commands:: 14580104862Sru* Graphics Commands:: 14581104862Sru* Device Control Commands:: 14582104862Sru* Obsolete Command:: 14583104862Sru@end menu 14584104862Sru 14585104862Sru@node Comment Command, Simple Commands, Command Reference, Command Reference 14586104862Sru@subsubsection Comment Command 14587104862Sru 1458855839Sasmodai@table @code 14589104862Sru@item #@var{anything}@angles{end of line} 14590104862SruA comment. Ignore any characters from the @samp{#} character up to 14591104862Sruthe next newline character. 1459269626Sru 14593104862SruThis command is the only possibility for commenting in the intermediate 14594104862Sruoutput. Each comment can be preceded by arbitrary syntactical space; 14595104862Sruevery command can be terminated by a comment. 14596104862Sru@end table 1459769626Sru 14598104862Sru@node Simple Commands, Graphics Commands, Comment Command, Command Reference 14599104862Sru@subsubsection Simple Commands 1460069626Sru 14601104862SruThe commands in this subsection have a command code consisting of a 14602104862Srusingle character, taking a fixed number of arguments. Most of them 14603104862Sruare commands for positioning and text writing. These commands are 14604104862Srusmart about whitespace. Optionally, syntactical space can be inserted 14605104862Srubefore, after, and between the command letter and its arguments. 14606104862SruAll of these commands are stackable, i.e., they can be preceded by 14607104862Sruother simple commands or followed by arbitrary other commands on the 14608104862Srusame line. A separating syntactical space is only necessary when two 14609104862Sruinteger arguments would clash or if the preceding argument ends with a 14610104862Srustring argument. 1461169626Sru 14612104862Sru@table @code 14613104862Sru@ignore 14614104862Sru.if (\n[@USE_ENV_STACK] == 1) \{\ 14615104862Sru.command { 14616104862SruOpen a new environment by copying the actual device configuration data 14617104862Sruto the environment stack. 14618104862Sru. 14619104862SruThe current environment is setup by the device specification and 14620104862Srumanipulated by the setting commands. 14621104862Sru. 14622104862Sru. 14623104862Sru.command } 14624104862SruClose the actual environment (opened by a preceding 14625104862Sru.BR { \~command) 14626104862Sruand restore the previous environment from the environment 14627104862Srustack as the actual device configuration data. 14628104862Sru. 14629104862Sru\} \" endif @USE_ENV_STACK 14630104862Sru@end ignore 1463169626Sru 14632104862Sru@item C @var{xxx}@angles{whitespace} 14633104862SruPrint a special character named @var{xxx}. The trailing 14634104862Srusyntactical space or line break is necessary to allow glyph names 14635104862Sruof arbitrary length. The glyph is printed at the current print 14636104862Sruposition; the glyph's size is read from the font file. The print 14637104862Sruposition is not changed. 1463869626Sru 14639104862Sru@item c @var{g} 14640114402SruPrint glyph@tie{}@var{g} at the current print position;@footnote{@samp{c} 14641104862Sruis actually a misnomer since it outputs a glyph.} the glyph's size is 14642104862Sruread from the font file. The print position is not changed. 1464369626Sru 14644104862Sru@item f @var{n} 14645114402SruSet font to font number@tie{}@var{n} (a non-negative integer). 1464655839Sasmodai 14647104862Sru@item H @var{n} 14648114402SruMove right to the absolute vertical position@tie{}@var{n} (a 14649104862Srunon-negative integer in basic units @samp{u} relative to left edge 14650104862Sruof current page. 1465169626Sru 14652104862Sru@item h @var{n} 14653104862SruMove @var{n} (a non-negative integer) basic units @samp{u} horizontally 14654104862Sruto the right. The original @acronym{UNIX} troff manual allows negative 14655104862Sruvalues for @var{n} also, but @code{gtroff} doesn't use this. 1465655839Sasmodai 14657104862Sru@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]} 14658104862SruSet the color for text (glyphs), line drawing, and the outline of 14659104862Srugraphic objects using different color schemes; the analoguous command 14660104862Srufor the filling color of graphic objects is @samp{DF}. The color 14661104862Srucomponents are specified as integer arguments between 0 and 65536. 14662104862SruThe number of color components and their meaning vary for the 14663104862Srudifferent color schemes. These commands are generated by 14664104862Sru@code{gtroff}'s escape sequence @code{\m}. No position changing. 14665104862SruThese commands are a @code{gtroff} extension. 1466669626Sru 14667104862Sru@table @code 14668104862Sru@item mc @var{cyan} @var{magenta} @var{yellow} 14669114402SruSet color using the CMY color scheme, having the 3@tie{}color components 14670104862Sru@var{cyan}, @var{magenta}, and @var{yellow}. 1467169626Sru 14672104862Sru@item md 14673104862SruSet color to the default color value (black in most cases). 14674104862SruNo component arguments. 1467569626Sru 14676104862Sru@item mg @var{gray} 14677104862SruSet color to the shade of gray given by the argument, an integer 14678104862Srubetween 0 (black) and 65536 (white). 1467969626Sru 14680104862Sru@item mk @var{cyan} @var{magenta} @var{yellow} @var{black} 14681114402SruSet color using the CMYK color scheme, having the 4@tie{}color components 14682104862Sru@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. 1468369626Sru 14684104862Sru@item mr @var{red} @var{green} @var{blue} 14685114402SruSet color using the RGB color scheme, having the 3@tie{}color components 14686104862Sru@var{red}, @var{green}, and @var{blue}. 1468755839Sasmodai@end table 1468855839Sasmodai 14689104862Sru@item N @var{n} 14690114402SruPrint glyph with index@tie{}@var{n} (a non-negative integer) of the 14691104862Srucurrent font. This command is a @code{gtroff} extension. 1469269626Sru 14693104862Sru@item n @var{b} @var{a} 14694104862SruInform the device about a line break, but no positioning is done by 14695104862Sruthis command. In @acronym{AT&T} @code{troff}, the integer arguments 14696114402Sru@var{b} and@tie{}@var{a} informed about the space before and after the 14697104862Srucurrent line to make the intermediate output more human readable 14698104862Sruwithout performing any action. In @code{groff}, they are just ignored, but 14699104862Sruthey must be provided for compatibility reasons. 1470055839Sasmodai 14701104862Sru@item p @var{n} 14702104862SruBegin a new page in the outprint. The page number is set 14703114402Sruto@tie{}@var{n}. This page is completely independent of pages formerly 14704104862Sruprocessed even if those have the same page number. The vertical 14705114402Sruposition on the outprint is automatically set to@tie{}0. All 14706104862Srupositioning, writing, and drawing is always done relative to a page, 14707104862Sruso a @samp{p} command must be issued before any of these commands. 1470855839Sasmodai 14709104862Sru@item s @var{n} 14710114402SruSet point size to @var{n}@tie{}scaled points (this is unit @samp{z}). 14711104862Sru@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. 14712104862Sru@xref{Output Language Compatibility}. 1471355839Sasmodai 14714104862Sru@item t @var{xxx}@angles{whitespace} 14715104862Sru@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace} 14716104862SruPrint a word, i.e., a sequence of characters @var{xxx} representing 14717104862Sruoutput glyphs which names are single characters, terminated by 14718104862Srua space character or a line break; an optional second integer argument 14719104862Sruis ignored (this allows the formatter to generate an even number of 14720104862Sruarguments). The first glyph should be printed at the current 14721104862Sruposition, the current horizontal position should then be increased by 14722104862Sruthe width of the first glyph, and so on for each glyph. 14723104862SruThe widths of the glyphs are read from the font file, scaled for the 14724104862Srucurrent point size, and rounded to a multiple of the horizontal 14725104862Sruresolution. Special characters cannot be printed using this command 14726104862Sru(use the @samp{C} command for special characters). This command is a 14727104862Sru@code{gtroff} extension; it is only used for devices whose @file{DESC} 14728104862Srufile contains the @code{tcommand} keyword (@pxref{DESC File Format}). 14729104862Sru 14730104862Sru@item u @var{n} @var{xxx}@angles{whitespace} 14731104862SruPrint word with track kerning. This is the same as the @samp{t} 14732104862Srucommand except that after printing each glyph, the current 14733104862Sruhorizontal position is increased by the sum of the width of that 14734114402Sruglyph and@tie{}@var{n} (an integer in basic units @samp{u}). 14735104862SruThis command is a @code{gtroff} extension; it is only used for devices 14736104862Sruwhose @file{DESC} file contains the @code{tcommand} keyword 14737104862Sru(@pxref{DESC File Format}). 14738104862Sru 14739104862Sru@item V @var{n} 14740114402SruMove down to the absolute vertical position@tie{}@var{n} (a 14741104862Srunon-negative integer in basic units @samp{u}) relative to upper edge 14742104862Sruof current page. 14743104862Sru 14744104862Sru@item v @var{n} 14745114402SruMove @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative 14746104862Sruinteger). The original @acronym{UNIX} troff manual allows negative 14747104862Sruvalues for @var{n} also, but @code{gtroff} doesn't use this. 14748104862Sru 14749104862Sru@item w 14750104862SruInforms about a paddable white space to increase readability. 14751104862SruThe spacing itself must be performed explicitly by a move command. 14752104862Sru@end table 14753104862Sru 14754104862Sru@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference 14755104862Sru@subsubsection Graphics Commands 14756104862Sru 14757104862SruEach graphics or drawing command in the intermediate output starts 14758104862Sruwith the letter @samp{D}, followed by one or two characters that 14759104862Sruspecify a subcommand; this is followed by a fixed or variable number 14760104862Sruof integer arguments that are separated by a single space character. 14761104862SruA @samp{D} command may not be followed by another command on the same line 14762104862Sru(apart from a comment), so each @samp{D} command is terminated by a 14763104862Srusyntactical line break. 14764104862Sru 14765104862Sru@code{gtroff} output follows the classical spacing rules (no space 14766104862Srubetween command and subcommand, all arguments are preceded by a 14767104862Srusingle space character), but the parser allows optional space between 14768104862Sruthe command letters and makes the space before the first argument 14769104862Sruoptional. As usual, each space can be any sequence of tab and space 14770104862Srucharacters. 14771104862Sru 14772104862SruSome graphics commands can take a variable number of arguments. 14773104862SruIn this case, they are integers representing a size measured in basic 14774104862Sruunits @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{}, 14775104862Sru@var{hn} stand for horizontal distances where positive means right, 14776104862Srunegative left. The arguments called @var{v1}, @var{v2}, @dots{}, 14777104862Sru@var{vn} stand for vertical distances where positive means down, 14778104862Srunegative up. All these distances are offsets relative to the current 14779104862Srulocation. 14780104862Sru 14781114402SruEach graphics command directly corresponds to a similar @code{gtroff} 14782114402Sru@code{\D} escape sequence. @xref{Drawing Requests}. 14783104862Sru 14784104862SruUnknown @samp{D} commands are assumed to be device-specific. 14785104862SruIts arguments are parsed as strings; the whole information is then 14786104862Srusent to the postprocessor. 14787104862Sru 14788104862SruIn the following command reference, the syntax element 14789104862Sru@angles{line break} means a syntactical line break as defined above. 14790104862Sru 1479155839Sasmodai@table @code 14792104862Sru@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14793104862SruDraw B-spline from current position to offset (@var{h1},@var{v1}), 14794104862Sruthen to offset (@var{h2},@var{v2}), if given, etc.@: up to 14795104862Sru(@var{hn},@var{vn}). This command takes a variable number of argument 14796104862Srupairs; the current position is moved to the terminal point of the drawn 14797104862Srucurve. 1479869626Sru 14799104862Sru@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break} 14800104862SruDraw arc from current position to 14801104862Sru(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at 14802104862Sru(@var{h1},@var{v1}); then move the current position to the final point 14803104862Sruof the arc. 1480469626Sru 14805104862Sru@item DC @var{d}@angles{line break} 14806104862Sru@itemx DC @var{d} @var{dummy-arg}@angles{line break} 14807104862SruDraw a solid circle using the current fill color with 14808114402Srudiameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost 14809104862Srupoint at the current position; then move the current position to the 14810104862Srurightmost point of the circle. An optional second integer argument is 14811104862Sruignored (this allows the formatter to generate an even number of 14812104862Sruarguments). This command is a @code{gtroff} extension. 1481369626Sru 14814104862Sru@item Dc @var{d}@angles{line break} 14815114402SruDraw circle line with diameter@tie{}@var{d} (integer in basic units 14816104862Sru@samp{u}) with leftmost point at the current position; then move the 14817104862Srucurrent position to the rightmost point of the circle. 14818104862Sru 14819104862Sru@item DE @var{h} @var{v}@angles{line break} 14820104862SruDraw a solid ellipse in the current fill color with a horizontal 14821114402Srudiameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both 14822104862Sruintegers in basic units @samp{u}) with the leftmost point at the 14823104862Srucurrent position; then move to the rightmost point of the ellipse. 14824104862SruThis command is a @code{gtroff} extension. 14825104862Sru 14826104862Sru@item De @var{h} @var{v}@angles{line break} 14827114402SruDraw an outlined ellipse with a horizontal diameter of@tie{}@var{h} 14828114402Sruand a vertical diameter of@tie{}@var{v} (both integers in basic units 14829104862Sru@samp{u}) with the leftmost point at current position; then move to 14830104862Sruthe rightmost point of the ellipse. 14831104862Sru 14832104862Sru@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break} 14833104862SruSet fill color for solid drawing objects using different color 14834104862Sruschemes; the analoguous command for setting the color of text, line 14835104862Srugraphics, and the outline of graphic objects is @samp{m}. 14836104862SruThe color components are specified as integer arguments between 0 and 14837104862Sru65536. The number of color components and their meaning vary for the 14838104862Srudifferent color schemes. These commands are generated by @code{gtroff}'s 14839104862Sruescape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other 14840104862Srucorresponding graphics commands). No position changing. This command 14841104862Sruis a @code{gtroff} extension. 14842104862Sru 14843104862Sru@table @code 14844104862Sru@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} 14845104862SruSet fill color for solid drawing objects using the CMY color scheme, 14846114402Sruhaving the 3@tie{}color components @var{cyan}, @var{magenta}, and 14847104862Sru@var{yellow}. 14848104862Sru 14849104862Sru@item DFd@angles{line break} 14850104862SruSet fill color for solid drawing objects to the default fill color value 14851104862Sru(black in most cases). No component arguments. 14852104862Sru 14853104862Sru@item DFg @var{gray}@angles{line break} 14854104862SruSet fill color for solid drawing objects to the shade of gray given by 14855104862Sruthe argument, an integer between 0 (black) and 65536 (white). 14856104862Sru 14857104862Sru@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} 14858104862SruSet fill color for solid drawing objects using the CMYK color scheme, 14859114402Sruhaving the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow}, 14860104862Sruand @var{black}. 14861104862Sru 14862104862Sru@item DFr @var{red} @var{green} @var{blue}@angles{line break} 14863104862SruSet fill color for solid drawing objects using the RGB color scheme, 14864114402Sruhaving the 3@tie{}color components @var{red}, @var{green}, and @var{blue}. 1486555839Sasmodai@end table 1486655839Sasmodai 14867104862Sru@item Df @var{n}@angles{line break} 14868114402SruThe argument@tie{}@var{n} must be an integer in the range @math{-32767} 14869104862Sruto 32767. 1487055839Sasmodai 14871104862Sru@table @asis 14872151497Sru@item @math{0 @LE{} @var{n} @LE{} 1000} 14873104862SruSet the color for filling solid drawing objects to a shade of gray, 14874104862Sruwhere 0 corresponds to solid white, 1000 (the default) to solid black, 14875104862Sruand values in between to intermediate shades of gray; this is 14876104862Sruobsoleted by command @samp{DFg}. 14877104862Sru 14878114402Sru@item @math{@var{n} < 0} or @math{@var{n} > 1000} 14879104862SruSet the filling color to the color that is currently being used for 14880104862Sruthe text and the outline, see command @samp{m}. For example, the 14881104862Srucommand sequence 14882104862Sru 1488375584Sru@Example 14884104862Srumg 0 0 65536 14885104862SruDf -1 1488675584Sru@endExample 1488755839Sasmodai 1488869626Sru@noindent 14889104862Srusets all colors to blue. 14890104862Sru@end table 1489169626Sru 1489269626Sru@noindent 14893104862SruNo position changing. This command is a @code{gtroff} extension. 1489469626Sru 14895104862Sru@item Dl @var{h} @var{v}@angles{line break} 14896104862SruDraw line from current position to offset (@var{h},@var{v}) (integers 14897104862Sruin basic units @samp{u}); then set current position to the end of the 14898104862Srudrawn line. 1489969626Sru 14900104862Sru@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14901104862SruDraw a polygon line from current position to offset (@var{h1},@var{v1}), 14902104862Srufrom there to offset (@var{h2},@var{v2}), etc.@: up to offset 14903104862Sru(@var{hn},@var{vn}), and from there back to the starting position. 14904104862SruFor historical reasons, the position is changed by adding the sum of 14905104862Sruall arguments with odd index to the actual horizontal position and the 14906104862Srueven ones to the vertical position. Although this doesn't make sense 14907104862Sruit is kept for compatibility. 1490869626Sru@ignore 14909104862SruAs the polygon is closed, the end of drawing is the starting point, so 14910104862Sruthe position doesn't change. 1491169626Sru@end ignore 14912104862SruThis command is a @code{gtroff} extension. 1491355839Sasmodai 14914104862Sru@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14915104862SruDraw a solid polygon in the current fill color rather than an outlined 14916104862Srupolygon, using the same arguments and positioning as the corresponding 14917104862Sru@samp{Dp} command. 14918104862Sru@ignore 14919104862SruNo position changing. 14920104862Sru@end ignore 14921104862SruThis command is a @code{gtroff} extension. 1492269626Sru 14923104862Sru@item Dt @var{n}@angles{line break} 14924114402SruSet the current line thickness to@tie{}@var{n} (an integer in basic 14925104862Sruunits @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the 14926104862Srusmallest available line thickness; if @math{@var{n}<0} set the line 14927104862Sruthickness proportional to the point size (this is the default before 14928104862Sruthe first @samp{Dt} command was specified). For historical reasons, 14929104862Sruthe horizontal position is changed by adding the argument to the actual 14930104862Sruhorizontal position, while the vertical position is not changed. 14931104862SruAlthough this doesn't make sense it is kept for compatibility. 14932104862Sru@ignore 14933104862SruNo position changing. 14934104862Sru@end ignore 14935104862SruThis command is a @code{gtroff} extension. 14936104862Sru@end table 1493755839Sasmodai 14938104862Sru@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference 14939104862Sru@subsubsection Device Control Commands 1494069626Sru 14941104862SruEach device control command starts with the letter @samp{x}, 14942104862Srufollowed by a space character (optional or arbitrary space or tab in 14943104862Sru@code{gtroff}) and a subcommand letter or word; each argument (if any) 14944104862Srumust be preceded by a syntactical space. All @samp{x} commands are 14945104862Sruterminated by a syntactical line break; no device control command can 14946104862Srube followed by another command on the same line (except a comment). 14947104862Sru 14948104862SruThe subcommand is basically a single letter, but to increase 14949104862Srureadability, it can be written as a word, i.e., an arbitrary sequence 14950104862Sruof characters terminated by the next tab, space, or newline character. 14951104862SruAll characters of the subcommand word but the first are simply ignored. 14952104862SruFor example, @code{gtroff} outputs the initialization command 14953104862Sru@w{@samp{x i}} as @w{@samp{x init}} and the resolution command 14954104862Sru@w{@samp{x r}} as @w{@samp{x res}}. 14955104862Sru 14956104862SruIn the following, the syntax element @angles{line break} means a 14957104862Srusyntactical line break (@pxref{Separation}). 14958104862Sru 1495955839Sasmodai@table @code 14960104862Sru@item xF @var{name}@angles{line break} 14961104862SruThe @samp{F} stands for @var{Filename}. 1496269626Sru 14963104862SruUse @var{name} as the intended name for the current file in error 14964104862Srureports. This is useful for remembering the original file name when 14965104862Sru@code{gtroff} uses an internal piping mechanism. The input file is 14966104862Srunot changed by this command. This command is a @code{gtroff} extension. 1496769626Sru 14968104862Sru@item xf @var{n} @var{s}@angles{line break} 14969104862SruThe @samp{f} stands for @var{font}. 1497069626Sru 14971114402SruMount font position@tie{}@var{n} (a non-negative integer) with font 14972114402Srunamed@tie{}@var{s} (a text word). @xref{Font Positions}. 1497369626Sru 14974104862Sru@item xH @var{n}@angles{line break} 14975104862SruThe @samp{H} stands for @var{Height}. 1497669626Sru 14977114402SruSet glyph height to@tie{}@var{n} (a positive integer in scaled 14978104862Srupoints @samp{z}). @acronym{AT&T} @code{troff} uses the unit points 14979104862Sru(@samp{p}) instead. @xref{Output Language Compatibility}. 14980104862Sru 14981104862Sru@item xi@angles{line break} 14982104862SruThe @samp{i} stands for @var{init}. 14983104862Sru 14984104862SruInitialize device. This is the third command of the prologue. 14985104862Sru 14986104862Sru@item xp@angles{line break} 14987104862SruThe @samp{p} stands for @var{pause}. 14988104862Sru 14989104862SruParsed but ignored. The original @acronym{UNIX} troff manual writes 14990104862Sru 14991104862Sru@display 14992104862Srupause device, can be restarted 14993104862Sru@end display 14994104862Sru 14995104862Sru@item xr @var{n} @var{h} @var{v}@angles{line break} 14996104862SruThe @samp{r} stands for @var{resolution}. 14997104862Sru 14998114402SruResolution is@tie{}@var{n}, while @var{h} is the minimal horizontal 14999104862Srumotion, and @var{v} the minimal vertical motion possible with this 15000104862Srudevice; all arguments are positive integers in basic units @samp{u} 15001104862Sruper inch. This is the second command of the prologue. 15002104862Sru 15003104862Sru@item xS @var{n}@angles{line break} 15004104862SruThe @samp{S} stands for @var{Slant}. 15005104862Sru 15006114402SruSet slant to@tie{}@var{n} (an integer in basic units @samp{u}). 15007104862Sru 15008104862Sru@item xs@angles{line break} 15009104862SruThe @samp{s} stands for @var{stop}. 15010104862Sru 15011104862SruTerminates the processing of the current file; issued as the last 15012104862Srucommand of any intermediate troff output. 15013104862Sru 15014104862Sru@item xt@angles{line break} 15015104862SruThe @samp{t} stands for @var{trailer}. 15016104862Sru 15017104862SruGenerate trailer information, if any. In @var{gtroff}, this is 15018104862Sruactually just ignored. 15019104862Sru 15020104862Sru@item xT @var{xxx}@angles{line break} 15021104862SruThe @samp{T} stands for @var{Typesetter}. 15022104862Sru 15023104862SruSet name of device to word @var{xxx}, a sequence of characters ended 15024104862Sruby the next white space character. The possible device names coincide 15025104862Sruwith those from the @code{groff} @option{-T} option. This is the first 15026104862Srucommand of the prologue. 15027104862Sru 15028104862Sru@item xu @var{n}@angles{line break} 15029104862SruThe @samp{u} stands for @var{underline}. 15030104862Sru 15031114402SruConfigure underlining of spaces. If @var{n} is@tie{}1, start 15032114402Sruunderlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces. 15033104862SruThis is needed for the @code{cu} request in nroff mode and is ignored 15034104862Sruotherwise. This command is a @code{gtroff} extension. 15035104862Sru 15036104862Sru@item xX @var{anything}@angles{line break} 15037104862SruThe @samp{x} stands for @var{X-escape}. 15038104862Sru 15039104862SruSend string @var{anything} uninterpreted to the device. If the line 15040104862Srufollowing this command starts with a @samp{+} character this line is 15041104862Sruinterpreted as a continuation line in the following sense. The 15042104862Sru@samp{+} is ignored, but a newline character is sent instead to the 15043104862Srudevice, the rest of the line is sent uninterpreted. The same applies 15044104862Sruto all following lines until the first character of a line is not a 15045104862Sru@samp{+} character. This command is generated by the @code{gtroff} 15046104862Sruescape sequence @code{\X}. The line-continuing feature is a 15047104862Sru@code{gtroff} extension. 1504855839Sasmodai@end table 1504955839Sasmodai 15050104862Sru@node Obsolete Command, , Device Control Commands, Command Reference 15051104862Sru@subsubsection Obsolete Command 15052104862SruIn @acronym{AT&T} @code{troff} output, the writing of a single 15053104862Sruglyph is mostly done by a very strange command that combines a 15054104862Sruhorizontal move and a single character giving the glyph name. It 15055104862Srudoesn't have a command code, but is represented by a 3-character 15056114402Sruargument consisting of exactly 2@tie{}digits and a character. 1505755839Sasmodai 15058104862Sru@table @asis 15059104862Sru@item @var{dd}@var{g} 15060104862SruMove right @var{dd} (exactly two decimal digits) basic units @samp{u}, 15061114402Sruthen print glyph@tie{}@var{g} (represented as a single character). 1506255839Sasmodai 15063104862SruIn @code{gtroff}, arbitrary syntactical space around and within this 15064104862Srucommand is allowed to be added. Only when a preceding command on the 15065104862Srusame line ends with an argument of variable length a separating space 15066104862Sruis obligatory. In @acronym{AT&T} @code{troff}, large clusters of these 15067104862Sruand other commands are used, mostly without spaces; this made such output 15068104862Srualmost unreadable. 15069104862Sru@end table 15070104862Sru 15071104862SruFor modern high-resolution devices, this command does not make sense 15072104862Srubecause the width of the glyphs can become much larger than two 15073104862Srudecimal digits. In @code{gtroff}, this is only used for the devices 15074104862Sru@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other 15075104862Srudevices, the commands @samp{t} and @samp{u} provide a better 15076104862Srufunctionality. 15077104862Sru 15078104862Sru@c --------------------------------------------------------------------- 15079104862Sru 15080104862Sru@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output 15081104862Sru@subsection Intermediate Output Examples 15082104862Sru 15083104862SruThis section presents the intermediate output generated from the same 15084104862Sruinput for three different devices. The input is the sentence 15085104862Sru@samp{hell world} fed into @code{gtroff} on the command line. 15086104862Sru 15087104862Sru@table @asis 15088104862Sru@item High-resolution device @code{ps} 15089104862Sru 15090104862SruThis is the standard output of @code{gtroff} if no @option{-T} option 15091104862Sruis given. 15092104862Sru 15093104862Sru@example 15094104862Sru@group 15095104862Srushell> echo "hell world" | groff -Z -T ps 15096104862Sru 15097104862Srux T ps 15098104862Srux res 72000 1 1 15099104862Srux init 15100104862Sru@end group 15101104862Srup1 15102104862Srux font 5 TR 15103104862Sruf5 15104104862Srus10000 15105104862SruV12000 15106104862SruH72000 15107104862Sruthell 15108104862Sruwh2500 15109104862Srutw 15110104862SruH96620 15111104862Srutorld 15112104862Srun12000 0 15113104862Sru@group 15114104862Srux trailer 15115104862SruV792000 15116104862Srux stop 15117104862Sru@end group 15118104862Sru@end example 15119104862Sru 1512069626Sru@noindent 15121104862SruThis output can be fed into @code{grops} to get its representation as 15122104862Srua PostScript file. 1512355839Sasmodai 15124104862Sru@item Low-resolution device @code{latin1} 1512555839Sasmodai 15126104862SruThis is similar to the high-resolution device except that the 15127104862Srupositioning is done at a minor scale. Some comments (lines starting 15128104862Sruwith @samp{#}) were added for clarification; they were not generated 15129104862Sruby the formatter. 15130104862Sru 15131104862Sru@example 15132104862Sru@group 15133104862Srushell> echo "hell world" | groff -Z -T latin1 15134104862Sru 15135104862Sru# prologue 15136104862Srux T latin1 15137104862Srux res 240 24 40 15138104862Srux init 15139104862Sru@end group 15140104862Sru# begin a new page 15141104862Srup1 15142104862Sru# font setup 15143104862Srux font 1 R 15144104862Sruf1 15145104862Srus10 15146104862Sru# initial positioning on the page 15147104862SruV40 15148104862SruH0 15149104862Sru# write text `hell' 15150104862Sruthell 15151104862Sru# inform about space, and issue a horizontal jump 15152104862Sruwh24 15153104862Sru# write text `world' 15154104862Srutworld 15155104862Sru# announce line break, but do nothing because ... 15156104862Srun40 0 15157104862Sru@group 15158104862Sru# ... the end of the document has been reached 15159104862Srux trailer 15160104862SruV2640 15161104862Srux stop 15162104862Sru@end group 15163104862Sru@end example 15164104862Sru 1516569626Sru@noindent 15166104862SruThis output can be fed into @code{grotty} to get a formatted text 15167104862Srudocument. 1516855839Sasmodai 15169104862Sru@item @acronym{AT&T} @code{troff} output 15170104862SruSince a computer monitor has a very low resolution compared to modern 15171114402Sruprinters the intermediate output for the X@tie{}Window devices can use 15172104862Sruthe jump-and-write command with its 2-digit displacements. 15173104862Sru 15174104862Sru@example 15175104862Sru@group 15176104862Srushell> echo "hell world" | groff -Z -T X100 15177104862Sru 15178104862Srux T X100 15179104862Srux res 100 1 1 15180104862Srux init 15181104862Sru@end group 15182104862Srup1 15183104862Srux font 5 TR 15184104862Sruf5 15185104862Srus10 15186104862SruV16 15187104862SruH100 15188104862Sru# write text with jump-and-write commands 15189104862Sruch07e07l03lw06w11o07r05l03dh7 15190104862Srun16 0 15191104862Sru@group 15192104862Srux trailer 15193104862SruV1100 15194104862Srux stop 15195104862Sru@end group 15196104862Sru@end example 15197104862Sru 15198104862Sru@noindent 15199104862SruThis output can be fed into @code{xditview} or @code{gxditview} 15200114402Srufor displaying in@tie{}X. 15201104862Sru 15202104862SruDue to the obsolete jump-and-write command, the text clusters in the 15203104862Sru@acronym{AT&T} @code{troff} output are almost unreadable. 15204104862Sru@end table 15205104862Sru 1520669626Sru@c --------------------------------------------------------------------- 1520769626Sru 15208104862Sru@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output 15209104862Sru@subsection Output Language Compatibility 1521055839Sasmodai 15211104862SruThe intermediate output language of @acronym{AT&T} @code{troff} 15212104862Sruwas first documented in the @acronym{UNIX} troff manual, with later 15213104862Sruadditions documented in @cite{A Typesetter-indenpendent TROFF}, 15214104862Sruwritten by Brian Kernighan. 1521555839Sasmodai 15216104862SruThe @code{gtroff} intermediate output format is compatible with this 15217104862Sruspecification except for the following features. 1521855839Sasmodai 15219104862Sru@itemize @bullet 15220104862Sru@item 15221104862SruThe classical quasi device independence is not yet implemented. 15222104862Sru 15223104862Sru@item 15224104862SruThe old hardware was very different from what we use today. So the 15225104862Sru@code{groff} devices are also fundamentally different from the ones in 15226104862Sru@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T} 15227104862SruPostScript device is called @code{post} and has a resolution of only 15228104862Sru720 units per inch, suitable for printers 20 years ago, while 15229104862Sru@code{groff}'s @code{ps} device has a resolution of 15230104862Sru72000 units per inch. Maybe, by implementing some rescaling 15231104862Srumechanism similar to the classical quasi device independence, 15232104862Sru@code{groff} could emulate @acronym{AT&T}'s @code{post} device. 15233104862Sru 15234104862Sru@item 15235104862SruThe B-spline command @samp{D~} is correctly handled by the 15236104862Sruintermediate output parser, but the drawing routines aren't 15237104862Sruimplemented in some of the postprocessor programs. 15238104862Sru 15239104862Sru@item 15240104862SruThe argument of the commands @samp{s} and @w{@samp{x H}} has the 15241104862Sruimplicit unit scaled point @samp{z} in @code{gtroff}, while 15242104862Sru@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an 15243104862Sruincompatibility but a compatible extension, for both units coincide 15244104862Srufor all devices without a @code{sizescale} parameter in the @file{DESC} 15245104862Srufile, including all postprocessors from @acronym{AT&T} and 15246104862Sru@code{groff}'s text devices. The few @code{groff} devices with 15247104862Srua @code{sizescale} parameter either do not exist for @acronym{AT&T} 15248104862Sru@code{troff}, have a different name, or seem to have a different 15249104862Sruresolution. So conflicts are very unlikely. 15250104862Sru 15251104862Sru@item 15252104862SruThe position changing after the commands @samp{Dp}, @samp{DP}, and 15253104862Sru@samp{Dt} is illogical, but as old versions of @code{gtroff} used this 15254104862Srufeature it is kept for compatibility reasons. 15255104862Sru 15256104862Sru@ignore 15257104862SruTemporarily, there existed some confusion on the positioning after the 15258104862Sru@samp{D} commands that are groff extensions. This has been clarified 15259104862Sruby establishing the classical rule for all @code{groff} drawing commands: 15260104862Sru 15261104862Sru@itemize 15262104862Sru@item 15263104862SruThe position after a graphic object has been drawn is at its end; 15264104862Srufor circles and ellipses, the `end' is at the right side. 15265104862Sru 15266104862Sru@item 15267104862SruFrom this, the positionings specified for the drawing commands above 15268104862Srufollow quite naturally. 15269104862Sru@end itemize 15270104862Sru@end ignore 15271104862Sru 15272104862Sru@end itemize 15273104862Sru 15274104862Sru 1527569626Sru@c ===================================================================== 1527655839Sasmodai 1527755839Sasmodai@node Font Files, , gtroff Output, File formats 1527855839Sasmodai@section Font Files 1527955839Sasmodai@cindex font files 1528055839Sasmodai@cindex files, font 1528155839Sasmodai 1528269626SruThe @code{gtroff} font format is roughly a superset of the 15283104862Sru@code{ditroff} font format (as used in later versions of @acronym{AT&T} 15284104862Sru@code{troff} and its descendants). Unlike the @code{ditroff} font 15285104862Sruformat, there is no associated binary format; all files are text 15286114402Srufiles.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary 15287104862Sruformat.} The font files for device @var{name} are stored in a directory 1528869626Sru@file{dev@var{name}}. There are two types of file: a device description 15289114402Srufile called @file{DESC} and for each font@tie{}@var{f} a font file 15290114402Srucalled@tie{}@file{@var{f}}. 1529155839Sasmodai 1529269626Sru@menu 1529375584Sru* DESC File Format:: 1529475584Sru* Font File Format:: 1529569626Sru@end menu 1529655839Sasmodai 1529769626Sru@c --------------------------------------------------------------------- 1529869626Sru 1529975584Sru@node DESC File Format, Font File Format, Font Files, Font Files 1530075584Sru@subsection @file{DESC} File Format 15301104862Sru@cindex @file{DESC} file, format 15302104862Sru@cindex font description file, format 1530369626Sru@cindex format of font description file 1530469626Sru@pindex DESC@r{ file format} 1530555839Sasmodai 15306104862SruThe @file{DESC} file can contain the following types of line. Except 15307104862Srufor the @code{charset} keyword which must comes last (if at all), the 15308104862Sruorder of the lines is not important. 1530955839Sasmodai 1531055839Sasmodai@table @code 1531155839Sasmodai@item res @var{n} 1531269626Sru@kindex res 15313114402Sru@cindex device resolution 15314114402Sru@cindex resolution, device 15315114402SruThere are @var{n}@tie{}machine units per inch. 1531669626Sru 1531755839Sasmodai@item hor @var{n} 1531869626Sru@kindex hor 15319114402Sru@cindex horizontal resolution 15320114402Sru@cindex resolution, horizontal 15321114402SruThe horizontal resolution is @var{n}@tie{}machine units. All horizontal 15322114402Sruquantities are rounded to be multiples of this value. 1532369626Sru 1532455839Sasmodai@item vert @var{n} 1532569626Sru@kindex vert 15326114402Sru@cindex vertical resolution 15327114402Sru@cindex resolution, vertical 15328114402SruThe vertical resolution is @var{n}@tie{}machine units. All vertical 15329114402Sruquantities are rounded to be multiples of this value. 1533069626Sru 1533155839Sasmodai@item sizescale @var{n} 1533269626Sru@kindex sizescale 15333114402SruThe scale factor for point sizes. By default this has a value of@tie{}1. 1533469626SruOne scaled point is equal to one point/@var{n}. The arguments to the 1533555839Sasmodai@code{unitwidth} and @code{sizes} commands are given in scaled points. 1533655839Sasmodai@xref{Fractional Type Sizes}, for more information. 1533769626Sru 1533855839Sasmodai@item unitwidth @var{n} 1533969626Sru@kindex unitwidth 1534069626SruQuantities in the font files are given in machine units for fonts whose 15341114402Srupoint size is @var{n}@tie{}scaled points. 1534269626Sru 15343104862Sru@item prepro @var{program} 15344104862Sru@kindex prepro 15345104862SruCall @var{program} as a preprocessor. Currently, this keyword is used 15346104862Sruby @code{groff} with option @option{-Thtml} only. 15347104862Sru 15348104862Sru@item postpro @var{program} 15349104862Sru@kindex postpro 15350104862SruCall @var{program} as a postprocessor. For example, the line 15351104862Sru 15352104862Sru@Example 15353104862Srupostpro grodvi 15354104862Sru@endExample 15355104862Sru 15356104862Sru@noindent 15357104862Sruin the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} 15358104862Sruif option @option{-Tdvi} is given (and @option{-Z} isn't used). 15359104862Sru 1536055839Sasmodai@item tcommand 1536169626Sru@kindex tcommand 1536269626SruThis means that the postprocessor can handle the @samp{t} and @samp{u} 15363104862Sruintermediate output commands. 1536469626Sru 1536569626Sru@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 1536669626Sru@kindex sizes 1536769626SruThis means that the device has fonts at @var{s1}, @var{s2}, @dots{} 15368114402Sru@var{sn} scaled points. The list of sizes must be terminated by@tie{}0 15369104862Sru(this is digit zero). Each @var{si} can also be a range of sizes 15370104862Sru@var{m}-@var{n}. The list can extend over more than one line. 1537169626Sru 1537269626Sru@item styles @var{S1} @var{S2} @dots{} @var{Sm} 1537369626Sru@kindex styles 15374114402SruThe first @var{m}@tie{}font positions are associated with styles 1537569626Sru@var{S1} @dots{} @var{Sm}. 1537669626Sru 1537769626Sru@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 1537869626Sru@kindex fonts 1537975584SruFonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 1538069626Sru@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 1538169626Srustyles. This command may extend over more than one line. A font name 15382114402Sruof@tie{}0 means no font is mounted on the corresponding font position. 1538369626Sru 1538455839Sasmodai@item family @var{fam} 1538569626Sru@kindex family 1538655839SasmodaiThe default font family is @var{fam}. 1538769626Sru 15388104862Sru@item use_charnames_in_special 15389104862Sru@kindex use_charnames_in_special 15390104862SruThis command indicates that @code{gtroff} should encode special 15391104862Srucharacters inside special commands. Currently, this is only used 15392104862Sruby the @acronym{HTML} output device. @xref{Postprocessor Access}. 15393104862Sru 15394104862Sru@item papersize @var{string} @dots{} 15395104862Sru@kindex papersize 15396104862SruSelect a paper size. Valid values for @var{string} are the ISO paper 15397104862Srutypes @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7}, 15398104862Sru@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter}, 15399104862Sru@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, 15400104862Sru@code{executive}, @code{com10}, and @code{monarch}. Case is not significant 15401104862Srufor @var{string} if it holds predefined paper types. Alternatively, 15402104862Sru@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file 15403104862Srucan be opened, @code{groff} reads the first line and tests for the above 15404104862Srupaper sizes. Finally, @var{string} can be a custom paper size in the format 15405104862Sru@code{@var{length},@var{width}} (no spaces before and after the comma). 15406104862SruBoth @var{length} and @var{width} must have a unit appended; valid values 15407104862Sruare @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and 15408104862Sru@samp{P} for picas. Example: @code{12c,235p}. An argument which starts 15409104862Sruwith a digit is always treated as a custom paper format. @code{papersize} 15410104862Srusets both the vertical and horizontal dimension of the output medium. 15411104862Sru 15412104862SruMore than one argument can be specified; @code{groff} scans from left to 15413104862Sruright and uses the first valid paper specification. 15414104862Sru 15415104862Sru@item pass_filenames 15416104862Sru@kindex pass_filenames 15417104862SruTell @code{gtroff} to emit the name of the source file currently 15418104862Srubeing processed. This is achieved by the intermediate output command 15419104862Sru@samp{F}. Currently, this is only used by the @acronym{HTML} output 15420104862Srudevice. 15421104862Sru 15422104862Sru@item print @var{program} 15423104862Sru@kindex print 15424104862SruUse @var{program} as a spooler program for printing. If omitted, 15425104862Sruthe @option{-l} and @option{-L} options of @code{groff} are ignored. 15426104862Sru 1542755839Sasmodai@item charset 1542869626Sru@kindex charset 1542955839SasmodaiThis line and everything following in the file are ignored. It is 1543055839Sasmodaiallowed for the sake of backwards compatibility. 1543155839Sasmodai@end table 1543255839Sasmodai 15433104862SruThe @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines 1543469626Sruare mandatory. Other commands are ignored by @code{gtroff} but may be 1543569626Sruused by postprocessors to store arbitrary information about the device 1543669626Sruin the @file{DESC} file. 1543755839Sasmodai 15438104862Sru@kindex spare1 15439104862Sru@kindex spare2 15440104862Sru@kindex biggestfont 15441104862SruHere a list of obsolete keywords which are recognized by @code{groff} 15442104862Srubut completely ignored: @code{spare1}, @code{spare2}, 15443104862Sru@code{biggestfont}. 1544455839Sasmodai 1544569626Sru@c --------------------------------------------------------------------- 1544669626Sru 1544775584Sru@node Font File Format, , DESC File Format, Font Files 1544875584Sru@subsection Font File Format 15449104862Sru@cindex font file, format 15450104862Sru@cindex font description file, format 1545169626Sru@cindex format of font files 15452104862Sru@cindex format of font description files 1545355839Sasmodai 15454104862SruA @dfn{font file}, also (and probably better) called a @dfn{font 15455104862Srudescription file}, has two sections. The first section is a sequence 15456104862Sruof lines each containing a sequence of blank delimited words; the first 15457104862Sruword in the line is a key, and subsequent words give a value for that 15458104862Srukey. 1545955839Sasmodai 1546055839Sasmodai@table @code 1546169626Sru@item name @var{f} 1546269626Sru@kindex name 15463114402SruThe name of the font is@tie{}@var{f}. 1546469626Sru 1546555839Sasmodai@item spacewidth @var{n} 1546669626Sru@kindex spacewidth 15467114402SruThe normal width of a space is@tie{}@var{n}. 1546869626Sru 1546955839Sasmodai@item slant @var{n} 1547069626Sru@kindex slant 15471114402SruThe glyphs of the font have a slant of @var{n}@tie{}degrees. 1547255839Sasmodai(Positive means forward.) 1547369626Sru 1547469626Sru@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 1547569626Sru@kindex ligatures 15476104862SruGlyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 1547769626Srupossible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 1547869626Sru@samp{ffl}. For backwards compatibility, the list of ligatures may be 15479114402Sruterminated with a@tie{}0. The list of ligatures may not extend over more 1548069626Sruthan one line. 1548169626Sru 1548255839Sasmodai@item special 15483104862Sru@cindex special fonts 1548469626Sru@kindex special 15485104862SruThe font is @dfn{special}; this means that when a glyph is requested 15486104862Sruthat is not present in the current font, it is searched for in any 1548755839Sasmodaispecial fonts that are mounted. 1548855839Sasmodai@end table 1548955839Sasmodai 1549069626SruOther commands are ignored by @code{gtroff} but may be used by 1549169626Srupostprocessors to store arbitrary information about the font in the font 1549269626Srufile. 1549355839Sasmodai 1549469626Sru@cindex comments in font files 1549569626Sru@cindex font files, comments 1549669626Sru@kindex # 1549769626SruThe first section can contain comments which start with the @samp{#} 1549869626Srucharacter and extend to the end of a line. 1549955839Sasmodai 1550055839SasmodaiThe second section contains one or two subsections. It must contain a 1550155839Sasmodai@code{charset} subsection and it may also contain a @code{kernpairs} 1550255839Sasmodaisubsection. These subsections can appear in any order. Each 1550355839Sasmodaisubsection starts with a word on a line by itself. 1550455839Sasmodai 1550569626Sru@kindex charset 15506104862SruThe word @code{charset} starts the character set 15507104862Srusubsection.@footnote{This keyword is misnamed since it starts a list 15508104862Sruof ordered glyphs, not characters.} The @code{charset} line is 15509104862Srufollowed by a sequence of lines. Each line gives information for one 15510104862Sruglyph. A line comprises a number of fields separated by blanks or 15511104862Srutabs. The format is 1551255839Sasmodai 15513104862Sru@quotation 15514104862Sru@var{name} @var{metrics} @var{type} @var{code} 15515104862Sru[@var{entity-name}] [@code{--} @var{comment}] 15516104862Sru@end quotation 1551769626Sru 1551869626Sru@cindex 8-bit input 1551969626Sru@cindex input, 8-bit 15520104862Sru@cindex accessing unnamed glyphs with @code{\N} 15521104862Sru@cindex unnamed glyphs, accessing with @code{\N} 15522104862Sru@cindex characters, unnamed, accessing with @code{\N} 15523104862Sru@cindex glyphs, unnamed, accessing with @code{\N} 1552469626Sru@kindex --- 1552569626Sru@noindent 15526104862Sru@var{name} identifies the glyph name@footnote{The distinction between 15527104862Sruinput, characters, and output, glyphs, is not clearly separated in the 15528104862Sruterminology of @code{groff}; for example, the @code{char} request 15529104862Srushould be called @code{glyph} since it defines an output entity.}: 15530114402SruIf @var{name} is a single character@tie{}@var{c} then it corresponds 15531114402Sruto the @code{gtroff} input character@tie{}@var{c}; if it is of the form 15532104862Sru@samp{\@var{c}} where @var{c} is a single character, then it 15533104862Srucorresponds to the special character @code{\[@var{c}]}; otherwise it 15534104862Srucorresponds to the special character @samp{\[@var{name}]}. If it 15535104862Sruis exactly two characters @var{xx} it can be entered as 15536104862Sru@samp{\(@var{xx}}. Note that single-letter special characters can't 15537104862Srube accessed as @samp{\@var{c}}; the only exception is @samp{\-} which 15538104862Sruis identical to @code{\[-]}. 1553955839Sasmodai 15540104862Sru@code{gtroff} supports 8-bit input characters; however some utilities 15541104862Sruhave difficulties with eight-bit characters. For this reason, there is 15542104862Srua convention that the entity name @samp{char@var{n}} is equivalent to 15543114402Sruthe single input character whose code is@tie{}@var{n}. For example, 15544114402Sru@samp{char163} would be equivalent to the character with code@tie{}163 15545114402Sruwhich is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set. 15546104862SruYou shouldn't use @samp{char@var{n}} entities in font description files 15547104862Srusince they are related to input, not output. Otherwise, you get 15548104862Sruhard-coded connections between input and output encoding which 15549104862Sruprevents use of different (input) character sets. 1555069626Sru 15551104862SruThe name @samp{---} is special and indicates that the glyph is 15552104862Sruunnamed; such glyphs can only be used by means of the @code{\N} 15553104862Sruescape sequence in @code{gtroff}. 1555455839Sasmodai 15555104862SruThe @var{type} field gives the glyph type: 15556104862Sru 1555755839Sasmodai@table @code 1555855839Sasmodai@item 1 15559104862Sruthe glyph has a descender, for example, @samp{p}; 1556069626Sru 1556155839Sasmodai@item 2 15562104862Sruthe glyph has an ascender, for example, @samp{b}; 1556369626Sru 1556455839Sasmodai@item 3 15565104862Sruthe glyph has both an ascender and a descender, for example, @samp{(}. 1556655839Sasmodai@end table 1556755839Sasmodai 1556855839SasmodaiThe @var{code} field gives the code which the postprocessor uses to 15569104862Sruprint the glyph. The glyph can also be input to @code{gtroff} 15570104862Sruusing this code by means of the @code{\N} escape sequence. @var{code} 15571104862Srucan be any integer. If it starts with @samp{0} it is interpreted as 1557275584Sruoctal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 15573104862Sruhexadecimal. Note, however, that the @code{\N} escape sequence only 15574104862Sruaccepts a decimal integer. 1557555839Sasmodai 15576104862SruThe @var{entity-name} field gives an @acronym{ASCII} string 15577104862Sruidentifying the glyph which the postprocessor uses to print the 15578104862Sru@code{gtroff} glyph @var{name}. This field is optional and has been 15579104862Sruintroduced so that the @acronym{HTML} device driver can encode its 15580104862Srucharacter set. For example, the glyph @samp{\[Po]} is 15581104862Srurepresented as @samp{£} in @acronym{HTML} 4.0. 1558255839Sasmodai 15583104862SruAnything on the line after the @var{entity-name} field resp.@: after 15584104862Sru@samp{--} will be ignored. 15585104862Sru 1558655839SasmodaiThe @var{metrics} field has the form: 1558755839Sasmodai 15588104862Sru@display 15589104862Sru@group 15590104862Sru@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction} 15591104862Sru [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]] 15592104862Sru@end group 15593104862Sru@end display 1559455839Sasmodai 1559569626Sru@noindent 1559669626SruThere must not be any spaces between these subfields (it has been split 1559769626Sruhere into two lines for better legibility only). Missing subfields are 15598114402Sruassumed to be@tie{}0. The subfields are all decimal integers. Since 1559969626Sruthere is no associated binary format, these values are not required to 1560069626Srufit into a variable of type @samp{char} as they are in @code{ditroff}. 15601104862SruThe @var{width} subfield gives the width of the glyph. The @var{height} 15602104862Srusubfield gives the height of the glyph (upwards is positive); if a 15603104862Sruglyph does not extend above the baseline, it should be given a zero 15604104862Sruheight, rather than a negative height. The @var{depth} subfield gives 15605104862Sruthe depth of the glyph, that is, the distance from the baseline to the 15606104862Srulowest point below the baseline to which the glyph extends (downwards is 15607104862Srupositive); if a glyph does not extend below the baseline, it should be 15608104862Srugiven a zero depth, rather than a negative depth. The 15609104862Sru@var{italic-correction} subfield gives the amount of space that should 15610104862Srube added after the glyph when it is immediately to be followed by a 15611104862Sruglyph from a roman font. The @var{left-italic-correction} subfield 15612104862Srugives the amount of space that should be added before the glyph when it 15613104862Sruis immediately to be preceded by a glyph from a roman font. The 15614104862Sru@var{subscript-correction} gives the amount of space that should be 15615104862Sruadded after a glyph before adding a subscript. This should be less 1561655839Sasmodaithan the italic correction. 1561755839Sasmodai 1561855839SasmodaiA line in the @code{charset} section can also have the format 1561955839Sasmodai 1562075584Sru@Example 1562155839Sasmodai@var{name} " 1562275584Sru@endExample 1562355839Sasmodai 1562469626Sru@noindent 15625104862SruThis indicates that @var{name} is just another name for the glyph 1562655839Sasmodaimentioned in the preceding line. 1562755839Sasmodai 1562869626Sru@kindex kernpairs 1562955839SasmodaiThe word @code{kernpairs} starts the kernpairs section. This contains a 1563055839Sasmodaisequence of lines of the form: 1563155839Sasmodai 1563275584Sru@Example 1563369626Sru@var{c1} @var{c2} @var{n} 1563475584Sru@endExample 1563555839Sasmodai 1563675584Sru@noindent 15637104862SruThis means that when glyph @var{c1} appears next to glyph @var{c2} 15638114402Sruthe space between them should be increased by@tie{}@var{n}. Most 15639114402Sruentries in the kernpairs section have a negative value for@tie{}@var{n}. 1564055839Sasmodai 1564155839Sasmodai 1564255839Sasmodai 1564369626Sru@c ===================================================================== 1564469626Sru@c ===================================================================== 1564569626Sru 15646104862Sru@node Installation, Copying This Manual, File formats, Top 1564755839Sasmodai@chapter Installation 1564855839Sasmodai@cindex installation 1564955839Sasmodai 1565069626Sru@c XXX 1565155839Sasmodai 1565255839Sasmodai 1565355839Sasmodai 1565469626Sru@c ===================================================================== 1565569626Sru@c ===================================================================== 1565669626Sru 15657104862Sru@node Copying This Manual, Request Index, Installation, Top 15658104862Sru@appendix Copying This Manual 1565969626Sru 15660104862Sru@menu 15661104862Sru* GNU Free Documentation License:: License for copying this manual. 15662104862Sru@end menu 15663104862Sru 15664104862Sru@include fdl.texi 15665104862Sru 15666104862Sru 15667104862Sru 15668104862Sru@c ===================================================================== 15669104862Sru@c ===================================================================== 15670104862Sru 15671104862Sru@node Request Index, Escape Index, Copying This Manual, Top 15672104862Sru@appendix Request Index 15673104862Sru 1567475584SruRequests appear without the leading control character (normally either 1567575584Sru@samp{.} or @samp{'}). 1567669626Sru 1567775584Sru@printindex rq 1567855839Sasmodai 1567955839Sasmodai 1568069626Sru 1568169626Sru@c ===================================================================== 1568269626Sru@c ===================================================================== 1568369626Sru 1568475584Sru@node Escape Index, Operator Index, Request Index, Top 15685104862Sru@appendix Escape Index 1568675584Sru 15687104862SruAny escape sequence @code{\@var{X}} with @var{X} not in the list below 15688104862Sruemits a warning, printing glyph @var{X}. 15689104862Sru 1569075584Sru@printindex es 1569175584Sru 1569275584Sru 1569375584Sru 1569475584Sru@c ===================================================================== 1569575584Sru@c ===================================================================== 1569675584Sru 1569775584Sru@node Operator Index, Register Index, Escape Index, Top 15698104862Sru@appendix Operator Index 1569969626Sru 1570069626Sru@printindex op 1570169626Sru 1570269626Sru 1570369626Sru 1570469626Sru@c ===================================================================== 1570569626Sru@c ===================================================================== 1570669626Sru 1570775584Sru@node Register Index, Macro Index, Operator Index, Top 15708104862Sru@appendix Register Index 1570955839Sasmodai 15710104862SruThe macro package or program a specific register belongs to is appended in 15711104862Srubrackets. 15712104862Sru 15713114402SruA register name@tie{}@code{x} consisting of exactly one character can be 15714104862Sruaccessed as @samp{\nx}. A register name @code{xx} consisting of exactly 15715104862Srutwo characters can be accessed as @samp{\n(xx}. Register names @code{xxx} 15716104862Sruof any length can be accessed as @samp{\n[xxx]}. 15717104862Sru 1571855839Sasmodai@printindex vr 1571955839Sasmodai 1572055839Sasmodai 1572155839Sasmodai 1572269626Sru@c ===================================================================== 1572369626Sru@c ===================================================================== 1572455839Sasmodai 1572575584Sru@node Macro Index, String Index, Register Index, Top 15726104862Sru@appendix Macro Index 1572755839Sasmodai 15728104862SruThe macro package a specific macro belongs to is appended in brackets. 15729104862SruThey appear without the leading control character (normally @samp{.}). 15730104862Sru 1573169626Sru@printindex ma 1573255839Sasmodai 1573355839Sasmodai 1573455839Sasmodai 1573569626Sru@c ===================================================================== 1573669626Sru@c ===================================================================== 1573769626Sru 1573875584Sru@node String Index, Glyph Name Index, Macro Index, Top 15739104862Sru@appendix String Index 1574075584Sru 15741104862SruThe macro package or program a specific string belongs to is appended in 15742104862Srubrackets. 15743104862Sru 15744114402SruA string name@tie{}@code{x} consisting of exactly one character can be 15745104862Sruaccessed as @samp{\*x}. A string name @code{xx} consisting of exactly 15746104862Srutwo characters can be accessed as @samp{\*(xx}. String names @code{xxx} 15747104862Sruof any length can be accessed as @samp{\*[xxx]}. 15748104862Sru 15749104862Sru 1575075584Sru@printindex st 1575175584Sru 1575275584Sru 1575375584Sru 1575475584Sru@c ===================================================================== 1575575584Sru@c ===================================================================== 1575675584Sru 1575775584Sru@node Glyph Name Index, Font File Keyword Index, String Index, Top 15758104862Sru@appendix Glyph Name Index 1575969626Sru 1576069626SruA glyph name @code{xx} consisting of exactly two characters can be 1576169626Sruaccessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 1576269626Sruaccessed as @samp{\[xxx]}. 1576369626Sru 15764104862Sru@c XXX 1576569626Sru 1576669626Sru 1576769626Sru 1576869626Sru@c ===================================================================== 1576969626Sru@c ===================================================================== 1577069626Sru 1577169626Sru@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 15772104862Sru@appendix Font File Keyword Index 1577369626Sru 1577469626Sru@printindex ky 1577569626Sru 1577669626Sru 1577769626Sru 1577869626Sru@c ===================================================================== 1577969626Sru@c ===================================================================== 1578069626Sru 1578169626Sru@node Program and File Index, Concept Index, Font File Keyword Index, Top 15782104862Sru@appendix Program and File Index 1578369626Sru 1578455839Sasmodai@printindex pg 1578555839Sasmodai 1578655839Sasmodai 1578755839Sasmodai 1578869626Sru@c ===================================================================== 1578969626Sru@c ===================================================================== 1579069626Sru 1579169626Sru@node Concept Index, , Program and File Index, Top 15792104862Sru@appendix Concept Index 1579355839Sasmodai 1579455839Sasmodai@printindex cp 1579555839Sasmodai 1579655839Sasmodai 1579755839Sasmodai@bye 15798